Habitat Alarm User Guide

Digital Energy
Alarm
User's Guide
Version: Habitat 5.11

Document Date: March 25, 2020
Copyright and Proprietary Information
Copyright 2020 General Electric Company and/or its affiliates (“GE”). All Rights Reserved. This document is the
confidential and proprietary information of GE and may not be reproduced, transmitted, stored, or copied in
whole or in part, or used to furnish information to others, without the prior written permission of GE.
Contents
About This Document ........................................................................................................ xi
Purpose of This Document ..............................................................................................................................xi
Who Should Use This Document ..................................................................................................................xi
Structure of This Document ............................................................................................................................xi
For More Information ...................................................................................................................................... xii
Conventions ....................................................................................................................................................... xiii
Change Summary ............................................................................................................................................ xiv
1. Introduction ...................................................................................................................... 1
1.1 What Is Alarm? ............................................................................................................................................. 1
1.2 Overview ......................................................................................................................................................... 1
1.3 Life Cycle of an Event ................................................................................................................................. 3
1.4 Terminology................................................................................................................................................... 4
1.5 Alarm Health Timer..................................................................................................................................... 6
2. Alarm Server Event Processing ................................................................................... 7

2.1 Events vs. Alarms......................................................................................................................................... 8
2.1.1 Unacknowledged Alarm or Log-Only Event?.............................................................................. 8
2.1.2 Auto-Acknowledgment ....................................................................................................................... 9
2.1.3 Abnormal State .................................................................................................................................... 10
2.2 Formatting ................................................................................................................................................... 10
2.2.1 The Time Format ................................................................................................................................. 10
2.2.2 The Text Format .................................................................................................................................. 11
2.3 Long-Name and MRID Support ............................................................................................................ 11
2.3.1 Supported Types ................................................................................................................................. 12
2.3.2 Alarm Event Block ............................................................................................................................... 12
2.3.3 Processing New Alarm Event Block Fields................................................................................. 14
2.3.3.1 Long Name Look Up .................................................................................................................... 14
2.3.3.2 Errors Reported if the Long Name Lookup Fails ............................................................... 14
2.3.3.3 Processing the object_mrid Field ........................................................................................... 15
2.3.3.4 Getting the Full Composite Key of the Object.................................................................... 15
2.3.4 Changing the .ALMMSG File for Long Name Support ............................................................ 15
2.3.4.1 New Tokens .................................................................................................................................... 15
2.3.4.2 Ability to Compress a Long Name.......................................................................................... 16
2.3.4.3 Processing a Long Name Longer Than 40 Characters .................................................. 16
2.4 The LINK Command .................................................................................................................................. 16
2.5 The Alarm Lists ........................................................................................................................................... 17
2.5.1 The Alarm Synopsis List .................................................................................................................... 17
2.5.2 Browser Alarm Displays ................................................................................................................... 17
2.6 The Formatted Logs ................................................................................................................................. 18
2.6.1 The Timesearch Formatted Logs .................................................................................................. 19
2.6.2 The Circular Formatted Log ............................................................................................................ 19
2.7 Event Replication ....................................................................................................................................... 19
2.8 When the Alarm List Is Full .................................................................................................................... 21
Proprietary – See Copyright Page iii

2.9 Improving Alarm Performance During a Storm ............................................................................. 22
2.10 Summary of Permission Checks ........................................................................................................ 22
2.11 Operating Procedure ............................................................................................................................. 23
3. Acknowledging and Deleting ..................................................................................... 24

3.1 Alarm Acknowledgment ......................................................................................................................... 24
3.1.1 Acknowledgment Notifications ..................................................................................................... 26
3.1.2 Logging of Acknowledgments ....................................................................................................... 27
3.2 Alarm Deletion ............................................................................................................................................ 27
3.2.1 Logging of Deletions .......................................................................................................................... 29
3.2.2 Acknowledgment and Deletion Performance .......................................................................... 29
3.2.2.1 Relating Unrelated Alarms ........................................................................................................ 29
3.2.3 Multiple Permission Areas ............................................................................................................... 29
3.3 Permissions ................................................................................................................................................. 30
3.4 Inhibiting Alarms........................................................................................................................................ 30
4. Printing and Archiving ................................................................................................. 31

4.1 Printing Events ........................................................................................................................................... 31
4.2 Archiving Events ........................................................................................................................................ 31
4.2.1 Archive File Naming ........................................................................................................................... 32
4.2.2 Archive File Scheduling ..................................................................................................................... 32
4.2.2.1 Periodic Scheduling ..................................................................................................................... 33
4.2.2.2 Daily Scheduling ........................................................................................................................... 33
4.2.2.3 Weekly Scheduling....................................................................................................................... 33
4.2.2.4 Monthly Scheduling ..................................................................................................................... 33
4.2.3 Miscellaneous Archive Settings ..................................................................................................... 34
5. Sounding and Silencing Tones .................................................................................. 35

5.1 Types of Tones ............................................................................................................................................ 35
5.2 Priority of Tones ......................................................................................................................................... 35
5.3 Processing within the Alarm Server ................................................................................................... 35
5.3.1 When to Issue a Tone ........................................................................................................................ 36
5.3.2 Silencing Tones .................................................................................................................................... 37
5.3.3 Permission Checks for Tones.......................................................................................................... 38
5.4 AudioAlarm in the Browser Viewer ..................................................................................................... 38
6. Adding Notes to an Alarm .......................................................................................... 40

6.1 How Does It Work? ................................................................................................................................... 41
7. Setting Up the ALARM Database .............................................................................. 43

7.1 The Validation Program .......................................................................................................................... 43
7.1.1 Executing the Validation Program ............................................................................................... 43
7.1.2 Limitations of the Validation Program ........................................................................................ 44
7.2 The ALARM Database Records ............................................................................................................. 44
7.2.1 The Application (APP) Record.......................................................................................................... 46
7.2.2 The Category (CAT) Record .............................................................................................................. 46
7.2.3 The Default Log (DEFLOG) Record................................................................................................. 47
Proprietary – See Copyright Page iv

7.2.4 The Object Definition (OBJDEF) Record....................................................................................... 47
7.2.5 The Exception Definition (EXCDEF) Record ................................................................................ 48
7.2.6 The Override Log (OVLOG) Record ................................................................................................ 49
7.2.7 The Location (LOC) Record .............................................................................................................. 49
7.2.8 The Console (CONSOL) Record ....................................................................................................... 49
7.2.9 The QUE Record ................................................................................................................................... 50
7.2.10 The QUEAREA Record...................................................................................................................... 50
7.2.11 The HORN Record ............................................................................................................................. 50
7.2.12 The TONE Record .............................................................................................................................. 51
7.2.13 The ZHORN Record .......................................................................................................................... 51
7.3 Setting Up Horns and Tones ................................................................................................................. 51
7.4 Miscellaneous Items ................................................................................................................................. 52
7.4.1 Default Alarm Settings ...................................................................................................................... 52
7.4.2 Transaction Timers............................................................................................................................. 52
7.4.2.1 PERMIT Timer ................................................................................................................................. 52
7.4.2.2 Hdb Transaction Timer ............................................................................................................... 53
7.4.3 Alarm Issued Alarms .......................................................................................................................... 53
7.4.4 Percent to Free in Full List ............................................................................................................... 53
7.4.5 Operating Procedures Directory ................................................................................................... 53
7.4.6 Use Special Area Alarming .............................................................................................................. 53
7.4.7 Maximum Number of Priorities ..................................................................................................... 53
7.4.8 Number of MRS Messages to Buffer before Committing a Transaction ........................ 54
7.4.9 Use Functional Permission Checking .......................................................................................... 54
7.4.10 Alarm Notes Event Consumer Port Number .......................................................................... 54
7.4.11 Use Long Names............................................................................................................................... 55
7.4.12 Ignore Long Names in APIs........................................................................................................... 55
7.4.13 Log a Message When Alarm is Falling Behind in Processing........................................... 55
7.4.14 Use Elasticsearch ............................................................................................................................. 55
7.4.15 Audible Alarm Suppression........................................................................................................... 55
7.4.16 Leave Duplicate Space in CIRCLG Text..................................................................................... 56
7.4.17 Alarm Database Lock Timeout .................................................................................................... 56
7.4.18 Force Flushing Events after a Transaction ............................................................................. 56
7.5 Simple Return to Normal Scenario ..................................................................................................... 56
7.6 Complex Return to Normal Scenario ................................................................................................. 58
7.7 Return to Normal Using Alarm API Functions ................................................................................ 59
7.8 Resizing the Alarm Database................................................................................................................ 59
7.9 Onlining the Alarm Database ............................................................................................................... 59
8. Creating Indexed Browser Displays ......................................................................... 60

8.1 Indexed Queries ......................................................................................................................................... 60
8.1.1 ALARMS Queries (ALMQ Records).................................................................................................. 60
8.1.1.1 Time Queries .................................................................................................................................. 61
8.1.1.2 Attribute Queries .......................................................................................................................... 62
8.1.1.3 Group Queries................................................................................................................................ 63
8.1.1.4 Calculated Fields .......................................................................................................................... 63
8.1.1.5 Unack / Ack Separator Bar ....................................................................................................... 64
Proprietary – See Copyright Page v

8.1.2 EVENTS Queries (SYSACT Records) ............................................................................................... 65
8.1.2.1 Time Queries .................................................................................................................................. 65
8.1.2.2 Attribute Queries .......................................................................................................................... 66
8.1.2.3 Group Queries................................................................................................................................ 66
8.1.2.4 Calculated Fields .......................................................................................................................... 66
9. Alarm Viewer .................................................................................................................. 68

9.1 Alarm Viewer User Interface Overview ............................................................................................. 68
9.1.1 Query View ............................................................................................................................................ 69
9.1.2 Results View .......................................................................................................................................... 71
9.1.2.1 Pasting Events into Excel........................................................................................................... 72
9.2 Alarm Viewer Startup............................................................................................................................... 72
9.3 Performance Considerations ................................................................................................................ 73
9.4 Configuration .............................................................................................................................................. 73
9.4.1 Required Configuration .................................................................................................................... 73
9.4.2 Required Configuration for a Standalone Alarm Viewer...................................................... 74
9.4.3 Permission Configuration ................................................................................................................ 75
9.4.3.1 Filter by Permissions in Alarm Viewer .................................................................................. 75
9.4.4 Optional Configuration Parameters ............................................................................................ 75
9.4.4.1 Optional Configuration for a Standalone Alarm Viewer ................................................ 78
9.4.5 Miscellaneous Configuration .......................................................................................................... 79
9.5 Alarm Viewer Operations ....................................................................................................................... 79
9.5.1 Save Query ............................................................................................................................................ 79
9.5.2 Load Query ............................................................................................................................................ 80
9.5.3 Save Preferences ................................................................................................................................ 80
9.5.4 Change Font ......................................................................................................................................... 81
9.5.5 Clear Cache ........................................................................................................................................... 81
9.5.6 Command Interface ........................................................................................................................... 81
9.6 Alarm Viewer Printing .............................................................................................................................. 82
9.7 Browser Integration ................................................................................................................................. 82
9.8 Alarm Viewer Help System..................................................................................................................... 82
9.9 Archive File Management ...................................................................................................................... 82
9.9.1 Archive File Loading ........................................................................................................................... 83
9.9.2 Archive File Publishing ...................................................................................................................... 83
10. Alarm Pager.................................................................................................................. 85

10.1 Alarm Interface ........................................................................................................................................ 85
10.2 Alarm Pages .............................................................................................................................................. 85
10.3 Alarm Pager Database ......................................................................................................................... 86
10.3.1 Database Validation........................................................................................................................ 86
10.3.2 Filter Records ..................................................................................................................................... 86
10.3.3 Address Records ............................................................................................................................... 88
10.3.4 Script Records .................................................................................................................................... 90
10.3.5 Group Records ................................................................................................................................... 91
10.3.6 Miscellaneous Records ................................................................................................................... 92
10.4 Display Description ................................................................................................................................ 93
Proprietary – See Copyright Page vi

10.5 User Actions .............................................................................................................................................. 95
10.6 Test Mode .................................................................................................................................................. 96
10.7 Setting Up the Alarm Pager ................................................................................................................ 97
10.7.1 Verify SMTP ......................................................................................................................................... 97
10.7.2 Modeling the Alarm Pager in PROCMAN ................................................................................. 97
10.7.3 Alarm Definition ................................................................................................................................ 98
10.7.4 Alarm Pager Definition ................................................................................................................... 98
10.7.4.1 Addresses ..................................................................................................................................... 98
10.7.4.2 Scripts ............................................................................................................................................ 98
10.7.4.3 Filters .............................................................................................................................................. 99
10.7.4.4 Groups......................................................................................................................................... 100
10.7.4.5 Miscellaneous........................................................................................................................... 100
10.7.4.6 E-Mail Context .......................................................................................................................... 100
10.7.5 Troubleshooting ............................................................................................................................. 101
10.7.5.1 Incorrect Filter Process ......................................................................................................... 101
10.7.5.2 Debug Message ....................................................................................................................... 101
11. Interfaces to Other Subsystems .......................................................................... 102

11.1 Dependencies........................................................................................................................................ 102
11.1.1 NETIO ................................................................................................................................................. 102
11.1.2 Hdb ..................................................................................................................................................... 102
11.1.3 PERMIT ............................................................................................................................................... 102
11.2 Optional Interfaces.............................................................................................................................. 103
11.2.1 MLF Message Daemon ................................................................................................................ 103
11.2.2 Configuration Manager ............................................................................................................... 103
11.2.3 PROCMAN ......................................................................................................................................... 104
11.2.4 Hdb/MRS ........................................................................................................................................... 104
11.2.5 Logman ............................................................................................................................................. 104
11.2.6 Browser List ..................................................................................................................................... 104
11.2.7 Identifier Mapping Service (IMS)............................................................................................... 104
11.2.8 Alarm Notes Event Consumer (ANEC) .................................................................................... 105
12. Using the Alarm API ................................................................................................ 106

12.1 API Introduction .................................................................................................................................... 106
12.2 Accessing the API................................................................................................................................. 106
12.3 Basic Use ................................................................................................................................................. 106
12.4 Performance Improvements ........................................................................................................... 107
12.5 Number of Events per Transaction ............................................................................................... 108
13. Alarm API Descriptions .......................................................................................... 109

alarm_acknowledge ..................................................................................................................................... 111
alarm_acknowledge_ex .............................................................................................................................. 113
alarm_acknowledge_ex2 ........................................................................................................................... 115
alarm_acknowledge_ex3 ........................................................................................................................... 117
alarm_category_exists ................................................................................................................................ 120
alarm_delete ................................................................................................................................................... 121
Proprietary – See Copyright Page vii

alarm_delete_ex ............................................................................................................................................ 123
alarm_delete_ex2 .......................................................................................................................................... 125
alarm_dump_history .................................................................................................................................... 127
alarm_enum_unack_objects .................................................................................................................... 128
alarm_enum_unack_objects_ex ............................................................................................................. 131
alarm_enum_unack_objects_ex2 ........................................................................................................... 134
alarm_enum_ack_objects.......................................................................................................................... 146
alarm_enum_ack_objects_ex................................................................................................................... 148
alarm_enum_ack_objects_ex2 ................................................................................................................ 151
alarm_exception_exists .............................................................................................................................. 154
alarm_flush_acknowledgments .............................................................................................................. 155
alarm_flush_events ...................................................................................................................................... 156
alarm_get_event ........................................................................................................................................... 157
alarm_get_event_ex .................................................................................................................................... 159
alarm_location_exists.................................................................................................................................. 161
alarm_post_event ......................................................................................................................................... 162
alarm_post_event_ex .................................................................................................................................. 166
alarm_post_event_ex2................................................................................................................................ 172
alarm_register_category ............................................................................................................................ 200
alarm_register_client ................................................................................................................................... 202
alarm_register_exception .......................................................................................................................... 204
alarm_register_location.............................................................................................................................. 206
alarm_reset_lists ........................................................................................................................................... 208
alarm_store_acknowledgment ................................................................................................................ 209
alarm_store_acknowledgment_ex ......................................................................................................... 211
alarm_store_acknowledgment_ex2 ...................................................................................................... 213
alarm_store_acknowledgment_ex3 ...................................................................................................... 215
alarm_store_event ........................................................................................................................................ 218
alarm_store_event_ex................................................................................................................................. 220
alarm_store_event_ex2 .............................................................................................................................. 222
alarm_subscribe ............................................................................................................................................ 230
alarm_subscribe_ex ..................................................................................................................................... 234
alarm_subscribe_ex2 ................................................................................................................................... 238
alarm_unregister_client.............................................................................................................................. 242
alarm_use_hdbha ......................................................................................................................................... 243
Proprietary – See Copyright Page viii

14. The Alarm Test Program ........................................................................................ 244
14.1 Running the Alarm Test Program .................................................................................................. 244
14.2 The Alarm Performance Test Menu .............................................................................................. 245
14.3 The Alarm Backup-Replication API Menu ................................................................................... 246
14.4 The Alarm API Validation Test Menu............................................................................................. 247
14.5 The Alarm Extended Function Test Menu ................................................................................... 248
14.6 The Alarm Subscribe Function Test Menu .................................................................................. 249
14.7 The Alarm Extended Ex3 Function Test Menu ........................................................................... 250
14.10 The Test Program as a Debugging Tool.................................................................................... 251
15. Frequently Asked Questions ................................................................................. 252

15.1 An Event Cannot Be Found in the System Activity Log.......................................................... 252
15.2 A Client Does Not Connect to the Alarm Server ....................................................................... 252
15.3 Tones Are Not Sounding.................................................................................................................... 253
15.4 Acknowledging an Alarm Does Not Silence the Tone ............................................................ 253
15.5 There Is a Need to Customize the Alarm Source Code .......................................................... 254
15.6 There Is a Need to Rebuild the ALARM Codeset ....................................................................... 255
15.7 Alarm Text Does Not Line Up Properly on Displays ................................................................ 256
15.8 Alarm Archive Files Not Readable by Alarm Viewer ............................................................... 257
Appendix A. Version Modification History ............................................................... 258

A.1 Changes from 5.3 to 5.4 ...................................................................................................................... 258
A.2 Changes from 5.4 to 5.5 ...................................................................................................................... 258
A.3 Changes from 5.7 to 5.8 ...................................................................................................................... 259
Appendix B. Changing APF Audible Profiles ............................................................ 260
Figures
Figure 1. Overview of Events Processing and Alarm Acknowledgment ........................................... 2
Figure 2. Life Cycle of an Event......................................................................................................................... 3
Figure 3. Overview of Event Processing ........................................................................................................ 7
Figure 4. UNACK vs. LOG-ONLY State ............................................................................................................ 9
Figure 5. Alarm and Browser Interaction ...................................................................................................18
Figure 6. Alarm and MRS Interaction ...........................................................................................................20
Figure 7. Alarm Acknowledgment .................................................................................................................26
Figure 8. Tones and Alarm ...............................................................................................................................37
Figure 9. Audio Alarm Tab in the Browser Viewer ...................................................................................39
Figure 10. ALARM Database ............................................................................................................................45
Figure 11. Use Long Names .............................................................................................................................55
Figure 12. Simple Return to Normal Example ...........................................................................................57
Figure 13. Complex Return to Normal Example .......................................................................................58
Figure 14. Indexed Query for Alarms ...........................................................................................................61
Proprietary – See Copyright Page ix

Figure 15. Indexed Query for Events ............................................................................................................65
Figure 16. Alarm Viewer Main Screen ..........................................................................................................69
Figure 17. Event Details.....................................................................................................................................72
Figure 18. Save Query Dialog Box .................................................................................................................79
Figure 19. Load Query Dialog Box .................................................................................................................80
Figure 20. Archive Web Server Configuration...........................................................................................84
Figure 21. Alarm Pager Filter Model .............................................................................................................87
Figure 22. Alarm Pager Address Model .......................................................................................................89
Figure 23. Alarm Pager Script Model ............................................................................................................90
Figure 24. Alarm Pager Group Model ...........................................................................................................91
Figure 25. Alarm Pager Miscellaneous Model ...........................................................................................92
Figure 26. Alarm Pager Filter Statistics .......................................................................................................94
Figure 27. Alarm Pager Address Statistics .................................................................................................94
Figure 28. Alarm Pager Script Statistics ......................................................................................................95
Figure 29. Alarm Pager Application Log .....................................................................................................95
Figure 30. Alarm Summary Page Display ...................................................................................................96
Figure 31. Alarm API Test Menu .................................................................................................................. 244
Figure 32. Alarm Performance Test Menu............................................................................................... 245
Figure 33. Alarm Replication API Test Menu ........................................................................................... 246
Figure 34. Alarm API Validation Test Menu ............................................................................................. 247
Figure 35. Alarm Extended Function Test Menu ................................................................................... 248
Figure 36. Alarm Subscribe Function Test Menu .................................................................................. 249
Figure 37. Alarm Extended Ex3 Function Test Menu ........................................................................... 250
Tables
Table 1. Event Processing Options .................................................................................................................. 9
Proprietary – See Copyright Page x

About This Document
This document is supplied as a part of GE’s Habitat (formerly e-terrahabitat) product.
Purpose of This Document

This document has two main purposes:
• To provide basic instructions on the programming procedures used to set up and define
the Habitat Alarm utilities.
• To provide operator instructions for those who operate and use the Habitat Alarm
utilities.
Who Should Use This Document

This guide is intended for programmers and operators who use and maintain the Habitat
Alarm utilities.
Structure of This Document

This document is structured in the following manner:
• Chapter 1 introduces the Alarm utilities.
• Chapter 2 describes Alarm server event processing.
• Chapter 3 describes how to acknowledge and delete alarms.
• Chapter 4 describes how to print and archive data in the Alarm utilities.
• Chapter 5 describes how to sound and silence tones.
• Chapter 6 describes how to add notes to an alarm.
• Chapter 7 provides instructions for setting up the Alarm database.
• Chapter 8 describes how to create indexed Browser (formerly e-terrabrowser) displays.
• Chapter 9 describes the Alarm Viewer.
• Chapter 10 describes the Alarm Pager.
• Chapter 11 describes interfaces to other subsystems.
• Chapter 12 describes how to use the Alarm API.
• Chapter 13 provides Alarm API descriptions.
• Chapter 14 describes the Alarm test program.
• Chapter 15 addresses frequently asked questions.
Proprietary – See Copyright Page xi

• Appendix A provides a version modification history.
• Appendix B describes how to change Advanced Presentation Framework (APF) Audible
profiles from a single user to all users.
For More Information

For more information about Platform (formerly e-terraplatform), refer to the following:
• Platform System Overview: An overall view of Platform and its components, their
functions and use, and how they are related functionally and structurally.
For more information about Browser, refer to the following:
• Browser User’s Guide: An overall view of Browser, its components, and their functions
and use.
For more information about NETIO, refer to the following:
• NETIO User’s Guide: Information about using and developing NETIO applications and
managing NETIO networks.
For more information about ESCATOOLS, refer to the following:
• ESCATOOLS User’s Guide: An introduction to the concepts and features of ESCATOOLS
and instructions for using ESCATOOLS procedures.
Proprietary – See Copyright Page xii

Conventions
The following conventions are used throughout this document. Commands that are specific
to an operating system are shown with the corresponding prompt symbol.
Command Prompts
Operating Prompt Description
System
Linux % All commands preceded by a percent sign prompt (%)
are issued from a Linux terminal window. Note that all
Linux commands are case sensitive.
Windows > All commands preceded by a greater-than sign prompt
(>) are issued from a Windows command line window.
All Operating The absence of any prompt character before a
Systems command indicates that the command is valid on all
operating systems.
Command Strings
Operating Delimiter Description
System
Linux Italics Text in italics indicates information you must supply. (*)
Linux [] Text enclosed in square brackets "[ ]" indicates optional
qualifiers, arguments, or data. (*)
All Operating Select When used in command strings, the term “Select”
Systems means placing the pointer over the specified item and
pressing the left (default) mouse button.
(*) Note: All Linux commands are case sensitive and must be typed exactly as shown.
Proprietary – See Copyright Page xiii

Change Summary
The following changes were made to this document for Habitat 5.11:
• Updated the description of the "Display in system line" option in section 7.2.2 The
Category (CAT) Record.
• Added section 7.4.14 Use Elasticsearch.
• Added section 7.4.15 Audible Alarm Suppression.
• Added the alarm_post_event_ex5 API description in chapter 13 Alarm API Descriptions.
• Added the alarm_store_event_ex5 API description in chapter 13 Alarm API Descriptions.
• Added section 14.9 The Alarm Extended Ex5 Function Test Menu.
Proprietary – See Copyright Page xiv

1. Introduction
The purpose of this chapter is to introduce you to the Alarm subsystem.
1.1 What Is Alarm?

The Alarm application provides a method of notifying operators, in real time, of events
occurring on their system. “Events” are changes to the system’s state that are detected by
application software.
An application that detects an event can use Alarm to bring the event to the operator’s
attention. An event is usually printed and archived by the Alarm application. It may be
processed as an alarm depending on the attributes modeled in the Alarm database and
attached to the event. An audible and/or visual indicator is used to report the alarm to the
operator. An alarm requires operator acknowledgment and/or deletion.
Each event is typically associated with a database object, such as a Scada (formerly
e-terrascada) point representing a circuit breaker, or a PROCMAN task. An event is posted
by the client application with a set of attributes. The Alarm application processes the event
according to these attributes and the modeling information stored in the Alarm database.
1.2 Overview
Figure 1 provides an overview of the functions that the Alarm application performs.
The Alarm application follows the traditional client-server model, where clients send
messages and requests to a server, which in turn processes them.
The duties of the Alarm application can be separated into two categories:
• Alarm clients notify Alarm of events occurring in the system. The Alarm API sends these
events to the Alarm server. Each event is processed based on the attributes specified
with the event and the information available in the Alarm database for the
object/exception definition related to the event. Processing of an event may result in an
alarm, which in turn may require a notification to the operator. The notification can
optionally include audible alarms and visual indicators. The notification is sent to some
number of users based upon their permissions as defined by the PERMIT application. In
addition to this notification, the Alarm server may insert each event in one or more logs
that are viewed using Browser (formerly e-terrabrowser) displays.
• Users can acknowledge and delete alarms using Browser. The acknowledgment request
may go directly to the Alarm server or it may be received by an application that uses the
Alarm API to perform the acknowledgment. Also, some clients (Scada, for instance)
require that they be informed of acknowledgment operations, since they may maintain
their own list of exceptions based on an abnormal and/or an unacknowledged state. In
this case, the notification of the acknowledgment is passed by the Alarm server to the
Alarm API in the client’s process.
Proprietary – See Copyright Page 1 Introduction

Alarm User’s Guide
Figure 1. Overview of Events Processing and Alarm Acknowledgment

1.3 Life Cycle of an Event
To illustrate how Alarm deals with events, Figure 2 shows the life cycle of a typical event
reported by an Alarm client.
Figure 2. Life Cycle of an Event
The following describes in detail each of the steps shown in Figure 2:

1. An Alarm client posts an event to the Alarm server.
2. Processing of the event leads the Alarm server to promote the event to an alarm. The
alarm is inserted in the list of alarms and in the logs.
3. The event is printed.
4. The alarm is associated with one or more tones, to provide an audible signal to the
operators.

5. The event is archived in a file.
Note: Steps 3, 4, and 5 happen at the same time and their order is not guaranteed.
6. An operator acknowledges the alarm.
Note: This step may occur right after step 5, or many hours later.
7. The Alarm server changes the state of the alarm from unacknowledged to
acknowledged. This entails moving the alarm from its unack. lists to its ack. lists.
8. The client application is notified that the alarm has been acknowledged.
9. The operator deletes the acknowledged alarm.
10. The alarm server removes the alarm from the alarm list.
The above steps can be applied to a vast majority of the events generated in a typical
Energy Management System (EMS). However, the Alarm application provides some options
to skip or automate some of these steps. To provide more clarity, this example does not
indicate any permission checks or any of the steps related to the replication of the events
on the standby machine.
1.4 Terminology
The following terminology is used in this document:
Event
A notable occurrence at a single place and point in time that is detected by the application
software and forwarded to the Alarm application.
Alarm
An indication (visual, or visual and audible) that an event has occurred. In the context of the
Alarm application, an alarm is an event that needs to be brought to the attention of at least
one operator. This is accomplished by inserting the event in the alarm list.
Client
An Alarm client that uses the Alarm API services provided by the Alarm server. Alarm clients
can be on any computer within the site.
User
A human user of the Alarm application. This includes integrators as well as operators.
Alarm Viewer
A Microsoft Windows application used for querying and viewing event data from Habitat’s
(formerly e-terrahabitat) Alarm application. The Alarm Viewer can run as a stand-alone
application or as a display within the Browser viewer.

Acknowledgment
The action taken by an operator to indicate that an alarm has been noted.
Database Object
Object records in Alarm represent generic database records used by the Alarm clients. It is
not required that Alarm objects match a record type in the client database, but it is highly
recommended for the sake of clarity. For example, Scada uses POINTS, ANALOGS, etc. The
Alarm application uses the attributes defined in the object definition (OBJDEF) record to
process an event.
Object Definition
The set of attributes attached to an Alarm database object. These attributes are used by
the Alarm server when processing events assigned to an object.
Exception
A database object that has changed to an abnormal or alarmable state. It remains an
exception as long as it is either in an abnormal state or has not been acknowledged.
Exception Definition
The set of attributes attached to an exception. The reference to the message displayed in
the lists and logs is modeled in the exception definition.
Related Alarms
Alarms that are issued under the same object definition and have the same object MRID or
composite ID. The object definition for an alarm is the parent record of the exception
definition with which the alarm is posted. The MRID or composite ID is a string value
assigned to the alarm via the Alarm API. The object definition modeling determines how
related alarms interact with one another. The related key is the object MRID, or the
composite ID if the MRID is not available.
Grouped Alarms
Alarms that have the same group identifier — a 64-bit integer assigned via the Alarm API
when the alarm is posted. This value is only persistent to the Alarm List database and is
used for filter alarms in Browser.
Category
A classification of alarms. Categories are used to group alarms that have similar attributes
for the purposes of convenient presentation and notification control. Each category is
assigned a priority.
Location
Locations are used to classify events geographically. In most Energy Management Systems,
locations are considered closely matching substations. Locations are used for display
presentation and notification control. The Alarm application supports alarm summary
information for each location.

Priority
Defines the grouping of alarms on some of the alarm lists. High-priority items are numbered
as 1. Low-priority items are numbered as 2 through 8, respectively.
Permission Area
A named set of permissions (READ, WRITE, EXECUTE, and AUDIBLE) associated with the user
by the PERMIT application. The name is often arbitrary (i.e., GURU) but it is used by Alarm
and PERMIT as the identifier. Every event/alarm issued by an application should be given a
permission area that is used by Alarm to query the PERMIT application and condition
displays and horns. A single alarm can have as many as five permission areas assigned to
it.
Alarm Synopsis Display
A specific Browser display that contains a combination of the following items: a location
line, a category line, the most recent event, the oldest unacknowledged alarms, and the
newest unacknowledged alarms.
Horn
A device capable of sounding one or more tones. In Browser, this refers to a Browser client
running on a particular PC.
Application
In Habitat, a related collection of databases (0 or more), displays, and programs called
“tasks”, with a unique name. An application may use savecases. Applications are defined in
files that are used by the Application Manager (APPMGR).
1.5 Alarm Health Timer

The Alarm process has an internal timer that writes the current time to a database record
every second. This timer is displayed on the Alarm Debug displays, and it can be used to
track that Alarm is running properly. If Alarm is not updating this time value, then Alarm is
either not running or is otherwise not functioning properly.

2. Alarm Server Event Processing
Most of the activity performed by the Alarm server is driven by incoming events and
acknowledgment requests. Alarm’s clients are application processes that communicate
with the Alarm server on the enabled host through the Alarm Application Programming
Interface (API), primarily to forward significant events that have been detected. These
events are processed by the Alarm server based on the attributes and data provided by the
client and the information contained in the Alarm database.
The objective of this chapter is to describe what the Alarm server does internally with
incoming events, how those events are promoted into alarms, and how Alarm maintains its
internal lists. Printing, archiving, and issuing tones are discussed in chapter 4 Printing and
Archiving and chapter 5 Sounding and Silencing Tones.
Figure 3 provides an overview of the processing performed by the Alarm server and the
information used for that processing.
Figure 3. Overview of Event Processing
Proprietary – See Copyright Page 7 Alarm Server Event Processing

2.1 Events vs. Alarms
Events are sent by clients to the Alarm server through the Alarm API. When receiving an
event from a client, the Alarm server first determines whether it is an unacknowledged
alarm based on the data supplied by the client and/or the information stored in the Alarm
database. This processing can be viewed as a three-phase operation:
1. Is the event an unacknowledged alarm or just an event?
2. If it is an alarm, should auto-acknowledgment be applied?
3. Is it reporting an abnormal state?
The following sections describe each of the three phases.
2.1.1 Unacknowledged Alarm or Log-Only Event?

An incoming event gets assigned one of the two following states:
• UNACK: The event is an unacknowledged alarm and it goes to the alarm lists and the
event logs, unless the client used the NOLOG option when it posted the event.
• LOG-ONLY: The event is not an alarm and it goes to the event logs.
The flowchart in Figure 4 describes the procedure used to determine the UNACK vs. LOG-
ONLY state. The decision is made based on the attributes of the exception definition
attached to the incoming event, and possibly on some of the options provided by the client
when the alarm_post_event or alarm_store_event functions are invoked.
Two attributes are used in the exception definition:
• Should the API’s option flags be used?
• If the API’s option flags are not used, should the event go to the lists?
If the API’s option flags should be used, two of them are relevant to the processing
described in the flowchart:
• ALARM_NOWUNACK: The event is an unacknowledged alarm.
• ALARM_NOLIST: The event should not be inserted in the alarm lists.

Figure 4. UNACK vs. LOG-ONLY State
2.1.2 Auto-Acknowledgment
If it has been decided that the event will go to the alarm lists, the Alarm server considers the
AUTOACK flag in the exception definition associated with the event. If the AUTOACK flag is
set, then the Alarm server performs an automatic acknowledgment of the new alarm. This
acknowledgment is done as if it were performed by an operator, except that there are no
permission checks. If the AUTODELETE flag in the exception definition is also set, the alarm
is automatically deleted as well. Related alarms are acknowledged if the MULTIPLE ACK flag
in the event’s object definition is set.
If automatic acknowledgment is triggered, the end result for the incoming event may vary.
Table 1 summarizes the options and their final result, assuming that the NOLOG option is
not specified by the client when posting the event. When the NOLOG option is used, the
processing is the same, except that the event never gets inserted into any formatted log.
Table 1. Event Processing Options

Default AUTOACK AUTODELETE AUTOACK
AUTODELETE
Use API’s if NOWUNACK if NOWUNACK if NOWUNACK if NOWUNACK
options unack alarm acked alarm unack alarm log only
else else else else
unack alarm log only log only log only

Default AUTOACK AUTODELETE AUTOACK
AUTODELETE
Do not use if not in list if not in list if not in list if not in list
API’s log only log only log only log only
options
else else else else
unack alarm acked alarm unack alarm log only
2.1.3 Abnormal State

In addition to the above processing, the Alarm server also determines whether the event
should be considered as abnormal.
The abnormal status is used only to set a field, required by Browser displays, to set the color
of the time field. Abnormal events are displayed with a red time field; normal events are
displayed with a black time field.
Depending on the modeling of the exception definition, the ABNORMAL flag is passed by the
client when it posts the event, or it is specified at the exception definition level.
2.2 Formatting
Before being inserted into alarm lists or event logs, an event must be formatted — that is,
the data provided for the event by the client must be presented in a readable text format.
This text includes a description of the alarm and when the alarm occurred.
2.2.1 The Time Format

The Alarm server receives each event with a TIMEDATE time stamp. This time value is
formatted for display purposes based on the format defined in the Alarm database in the
DISTIFMT_ITEMS global field. This time format should be defined from the
ALARM_MODEL_MISCELLANEOUS display, using the TIMEDATE tokens, since the formatting
is done by calling the TIMEDATE_FORMAT_HABTIME function. If the database field is not
filled in, the “%c” format is used.
Note: To show the duplicated hour indicator (*) on the alarm lists and logs displays during
the change from Daylight Saving Time to Standard Time, the field DISTIFMT_ITEMS must
be configured with “%#R” at the end of the format. The modification of this field can only
be done with HdbRIO.

Note: In the time format for archive files, the DISTIFMT_ITEMS field is used only to format
the time on the Alarm displays. It is not used to format the time in the archive files; the
ARCTIFMT_ITEMS field is provided for that purpose1.
2.2.2 The Text Format

The text format for an event is specified in an Alarm message file2 (.ALMMSG)3 for every
exception defined in the Alarm database. The Alarm server uses the information specified in
the exception definition record to locate the formatting specification as follows:
• The set name
• The message name
If the set cannot be found, the Alarm server uses its default set (ALMPRIVATE.ALMMSG) and
formats the event using a default message defined in the default set. A message is logged
in the Alarm Log that indicates the missing set.
If the Alarm server cannot find its default set, an installation problem is indicated and the
server aborts.
If the message name cannot be found, the default message in the Alarm default set is used
and a message is logged in the Alarm Log.
Note that the formatting of an event may result in a multi-line message. If the event is an
alarm, only the first line of the message is visible in the alarm list. However, the entire
message is written in the event log(s).
2.3 Long-Name and MRID Support

The post and store event APIs support the following:
• Posting alarms that may contain long names substituted into the alarm text.
• Inserting the MRID and the full composite key of the object that is alarmed into the
alarm record.
1
Alarm can support the e-terrahabitat 5.2 alarm archive output format. The ARCTIFMT field is only used if
ALARM is configured to use this older format. This older format is not compatible with Alarm Viewer and is not
recommended for use. This format will not be available in future releases.
2
For more information regarding the syntax used to define Alarm messages, see the Message Logging Facility
User’s Guide.
3
For more information regarding the LINK command, refer to the Habitat User’s Guide.

2.3.1 Supported Types
Along with the APIs, some types are defined to serve as fields in the Alarm event block
structure to support these functions. Note that these types require C++ and the Standard
Template Library (STL).
/*
** AlarmMrid - MRID of the object that is alarmed
** The MRID is assumed to be a string representation of a UUID.
*/
typedef std::string AlarmMrid;
/*
** AlarmMridList - an ordered list of MRIDs. Each MRID is
** represented by a string object. The MRID itself is
** assumed to be a string representation of a UUID.
*/
typedef std::vector<AlarmMrid> AlarmMridList;
/*
** AlarmLongNameList - an ordered list of Long Names
*/
typedef std::vector<std::string> AlarmLongNameList;
/*
** AlarmCompositeKey - a structure to store the composite key
** of a power system object.
**
** The domain field identifies the domain in IMS (Identifier Mapping Service)
** where the composite_key field is defined.
**
** The composite_key field is the composite key string stored in IMS.
*/
struct AlarmCompositeKey
{
std::string domain; // IMS Domain
std::string composite_key; // IMS Alias
};
/*
** AlarmCompositeKeyList - an ordered list of AlarmCompositeKey's
*/
typedef std::vector<AlarmCompositeKey> AlarmCompositeKeyList;
2.3.2 Alarm Event Block

For example, the alarm_post_event_ex3 and alarm_store_event_ex3 functions take an
ALARM_EVENT_BLOCK_EX3 argument. This event block is essentially the same as
ALARM_EVENT_BLOCK_EX2, but with the addition of five fields.
Three fields support long names in alarm text:
• long_name_list

• mrid_list
• composite_key_list
Two fields support REPLAY, ETNAV, and Historian (formerly e-terraarchive):
• object_mrid: The Alarm client specifies the MRID of the object that is alarmed.
• object_comp_key: Contains the full composite key and the domain of the object that is
alarmed. If the domain is not specified, ALARM defaults to the domain specified at the
application level in the ALARM database.
The “object_mrid” and “object_comp_key” fields are used in the following areas:
• As the object_mrid in the CIRCLG record of ALARM for sampling in Historian to manage
the preservation of historical values, in case the composite key or long name is
renamed.
• As the object_mrid for REPLAY to identify the ALARM object across sites, since the power
system model can be different on the active versus the passive site.
• As the full composite key to support ETNAV. External services that invoke the Alarm web
service may not be able to pass a composite key, but users still need to be able to go to
a related display using ETNAV. If the Alarm web service passes the object_mrid, the
Alarm server looks up the composite key in Identifier Mapping Service (IMS) and updates
the composite key field in the alarm/logs records.
/*
** This extended structure was introduced with HABITAT 5.9
*/
struct ALARM_EVENT_BLOCK_EX3
{
. . .
/*
** Support for Replay, ETNAV, Historian
** ------------------------------------------
** The Alarm API client needs to provide the alarm object MRID and/or the
** alarm object full composite key.
** If only the full composite key is provided, the Alarm server will look
** up in IMS for the MRID.
** If only the MRID is provided, the Alarm server will look up in
** IMS for the full composite key
*/
AlarmMrid object_mrid;
AlarmCompositeKey object_comp_key;
/*
** Alarm Long Name support
** -----------------------
** The Alarm API client can choose one of the three options:
** (1) a long_name_list, or
** (2) a mrid_list, or

** (3) a composite_key_list
**
** The API's precedence of resolving the long name is:
** if (1) exists, use long_name_list directly in the alarm message
** else if (2) exists, use mrid_list and ask IMS to translate MRIDs to
** LongNames
** else if (3) exists, use composite_key_list and ask IMS to translate
** CompKeys to LongNames else no long name translation.
*/
AlarmLongNameList long_name_list;
AlarmMridList mrid_list;
AlarmCompositeKeyList composite_key_list;
};
2.3.3 Processing New Alarm Event Block Fields
2.3.3.1 Long Name Look Up

For long names, the Alarm client application can choose to supply one out of these three
members: long_name_list, mrid_list, or composite_key_list.
If the Alarm client supplies long_name_list, Alarm uses the supplied strings without
translation.
If the Alarm client supplies mrid_list, Alarm consults the IMS to translate each MRID in the
list to its corresponding long names.
If the Alarm client supplies the composite_key_list, Alarm looks up the MRID for each
composite key in the list that consists of a “domain” and a “composite key” from IMS. Then
Alarm translates the MRID to its corresponding long name. The IMS is assumed to be
populated with composite keys and their domains from data originating from Source
(formerly e-terrasource). When the Alarm client supplies composite keys for long name
parameters, the composite key/domain pair must match exactly with what is in IMS;
otherwise the long name lookup fails.
2.3.3.2 Errors Reported if the Long Name Lookup Fails

If looking up a long name fails, ALARM logs an error message into its Habitat log and
indicates the information that was used for the lookup, such as the composite key.
ALARM creates the alarm within the alarm text with the most possible information about
the missing ID.

2.3.3.3 Processing the object_mrid Field
The “object_mrid” field represents the MRID of the object that is alarmed. This field is
provided by the Alarm client when calling the post API, and is passed by the Alarm API to
the Alarm server. ALARM stores the object_mrid in the ALARMLST database in the following
records: ALMQ, CIRCLG, LOG2, LOG3, SCLOG, SYSACT, and ACKLOG.
If the object_mrid is not passed by the Alarm client, ALARM tries to look for it in IMS using
the full composite key and domain name. If the object_mrid cannot be found, the
object_mrid field remains blank in the ALARMLST database.
2.3.3.4 Getting the Full Composite Key of the Object

ETNAV uses the composite key of the object that is alarmed to navigate to other displays
where this object is visualized.
If the full composite key is not provided by the Alarm client when posting an alarm, the
Alarm server queries the IMS to get the composite key from the object MRID.
Alarm saves the full composite key in the following records: ALMQ, CIRCLG, LOG2, LOG3,
SCLOG, SYSACT, and ACKLOG.
2.3.4 Changing the .ALMMSG File for Long Name Support
2.3.4.1 New Tokens

The Alarm client applications update the alarm definition for alarms that need to use long
names.
For example, assume you have the following alarm message (with the DOCUMENTATION
part removed):
MSG s021 SEVERITY info
ALIAS siteid = char1[1:8]
ALIAS almtxtsite = char1[9:38]
BEGIN
LINE "SITE %<siteid>s %<almtxtsite>s INTERSITE DATA PATH FAILED"
...
END_MSG
If you want to replace the “siteid” and “almtxtsite” arguments with long names, edit the
alarm message to look similar to the following:
BEGIN
LINELN "SITE %%LN1%% %%CLN2%% INTERSITE DATA PATH FAILED"

The proxy string uses “%%” to allow the AEM compiler to escape the double “%%” into a
single “%” in the generated text.
The .almmsg file supports one line (“LINE” or “LINELN” format) or two lines (“LINE” and
“LINELN”) for defining a given alarm.
2.3.4.2 Ability to Compress a Long Name

Compression is configurable at the token level.
On the line “LINELN”, using the token “CLNx” causes the long name to be truncated,
meaning that spaces before and after the actual long name are removed. When using the
token “LNx”, the long name is not truncated.
For the definition of alarm “s021” in the following example, the long name in place of “LN1”
is not truncated. However, the long name in place of “CLN2” is truncated.
BEGIN
LINELN "SITE %%LN1%% %%CLN2%% INTERSITE DATA PATH FAILED"
2.3.4.3 Processing a Long Name Longer Than 40 Characters

The “LNx” token is always replaced by a 40-character string that is "fixed in width". If the
provided long name is shorter, it is filled with spaces up to 40 characters. If the long name is
longer than 40 characters, it is truncated. In either case, the line length is truncated to 160
characters after the alarm text is formatted.
2.4 The LINK Command

The buildlst command is used to regenerate all or some of the Habitat executables, but it is
also used when some .ALMMSG files have been updated and the changes should be picked
up by the Alarm server.
After modifying an .ALMMSG file and rebuilding the codeset, the following Habitat link
command must be used to make these changes visible to the Alarm server.
To link the shared message file, use the buildlst command:
buildlst -almmsg
This command forces the creation of a new shared image (DLL in Windows) that is used by
the Alarm server to format alarms and events. Once the command has been executed, the
Alarm server needs to be restarted.

2.5 The Alarm Lists
Habitat provides a variety of ways to view events and alarms.
2.5.1 The Alarm Synopsis List

To provide a summary of the unacknowledged alarms under the responsibility of each
operator, the Browser server maintains a special list for every logged-on user: the Alarm
Synopsis list. This list is used to build several versions of the Synopsis display, which are
usually displayed on every client within their own viewport.
The Synopsis list contains five different types of sublists:
• The categories that contain unacknowledged alarms visible to the user
The Synopsis list can contain up to eight different categories. If all the unacknowledged
categories cannot be inserted in the Synopsis list, a More pseudo-category can
optionally be added to indicate that there are more unacknowledged categories than
those displayed in the Synopsis list. Categories in the list are ordered based on their
severity, with the most severe (lowest number) being placed first. The text displaying the
category name matches the color settings for that category.
• The locations that contain unacknowledged alarms visible to the user
The Synopsis list can contain up to eight different locations. If all the unacknowledged
locations cannot be inserted in the Synopsis list, a More pseudo-location can optionally
be added to indicate that there are more unacknowledged locations. Locations in the
list are ordered based on their severity, with the most severe (lowest number) being
placed first. The severity of a location is determined by the highest severity of the
categories of the alarms within that location. The text displaying the location name is
colored to match the most recent highest-priority alarm’s category color setting.
• The latest formatted events
The Synopsis list can contain up to three of the latest formatted events that the client
can see.
• The oldest unacknowledged alarms
The Synopsis list can contain up to three of the oldest formatted alarms that the client
can see.
• The newest unacknowledged alarms
The Synopsis list can contain up to three of the newest formatted alarms that the client
can see.
2.5.2 Browser Alarm Displays

There is a set of displays that use the Browser index interface: alarm_dset.ddl and
alarm_eset.ddl.

These displays are driven by the Browser server and not by an internal alarm list.
When Alarm receives an event, Alarm notifies the Browser server that an event has been
added to the Alarm List database. The Browser server then updates its index based on the
new event data. The Alarm server also notifies the Browser server when an
acknowledgment or deletion occurs. These displays are required to accurately display
partial acknowledgment and deletion states on a per-user basis. This display allows a single
alarm to appear acknowledged for one user and unacknowledged for another user.
Figure 5. Alarm and Browser Interaction
2.6 The Formatted Logs

Formatted logs are tabular displays consisting of one or more lines per event, arranged
chronologically. All events posted by Alarm’s client are posted to the event log(s) according
to the following rules:
• If the exception associated with the event owns one or more override logs (OVLOG
records), the event is inserted in the formatted log specified by the OVLOG records.

• If the exception associated with the event does not have an override log, the default
logs specified at the application level (DEFLOG records) are used.
All events are inserted in one or more formatted logs, unless one of the following conditions
is encountered:
• The client used the ALARM_NOLOG option when it posted the event.
• The application defined in Alarm does not have a default log, and the exception
associated with the event does not have an override log.
By default, the Alarm application contains five formatted logs:
• The System Activity Log (SYSACT records)
• The Scada event log (SCLOG records)
This log is used for logging all Scada operator actions.
• The Acknowledgment Activity Log (ACKLOG records)
This log is used for logging acknowledgment and deletion of alarms by default, but it
could be used for any event.
• LOG2 (for user-defined purposes)
• LOG3 (for user-defined purposes)
2.6.1 The Timesearch Formatted Logs

The Alarm Viewer is used to search the formatted logs by time. The timesearch formatted
logs allow an operator to position quickly to a certain point in time in any of the five
formatted logs described above.
2.6.2 The Circular Formatted Log

All new events are inserted in the circular formatted log (CIRCLG record). This log is
designed to be used by the HABConnect Sampler and the Relational Database Recorder
(RDR) to store events in an Oracle database. Events that have been formatted on multiple
lines are inserted in a minimum number of CIRCLG records by concatenating the lines
together.
There is no display attached to this log.
2.7 Event Replication

The Alarm server runs on both the primary and the standby machines.
Once an event has been processed on the primary machine (where the enabled Alarm
server is running), the event must be replicated on the standby machine (where the standby

Alarm server is running). Replication services are provided by the Memory Replication
Services (MRS) subsystem.
The MRS task reads data on the enabled computer to pass it to the MRS task on the standby
computer.
The replication of Alarm events is relatively complex, as represented in Figure 6, which
illustrates the interactions between Alarm and MRS.
Figure 6. Alarm and MRS Interaction
Replication of the events can be done in two different ways:

• By default, the event gets sent to the Alarm server running on the primary machine,
which in turn sends it to the Alarm server running on the standby, using MRS.

• If the client requests to use MRS from the Alarm API, the events that are posted by the
client are sent to the primary Alarm server and passed to MRS from within a transaction
executed by the Alarm client. When a client chooses this option, it is assured that the
database update and the event associated with this update are replicated on the
standby machine at the same time. This functionality is used, for example, by Scada
tasks to guarantee consistency between points and analog changes, and the alarms
associated with these changes.
Note: In both cases, the replication of the events is not truly done by the MRS subsystem.
MRS and Alarm cooperate to perform some message tunneling, so that the server on the
standby can update its database and stay in synch with the primary.
The recovery of the Alarm database is performed by the MRS subsystem. The ALARMLST
database is entirely recovered once the appset on the standby machine transitions to the
standby role.
At first glance, you would think that the Alarm server on the primary should not need to
replicate events for clients that are using MRS, since these events should be replicated
through a transaction done from within the client’s process. However, there is a potential
timing problem with this approach if the following situation occurs:
1. The Scanner process, which is an Alarm client that uses MRS, posts an event. This event
synchronously gets to the MRS task, which discards it because at this time the Alarm
recovery set status is invalid.
2. The Alarm server on the primary also gets this event but is slow to process it. As a result,
the event sits in a queue and the database update is not done.
3. The MRS task initiates a recovery of the ALARMLST database and takes a snapshot
before the Alarm server processes the Scanner event.
4. Eventually, Alarm gets around to processing the Scanner event. Alarm believes that the
event has already been replicated, when in fact it has not.
To prevent this situation from happening, the Alarm server on the primary always replicates
the events it is processing, even if these events have already been replicated from within
the client’s context. Some intelligence has been added to the MRS task so that it does not
send the same replication message to the MRS task on the other node more than once.
2.8 When the Alarm List Is Full

By default, alarm lists are sized to contain up to 10,000 alarms. This number can be
increased by changing the database dimensions. It is unlikely that operators would run a
system with as many as 10,000 alarms, but in a Grid Simulation (formerly e-terrasimulator)
environment or during testing, the alarm lists may become full. When this happens, the
Alarm server must make room by applying the following logic:
• If there are some acknowledged alarms, the oldest ones with the lowest priority are
deleted to make room.

• If all Alarms in the lists are unacknowledged, the oldest ones with the lowest priority are
acknowledged and deleted.
For performance reasons, Alarm does not recycle the Alarms one by one, but frees a certain
percentage of the size of the alarm list. This percentage can be specified on the
ALARM_MODEL_MISCELLANEOUS display.
With the above logic, you must keep in mind that alarms of the lowest priority may not stay
in the list very long when the list is full, or if there are very few alarms with that priority. For
example, consider a situation where the alarm list is almost full with priority 7 (or higher)
alarms. If a client issues a group of priority 8 alarms, the following happens:
1. The first alarms are inserted in priority 8 until the list gets full.
2. The next alarm triggers the cleaning operation and causes the first alarms (priority 8) to
be recycled. If the batch of alarms was issued in a very short time (i.e., one second), it is
possible that some alarms will never be seen by the operators.
Keep in mind that the above scenario occurs only if the alarm list is allowed to become full.
In addition, all the recycled messages remain in the formatted logs.
2.9 Improving Alarm Performance During a Storm

While you are conducting performance tests that simulate a large number of alarms sent
per minute, a delay may be seen between the time an alarm is sent and the time it appears
in the alarm list. This delay appears on the enabled server on the primary site, when the
alarm list gets full and Alarm needs to make space for new alarms. However, the alarm lists
on the standby server and on the emergency backup site server(s) are up to date.
To eliminate the delay on the primary site, you can decrease the maximum number of
actions (acknowledgment, delete) sent all at once by Alarm to the MRS API. This maximum
value is kept in the ALARM database, in the AXPERTXN field under the ITEMS record. If set
to 0, a default value of 500 is used.
2.10 Summary of Permission Checks

During the processing of each event, the Alarm server uses the PERMIT API to check
permissions for the area attached to the event. The event has permission if at least one of
the assigned areas has permission. These permission checks are performed as follows:
• The READ permission for the PERMIT areas attached to the event is checked based on
the current user. If a user does not have READ permission for any of the areas, the alarm
is not inserted into the Synopsis list for that client and it does not contribute to the list of
categories and locations for that client.
• If it has been determined that a tone should be sounded, the AUDIBLE permissions for
all areas assigned to the alarm are sent to the Browser client along with the tone, and
the client determines if the user can play the tone.

Note: Permission checks are also performed by Browser on the displays showing the list
of alarms as well as on the formatted log displays.
Note: The EXECUTE permission is not used. To acknowledge or delete an alarm, the user
must have the WRITE permission for the area attached to the alarm.
2.11 Operating Procedure

The basic functionality attached to an operating procedure is for Alarm to allow
applications to attach a document when posting an event.
During the processing of each event, the operating procedure is performed as follows:
• If the event has no document reference and its exception definition has no document
reference either, there is nothing to do.
• If the event has no document reference and its exception definition does have a
document reference, the event references the DOC record containing the URL defined in
the exception definition.
• If the event has a document reference, a lookup is done in the DOC records to find
whether that reference already exists. If this URL does not exist yet, a new record is
inserted, and the event is then persisted with a pointer to the DOC record.

3. Acknowledging and Deleting
Acknowledgment is the action taken by an operator to indicate that an event has been
noted. When Alarm receives an acknowledgment request, it updates the alarm lists to move
the alarm from the unacknowledged state to the acknowledged state. An acknowledgment
can be done by any application that uses the API or by any operator who has the required
permissions.
Deletion (or purging) is the action taken by an operator to indicate the removal of the
acknowledged alarm left in the acknowledged section of the lists. Acknowledged alarms
must be deleted to create space for other alarms.
When an alarm has more than one permission area assigned to it, acknowledgment or
deletion by a particular operator causes the alarm to be considered acknowledged or
deleted only for those areas for which the operator has permission. In these circumstances,
the alarm is considered partially acknowledged or deleted. Only when an alarm has been
acknowledged or deleted by one or more operators representing all permission areas
assigned to it does the alarm move to the fully acknowledged or deleted state.
When multiple areas are assigned to an alarm, only indexed Browser displays specifically
designed to handle multiple areas should be used. For the Browser server to keep track of
alarm data, an index needs to be set in the Browser server database.
3.1 Alarm Acknowledgment

There are several different ways that an individual alarm can be acknowledged:
• All the Alarm displays showing alarms allow operators to acknowledge alarms one by
one or to acknowledge an entire selection, assuming they have the required
permissions to do so. The operator action to acknowledge alarms is allowed only from
displays connected to the primary machine.
• An alarm can be acknowledged as a result of another alarm being acknowledged. This
occurs if the multiple ack attribute has been set in the object definition record.
• A set of unacknowledged alarms can be selected individually or using the
RUBBERBAND/SELECT method, and acknowledged all at once using the MULTIACK
RUSER/MAIL command.
• Selecting a category from the Synopsis display can cause all the alarms in the category
to be acknowledged, if the attribute When selected, acknowledged is set for that
category.
• Alarm’s clients can provide their own displays, allowing operator actions that lead to a
call to the ALARM_ACK or ALARM_FLUSH_ACKNOWLEDGMENT API functions.
Note: The API functions can be called from any computer within the local site, since
the Alarm API forwards the requests to the enabled server. This makes it possible to
acknowledge alarms from any computer.
Proprietary – See Copyright Page 24 Acknowledging and Deleting

• Clients that acknowledge alarms cannot send RUSER mail commands directly to Alarm
to do so. The clients must determine the alarms they wish to acknowledge and then use
the Alarm API to acknowledge those alarms.
• If the alarm list is full of unacknowledged alarms and an incoming event must be
inserted in the list, the Alarm server acknowledges and deletes the oldest alarm with the
lowest priority to make room for the new alarm.
• If the AUTOACK option is set on an exception definition, any incoming Alarm using such
an exception is acknowledged as if by an operator, but without any permission checks.
If the object definition for that exception has been modeled with the Multiple Ack flag,
then all related alarms attached to the same instance of the object are acknowledged.
In all cases, the acknowledgment of an alarm causes the following to happen:
• If the alarm’s exception definition has the auto-delete attribute, it is removed from the
alarm list. Otherwise, it is moved from the unacknowledged state to the acknowledged
state, but it remains in the alarm lists.
• If the object associated with the alarm has no more unacknowledged alarms,
notifications are sent to the clients that have called the enum_unack_objects API
functions. These notifications allow applications such as Scada to maintain their
exception lists.
• The Alarm database can be modeled so that all acknowledgments are logged in a user-
specified formatted log.
An alarm that has multiple areas assigned to it can be partially acknowledged for a
subset of the assigned areas.
• When an alarm is acknowledged by a user who does not have write permission for all of
the assigned areas, the alarm is said to be partially acknowledged.
• If a user partially acknowledges the alarm for the areas that user has read permissions
for, the alarm appears fully acknowledged to that user.
• As long as the user has read permissions for an area that is unacknowledged, the alarm
appears as unacknowledged.
• In the case of auto-ack and overlay/ack, the alarm is acknowledged for all assigned
areas.
• In the case of sympathetic auto-ack, the alarm is acknowledged only for the areas that
the previous related alarm has been acknowledged for.
• In the case of multiple ack, all of the related alarms are partially acknowledged for the
areas assigned to that user.
• In the case of auto-delete, the alarm is partially deleted for the areas assigned to that
user.
Note: Acknowledging alarms does not cause any tones to be silenced.

Figure 7 illustrates the interactions among Browser, the Alarm server, and the Alarm
server’s clients.
Figure 7. Alarm Acknowledgment
3.1.1 Acknowledgment Notifications

Alarm provides a callback that notifies Alarm clients when any alarms on their objects
become acknowledged. This callback delivery is optional; it is provided to allow a client to
update its database if it maintains an UNACK flag on alarmable objects. For example, Scada
relies on this callback to update its exception list. Alarm is not responsible for updating this
field in the client’s database.
By default, Alarm assumes that clients do not need to maintain an unacknowledged state in
their database and the callbacks are not delivered. Clients can invoke the
ENUM_UNACK_OBJECTS API function to get the current states of their objects and receive
subsequent updates.
When an unacknowledged alarm is attached to an object instance that currently has no
unacknowledged alarms, the client owning the object is notified through a callback —
assuming it previously invoked the enum_unack_objects API call for the object.
It is the responsibility of the client to provide a unique numeric identifier for object instances
when it issues an event. The Alarm server keeps this identifier and uses it when dispatching
the acknowledgment callback. This identifier should be designed such that, if insertions or

deletions4 of some object instances are performed, the identifier does not change. For
example, in the case of Scada, the identifier should be the SCAPI key rather than the
subscript.
3.1.2 Logging of Acknowledgments

The Alarm server can be modeled so that it logs all operator acknowledgments. This feature
is optional; some customers may not desire the extra entries it generates in the log. To
uniquely identify the alarm being acknowledged, every event is assigned a sequence
number when it is received by the Alarm process.
If alarm acknowledgment logging is enabled, the server performs the following processing:
• All acknowledgment notifications go to the formatted log identified in the Alarm
database.
• The acknowledgment notification identifies the originating computer name and user
name of the operator who performed the action.
• When related alarms on an object are acknowledged as the result of an operator
acknowledging a single alarm, all the alarm acknowledgments are logged.
• When an application acknowledges an alarm through the API, it passes the user
information to the Alarm server. This information is recorded in the acknowledgment
log.
• If an unacknowledged alarm is removed from the alarm list because the lists are full, the
acknowledgment is also logged in the acknowledgment log.
By default, all acknowledgment actions are recorded in a formatted log called the
“Acknowledgment Activity Log”, but another formatted log could be specified by using the
3.2 Alarm Deletion

Alarms are initially stored in the alarm lists in the unacknowledged state. It is then assumed
that either operators acknowledge alarms, or the system state evolves so that things return
to normal, which causes the Alarm server to move alarms to the acknowledged sections of
the alarm lists (except when auto-deletion occurs). Once in the acknowledged sections,
these alarms are candidates for deletion to create space for future alarms.
Alarms are deleted under the following circumstances:
• Deleting alarms can be done from the alarm list displays. It cannot be done from an
application display, since the application has no way to notify the Alarm server.
4
If a new database is brought online and some records have been deleted, users should also consider that
they may receive an acknowledgment notification on an object that is no longer in their database.

Operators can delete alarms one by one, or they can delete all the alarms that can be
selected in their viewport.
• A set of acknowledged alarms can be selected individually or using the CTRL key to
select multiple alarms so they can be purged all at once using the MULTIPURGE
RUSER/MAIL command.
• If an alarm is acknowledged and its associated exception specifies automatic deletion,
the alarm is removed from the lists and is not inserted in the list of acknowledged
alarms.
• Automatic deletion occurs when the alarm lists are full. The oldest acknowledged
alarms with the lowest priority are deleted by the Alarm server when room is needed to
insert new alarms. If all alarms are unacknowledged, then the oldest ones are
acknowledged and deleted.
• Prevent Abnormal Alarm Deletion: If this option is set on the Category record for an
abnormal alarm, the alarm cannot be deleted. This should be used to prevent accidental
deletion of alarms that are considered serious.
• Force Purge: The force purge and force page purge RUSER commands are provided in
case Prevent Abnormal Alarm Deletion is preventing an alarm from being deleted and it
is necessary to purge the alarm. These commands are similar to the other acknowledge
and purge RUSER commands. The FORCEPURGE and FORCEPAGEPURGE commands
disregard the delete restriction set by the category of the alarm. FORCEPURGE works for
a single alarm and FORCEPAGEPURGE works for multiple alarms.
An alarm that has multiple areas assigned to it can be partially deleted for a subset of
the assigned areas.
• When an alarm is deleted by a user who does not have write permission for all of the
assigned areas, the alarm is said to be partially deleted.
• If the user partially deletes the alarm for the areas that the user has read permissions
for, the alarm appears fully deleted to that user.
• As long as the user has read permissions for an area that is acknowledged, the alarm
appears as acknowledged.
• In the case of automatic deletion and overlay/delete, the alarm is deleted for all
assigned areas.
• In the case of multiple delete, all of the related alarms are partially deleted for the areas
assigned to that user.
• Non-Deletable Selected: If this option is set from the right-click menu of an alarm, the
alarm cannot be deleted until Non-Deletable Cleared is set.

3.2.1 Logging of Deletions
The Alarm database can be modeled so that deletions of alarms are logged in a default or a
user-specified formatted log.
If logging of deletions is enabled:
• All types of deletions are logged (operator action, auto-delete, and automatic deletion
when the alarm lists are full).
• The deletion notification identifies the originating computer name and the user name of
the operator who performed the action.
• All deletion notifications go to the same formatted log.
By default, all deletions are recorded in the Acknowledgment Activity Log. From the
ALARM_MODEL_MISCELLANEOUS display, the user can specify a different formatted log.
3.2.2 Acknowledgment and Deletion Performance

When a single alarm is acknowledged or deleted, and the object for the alarm has the
multiple acknowledge or multiple delete setting on, the alarm acknowledges or deletes all
the related alarms.
3.2.2.1 Relating Unrelated Alarms

The multiple acknowledge and multiple delete settings affect only alarms that have the
same MRID or composite ID as the original. To avoid relating alarms that are in fact
unrelated, this MRID or composite ID must be set when the alarm is issued. If this value is
not specified, then the value is set to 0 and all alarms under the object posted without an
MRID or a composite ID are related.
It is possible to have many alarms that are correctly related. Under these circumstances,
Alarm requires some additional time to acknowledge or delete all the related alarms.
However, when trying to locate the alarm to acknowledge in the related alarm list, a
performance problem is encountered. For example, when all alarms are related, one large
alarm list is generated. If the alarms were posted with correct (that is, different) MRID or
composite ID values, each value would have its own list. Having smaller lists to search
greatly increases Alarm’s performance.
3.2.3 Multiple Permission Areas

This is related to section 3.2.2.1 Relating Unrelated Alarms with respect to related alarms,
with the addition of multiple permission areas. This example uses the category
acknowledgment functionality.

When a category acknowledgment is performed, the following occurs:
• When an operator acknowledges an alarm, Alarm acknowledges each alarm under the
category, for all the areas for which the operator has permissions.
If this results in the alarm being partially rather than fully acknowledged and if the
object for the alarm has multiple acknowledgments set, then each of the related alarms
under this object is also partially acknowledged.
• When the second alarm in the category is acknowledged by the category
acknowledgment, Alarm again attempts to acknowledge the first alarm, since it and all
related alarms have not been fully acknowledged.
This is a problem of polynomial complexity — a function of the number of unacknowledged
alarms in the category times the number of unacknowledged alarms in the object.
3.3 Permissions
When posting events, clients can assign as many as five permission keys (i.e., PERMIT areas)
to the event, which are used by the Browser server to restrict the display of alarms based
on the permissions assigned to each user as defined by the PERMIT application.
Acknowledgment and deletion operations are subject to permission checks. For an operator
to acknowledge or delete an alarm, that operator needs to have the WRITE permission for
one or more of the permission keys assigned to that alarm. If a permission check fails, the
operator is notified through an RUSER pop-up message.
Note: The EXECUTE permission is not used by the Alarm server.
Permissions attached to a user can be changed by operators “on the fly” in the PERMIT
application. Alarm periodically checks the PERMIT database and rebuilds its lists when it
detects a change in the PERMIT database. Using the ALARM_MODEL_MISCELLANEOUS
display, the user can specify how often the PERMIT database should be checked.
3.4 Inhibiting Alarms

The alarm from a Scada point or analog can be inhibited directly from the Alarm display.
• The Alarm display allows operators to inhibit alarms for the associated Scada point or
analog one by one, or to inhibit an entire selection, assuming they have the required
permissions to do so. The operator action to inhibit alarms is allowed only from displays
that are connected to the primary machine.
• When an operator inhibits an alarm, the alarm is acknowledged first, and then the
associated Scada point or analog is inhibited.

4. Printing and Archiving
The purpose of this chapter is to describe the two archiving methods supported by the
Alarm application:
• Printing: Printers can be used as an archiving mechanism for all events and alarms
issued, 24 hours a day.
• File archiving: Alarm can also record all events and alarms in flat files (ASCII files) for
later review and analysis. An archive format is also available that generates files that
can be read by the Alarm Viewer application.
4.1 Printing Events

The Alarm server establishes an interface with the Logman application and provides the
ability to send events to Logman queues. The Logman application then prints the events on
one of the printers assigned to the queue. Each queue is assigned a set of permission areas
that filter which events are printed. These Logman queues and permission filters are
specified in the Alarm database.
If printing slows down or stops due to printer problems, back pressure is not applied to the
Alarm server. In other words, the Alarm server can continue processing events even if they
cannot be printed.
Note: Alarm printouts can be lost if all printers assigned to a queue have failed and the
Logman buffers are full.
When the connection with the Logman server is lost and then re-established, the Alarm
server reprints the events of the last n seconds, as specified in the REPRDELT global field.
4.2 Archiving Events

The Alarm server provides the ability to record all events in ASCII text files in a readable
format. These files can be stored for later review, or simple tools can be developed to parse
them — for example, to import their contents into a third-party database. Events in the file
are stored in ascending order, meaning that the most recent events are at the end of the
file.
This archiving of events can be turned on or off using the MISCELLANEOUS ITEMS view of
the Alarm Definition display.
There are two formatting options available for the archive files: the standard format and
the full format.
• The standard format stores all the necessary data for the Alarm Viewer application to
read and display the alarm data. When this option is selected, many of the modeling
options are no longer available to guarantee accurate and complete data in the file.
Proprietary – See Copyright Page 31 Printing and Archiving

• The full (All Data) format adds all of the data for the archived event to the archive file.
If the archiving function is turned on, the following items should be specified to control the
creation of archiving files:
• Archive file naming
• Archive file scheduling
• Miscellaneous archive settings
4.2.1 Archive File Naming

The full archive file name must be specified, meaning that a directory specification should
be used. The file name can be built using tokens that are translated when the file is created
(or when it is closed, if using the %ENDTIME% token). The following tokens are available:
• %NODE%: This token is translated into the name of the computer where the enabled
Alarm server is running.
• %FAM%: This token is translated into the HABITAT family of the Alarm clone.
• %GRP%: This token is translated into the HABITAT group number.
• %STARTTIME%: This token is translated into a date + time string matching the exact
time the file was opened.
• %ENDTIME%: This token is translated into a date + time string matching the exact time
the file was closed.
4.2.2 Archive File Scheduling

The archive files cannot grow indefinitely; they need to be closed periodically and new files
opened. Therefore, system integrators should specify in the Alarm database how long an
archive file is to be used. The following sections describe the periodic, daily, weekly, and
monthly scheduling options available to the integrator.
Caution: When using the Alarm Viewer to parse the archive files, the Periodic setting
should be used to keep the size of the archive files small. Using the Daily, Weekly, or
Monthly schedule may produce very large archive files, and the Alarm Viewer is required
to download the entire file even if only part of the file is required.
Integrators need to set the “Base time for opening a new archive file” for whichever option
is chosen. The “Base time for opening a new archive file” is used to compute when the first
archive file should be closed and a new file should be opened. At startup (or after a failover),
the enabled Alarm server creates an archive file and schedules the opening of a new one. It
uses the base time and the period specified for how long the same file should be used as
follows:
closing_time = base_time + n*period

where n is the smallest possible integer that puts closing_time in the future.
4.2.2.1 Periodic Scheduling

This schedule is based on the number of minutes an archive file is used. It is the number of
minutes an archive file is open before a new file is created or specified.
For example, with a base time of January 1, 2004, 12:00, and a 60-minute period, if the
Alarm server starts today at 9:25, the first archiving file is closed at 10:00, the second at
11:00, etc.
Note: If Daylight Saving Time is observed, this time must be adjusted by a factor of one
hour (60 minutes) twice per year to maintain a consistent archiving time. For example, if
archiving is scheduled to occur every night at midnight, archiving begins at 1:00 a.m.
when Spring Daylight Saving Time is in effect.
4.2.2.2 Daily Scheduling

This schedule produces one archive file per day and contains all archive data for a 24-hour
period. The base time setting specifies the hour of the day that the file is closed and a new
archive file is opened.
For example, with a base time of January 1, 2004, 9:00 a.m., the archive file is closed and a
new archive file is opened each day at 9:00 a.m.
4.2.2.3 Weekly Scheduling

This schedule produces one archive file per week and contains all archive data for that
week. The base time setting specifies the day of the week that the file is closed and a new
archive file is opened.
For example, with a base time of Monday, January 5, 2004, 9:00 a.m., the archive file is
closed and a new archive file is opened every Monday at 9:00 a.m.
4.2.2.4 Monthly Scheduling

This schedule produces one archive file per month and contains all archive data for that
month. The base time setting specifies the day of the month that the file is closed and a
new archive file is opened.
For example, with a base time of January 1, 2004, 9:00 a.m., the archive file is closed and a
new archive file is opened the first day of every month at 9:00 a.m.

4.2.3 Miscellaneous Archive Settings
In addition to controlling when archive files are created, you can also control the format of
the events within the files, using the following options:
• Time stamp format: The formatting of the time attached to the event can be specified
using a TIMEDATE format. If nothing is specified, the “%c” format is used. Note that the
chosen format can be different from the format used on the displays.
• Priority indicator: The priority of each event can be written in the file.
• Audible indicator: An audible indicator can be written to the file, to indicate whether the
alarm sounded a tone.
• Alarm vs. event indicator: Alarms can be flagged with an indicator so that events can
be distinguished from alarms.
• Archive file version: By default, the Alarm application generates a version 4 archive file.
If the ALARM_ARCHIVER_VERSION environment variable is set to 3, the Alarm
application generates a version 3 archive file, which is compatible with the old Alarm
Viewer.
Note: By default, the Alarm application aborts when it fails to write the archive file to the
archive directory. The write operation may fail when the archive directory is unavailable
or read-only, or when the current archive file is read-only. If the
ALARM_ARCHIVE_NOABORT environment variable is set, the alarm application ignores
this error.

5. Sounding and Silencing Tones
The purpose of this chapter is to present the options available for sounding and silencing
tones. The Alarm application indirectly interfaces with the Browser viewer5 program to play
tones on PCs equipped with sound cards.
5.1 Types of Tones

A “tone” is an audio file that is played by the Browser client when certain conditions are
met.
Alarm supports two different types of tones:
• Single-stroke tone: The tone is sounded once; if needed, the playback might be
repeated. Such a tone does not need to be silenced.
• Continuous tone: The tone is sounded continuously until a silence request is sent by the
Alarm server to the Browser client.
5.2 Priority of Tones

For instances of Platform (formerly e-terraplatform) with the Advanced Presentation
Framework (APF), the tone priority file (priority.txt) was deprecated. The tone priority is
instead part of the Audible profile defined in the APF Audible Management and Audible
Configuration applications. For more information about how to define an Audible profile,
refer to the section “Configuring Audibles” in the Advanced Presentation Framework User’s
Guide.
For instances of Platform without APF, every tone has an associated priority level assigned
to it, which allows a higher-priority tone to take precedence over a lower-priority tone. This
is useful when a continuous tone is playing and the conditions are met for a higher-priority
tone to be played. Under these circumstances, the original tone is silenced and the higher-
priority tone is played.
The tone priorities are defined in the priority.txt file on the local workstation. The wave file
listed first in the file has the highest priority, followed by the wave file listed second in the
file, and so on.
5.3 Processing within the Alarm Server

The Alarm server is in charge of deciding which incoming events cause a tone to be
sounded. This section describes how Alarm makes this decision.
5
The Browser viewer is delivered as part of the Browser client. For more details, refer to the Browser User’s
Guide.
Proprietary – See Copyright Page 35 Sounding and Silencing Tones

5.3.1 When to Issue a Tone
The following options are available for controlling tones:
• Tones can be assigned to exceptions.
• Tones can be assigned to categories.
• When issuing an event, a client can specify that no tone be sounded regardless of what
is configured in the Alarm database.
• It is possible to specify, at the exception definition level, that no tone should be issued.
When an event is posted, the Alarm server applies the following logic to decide if one or
several tones should be issued:
• If the NOTONE option has been specified by the Alarm client, then when the event is
posted, no tone is issued.
• If the event is a log-only event (that is, the client has explicitly specified that the event
should not go into the alarm list), then no tone is issued.
• If the event is assigned to an exception that has the Issue Tone flag set OFF, then no
tone is issued.
• If the event is associated with a database object (OBJDEF record) that is configured to
suppress multiple tones, and if there is at least one unacknowledged alarm associated
with the same object, then no tone is issued.
• If no tone is assigned to either the exception or the category specified within the event,
then no tone is issued.
• If a tone is assigned to the exception specified within the event, this tone is selected to
be issued subject to permissions (see section 5.3.3 Permission Checks for Tones).
• If a tone is assigned to the category specified within the event, this tone is selected to be
issued subject to permissions (see section 5.3.3 Permission Checks for Tones).
• All selected tones are sent to each Browser client currently logged on (see Figure 8).
Attached to each tone order are up to five areas attached to the event that triggered
the tone. It is then up to the Browser viewer to scan these areas and play the tone if the
user has audible permissions for at least one of the areas.

Figure 8. Tones and Alarm
5.3.2 Silencing Tones

Single-stroke tones do not require silencing since, by definition, they are only sounded for a
specific, short time interval. However, continuous tones must be silenced. Users can silence
tones from many Alarm displays.
A Browser user can silence all tones belonging to horns that are modeled as “Horn to
Silence” on the ALARM_MODEL_AUDIBLE_TONES display under horn/computer. As shown in
Figure 8, a user sitting at Computer 1 can silence tones for all three computers in the room
if Horn1, Horn2, and Horn3 are modeled as Horn to Silence under Horn1.
If the Silence Alarm flag is set, the Alarm server automatically silences tones when
acknowledging an audible alarm through an RUSER command if there are no remaining
unacknowledged audible alarms. You can set this flag from the

5.3.3 Permission Checks for Tones
Sounding and silencing tones are actions subject to the following permission checks:
• When sounding tones in Browser, Alarm passes the audible command to the Browser
viewer along with the permissions assigned to the alarm that issued the tone. The
Browser viewer then determines if the current user has the proper audible permissions
to hear the tone.
• A Browser user can only silence a tone if that user has AUDIBLE permission for the area
defined on the Horn record.
• Silencing of the tones under a horn can only occur if the user issuing the request has
AUDIBLE permission for the modeled silence area.
Note: Alarm does not get the permissions for each application from Permit. Instead, Alarm
retrieves the permissions for each area. Therefore, changing the audible settings for a
particular application under a mode (from the “Mode_application” Permit display) does
not have any effect on the alarms for that application.
5.4 AudioAlarm in the Browser Viewer

For instances of Platform with APF, the Browser AudioAlarm feature was replaced by
features in the APF Audible Management and Audible Configuration applications. For more
information, refer to the Browser User’s Guide and the Advanced Presentation Framework
User’s Guide.
For instances of Platform without APF, the Browser viewer, delivered with the Browser
client, has a version of the AudioAlarm program embedded within it. This allows Browser to
sound tones that are sent to it without requiring any application to be running separately.
When the Browser viewer processes the AudioAlarm command, the passed-in permission
areas are checked for the proper audible permissions:
• If any one area has audible permissions, the tone plays for that client.
• If the user does not have audible permissions for any of the passed-in areas, the tone is
discarded.
There are no permission checks performed by the Alarm server.
Note: The Browser viewer requires an AudioAlarm folder that contains .WAV files and the
priority.txt file.

Figure 9. Audio Alarm Tab in the Browser Viewer
The Browser AudioAlarm can be tested from its own user interface by issuing commands
from the command line.
To play a wave file once:
Oleauto/user=fg.audioalarm "wavefilename /AREA = area1,area2,area3,area4,area5"
To play a wave file continuously:
Oleauto/user=fg.audioalarm "wavefilename/c /AREA = area1,area2,area3,area4,area5"
To silence by playing the NoSound.wav file:
Oleauto/user=fg.audioalarm "/s"
The Browser AudioAlarm can handle from zero to five permission areas separated by
commas. The Alarm application automatically generates this command string using the
areas that were passed with the alarm that issued the tone.

6. Adding Notes to an Alarm
From any display with a list of alarms on the Enabled host, an operator can right-click an
alarm and select Create Note to create a note for that particular alarm.
1. Right-click the alarm and select Create Note.
The Create new Note dialog box appears.
Proprietary – See Copyright Page 40 Adding Notes to an Alarm

2. Enter the note text in the Comment box, and then click OK.
The note is saved in the database of the Notes Service, and a small yellow-sticky icon
appears next to the alarm.
3. You can edit or delete notes as follows:

– To edit a note, click the yellow-sticky icon. A dialog box for editing the note appears.
– To delete the note, right-click the alarm and select Delete Note.
6.1 How Does It Work?

Several components are involved in the alarm note feature:
• A Browser component configured to access the Notes Service
• The Notes Service running inside an application server
• The PubSub service running inside an application server
• The Alarm Notes Event Consumer (ANEC) running inside an application server
• The Alarm server configured to get notifications of a Note Event from the ANEC
When the operator clicks OK on the “Create new Note” dialog box, Browser invokes a web
service call on the Notes service.

The Notes service processes this create note request, and saves the note content into a
relational database. It then publishes this create note event to the PubSub service.
The ANEC service subscribes for Notes events with the PubSub service. When the Notes
service publishes a note event to the PubSub service, this event is relayed to all Notes event
subscribers. In this case, ANEC is one such subscriber and it receives the note event. ANEC
determines if this note event is of the type AlarmNote. If so, it notifies the Alarm server that
a note has been added to a specific alarm.
The Alarm server, upon receiving a notification from the ANEC, will locate the ALMQ record
and set a flag on that alarm to display the yellow-sticky icon on the alarm.
The same sequence of operations is executed when an alarm note is being deleted; the end
result is that the Alarm server clears the flag on the ALMQ record to remote the yellow-
sticky icon from the alarm.
To communicate with the Alarm server, the ANEC opens a TCP connection to the Alarm
server. On the ANEC side, the port for this TCP connection is set by the
“anec.alarm.server.portnum” property in the alarm-note-event-consumer.properties file on
the application server. On the Alarm server side, the listening port is set by the Alarm Notes
Event Consumer Port Number setting. For more information, see section 7.4 Miscellaneous
Items.
Configuring Browser, the PubSub service, and the Notes service are outside the scope of
this guide. For more information, refer to the Browser Software Installation and
Maintenance Guide and the Advanced Services Framework Software Installation and
Maintenance Guide.

7. Setting Up the ALARM Database
When the Alarm application is configured for a given site, its database must be defined to
reflect the site’s configuration and to obtain the desired behavior during the alarming of
significant events. Most of these modifications to the database are generally defined when
the Energy Management System (EMS) is installed. However, it is fairly common for system
managers to update their Alarm modeling to satisfy operator requests (e.g., auto-delete or
multiple acknowledgment features), or to deal with hardware modifications such as new
printers.
The objective of this chapter is to document the various records and record attributes that
make up the Alarm database.
7.1 The Validation Program

All modeling information for the Alarm application is contained in the Alarm database. Any
modification of the database should be validated by executing the ALARMVAL task. A
successful validation of the Alarm database is required for the Alarm server to run.
If the Alarm database has been modified and not validated, the Alarm server detects that a
validation is required at startup, executes the validation code, and then starts its “real
work” only if the validation is successful. Therefore, to avoid surprises at run time, it is a
good practice to verify the Alarm database offline using the validation program.
The validation check is based on the Hdb write stamp in each database partition.
7.1.1 Executing the Validation Program

The validation program can be executed by using any one of the following methods.
Note: Regardless of the method chosen, the validation program can only be run
successfully while the Alarm server is not running. Given this restriction, it might be
convenient to perform the Alarm modeling tasks using a different clone than the one used
by the EMS.
• From Analyst Displays > Alarm Modeling, select a modeling display. To display the
validation pop-up, click Database Validation. To run the validation program, click Verify
Database Definition.
• Using TVIEW, run the validation program with the following command:
% tview run alarmval alarm family
where family is the family of the ALARM clone.
• Run the validation program interactively by setting the right context and running the
alarmval executable.
Proprietary – See Copyright Page 43 Setting Up the ALARM Database

Results of the validation program can be seen by calling up the ALARM_LOG display. The
last message in the LOG always indicates whether the validation succeeded or failed. If the
database has errors, a message is issued to flag the offending record(s). The online
message help can be referenced for each message, to obtain explanations and actions
necessary to resolve the problem.
Once all errors have been corrected, the validation program should be run again.
7.1.2 Limitations of the Validation Program

The validation program only scans the Alarm database. It does not access the ALARMLST
database, which is used only at run time. This creates the following limitations:
• The maximum number of records in the Alarm database (MX$) is not validated against
the MX$ of the ALARMLST database.
• IDs used in DEFLOG and OVLOG records are not validated against records identifying
formatted logs in the ALARMLST database.
• IDs of the Logman queues are not checked against the queues defined in the LOGMAN
database.
However, the Alarm server performs such validations at startup and reports any errors
related to the above items.
7.2 The ALARM Database Records

All the modeling information used by the Alarm application is stored in the Alarm database,
while the ALARMLST database contains the alarm lists at run time. Figure 10 shows the
hierarchy of records within the Alarm database.

Figure 10. ALARM Database

7.2.1 The Application (APP) Record
The APP record identifies the applications used by the Alarm clients. Each client that uses
Alarm must have an associated APP record defined. The APP record consists of the
following fields:
• Name: An 8-character string naming the Habitat application.
• Message set: The name of the MLF message set that is used to format the events that
are posted by the clients registered under the application.
7.2.2 The Category (CAT) Record

The CAT record is used to specify the options attached to a category, as follows:
• Name: A 10-character string used to identify the category.
• Label: A 10-character string used to identify the category on the synopsis displays.
• Priority: Defines the priority of the alarms issued in the category. Alarm supports
priorities from 1 to 8, with 1 being the highest priority.
• Severity: Used to sort the Category and Location buttons on the synopsis displays from
the lowest (least severe) to the highest (most severe). For more information, see section
2.5.1 The Alarm Synopsis List.
• Color: The color chosen for the category is used on the Category button of the synopsis
displays and the events text.
• Prevent abnormal alarm deletion: Any abnormal alarm issued under this category
cannot be deleted by an operator action if this flag is set to true. These alarms can only
be deleted by auto-delete, multiple delete, or overlay/delete operations or by the RUSER
force commands.
• Prevent category acknowledgment: Prevents an operator from performing an
acknowledgment on every alarm issued under the category if this flag is set. This option
directly corresponds to the RUSER CATACK command.
• Display in system line: If desired, a category can be defined to not appear on the
synopsis displays. If this flag is not defined, WebFG Server (which maintains the
counters) will not count alarms where the flag is set for the alarm’s category. This can
cause the number of alarms at the location or category to not correspond with the
counter.
• Action(s) to perform when the Category button is selected on the synopsis displays:
– Display: When the button is selected, the specified Browser command is executed.
The most typical command is to call a display.
– Silence: Silence any tones associated with the category.
– Acknowledge: Acknowledge all the alarms issued in the category.

• FG command: A command that is executed when the Category button is clicked from
the synopsis or category list displays.
Two lines are available for the command string to allow for the use of proxy strings. The
category has two proxy strings available: %CATID% and %CATLABEL%. The %CATID%
proxy substitutes in the two-letter category ID for the category, and the %CATLABEL%
proxy substitutes in the category label. The proxies are to be used the same way they
are used in keysets. It is recommended that the %CATID% be set to key3 and the
%CATLABEL% be set to key4.
7.2.3 The Default Log (DEFLOG) Record

The DEFLOG record identifies the default formatted log to use for the application. If the
OVLOG field is defined in the exception definition for a particular event, the event is sent to
that log instead. Otherwise, it is sent to the log indicated by DEFLOG. More than one default
log can be defined under an APP record.
The DEFLOG record has only one field, which contains the name of a formatted log (a
6-character string). If an invalid name is specified, the Alarm validation program does not
detect it, but the Alarm server aborts at startup with a meaningful explanation.
7.2.4 The Object Definition (OBJDEF) Record

The object definition (OBJDEF) record consists of a set of attributes that describe an Alarm
database object. These attributes are used by the Alarm server when processing events
associated with the object.
The OBJDEF record consists of the following fields:
• Name: An 8-character string used to identify the object definition. Typically, it matches a
record type in the client database.
For example, the Scada application may define a “POINT” OBJDEF record that is used to
define the exception definitions associated with events related to Scada points.
• Information regarding the processing of events attached to the object definition:
– Multiple tone suppression: If set on, the Alarm server does not issue a second tone if
a tone has already been issued for one of the related alarms.
– Multiple acknowledgment: If defined, acknowledgment of any one of the alarms
under the same instance of the same object definition causes all the related alarms
to be acknowledged.
– Multiple delete: If defined, deletion of an alarm causes all the alarms under the
same object definition to be deleted as well.
– Overlay/Ack: If defined, there can only be one unacknowledged alarm under the
object definition. A new alarm under the object definition is unacknowledged and the
previous alarm is automatically acknowledged.

– Overlay/Del: If defined, there can be only one alarm under the object definition that
is either unacknowledged or acknowledged. A new alarm under the object definition
is unacknowledged and the previous alarm is automatically acknowledged and
deleted.
7.2.5 The Exception Definition (EXCDEF) Record

The (EXCDEF) record consists of a set of attributes that describe a particular exception.
These attributes are used by the Alarm server when processing events reporting the
exception.
The EXCDEF record consists of the following fields:
• Name: An 8-character string used to identify the exception record.
• Message ID: A 10-character string that identifies the message to be used to format the
event. This ID identifies the proper formatting function within the message set defined
either on the APP record or in the overriding message set field of the EXCDEF record. An
invalid ID causes the Alarm validation to produce a warning message and the Alarm
server to use a default message.
• Overriding message set: A 10-character string naming the message set to be used
instead of the one specified on the APP record.
• Operating procedure: Specifies a file to display for this alarm when an operator selects
the URL icon on the alarm. This is designed to guide the operator in the actions to be
taken when this alarm occurs. The URL icon appears only when this field is defined in
the database. The directory specification for these files is modeled on the Miscellaneous
Modeling display.
• Information regarding the processing of events attached to the exception:
– Inhibit: When selected, indicates that the alarm for this exception is suppressed.
– Use the API options: Indicates whether the options specified by the client, when it
posts the event, should be used to process the event.
– Not in the list: If the API options are not used, this flag is used to decide if the event
is an alarm or not.
– Auto-ack: If set, the incoming alarm is acknowledged automatically, as well as the
related alarms if “multiple ack” is set on the object definition.
– Auto-delete: If set, when the alarm is acknowledged it is also deleted, as well as
related alarms if “multiple delete” is set on the object definition.
– Allow abnormal alarm deletion: If set, an incoming alarm or event that is not
abnormal causes deletion restrictions on related alarms to be removed. These
related alarms are still abnormal, but the operator can delete them.
– Abnormal: Indicates whether the event is abnormal. Abnormal events appear with a
red time field on the alarm displays; normal events have a black time field.

If this field is set to YES, then the alarm is forced to always be abnormal. If this field is
set to NO, then the alarm is forced to always be normal. If it is set to conditional,
then the client issuing the alarm is responsible for determining the normal/abnormal
state of the alarm.
– Issue tone: If not specified, the Alarm server does not issue a tone for the alarm.
7.2.6 The Override Log (OVLOG) Record

The Override Log (OVLOG) record identifies a formatted log used to log events that are
posted with the exception definition that owns the APP record. Multiple OVLOG records can
be specified under the same exception. The name specified for an OVLOG must match the
name of a formatted log defined in the ALARMLST database. By default, there are five
formatted logs: sysact, sclog, log2, log3, and acklog.
When OVLOG records are defined under an exception, the formatted log specified by the
DEFLOG record at the application level is ignored.
The OVLOG record has only one field, which contains the name of a formatted log (a
6-character string). If an invalid name is specified, the Alarm validation program does not
detect it, but the Alarm server aborts at startup with a meaningful explanation.
7.2.7 The Location (LOC) Record

The LOC record identifies a location. Locations are one of the keys used by Alarm to classify
alarms. Every client specifies a location when it posts an event, and the Alarm server
maintains lists of alarms for every location. Locations usually match the list of Scada
substations in the system. However, it is fairly common to have a few additional LOC
records that are used for events related to the control center (Cfgman or PROCMAN alarms,
for example). If no location is specified when an event is issued, a default location modeled
in the Alarm database is used.
The LOC record consists of the following fields:
• Name: A 12-character string identifying the location.
• Displays in system line: If this flag is set on, the location appears on the Synopsis
display.
• FG command: The FG command to be executed when a user selects this location from
the Synopsis display. Two lines are used to define the command to make use of proxy
strings. The %LOCID% proxy substitutes the location name for the proxy and needs to
be set to key201.
7.2.8 The Console (CONSOL) Record

The CONSOL record defines a Habitat console that is within hearing range of the HORN. This
assignment is used with the PERMIT database to build the Horn-Permission Area two-

dimensional structure, which is used directly to determine which Horns should emit tones
for an exception assigned to a permission area.
Each CONSOL record also defines a console that has “bin” lines based on area of
responsibility and/or association with horns. There is a two-line display that lists categories
on one of the lines and locations on the other. A category or location is listed only if there is
an alarm in it. The “bin” line has this name because the categories and locations are like
bins where the alarms are added.
7.2.9 The QUE Record

The QUE record identifies a Logman queue to use for printing events.
The QUE record has only one field, which contains the name of a Logman queue.
If an invalid name is specified, the Alarm validation program does not catch the error. An
invalid name is one that does not match one of the queues defined in the LOGMAN
database. It is only when Alarm tries to print an event on that invalid queue that an error
message is logged in the Alarm message log.
7.2.10 The QUEAREA Record

The QUEAREA record defines the permission areas that filter the events sent to the logger.
The QUEAREA records are associated with the Logman queue using the Logman/Area
Assignment display. If there are no permission areas associated with a Logman queue, then
all events are printed.
These areas are checked against the PERMIT database during validation, to ensure that
proper permission areas are entered. Validation fails if a permission area does not exist in
the PERMIT database.
7.2.11 The HORN Record

The HORN record identifies a PC name where the Browser client is running. Every PC that is
used as a Browser client should be modeled.
The HORN record consists of the following fields:
• ID: An 8-character string identifying the horn in the Alarm database.
• Computer name: This specifies the computer to which the audio command is to be sent.
This is the network name of the computer.
• Silence area: This permission area is used when a silence command is received from the
computer to which the horn is attached. The user needs to have audible permissions for
this area to silence the tones.

7.2.12 The TONE Record
The TONE record identifies a wave file to be sounded by the Browser client. The TONE
record is a child of the HORN record. Since a tone only identifies a wave file to be played, a
horn can have any number of tones.
Tones can be associated with categories and/or exceptions. Such associations are made to
identify which tone(s), if any, should be sounded for incoming alarms. The exception
definition and the category used to issue the alarm are the keys to decide which tone to
sound.
The TONE record consists of the following fields:
• The wave file name: For instances of Platform with APF, the name of the Audible profile
defined in the APF Audible Configuration application should be used in this field.
For instances of Platform without APF, this is a 40-character string matching the name
of a file located in the AudioAlarm directory.
• A single-stroke/continuous indicator.
Note: For instances of Platform with APF, this setting takes precedence over the Mode
of the Audible profile defined in the APF Audible Configuration application.
• Priority of the tone: For instances of Platform with APF, the priority.txt file was
deprecated. The priority is now defined in the Audible profile of the APF Audible
Configuration application.
For instances of Platform without APF, the priority.txt file specifies the priority of tones to
be sounded in Browser. The first tone listed in the file has the highest priority; each
additional tone has a priority lower than the previous one.
7.2.13 The ZHORN Record

The ZHORN record is used to specify additional horns to silence when the parent horn
receives a silence request. The modeling requires the index of the horn record that needs to
be silenced. A horn index reference is available on the header of the display. There are no
permission checks for these silences, but the parent horn must have audible permissions
for its silence area to silence the additional horns.
7.3 Setting Up Horns and Tones

To configure horns and tones in the Alarm database for issuing and silencing tones, do the
following:
1. From the Horns/Tones Alarm Definition display, define the horns and their tones (for
more information, see sections 7.2.11 The HORN Record and 7.2.12 The TONE Record).

2. From the Category/Tone Assignments Alarm Definition display, define the tone(s) to
issue when the Alarm server processes an alarm with a given category.
3. From the Exception/Tone Assignments Alarm Definition display, define the tone(s) to
issue when the Alarm server processes an alarm with a given exception.
In addition, from the Exceptions/Categories Alarm Definition display, the following
configurations can be done at the object definition, exception, and category levels:
• Object definition: If the Multiple Tone Suppression flag is set ON when a new alarm for
this object is processed with a tone to sound, the Alarm server checks to see if there is
already at least one unacknowledged alarm for the same object. In that case, the tone
is not issued.
• Exception: If the Issue Tone flag is set OFF, no tone is issued for an alarm associated
with this exception.
• Category: If the When Selected, Silence flag is set ON, and the user has the AUDIBLE
permission for the silence area defined on the Horn record, then the tones associated
with this category are silenced when the Category button is selected.
7.4 Miscellaneous Items

This display allows the modeling of global alarm settings that are used for all of Alarm.
Some of these fields are self-explanatory, while others need a more detailed description.
7.4.1 Default Alarm Settings

The default settings for Exception, Category, Permission Area, and Location are used when
an event posted to Alarm has one or more of these fields that are invalid. When an invalid
field is encountered, it is replaced by the corresponding default value.
7.4.2 Transaction Timers

The Timer settings determine how often to update information. For performance reasons, it
is important to set these values at reasonable levels.
7.4.2.1 PERMIT Timer

The PERMIT settings do not change often — but when they do, Alarm should reload them.
The recommended setting for this timer is 30 seconds. Checking too often results in
deteriorated performance. In this scenario, the worst case for the new PERMIT settings to
take effect is 30 seconds.

7.4.2.2 Hdb Transaction Timer
Information included on displays is based on values in the Hdb database; therefore, if this
timer value is too long, the information displayed may not be timely. The recommended
setting for this timer is 0.5 seconds.
7.4.3 Alarm Issued Alarms

The Alarm List Full is issued when the alarm list has reached a defined percentage. Only one
alarm is issued when this value is reached, until the alarm list returns to below the defined
percentage and then exceeds it again.
7.4.4 Percent to Free in Full List

When the alarm list becomes 100% full, Alarm automatically frees 1% of the alarms in the
list by default. Depending on how fast alarms are entering the system, this value can be
increased to avoid this process repeating over and over. Alarm removes the oldest, lowest-
priority alarms first and then proceeds to newer, higher-priority alarms.
7.4.5 Operating Procedures Directory

Specific alarms may have a document attached to them that provides additional
information. This directory specifies where these documents are stored.
7.4.6 Use Special Area Alarming

Special Area Alarming defines a set of permission areas for which Alarm auto-
acknowledges all incoming alarms. The text field for the list of areas can hold 76 characters.
The areas in the list must be separated by commas, with no spaces in between
(Area1,Area2,Area3).
7.4.7 Maximum Number of Priorities

This setting is used to set the number of priority buttons to show on the Alarm displays.
When this value is set to zero, only the priority buttons that contain alarms are displayed.
Otherwise, if all priority buttons are to be shown regardless of the alarms in the system, this
value is set to the largest priority value used. By default, Alarm uses eight priority levels, so
this value would be set to 8.

7.4.8 Number of MRS Messages to Buffer before Committing a
Transaction
This is the maximum number of acknowledge or purge actions per transaction. It is used to
commit smaller transactions, especially during storms. If this value is 0, a default of 500 is
used.
7.4.9 Use Functional Permission Checking

If functional permission checking is enabled, users must have permission for a functional
permission area as well as a geographic permission area to perform certain alarm
operations. Functional permission checking is enabled by selecting the “Use Functional
Permission Checking” check box on the Alarm Definition display. If functional permission
checking is not enabled, only geographic permission area checks are applied. Permission
areas for the “Switching” functional permission area and the “No Checking” functional
permission area are also defined on the Alarm Definition display.
No functional permission checking occurs for a user if the user has write access to the “No
Checking” functional permission area. Only the geographic permission behavior applies in
this case.
For certain RUSER commands, Alarm checks that the user has write access to the
“Switching” functional permission area along with the geographic permission area. The
following RUSER commands are subject to functional permission checking:
• ACK
• PAGEACK
• MULTIACK
• INHIBIT
• INDEXCATACK
• PURGE
• PAGEPURGE
• MULTIPURGE
7.4.10 Alarm Notes Event Consumer Port Number

The Alarm Notes Event Consumer port number specifies the listening port that the Alarm
server listens on for a connection from the Alarm Notes Event Consumer. If this is set to
zero, then the Alarm server listens on port number 9222 by default.
For more information about the alarm notes feature, see chapter 6 Adding Notes to an
Alarm.

7.4.11 Use Long Names
Enable this so Alarm will look up the long name from an MRID or composite key in the
parameter posted by an alarm client. The text field specifies the URL that Alarm uses to
access the Identifier Mapping Service (IMS) to perform the long name lookup. For example:
Figure 11. Use Long Names
For more information about Long Names and MRID Support, see section 2.3 Long-Name
and MRID Support.
7.4.12 Ignore Long Names in APIs

Enable this so Alarm ignores long names provided in the post or store event API. Alarm
always uses the text string in the API to format the alarm message.
7.4.13 Log a Message When Alarm is Falling Behind in Processing

Log a message in the application log when Alarm is falling behind at this value (in seconds)
during processing. If the value is zero, the message will not be logged. The Alarm processing
time is calculated between the time when the Alarm server receives and finishes processing
an event.
7.4.14 Use Elasticsearch

Enabling the Elasticsearch feature in Alarm will forward Alarm events to Elasticsearch. The
HTTP URL for Elasticsearch and Alarm consists of a hostname followed by the port number
(http://<hostname>:<portnumber).
For example, http://192.168.2.112:9200.
7.4.15 Audible Alarm Suppression

This feature enables Alarm to temporarily suppress the alarm sound of a selected priority
for a fixed period, which is set in the Audible Alarm Suppression Timeout. To select a priority,
right-click an alarm from the priority bucket on the Alarm Summary display.
The timer will start at the time when you first select the priority to suppress, and end at the
time when the timeout value is passed. This feature is reset by clicking Audible Suppression
Reset at any time during the suppression time.

7.4.16 Leave Duplicate Space in CIRCLG Text
By default, the Alarm server removes duplicate spaces from the formatted text that is
placed in the Circular Log. When spacing is critical for the formatted text, this setting
prevents Alarm from removing the duplicate white space in the text before placing it into
the CIRCLG Log. This option is available on the Alarm Control Flags pop-up.
7.4.17 Alarm Database Lock Timeout

When acquiring an Hdb lock for Alarm clone database access, Alarm uses a default lock
timeout value of 30 seconds. This is hard-coded and is not in the Alarm model database.
An optional environment variable named “ALARM_HDBLOCK_TIMEOUT” can override this
default value. This variable specifies the timeout value and is the number of seconds that
Alarm waits for a lock in an Hdb API call before timing out.
If Alarm is unable to acquire a lock to access its own database within the timeout period,
error messages will be logged to the MLF log and the standard OUT file, and the Alarm task
will exit. You can then use the hdbcloner scan_lock command to determine if any other
tasks have a lock on a partition within one of the Alarm application databases.
7.4.18 Force Flushing Events after a Transaction

An optional environment variable named “ALARM_TRANSACTION_CHECKPOINT” can be
used to force the flushing of the buffer of incoming events after a transaction. It prevents
the possibility of losing the data in this buffer if a system is rebooted accidently.
Using this option decreases Alarm’s performance because the Alarm database is accessed
more frequently. Use the option with caution.
7.5 Simple Return to Normal Scenario

This example is intended to show how to model Alarm so that alarms designed to notify
users of an abnormal state are automatically acknowledged or deleted when the state
returns to normal.
In this example, an analog alarm is used to demonstrate an analog value that crosses a
high threshold and signals an Abnormal alarm. The analog then returns below the
threshold back into its proper value range and signals a Return to Normal alarm. In many
cases, once the Return to Normal alarm has been issued, the previous abnormal alarm can
be automatically removed.
For this example, the Prevent Abnormal Alarm Deletion option is set on the category for the
abnormal alarm. This option prevents an operator from deleting the alarm; however, it can
still be acknowledged. The only way this alarm can be deleted is for another alarm with the
same Object Identifier to be issued with an Object Definition having the multiple delete
option set.

Figure 12. Simple Return to Normal Example
The following describes in detail how the Alarm server handles the Simple Return to Normal
scenario shown in Figure 12.
1. Abnormal Alarm Settings
– The analog object definition has the multiple delete option on.
– The category definition has the Prevent Abnormal Alarm Deletion option on.
– The exception definition has the auto-delete option off.
– Issue the alarm with a specific object identifier number.
– Acknowledge the alarm from an alarm display.
– Ensure that the alarm cannot be deleted.
2. Return to Normal Alarm Settings
– The analog object definition is the same as the abnormal alarm.
– The category definition has the Prevent Abnormal Alarm Deletion option off.
– The exception definition has the auto-delete option on.
– Issue the alarm with the same object identifier as the abnormal alarm.
If there are two alarms in the list, related based on the same object identifier, then when the
Return to Normal alarm is acknowledged, the auto-delete function deletes it and any other
related alarms with the same object identifier, including the Abnormal alarm.
If the Abnormal alarm remains unacknowledged when the Return to Normal alarm is
acknowledged, the Abnormal alarm is not deleted. To compensate for this, set the multiple
ack and multiple delete settings on the object definition.
If the user does not need to be alerted about these alarms once they return to normal,
setting the auto-acknowledge and auto-delete options on the exception definition removes

the Return to Normal alarm and the previous Abnormal alarms without any user interaction
whatsoever.
7.6 Complex Return to Normal Scenario

This example is designed to show an analog that passes through multiple threshold ranges
and overwrites the previous alarm with the latest alarm.
For this example, three thresholds are used and, at any given time, only one alarm is
displayed. Once the analog returns to its normal state, the notifying alarm is automatically
acknowledged by the alarm process.
Figure 13. Complex Return to Normal Example
The following describes in detail how the Alarm server handles the Complex Return to
Normal scenario shown in Figure 13:
1. Threshold Violation Alarm Settings
– The analog object definition has the Overlay Delete option on.
– The exception definition has no options selected.
– The category definition has no options selected.
– Issue the alarm with a specific object identifier number.
2. Return to Normal Alarm Settings
– The analog object definition has the Overlay Delete option on.
– The exception definition has the auto-acknowledge option on.

– The category definition has no options selected.
– Issue the alarm with the same object identifier as the violation alarm.
When the Threshold 2 level is crossed, a Threshold Violation alarm is issued. When the
analog drops into Threshold 1, a second Threshold Violation alarm is issued, which
acknowledges and deletes the first alarm. When the analog enters the Threshold 3 range, a
Violation alarm is issued that acknowledges and deletes the second alarm. Finally, the
analog enters the Normal operating range and a Return to Normal alarm is issued; this
acknowledges and deletes the Violation alarm, and then auto-acknowledges itself.
At any given time in the span of this example, only one alarm is displayed in the alarm list.
Any user acknowledgments or deletions of the Violation alarms have no effect on the final
results.
7.7 Return to Normal Using Alarm API Functions

There are two functions that can be used to provide additional functionality when Returning
to Normal. The Alarm Acknowledge and Alarm Delete functions can be used after the final
Return to Normal is issued. These functions acknowledge or delete all the related alarms
that have matching object identifiers. For more information about using these functions,
see chapter 13 Alarm API Descriptions.
7.8 Resizing the Alarm Database

Under normal circumstances, it is not necessary to recompile to resize the Alarm database.
The exception to this is when increasing the max priorities, max locations, max categories,
max consoles, max notify, or max alarm queue sizes. These maximums are intentionally set
to be large, and they should not need to be increased. However, if they do need to be
increased, the Alarm code set needs to be rebuilt.
7.9 Onlining the Alarm Database

All partitions in the ALARM database (alarm.dbdef) are marked as replicated. This change
from previous versions of Habitat allows a new Alarm model to be recovered by MRS from
the enabled EMS server to the standby.
Once the Alarm recovery set is fully recovered, the Alarm process on the standby stops and
is then restarted by PROCMAN to read its new model.
If the ALARM_SKIP_TIMESTAMP_CHECKING_AFTER_RECOVERY environment variable is
defined, the Alarm process on the standby does not check if a new model has been
recovered and, therefore, it does not stop.

8. Creating Indexed Browser Displays
Indexed Browser displays are used to control how partially acknowledged and deleted
alarms appear on a Browser display. By using indexed displays, alarms can appear as fully
acknowledged, or as deleted to one user and not to another. As long as an alarm is
acknowledged for the areas in which a user has READ permissions, the alarm appears as
acknowledged for that user. The same alarm appears as unacknowledged to another user
who has at least one area with READ permissions that is not yet acknowledged.
8.1 Indexed Queries

Indexed Browser displays are constructed using the Full-Graphics Display Builder, knowing
that two different indexes are maintained by the Browser server:
• The ALARMS index: Provides specific sorting criteria for the ALMQ records (alarms).
• The EVENTS index: Provides specific sorting criteria for the SYSACT records (events).
The indexes can be sorted by time and by some additional attributes such as location,
category, and priority. Various combinations can be used to create specific displays.
8.1.1 ALARMS Queries (ALMQ Records)

Indexes are set on each layer of the display by setting the indexed option for the Tabular
Type and then defining the query on the Indexed Tab.
The figure below shows the dialog box provided by the Display Builder when specifying an
indexed query using the ALARMS index.
Proprietary – See Copyright Page 60 Creating Indexed Browser Displays

Figure 14. Indexed Query for Alarms
The general query syntax lists the time query first, then the attribute queries, followed by
the attribute filter values. If a specific attribute query is not needed, it can be omitted from
the query and no filter is applied. The ALL argument can also be used for the filter value that
returns all of the alarms under that attribute.
Syntax: sortOrder filter filterValues
Examples:
unacked_first_desc_time priority 1,3
asc_time priority_location 1,5 loc1,loc2
8.1.1.1 Time Queries

• desc_time: Lists the alarms in time order starting with the most recent.
• unacked_first_desc_time: Lists the alarms in time order starting with the most recent.
Used when the display requires that alarms move below a separator when they are
acknowledged.
• asc_time: Lists the alarms in time order starting with the oldest.
• unacked_first_asc_time: Lists the alarms in time order starting with the oldest. Used
when the display requires that alarms move below a separator when they are
acknowledged.

• desc_priority_desc_time: Lists the alarms starting with the highest priority value (for
example, 4, 3, 2, 1) in descending time order, then the next priority in descending time
order, and so on.
• asc_priority_desc_time: Lists the alarms starting with the lowest priority value (for
example, 1, 2, 3, 4) in descending time order, then the next priority in descending time
order, and so on.
• unacked_first_desc_priority_desc_time: Lists the alarms starting with the highest
priority value in descending time order, then the next priority in descending time order,
and so on. Used when the display requires that alarms move below a separator when
they are acknowledged.
• unacked_first_asc_priority_desc_time: Lists the alarms starting with the lowest priority
value in descending time order, then the next priority in descending time order, and so
on. Used when the display requires that alarms move below a separator when they are
acknowledged.
8.1.1.2 Attribute Queries

• location: Filters the alarms to display only those alarms under the specified location.
Multiple locations can be checked by using a comma to separate the location names.
• location_ack: Filters the alarms to display only those alarms under the specified
location with an additional unack or ack parameter. The unack parameter returns only
unacknowledged alarms, and the ack parameter returns only acknowledged alarms.
• priority_location: Filters the alarms to display only those alarms under the specified
priority and location. Multiple priorities and locations can be checked by using a comma
to separate the priority numbers and location names. The first argument is the priority
(priorities) and the second argument is the location(s).
• priority_location_ack: Filters the alarms to display only those alarms under the
specified priority and location with an additional unack or ack parameter. The unack
parameter returns only unacknowledged alarms, and the ack parameter returns only
acknowledged alarms. Multiple priorities and locations can be checked by using a
comma to separate the priority numbers and location names. The first argument is the
priority (priorities) and the second argument is the location(s).
• category: Filters the alarms to display only those alarms under the specified category.
Multiple categories can be checked by using a comma to separate the category names.
The category name is the category label from the modeling display, not the category ID.
There is no reason to combine the category filter with a priority filter, since the category
defines the priority of the alarm.
• category_ack: Filters the alarms to display only those alarms under the specified
category with an additional unack or ack parameter. The unack parameter returns only

• priority: Filters the alarms to display only those alarms under the specified priority.
Multiple priorities can be checked by using a comma to separate the priority numbers.
• priority_ack: Filters the alarms to display only those alarms under the specified priority
with an additional unack or ack parameter. The unack parameter returns only
Multiple priorities can be checked by using a comma to separate the priority numbers.
8.1.1.3 Group Queries

These queries are used to return locations, categories, and priorities that contain alarms.
The syntax for these queries is as follows:
SortOrder GroupType (withunack)
• SortOrder:
– asc_severity: Lists the categories or locations containing alarms, starting with the
category or location with the lowest-severity alarm to the location or category with
the highest-severity alarm.
– desc_severity: Lists the categories or locations containing alarms, starting with the
category or location with the highest-severity alarm to the location or category with
the lowest-severity alarm.
– asc_priority: Lists only the priorities containing alarms from priority 1 through
priority 8.
• GroupType: The group type specifies the type of data to return; it can be one of the
following values: groupbylocation, groupbycategory, or groupbypriority.
• withunack: Filters the locations and categories to only list locations or categories that
contain unacknowledged alarms.
8.1.1.4 Calculated Fields

There is a set of values stored by the index that are used for display and CAM purposes.
Calculated fields are designated by open and close square brackets after the attribute
name.
The following values are available:
ALARMS[]
UNACKALARMS[]
SEVERITY[]
WHITE[]
GREEN[]
INDRED[]
YELLOW[]

ORANGE[]
MAGENTA[]
RED[]
CYAN[]
BLUE[]
BLACK[]
PRIORITY[]
The ALARMS and UNACKALARMS fields are used to display the number of alarms under a
given location or category. These can also be used in Conditional Attribute Modifiers (CAMs)
on the Location and Category buttons to display the alarm bell when unacknowledged
alarms are present.
SEVERITY can be used on the Location or Category buttons to display the severity of the
alarms.
The color attributes are used in CAMS to control the color of the text on the Location and
Category buttons.
The PRIORITY field is used to display the priority buttons on the header of the alarm displays
that are designed to filter by priority. The priority of an alarm is an attribute of the category
assigned to the alarm, so “_CAT” must be appended to work properly — i.e., PRIORITY[]_CAT.
There is no equivalent for the location since it does not apply.
For all the fields, the type of record must be appended to the name of the field — i.e.,
CYAN[]_LOC and CYAN[]_CAT.
8.1.1.5 Unack / Ack Separator Bar

Certain alarm displays separate the unacknowledged and acknowledged alarms via a black
bar. The position of this bar on the display is controlled by the index. The index uses the
OLDPRI picture group to display the bar on the display.

8.1.2 EVENTS Queries (SYSACT Records)
Indexes are set on each layer of the display by setting the indexed option for the Tabular
Type and then setting the query on the Index Tabular.
The figure below shows the dialog box provided by the Display Builder when specifying an
indexed query using the EVENTS index.
Figure 15. Indexed Query for Events
The general query syntax lists the time query first, then the startTime option, followed by
the attribute filter values. If a specific attribute query is not needed, it can be omitted from
the query and no filter is applied. The ALL argument can also be used for the filter value that
returns all of the alarms under that attribute.
Syntax: sortOrder startTime filter filterValues
Examples:
desc_time All category cat1,cat4
asc_time All location loc1,loc5
8.1.2.1 Time Queries

• desc_time: Lists the events in time order starting with the most recent first.
• asc_time: Lists the events in time order starting with the oldest first.

• startTime: Provides the ability to specify a start time for the query. This must be in the
TIMEDATE format or it must use the All qualifier.
8.1.2.2 Attribute Queries

• category: Filters the events to display only those events under the specified category.
The category name is the category label from the modeling display, not the category ID.
• location: Filters the events to display only those events under the specified location.
8.1.2.3 Group Queries

These queries are used to return locations and categories that contain events. The syntax
for these queries is as follows:
SortOrder GroupType
• SortOrder:
– asc_severity: Lists the categories or locations containing events, starting with the
category or location with the lowest-severity event to the location or category with
the highest-severity event.
– desc_severity: Lists the categories or locations containing events, starting with the
category or location with the highest-severity event to the location or category with
the lowest-severity event.
• GroupType: The group type specifies the type of data to return. It can be one of the
following values: groupbylocation or groupbycategory.
8.1.2.4 Calculated Fields

There is a set of values stored by the EVENTS index that are used for display and CAM
purposes. Calculated fields are designated by open and close square brackets after the
attribute name.
The following values are available:
EVENTS[]
SEVERITY[]
WHITE[]
GREEN[]
INDRED[]
YELLOW[]
ORANGE[]
MAGENTA[]
RED[]
CYAN[]
BLUE[]

BLACK[]
The EVENTS field is used to display the number of events under a given location or category.
SEVERITY can be used on the Location or Category buttons to display the severity of the
events.
The color attributes are used in CAMS to control the color of the text on the Location and
Category buttons.
For all the fields, the type of record must be appended to the name of the field — i.e.,
CYAN[]_LOC and CYAN[]_CAT.

9. Alarm Viewer
The Alarm Viewer is a Microsoft Windows application used for querying and viewing event
data from Habitat’s Alarm application. The Alarm Viewer interacts with the Alarm
application in a Habitat environment, accessing event information from Alarm’s real-time
database and/or the Alarm-produced archive files. It also interacts with Control (formerly
e-terracontrol), Control–generated archive files, and Historian.
The Alarm Viewer runs within the Browser viewer as an ActiveX control that is installed and
registered during the Browser client installation. The Alarm Viewer ActiveX control is labeled
as “AlarmViewerOcx.ocx”. A standalone version of Alarm Viewer is also available only for
interacting with Historian.
At startup, the Alarm Viewer retrieves all Alarm events from the CIRCLG record in the
ALARMLST database (it also receives refresh data when events are added after the initial
download). Once the events are in memory, a user can execute queries against that data
and view the results of those queries in a row/column list. It is possible to configure Alarm
Viewer to obtain events from CIRCLG, archive files, or both.
The Alarm Viewer allows users to create queries based on fields contained in Alarm events.
Queries are constructed using the following fields:
• Event Time
• Alarm Text
• Priority
• Location
• Category
• Permission Area
• Formatted Log
9.1 Alarm Viewer User Interface Overview

The Alarm Viewer has two primary views, as shown in Figure 16. The top view is called the
Query View, and it is used to construct and submit queries. The lower view is called the
Results View, and it shows query results in a row/column format.
Proprietary – See Copyright Page 68 Alarm Viewer

Figure 16. Alarm Viewer Main Screen
9.1.1 Query View

Queries are constructed by providing values for fields that are part of an Alarm event. A
user can provide values for any of the fields listed below by using the provided check boxes,
edit controls, time controls, and buttons. A query requires that a time range be specified; all
other fields are optional. If a value is not provided for a specific field, that field is not
considered in resolving the query.
Several convenience buttons are available to quickly set or clear values in the Query View:
Checks all the related filter values
Clears all the related checked filter values
The following fields can be used to construct a query:
• Time: Standard time controls are used to select a time range. There are also time preset
buttons available to automatically set the time to cover the full range of all events
stored in memory or to specify only those events that occurred within the last n hours. A
query must always have a time range specified.
• Manual End Time: The setting for this check box determines how a query end time is
specified. When the box is checked, a user must manually set an end time. When the
check box is cleared, the end time is automatically set to the time of the most recent
alarm event in the Alarm Viewer’s memory.
• Text: This allows a user to specify a string for which to search within the Alarm Text field.
Case-sensitivity can be configured. Simple wildcarding is allowed by using the asterisk
character. For example, entering a value of “*ack*” within the edit control results in a

match for any alarm event that has the words “unacknowledged” or “acknowledged” in
it. Strings without the wildcard character require an exact match.
• Advanced: The Advanced button displays a dialog box that allows more advanced text
matching criteria. As shown in the figure below, a user can specify a series of clauses
that combine the use of AND, OR, and NOT operations for text matching. A clause can
contain up to four text strings that are logically connected to one another. Any number
of clauses can be linked together using AND or OR.
• Area Permissions: This control allows the user to switch between filtering on user-based
read permissions and showing all data. The OFF mode displays data regardless of
permission areas, and the ON mode filters on read permissions. When a user switches
modes, the entire contents of the Alarm Viewer are emptied and new data is requested
from the Browser server. This operation affects all viewports running in the Browser
client, because they all share the same data source.
When switching area filtering from OFF to ON, it is possible to have fewer categories
and locations, since these lists are populated based on data in the Alarm Viewer.
Therefore, selecting a category or location and then submitting the query may result in
the Results View not being filtered on the desired values because they do not exist in the
permission-filtered cache.
• Data Source: This drop-down menu appears only when DATA_SOURCE_ETA is enabled
in the configuration. This provides the ability to switch between ALARMLST and Historian
as the data source.
• Locations: A user can select one or more locations using the list of check boxes.
Additionally, the NOT, AND, and OR logical operators can be applied to the list of
locations.

• Categories: A user can select one or more categories using the list of check boxes.
Additionally, the NOT, AND, and OR logical operators can be applied to the list of
categories.
• Permission Area: A user can select one or more areas using the list of check boxes.
Additionally, the NOT, AND, and OR logical operators can be applied to the list of areas.
• Logs: A user can select none, some, or all the logs using the provided check boxes.
• Priorities: A user can select none, some, or all the priorities using the provided check
boxes.
• Submit Query: When selected, the entered query data is processed and the Results
View is refreshed to display the filtered data.
• Reset Query: When selected, all the entered query data is cleared from the Query View,
and the begin and end time settings are set to the current range of data in the Alarm
Viewer cache.
9.1.2 Results View

The Results View displays the results of the most recently submitted query. The order and
width of columns shown can be configured, as discussed in section 9.4 Configuration; the
number of rows shown on a single page can also be configured. If the query results in more
than a single page of data, it is possible to page up or down using the arrow keys in Query
View.
Events from this view can be copied and pasted into Microsoft Excel by copying the selected
events and then pasting them, or by dragging and dropping. The events can be copied
either by sending the CopyEvents command through the command interface or by right-
clicking an event and selecting Copy Events.
To view the details for a given row, either double-click an entry or right-click an entry and
select Details. From the Event Details screen, use the up and down buttons to view adjacent
events.

Figure 17. Event Details
9.1.2.1 Pasting Events into Excel

Using various methods, events can be selected in the Results View and then copied to the
clipboard and later pasted into Excel. There are various methods for selecting the events to
copy while adhering to the Microsoft List Control standards. Single events can be selected
by using the “Ctrl left-click” method, and a block of events can be selected using the “Shift
left-click” method or the rubber-band selection method. The events can then be copied by
right-clicking an event and selecting Copy Events. The copied events are pasted in Excel
using the standard paste commands. Using the Alarm Viewer command interface, the
SelectAll and CopyEvents commands can be specified.
9.2 Alarm Viewer Startup

By default, the Alarm Viewer downloads Alarm events from the ALARMLST database at
startup. This option can be configured by the user (see section 9.4 Configuration). The length
of the download operation is dependent on the size of the ALARMLST database; however,
on a typical high-speed LAN, it takes approximately one second for every 1,000 records.
Once the download is complete, a time-descending list of that data is presented in the
Results View.

9.3 Performance Considerations
Once the initial data is downloaded to Alarm Viewer, there are a few guidelines to follow to
optimize the performance of queries and data presentation:
• Time Ranges: The data within Alarm Viewer is organized into segments of time-ordered
collections. If you know that a query should consider events within a specific time range,
then that range should be specified as part of the query.
• Queries Using Text: Text searches are most efficient when using the single text edit
control labeled “Text”. You can use simple wildcard searches using the * as a
substitution character within this text box. Using the Advanced Text Search dialog box is
more powerful, but also slower.
• Logs, Priorities, Locations, and Categories: It is most efficient to leave these search
fields unchecked.
• Records per Page: Restricting the number of records shown on a page has the greatest
effect on performance. Showing up to a few hundred records has minimal impact on
performance. Showing a few thousand records has a severe impact on performance.
• Time Ordering: Sorting the results in time-descending order (the default) is the most
efficient way to display results.
9.4 Configuration
Before you attempt to run the Alarm Viewer, several configuration parameters must be set.
The AlarmViewer_config.txt file has comments and examples for these parameters; this file
is placed in the Alarm Viewer directory under the WebFGCache directory for Browser during
installation. Some parameters are required, while others are optional. Where possible, if a
property is not defined in the configuration file, a default value is provided in the code.
The configuration file to use is specified on the Configuration tab in the Browser viewer. This
file specification may include a URL or a directory specification to load the configuration file.
This specification must also include the configuration file to be loaded. If only the name of
the configuration file is specified, the Alarm Viewer loads the specified file from the
Eterra\webfg\webfgcache\alarmviewer directory on the client computer. If no file is
specified, the Alarm Viewer loads the AlarmViewer_config.txt file in that directory; this
allows each Browser client connection to use a different configuration for the Alarm Viewer.
9.4.1 Required Configuration

The Alarm Viewer does not run properly without setting the following properties in the
Alarm Viewer configuration file. (The connection information must match the
webfg_config.xml connection information, to avoid duplicate logon requests and multiple
PERMIT sessions.)

• DATA_SOURCE: Specifies the data source to obtain data from. Possible values are as
follows.
Note: The following values are case-sensitive. Entering lowercase values causes
Browser to crash.
– ALARMLST: Get data only from the ALARMLST database. This is the default.
– ARCHIVE: Get data only from archive files.
– ALL: Get data from either.
– SMP: Get data from the Control server.
– SMP_ALL: Get data from Control or Control–generated archive files.
– SMP_ARCHIVE: Get data from Control–generated archive files only.
• HOST1: If data is to be acquired from ALARMLST, the host name must be provided. The
form of the name is <host>::<habitat group>.
• HOST2: If data is to be acquired from ALARMLST, the host name must be provided. The
form of the name is <host>::<habitat group>.
• PORT: Specifies the port on which the data server is listening. The port number is
specified in the definition for the Browser data server. This is required when not using
NIOARC and data is to be acquired from ALARMLST.
• DATASOURCENAME: This is an optional setting. It can be used to replace the three
settings host1, host2, and port. The value of this setting must match the data source ID
specified in the configuration file webfg_config.xml. DATASOURCENAME = default is an
example.
• NIOARC: Specifies whether the data server uses NIOARC. When using this feature, it is
possible to get a second logon screen when running in Browser after the initial logon to
Browser is performed.
• NAP_SERVER: Specifies the Network Access Point (NAP) defined for the Browser server
from which the data is going to be retrieved.
• DATA_SOURCE_ETA: If data is acquired from Historian, this property must be set to YES.
• ETAURL1/ ETAURL2: If data is acquired from Historian, a URL for the Web service must
be specified.
9.4.2 Required Configuration for a Standalone Alarm Viewer

The Alarm Viewer does not run properly without having the following property set in the
Alarm Viewer configuration file:
• ETAURL1/ ETAURL2: Specifies the address of the Historian Web service where the Alarm
Viewer retrieves data from.

There are several properties, many of which are mentioned in section 9.4.1 Required
Configuration, that have no effect on the standalone Alarm Viewer because the features
are not supported. The standalone Alarm Viewer can only connect to Historian; therefore,
properties to configure other data sources are ignored.
9.4.3 Permission Configuration

The Alarm Viewer can be configured to show data for the entire system or only for the data
for which the current user has read permissions. These settings are applied to real-time
data supplied by the Browser server, data obtained from archive files, and data obtained
from Historian.
Note: These settings are not applied to data obtained from Control–generated archive
files and data obtained from Historian for the standalone Alarm Viewer.
• PERMISSION_AREAS: Specifies the permission startup mode of the Alarm Viewer. The
OFF option displays data for the entire system, and the ON option filters on permission
areas.
• PERMISSION_SWITCH: Specifies whether the user is allowed to switch between the two
permission modes at run time. When set to NO, the Area Permissions controls of the
Query View are inactive; when set to YES, these controls are active.
9.4.3.1 Filter by Permissions in Alarm Viewer

Previously, the EMS permissions (read, write, execute, and audible) were only honored when
viewing alarm data in the alarm list. When the historical logs were accessed, the
permissions were not honored, and every user had full access to the historical alarm data.
If EMS permission checks are enabled (set to ON), then events originating from alarm
archive files have EMS permission filtering applied before they are presented to the user.
It is not possible to query for the archived alarm event data without a connection to the
Browser data server. When not connected to the Browser data server, the Submit Query
option is not available and no data is loaded at Alarm Viewer startup.
However, for the archive files generated by the alarm viewer to contain the area
permissions, the Archive All Data option must be selected when generating the archive files.
9.4.4 Optional Configuration Parameters

The following properties affect the behavior of Alarm Viewer, but they are not required to be
set prior to running the application.
• USE_SERVERS: Specifies whether the Browser client top URL is used to locate the
archive files, or if separate servers are used. Set it to NO if the archive files are on the
same server as the display files; set it to YES if the archive files are located on different
servers.
Browser creates a file control that allows it to download the displays from the Web
server; it is possible to use the same control for the Alarm Viewer, or the Alarm Viewer
can create its own control. Setting this value to NO uses the Browser file control; setting
it to YES causes the Alarm Viewer to create its own file control.
• FILE_SERVER(n): Specifies the Uniform Resource Locator for archive files. This is required
if data is to be obtained from archive files. The values for FILE_SERVER(n) must all be the
complete URL to the directory where the archive files are stored.
For example, assume the archive files are located at
http://laurel.mysite.com/test/archiveFiles. This would require the following entry in the
configuration file:
FILE_SERVER1 = http://laurel.mysite.com/test/archiveFiles
In Browser, this URL must be a branch off of the display directories to use the Browser
file control. When the USER_SERVERS setting is NO, this value must contain the same
base URL as the top-level URL in Browser.
• QUERY_DIR: Specifies the location on the local machine to save and load queries from.
• QUERY_URL: Specifies the Uniform Resource Locator from which to load shared queries
that have been posted on a Web server.
• DEFAULT_QUERY: Specifies a query to load and execute when the Alarm Viewer
initializes.
• ARCHIVE_LIMIT: Specifies the threshold size in bytes of archive data to download. When
this value is exceeded, the user is notified and given the option to cancel or continue the
download.
• INITIAL_DOWNLOAD: Specifies the number of records to download at startup if data is
acquired from ALARMLST. The default is to have no value assigned. Being undefined
means that the number of records equal to the MX value for the CIRCLG record is
downloaded.
• MAX_EVENTS_SHOWN: Specifies the maximum number of records to display on a single
page. This limits the size of the scrollable list showing query results. Leaving this
property undefined places all results on a single page.
• MAX_EVENTS: Specifies the maximum number of events stored in Alarm Viewer
memory. When the number of records downloaded exceeds this value, events are
cleared from memory according to the value specified by EVENT_TRIM_AMOUNT. The
default value is 100000.
• EVENT_TRIM_AMOUNT: Specifies the percentage of MAX_EVENTS to remove from the
Alarm Viewer. Events with the oldest timestamps are released from memory when the
cache trimming occurs. The default value is 10.
• COLUMN_ORDER: Specifies the order and width of columns used for displaying query
results. The default value is shown in the configuration file.

• LIST_BACKGROUND_COLOR: Specifies the background color for the Results View as an
RGB triplet, in decimal. The default value is 212,212,212 (gray).
• Alarm Text Color: Specifies the RGB triplet in decimal form for the color mapping of the
text. Changing the CAM on the display can modify the standard category color settings.
To keep the colors in the Alarm Viewer consistent with the Alarm displays, this allows
any standard color to be changed to match the colors in the CAM.
• CASE_SENSITIVE: Specifies whether text searches are case-sensitive or not. The default
value is OFF, or not case-sensitive.
Note: This parameter has no effect when using Historian as a data source.
• REFRESH: Specifies whether the Results View and Query View are updated when refresh
events are received from the data server. The default value is ON.
• REFRESH_RATE: Specifies the refresh rate in seconds. The default value is 2 seconds.
• TIME_FORMAT_STRING: Specifies a formatting string for time values. This uses standard
codes for the C Run-Time Library function strftime (except for “%#R”, which is used to
indicate the repeated hour when Daylight Saving Time transitions to Standard Time).
The default formatting string is “%m/%d/%Y %H:%M:%S%#R”.
• USE_CTIME: Specifies if the time values are to be sent in CTime format. This is only
supported in later versions by the Browser data server, and it is required for the Alarm
Viewer to accurately display repeated hour information. It is recommended that this
option be enabled when available.
• REPEATED_HOUR_INDICATOR: This indicator is used for formatting time strings when
the repeated hour is encountered, if using the %#R in TIME_FORMAT_STRING. The
default value is *.
• TIME_ZONE_OFFSET: Specifies the time offset from the host machines in minutes. For
example, if the server is in PST and the client is running in EST, the correct setting is -
180.
• STARTUP_DATA_SOURCE: Specifies whether to start Alarm Viewer connected to
ALARMLST or ETA. This parameter is only relevant when DATA_SOURCE_ETA is YES.
• ETA_RETRY_CONNECT: Specifies the number of times Alarm Viewer tries to make
connections to one of the Web services defined by ETAURL1 and ETAURL2.
• ETA_PROMPT_USER_LOGIN: Set to YES if users should be allowed to enter credentials
for connecting to the Historian Web service. If not set, or if set to NO, the current user’s
Windows authentication is required.
• ETA_TIMEOUT: Specifies the number of seconds to wait for the Historian query to return.
Defaults to no timeout.

9.4.4.1 Optional Configuration for a Standalone Alarm Viewer
• QUERY_DIR: Specifies the location on the local machine to save and load queries from.
• QUERY_URL: Specifies the Uniform Resource Locator from which to load shared queries
that have been posted on a Web server.
• MAX_EVENTS_SHOWN: Specifies the maximum number of records to display on a single
page. This limits the size of the scrollable list showing query results. If this is left
undefined, the maximum number depends on the configuration of Historian.
• COLUMN_ORDER: Specifies the order and width of columns used for displaying query
results. The default value is shown in the configuration file.
• LIST_BACKGROUND_COLOR: Specifies the background color for the Results view as an
RGB triplet, in decimal. The default value is 212,212,212 (gray).
• Alarm Text Color: Specifies the RGB triplet in decimal form for the color mapping of the
text. Changing the CAM on the display can modify the standard category color settings.
To keep the colors in the Alarm Viewer consistent with the Alarm displays, this allows
any standard color to be changed to match the colors in the CAM.
• CASE_SENSITIVE: Specifies whether text searches are case-sensitive or not. The default
value is OFF, or not case-sensitive.
• TIME_FORMAT_STRING: Specifies a formatting string for time values. This uses standard
codes for the C Run-Time Library function strftime (except for “%R”, which is used to
indicate the repeated hour when Daylight Savings Time transitions to Standard Time).
The default formatting string is “%m/%d/%Y %H:%M:%S%R”.
• USE_CTIME: Specifies if the time values are to be sent in CTime format. This is only
supported in later versions by the Browser data server, and it is required for the Alarm
Viewer to accurately display repeated hour information. It is recommended that this
option be enabled when available.
• REPEATED_HOUR_INDICATOR: This indicator is used for formatting time strings when
the repeated hour is encountered, if using the %R in TIME_FORMAT_STRING. The default
value is *.
• ETA_RETRY_CONNECT: Specifies the number of times Alarm Viewer tries to make
connections to one of the Web services defined by ETAURL1 and ETAURL2.
• ETA_PROMPT_USER_LOGIN: Set to YES if users should be allowed to enter credentials
for connecting to the Historian Web service. If not set, or if set to NO, the current user’s
Windows authentication is required.
• ETA_TIMEOUT: Specifies the number of seconds to wait for the Historian query to return.
Defaults to no timeout.

9.4.5 Miscellaneous Configuration
The following properties are not likely to be used or changed, but they are documented
here for completeness:
• EVENT_GROUP_TIME_RANGE: This is a tuning parameter for Alarm Viewer memory
layout. The default value is 3600.
• CACHE_MENU: Specifies whether the cache summary is available from the right-click
pop-up menu on the List View.
9.5 Alarm Viewer Operations

There are functions available to the user from pull-down and pop-up menus. These menus
provide the ability to save and load queries, save preferences, set the font, and get details
about the Alarm Viewer. The Alarm Viewer Help system is also available from the menu, and
it opens to the contents section of the help. There are also two query commands: one to
clear and execute the query, and another to execute the default query.
9.5.1 Save Query

To save a query, it must first be applied by clicking the Submit Query button. Then, by
selecting the Save Query menu option, the following dialog box is displayed:
Figure 18. Save Query Dialog Box
The name entered automatically has the avquery extension appended to it, unless the
name itself contains the extension. The file is saved in the directory specified by the
QUERY_DIR value in the configuration file. The Include Time Filter check box specifies
whether to store the current time settings with the saved query.

9.5.2 Load Query
To load a query, select the Load Query menu option to display the Load Query dialog box.
Figure 19. Load Query Dialog Box
There are two locations in which the Alarm Viewer looks for available queries. The Local
location is the directory specified by the QUERY_DIR, and the Shared location is specified by
the QUERY_URL. Each location requires a query_list.txt file that contains the names of the
available queries. This file can be generated using the command “dir /b *.avquery >
query_list.txt”. When a query is saved, the Alarm Viewer updates the local copy of the
query_list.txt file.
When running within Browser, the Shared queries are loaded from the location specified by
the Alarm Viewer URL on the Configuration tab. Select the desired query and click OK. The
Submit Query button must still be clicked to execute the query.
9.5.3 Save Preferences

Saves the current font, column settings, and background color to the alarm_viewer.ini file
that are read when the Alarm Viewer is started. When the alarm_viewer.ini file is present,
the Alarm Viewer always uses the settings in the .ini file, not the corresponding settings in
the AlarmViewer_config.txt file. If the .ini file is not found, the Alarm Viewer uses the default
settings provided in the AlarmViewer_config.txt file. The column settings preserve the
column width and order. The .ini file is saved to the directory specified by the QUERY_DIR
configuration value.

9.5.4 Change Font
Provides a Font Settings dialog box to change the font of the Alarm Viewer. This affects the
font of the column headers and data only.
9.5.5 Clear Cache

Removes all the contents in the Alarm Viewer cache. If real-time data is being used, the
latest data is automatically downloaded after the cache has been cleared.
This should be used when the cache limit has been reached by performing an archive load
and, as a result, archive loading has been disabled. Clearing the cache re-enables the
loading of archive files.
9.5.6 Command Interface

The Alarm Viewer contains a set of functions that can be accessed using the OLEAUTO
interface.
Below is the command syntax required for these commands:
OLEAUTO/USER=ALARMVIEWEROCX.ALARMVIEWEROCXCTRL "command"
The following commands are available:
• LoadData: Creates a new Alarm Viewer Window
• SaveQuery: See section 9.5.1 Save Query
• LoadQuery: See section 9.5.2 Load Query
• SetFont: See section 9.5.4 Change Font
• SavePreferences: See section 9.5.3 Save Preferences
• About: Provides information about the Alarm Viewer version
• Print: Prints the current contents of the Alarm Viewer
• PrintPageSetup: Issues a Print dialog box prior to printing the current contents of the
Alarm Viewer
• CopyEvents: Copies all the selected events in the Alarm Viewer to the clipboard, with
additional formatting to paste events into Microsoft Excel
• SelectAll: Selects all the events currently visible in the Alarm Viewer

9.6 Alarm Viewer Printing
The Alarm Viewer has a built-in print feature that prints the current contents of the Results
View. The printed output is formatted to include a header section that displays the query
settings that produced the results; each page contains this header followed by the Results
View data.
The Alarm Viewer can be printed by using the print icon on the Browser viewport displaying
the Alarm Viewer. A custom icon can also be added to execute the following command:
OLEAUTO/USER=ALARMVIEWEROCX.ALARMVIEWEROCXCTRL PRINT
Note: This is the only way to print the contents of the Alarm Viewer. The print commands
for printing normal displays do not work for the Alarm Viewer.
9.7 Browser Integration

When the Alarm Viewer is running in an Browser viewport, it is treated the same as any
other display. This allows the Alarm Viewer to be saved as part of a room for future use.
When the room is loaded, the Alarm Viewer returns to the state in which it was saved. This
is true for all query data except for the time filter. Specifically, all the column, font, and
background color settings — as well as the current filter applied to the data — are loaded.
9.8 Alarm Viewer Help System

The Alarm Viewer has a built-in Help system that makes use of the Browser HTML Help
functionality. The Help system is accessed by using the right mouse button and selecting
the Alarm Viewer Help option. This help mode can be entered by pressing the button;
this changes the cursor to a point with a question mark. Clicking on any button, enterable
field, or check box provides help specific to the item that was selected. This feature can also
be accessed by pressing F1.
9.9 Archive File Management

The Alarm application can generate archive files that log all events and can later be used
by the Alarm Viewer. There are two format options available for archive files.
To use this feature, the Alarm Viewer requires the All Data setting, which is set on the Alarm
Archiving pop-up of the Alarm Miscellaneous modeling display. This option places all the
data necessary into the archive file for each individual event, so that the Alarm Viewer can
read the file and display the event data.

9.9.1 Archive File Loading
When a query is executed from the Query View of the Alarm Viewer and when the Begin
Time is older than any data that is currently loaded in the Alarm Viewer, archive files are
downloaded if Alarm Viewer has been so configured. All of the necessary files to meet the
entered Begin Time are downloaded. When an archive file is loaded, the entire contents of
the file are loaded. Archive data does not take permission areas into consideration when
displaying data.
If the modeled cache size of the Alarm Viewer is reached, the loading of archive files is
stopped and disabled. This is to prevent the continual loading of archive files and trimming
of the cache. The archive files are loaded from the most-recent data to the oldest data.
When the cache is trimmed, the oldest events are removed from the cache, so stopping
archive loading prevents a lot of unnecessary CPU usage.
To enable the loading of archive files, the Alarm Viewer cache must be cleared from the
right pull-down menu.
9.9.2 Archive File Publishing

The Alarm application places the archive files in the HABDATAXX\ALMARC directory. Archive
files are closed on an hourly basis and new files are opened. The name of the archive file
represents the begin and end times of the data range in the file.
When an archive file is closed by Alarm, it must be moved to a Web server for access by the
Alarm Viewer. The Web server must contain an archive_list.txt file that includes the
directory reading of all available archive files. The directory reading needs to be performed
with one of the following commands:
Windows: dir /-c *.archive > archive_list.txt
Linux: ls -l $HABITAT_ALMARC/av_*.archive >> $HABITAT_ALMARC/archive_list.txt
This command is performed frequently to ensure that the archive_list.txt file is current. This
can be done using various methods; the test configuration uses Windows Task Manager to
execute the command every n minutes.
When archive files are required to meet a query, the Alarm Viewer opens the archive_list.txt
file and determines which files to open based on the time values in their titles. The title of an
archive file consists of a begin time and an end time that represent the time range of the
events included in the file. Therefore, an open archive file (contains “_endtime_” in the title)
must never be published on the Web server. Archive files from both the primary and
standby alarm applications need to be published to the Web server in the event of a
failover.

Figure 20. Archive Web Server Configuration
This figure demonstrates the recommended method for publishing archive files to the Web
server. Each Web server requests the archive files from both the primary and standby
Energy Management System (EMS) servers. Since the archive files are named after their
time values, there should never be a case where two files on different machines have the
same name. There are applications that perform this functionality, but they must be secure
and they must be able to exclude archive files that are still open; SAMPCOPY, or a third-
party SFTP-based application, is recommended.
For more information about archive files, see section 4.2 Archiving Events.

10. Alarm Pager
The Alarm Pager application filters events that are received by the Alarm server and issues
pages to a specified list of recipients when certain alarms are detected. This is achieved by
defining filters that are compared against the received Alarm events. When a filter is valid,
the assigned list of recipients of the filter is paged. The filter can also be designated to
execute a script.
Individual alarms can be paged from the Alarm Summary displays to a specified group of
recipients. This is a separate application that runs independently of the Alarm server, but it
requires the Alarm server to be running to be useful.
10.1 Alarm Interface

The Alarm Pager uses the Alarm Subscribe API to receive events from the Alarm server;
therefore, it is necessary that the alarm application be running for the pager to work
properly.
When an application subscribes to the Alarm server, previous events are sent to the
subscriber based on a time period specified for the Alarm server. This is to protect against
missed events during a failover between the time the failover occurs and the time when the
application re-subscribes to the Alarm server. This can result in duplicate pages being sent
during a failover, or a restart of the Alarm server or pager applications.
The application stores the events received from the Alarm server, and later it processes the
stored events on a periodic timer. This allows the Alarm server to continue executing
without having to wait for the Alarm Pager to filter each event.
10.2 Alarm Pages

The application makes use of Simple Mail Transfer Protocol (SMTP) to send the page
messages. The SMTP messages are created using the modeled e-mail and pager addresses;
the messages are sent on the standard SMTP port 25.
For security purposes, the port should only be open for outbound messages; it should not
be open to inbound messages. The application does not check the response from the SMTP
message, so it is not necessary for the port to allow inbound messages.
The application requires a mail server to send the SMTP messages. The application does not
have the ability to send the actual message to the e-mail account or mobile device. It is not
necessary to have a particular mail server such as Microsoft Exchange, since all mail
servers accept standard SMTP messages.
Proprietary – See Copyright Page 85 Alarm Pager

10.3 Alarm Pager Database
The application has only one database, which contains both the modeling and the real-time
information for the application. The database is replicated for real-time data only; it does
not include the modeled data. When a change is made to the model on one host, the
redundant server’s model must also be updated.
Section 10.3.2 Filter Records provides descriptions of the various fields that make up the
Alarm Pager model. It is only necessary to model the desired functionality for the
application. If the scripting functionality is not desired, it is not necessary to model any
script-related records. The entire application can be modeled from the displays from an
empty database, except for the DECK record that must be entered first using Hdbrio. The
modeling for the application is performed using various displays accessed from the Alarm
Server Modeling displays.
10.3.1 Database Validation

The application database must be validated prior to running the application. If the
application detects that a validation has not been performed, the application performs the
validation prior to running. The database can be validated by clicking the Database
Validation button on the header of any modeling display for the application, or by entering
“almpager -val” from the command prompt.
Validation only checks that all the required fields are populated and that duplicates do not
exist for key fields on the records. Validation does not verify the validity of the data in the
database. When validation errors occur, check the application log for additional
information about how to resolve the errors.
The Mail Server must be defined for the Alarm Pager to pass validation.
10.3.2 Filter Records

The filter records determine the events that are to be processed by the application. Each
event received from the Alarm server is processed through all of the modeled filters; if all of
the enabled filters match, then the specified action is taken (an “AND” of the filters).
Below are the various event attributes that an event can be filtered on. Each attribute must
be selected as “in use” for each filter if the attribute for that filter applies. If a value is
specified for the attribute but the attribute is not in use, then it is not considered for the
filter. These values are specified when the event is issued to the Alarm server using the
Alarm API.

Figure 21. Alarm Pager Filter Model
Inhibit: Prevents the application from processing the filter during execution. This setting
cannot be removed while the application is running, and it is only detected when the
application is started.
Exception: This is the exception that was issued with the event. This value matches the
exception definition values in the Alarm server database. In most cases, there is a one-to-
one correspondence between the exception and the event.
Category: This is the category ID that was issued with the event, not the category label. The
category ID is the two-character representation for the category.
Location: This is the location specified with the event. In some cases, it represents the
substation where the event was detected.
Text: This is the formatted text for the event as it is displayed on the Alarm Summary
displays.
Composite ID: The composite ID is used to relate similar alarms to one another. In the
context of SCADA applications, this represents the point that the event is generated for. This
allows the filter to monitor all the events that come from a particular point in SCADA.
Permission Areas: These are the five permission areas that are specified with the event.
Only one area is required, but up to five areas can be specified for each event.
Priority: This is the priority of the alarm that is determined by the category assigned to the
event. The valid values for the priority are 1–8, and they can be specified by a range of

values. If a single priority value is to be used, then specify the value for the low and high
ends of the range.
Alarm State: This specifies if the event is normal or abnormal as determined by the
exception assigned to the event.
Filter Limit: Specifies the maximum number of times to process the filter for a given time
period. This limits sending multiple pages for the same filter repeatedly. The Reset Time is
the number of seconds the restriction lasts for, and the Max Alarms represents the number
of times to process the filter during the Reset Time. If the values of 30 and 2 are specified,
then the filter can be used only twice within 30 seconds. This option should be used in
combination with others.
Alarm Type: This specifies if the event is an alarm or just an event.
Page Parameters: These specify additional information that is contained in the page in
addition to the text of the event. This includes the subject of the page and three additional
lines of text that provide additional information about the event. Using environment
variables (e.g., %YOUR_ENVVAR%) in these fields is supported.
Text Filtering: The text parameters make use of some regular expressions to enhance the
filter capability. Below are examples of the available expressions:
• ^ (Shift-6): Matches the start of the alarm message. For example, if the filter text is
“^Kirkland”, the filter triggers on the alarm message “Kirkland Station Door” but not on
the alarm message “Chenaux Kirkland Mw”. If the alarm filter text only included
“Kirkland”, then both examples would trigger the filter.
• $ (Shift-4): Matches the end of the alarm message. For example, if the filter text is “Bkr$”,
the filter triggers on the alarm message “Kirkland 540c Bkr” but not on the alarm
message “Kirkland Bkr1 Disc”. If the alarm filter text was just “Bkr”, both examples would
trigger the filter.
• * (Shift-8): Matches any (including none) characters. For example, the filter text
“Kirkland*Bkr” matches all of the following alarm messages: “Kirkland Bkr1 Disc”,
“KirklandBkr Open”, “Kirkland 540c Bkr”, and “Chenaux Kirkland Bkr”.
10.3.3 Address Records

The address records determine the e-mail or pager addresses for the recipients of pages.
These records are associated with the filter and group records using pointers to the
addresses.
The following attributes are used to model the address record.

Figure 22. Alarm Pager Address Model
Inhibit: Prevents the application from using the address during execution. This setting
cannot be removed while the application is running, and it is only detected when the
application is started.
Address: This is the label for the address record, and it is only used as a reference to the
record. This attribute should contain some information about whom and what the address
is designated for. For an address that is a mobile pager or a cellular phone, consider a label
such as “John’s Pager”. This attribute is used to associate the address with a filter or group.
E-mail: This is the e-mail address that is used for this address to send the page. This
attribute is the same as typing a recipient’s e-mail address into any e-mail application. To
page a cellular phone or mobile pager, specify the phone number and the proper address
for the phone carrier. This functionality is only supported if the mobile device supports SMS
messaging and if the device account allows text messaging.
Note: Additional charges may apply to text messaging depending on the type of account
with the mobile device carrier. This functionality is not provided by the Alarm Pager or by
GE.
Address Is a Pager: This setting is used to specify if this address only supports SMS
messaging. The majority of mobile devices only support SMS messaging, which limits the
amount of text that can be sent to the device. This setting removes the subject and
additional lines of text specified on the filter record and only sends the text of the alarm to
the device.

10.3.4 Script Records
The script records specify the script to be performed when a particular filter is processed.
The script is associated with a filter by specifying a pointer to the script record as a child of
the filter record.
The following attributes are used to model the script record.
Figure 23. Alarm Pager Script Model
Inhibit: Prevents the application from using the script during execution. This setting cannot
be removed while the application is running, and it is only detected when the application is
started.
Script: This is the label for the script record. It is only used as a reference to the record.
Script Name: The name of the actual script to run as it appears on the system, including the
file extension.
Script Arguments: The optional arguments provided to the script.

10.3.5 Group Records
The group records define a collection of addresses to page from operator-initiated pages.
The operator-initiated page contains the group to send the page for. The address records
are assigned to the group using a pointer to the address as a child of the group.
The following attributes are used to model the group record.
Figure 24. Alarm Pager Group Model
Inhibit: Prevents the application from using the group during execution. This setting cannot
be removed while the application is running, and it is only detected when the application is
started.
Group: This is the label for the group that is used in the RUSER “PAGE” command.

10.3.6 Miscellaneous Records
These values are global parameters that apply to the application.
Figure 25. Alarm Pager Miscellaneous Model
Time Period: Periodic timer to check the application’s list of events received from the Alarm
server. When the timer expires, the list of events is compared against the modeled filters. If
there is no value specified, the default period is set to 30 seconds.
Mail Server: Network address of the mail client the application sends the SMTP messages
to. This is a mandatory field that must be defined for the Alarm Pager to pass validation. If
the Alarm Pager is only used for script execution, then define a dummy address that is not
valid.
Mail “From:” Address: Specifies the sender of the alarm sent with the page.
Page Time Format: Specifies the format to display the date and time of the alarm sent with
the page. This is a mandatory field that must be defined for the Alarm Pager to pass
validation.
Script Directory: Specifies the location of the script files that are to be executed by the
application. This is optional if the scripting functionality is not used or if the scripts are
contained in HABITAT_BINDIR.

Test Directory: Specifies the directory where the test file is stored when the application is
running in test mode.
Alarm Location: Specifies the name of the location that is used when posting a message to
the Alarm System Activity Log.
Permission Area1 to 5: Specifies the permission areas that are used when posting a
message to the Alarm System Activity Log.
Test Mode: Sets the application to execute in test mode when pages are not sent but stored
in a text file. This removes unnecessary pages sent during the testing phase.
Skip Cfgman Registration: Prevents the application from attempting to register with
Cfgman. When this value is set or when Cfgman is not available, the application assumes
the primary role.
Suppress Alarm Messages: Prevents the application from sending page messages to the
Alarm System Activity Log.
10.4 Display Description

There are two types of displays used for the application. The first type is used to model the
application, and the second type is used to control and monitor the application during run
time. All the displays are accessed from the Alarm Analyst display menus.
ALMPAGER_FILTER_MODEL: Provides an interface to model the filter records and to assign
the script and address records to the filter. The pointers for the address and script records
are displayed by selecting the key icon on the header of the display (except for the Pager
Log).
ALMPAGER_ADDRESS_MODEL: Provides an interface to model the address records for the
e-mail and mobile device addresses.
ALMPAGER_SCRIPT_MODEL: Provides an interface to model the script records.
ALMPAGER_GROUP_MODEL: Provides an interface to model the group records and to
assign the address records to the group.
ALMPAGER_MISC_MODEL: Provides an interface to model the global parameters of the
application.

Figure 26. Alarm Pager Filter Statistics
ALMPAGER_FILTER_NIS: Provides access to statistical information for the filters, including

the number of times the filter has been valid and the last time an event passed the filter.
The filter can also be removed from service from this display.
Figure 27. Alarm Pager Address Statistics
ALMPAGER_ADDRESS_NIS: Provides access to statistical information for the addresses,

including the number of times the address has been paged and the last time an event was
paged. The address can also be removed from service from this display.

Figure 28. Alarm Pager Script Statistics
ALMPAGER_SCRIPT_NIS: Provides access to statistical information for the scripts, including

the number of times the script has been executed and the last time an event triggered the
script. The script can also be removed from service from this display.
Figure 29. Alarm Pager Application Log
ALMPAGER_LOG: Provides access to the application log, including execution and model
validation information.
10.5 User Actions

There are two types of user actions that are provided by the application. The first allows the
operators to remove individual script, address, and filter processing while the application is
running. This action is performed from the statistics displays provided for each.
The second user action is the manual paging of alarms from the Alarm Summary displays.
There are two types of manual paging, described below.

Individual Paging
This allows the operator to page an alarm from the Alarm Summary displays to either an
individual e-mail address or a group. The individual page can be sent by entering the actual
e-mail address or the address ID from the database. When specifying the actual e-mail
address, the application verifies that the address is modeled as an address record. It is not
possible to e-mail to an address that is not specified in the database. To page a group of
addresses, enter the group ID in the display.
Figure 30. Alarm Summary Page Display
This display is accessed from the pull-down menu from the Alarm text on the Alarm
Summary displays. To page the alarm, enter the desired address ID, e-mail address, or
group ID and click the Send button. After the page is sent, the display is closed.
Note: The timestamp format of a manual individual paging is m/d/yyyy HH:mm:ss.
Group Paging
This allows the operator to page an alarm from the Alarm Summary displays to a group of
e-mail addresses. This command is designed so that the operators do not need to know the
group IDs. The operator-initiated group pages can be added to the menus that are
attached to all alarms and events on the Alarm Summary displays. The command specifies
the group that the alarm is paged to. The syntax of the command is below, where the
<group> field is the group ID modeled for the application:
MAIL/USER=ALMPAGER_%DISFAM% “PAGE <group> %TXTFMT_ALMQ”
Note: This command is not placed on the menus by default.
10.6 Test Mode

This mode allows the application to store the pages in a text file instead of sending the
actual page. The text file is stored in the directory specified on the Miscellaneous Modeling
display. This option is useful during the testing phase, to avoid sending multiple pages for

test data. The text file contains the text of the page and the list of recipients the page was
designated for.
The command-line test option verifies that the correct mail client is specified and each
modeled recipient can be paged from the application. The command requires the page
address, the subject, and the text of the page. To verify each address record, this test must
be performed for each address.
To send a test message, enter the following on the command line:
almpager -test <address> <subject> <message>
Note: If a command-line parameter or environment variable contains spaces, it should be

enclosed in quotation marks. For example:
almpager- test <address> "%test subject%" "%test message%"
10.7 Setting Up the Alarm Pager

This section describes the basic steps for configuring the Alarm Pager.
Before you move forward to the configuration instructions, ensure the following:
• The Habitat Alarm application is configured and functioning correctly.
• There is an e-mail server for the Alarm Pager to use.
10.7.1 Verify SMTP

The Alarm Pager uses SMTP to send the page messages. The application sends the
message on the standard SMTP port 25. Verify that port 25 is open and that the message
can be sent through it.
10.7.2 Modeling the Alarm Pager in PROCMAN

The Alarm Pager task must be modeled in PROCMAN. It is usually modeled with the default
installation of Habitat.
If there is no definition for the Alarm Pager, you need to create the definition, as shown in
the image below.

10.7.3 Alarm Definition
An Alarm definition for the Alarm Pager application is required for the Alarm Pager to run
successfully. Define the ALMPAGER application and other information, as shown in the
image below. Then, validate the database and restart the Alarm application.
10.7.4 Alarm Pager Definition
10.7.4.1 Addresses
Insert all of the addresses for receiving alarm messages, as shown in the image below. For
the addresses that only support SMS messaging, select the Address Is a Pager check box.
10.7.4.2 Scripts
Insert all scripts used by filters by entering the script name and arguments in the fields, as
shown in the image below.

10.7.4.3 Filters
To insert a filter:
1. Insert a filter using the name you prefer.
2. Fill out the attributes, and enable the attributes that you want to apply as a filter.
For example, in the image below, Location is the only attribute used to filter the Alarm
for the Alarm Pager. Use Location is enabled by checking its associated check box.
Use Limit, Use Priority, Use Exception, and Use Area are not active in the image below,
even though values are defined for each attribute.
3. Insert the addresses of the recipients for the Alarm.
To find the index of an address, use the address icon .
4. Insert the scripts that run when a particular filter is processed.
To find the index of a script, use the script icon .

5. To insert more filters, repeat steps 1 through 4.

10.7.4.4 Groups
Insert a group that consists of at least one address. A group is used when the operator
initiates pages.
10.7.4.5 Miscellaneous
From the ALMPAGER Database Editor display, select the Misc. tab and define all of the
information needed for the Alarm Pager to start successfully.
10.7.4.6 E-Mail Context

Based on the example filter in the image below, the e-mail message is composed as follows:
• The Title/Subject is the Page Subject, “Example page subject”.
• The first message of the e-mail content is the Alarm message.

• Below the Alarm message, you can see the page text defined for each filter, such as
“Example for additional text line 1”.
10.7.5 Troubleshooting
10.7.5.1 Incorrect Filter Process

When you have a problem with Alarm filtering or receiving an e-mail message, select the
Test Mode check box on the Misc. tab. Test Mode prevents having the e-mail sent to the
SMTP, and it writes the message into a file. The file is found in the directory you specify in
the Test Directory of the Miscellaneous section. This is a good way to identify the possible
location of a problem.
10.7.5.2 Debug Message

If you have a problem setting up the Alarm Pager, enabling the environment variable
ALARMPAGER_DEBUG provides some information. Log files are located in the
%HABITAT_LOGDIR%.

11. Interfaces to Other Subsystems
This chapter covers Alarm’s dependencies and optional interfaces with other subsystems.
11.1 Dependencies
This section describes the subsystems that must be available for Alarm to function.
11.1.1 NETIO
Alarm uses the NIOSOCK API provided by NETIO for all communication paths with its clients.
To establish these connections, the three NETIO tasks (NIOARC, NIOCLERK, and NIOSERVE)
must be running and the NETIO server must have taken the enabled role.
Alarm also uses the NIONTS API, provided by NETIO, to establish its link with the MRS task
on the standby machine. To establish this connection, technically, only the NETIO Address
Registry Clerk (NIOARC) is required to be running on the standby machine.
11.1.2 Hdb
Hdb is the database subsystem within Habitat. Alarm uses the documented Hdb API to
access the ALARMLST database and update the alarm lists.
11.1.3 PERMIT
Alarm needs to check permissions before inserting alarms into the lists and for operator
actions such as acknowledgment and purging. Alarm does not map directly to the PERMIT
database; instead, the Alarm server uses the PERMIT API to perform its permission checks:
• Any given alarm can have up to five permission areas assigned to it when it is issued. As
long as a user has write permissions for one area, the alarm can be partially
acknowledged or deleted for that area.
• A user who has write permissions for all of the assigned areas can fully acknowledge or
delete the alarm.
• An alarm is not considered fully acknowledged or deleted until it has been
acknowledged or deleted for all of the assigned areas.
• Blank areas or non-assigned areas are treated as default values that are acknowledged
or deleted as soon as a user with at least one of the areas acknowledges or deletes that
alarm.
Proprietary – See Copyright Page 102 Interfaces to Other Subsystems

Given the potential number of permission checks needed when a burst of events occurs or
when acknowledging and purging alarms, a special approach is taken by Alarm:
• Alarm uses the caching functionality provided by the PERMIT API. Alarm requests the
timestamp of the PERMIT database, which causes the PERMIT API to read the entire
PERMIT database and store a copy in the address space of the Alarm server.
Subsequent queries for permissions are then handled by the PERMIT API by reading data
cached in the process address space.
• The Alarm server periodically requests the timestamp of the PERMIT database, which
causes the PERMIT API to reload the PERMIT database in the process space if the
timestamp has changed.
The above approach means that any change regarding permissions assignments to areas
is not detected until the next time the Alarm server requests the PERMIT timestamp through
the PERMIT API. The frequency of these requests is configurable in the Alarm database and
can be set on the ALARM_MODEL_MISCELLANEOUS display.
11.2 Optional Interfaces
11.2.1 MLF Message Daemon

The Alarm server records messages in the Alarm message log (database ALARMESS). A
message logging daemon (MLFDMN) is required if any messages are to be placed into a
Habitat database resident log (HABLOG). The daemon is responsible for placing the
message text into the respective Habitat databases.
Typically, the MLFDMN task is one of the first tasks that is started by PROCMAN, and the
Alarm server is usually started later. However, if messages are issued by Alarm prior to the
daemon being started, they are queued within the message logging (MLF) API, and sent to
the daemon as soon as it is started and the link from Alarm to the daemon is established.
11.2.2 Configuration Manager

The Alarm server establishes an interface with Configuration Manager in order to receive a
role. The three different possible roles are handled as follows:
• Enabled: The Alarm server declares a NETIO connect path to allow clients to connect to
it and post events.
• Standby: The Alarm server waits for a recovery and, once complete, it processes
replicated events.
• Disabled: Upon reception of this role, the Alarm server undeclares its NETIO connect
path and says idle.
In an environment where Configuration Manager is not running (e.g., Grid Simulation), Alarm
assumes the enabled role at startup.

11.2.3 PROCMAN
Typically, the Alarm server is started by PROCMAN. The PROCMAN model should contain a
Start node for the Alarm task, and it should start the Alarm clients after this node has been
executed.
Because the Alarm task is started by PROCMAN and PROCMAN may use the Alarm API,
PROCMAN cannot initialize its interface to Alarm until the Alarm task is up. Therefore, the
PROCMAN model must include a TELL command to let PROCMAN know when it should
initialize its interface to Alarm.
A common mistake when restarting the Alarm server from a PROCMAN display is to start
the task from the PROCMAN_MASTER display and not trigger the path to the ALARM start
node. Without executing the ALARM start node, the Alarm server will not be functional. The
best way to restart the Alarm Server from PROCMAN is to use the PROCMAN_PATHS display
and run the path to the ALARM start node.
It is also possible to run Alarm without PROCMAN. When starting up, the Alarm server only
waits for PROCMAN to fire its node if it detects that PROCMAN is running. If Alarm is started
on a system where PROCMAN is not up, it executes its startup sequence as if PROCMAN had
told it to do so.
11.2.4 Hdb/MRS
The Alarm server uses the Memory Replication Service (MRS) to replicate the events on the
standby computer. It replicates events by attaching messages on top of the regular flow of
data going from the primary to the standby computer. To attach these messages, the Alarm
server uses a dedicated API function provided by MRS.
Calls to the MRS API can be disabled from the ALARM_MODEL_MISCELLANEOUS display, in
which case replication of events does not occur.
11.2.5 Logman
Alarm uses the Logman API to print events on the Logman queues. The Logman API can be
turned off using the ALARM_MODEL_MISCELLANEOUS display.
11.2.6 Browser List

Alarm uses the Browser list interface to notify the Browser server when events are added,
and when alarms are acknowledged or deleted, to keep its alarm index up to date.
11.2.7 Identifier Mapping Service (IMS)

Alarm can optionally use the Identifier Mapping Service to look up the long name of an
identifier from an MRID or a composite key.

Use the Miscellaneous Items display to configure Alarm to access IMS. For more
information, see section 7.4 Miscellaneous Items.
11.2.8 Alarm Notes Event Consumer (ANEC)

Alarm can optionally receive note events from the Notes service forwarded by the Alarm
Notes Event Consumer. For more information, see chapter 6 Adding Notes to an Alarm.

12. Using the Alarm API
This chapter provides a high-level introduction to the Alarm API and its intended uses.
12.1 API Introduction

The Alarm API is designed to accommodate the different needs of each of its clients. For
example, the Cfgtimestat client needs to issue only one alarm each time it loses its
connection with the satellite, and to let the operator acknowledge the alarm through the
Alarm displays.
At the other end of the scale, Scada clients may issue hundreds of events per minute, need
to bundle the replication of database object changes with the event replications, know
when objects are acknowledged, and (in some cases) acknowledge alarms from within their
own tasks.
The following provides some hints regarding the use of the API based on what each client
wants to achieve.
12.2 Accessing the API

The Alarm API is included in the habutils shared library6.
12.3 Basic Use

The basic purpose of the Alarm API is to provide functions that allow a client to post one or
more events that can then be processed by the Alarm server. This can be achieved in two
steps:
1. First, the client must invoke the AlarmRegisterClient function to register itself with the
Alarm server. This call is required to initialize the Alarm API, and no other Alarm function
can be invoked before the callback provided with this call is dispatched.
2. Once the registration callback has been invoked, all a client needs to do to post events
is call the AlarmPostEvent function.
This is typically how clients such as PROCMAN, PLCMGR, and CFGMAN use the API to
generate alarms, and this approach is quite adequate given the small number of events
these clients have to report. However, clients such as Scada tasks may need a more-
sophisticated approach to improve performance and to ensure consistency between the
alarms and the system state.
6
Dynamic Link Library (DLL) in Microsoft Windows.
Proprietary – See Copyright Page 106 Using the Alarm API

12.4 Performance Improvements
The Alarm API provides two ways to improve performance for clients that post a lot of
events:
• Handles can be used to identify the exception, category, and location attached to each
event.
When handles are not used, the Alarm API must do a lookup using the character string
parameters to find the handles, since the Alarm server only expects handles. Handles
can be obtained using the AlarmRegisterException, AlarmRegisterCategory, and
AlarmRegisterLocation functions. For example, a SCANNER-like client would typically
register all its exceptions, categories, and locations from within the Alarm registration
callback and would use the handles when posting events.
Note that the handles must be re-obtained each time the registration callback is
invoked, which happens when a failover occurs or when the Alarm server is restarted.
The performance savings is a function of the number of exceptions/categories defined
in the Alarm database under the client’s application, the overall number of locations,
and the number of events posted by the client.
• Events can be buffered within the client’s process space until the client decides to send
them to the server.
This may reduce the number of I/O transactions performed to send the events to the
Alarm server, and it allows the Alarm server to process all the events within a single
transaction.
This approach should only be considered by clients that may potentially issue hundreds
of alarms in a short period of time (a minute or two). Events are buffered by calling the
AlarmStoreEvent function and are then flushed when invoking the AlarmFlushEvents
function. The same approach can be applied to acknowledgment requests made
through the API with the AlarmStoreAcknowledgment and AlarmFlushAcknowledgments
functions.
Note: By default, the maximum number of events stored by the API AlarmStoreEvent
is 4,000. If the ALARM_EVENTS_BUFFERED_MAX environment variable is defined, the API
uses this value instead.
When Should a Task Use the AlarmUseHdbha?

Some clients, such as Scada clients, have a need to bundle the replication of each event
with the replication of the associated database object. For example, it is critical that a
change of state for a point and the event signaling that change both be replicated on the
standby machine at the same time. If only the state were replicated to the standby right
before a failover occurred, the alarm would be lost. Interestingly, if neither of the two
reaches the standby machine before the failover, then the Alarm is reissued by Scada. A
client such as PLCMGR does not need to use this feature since, after a failover, it updates its
database with the state of the PLCs and reissues the alarm.

The bundling of the replication of each event with the replication of the database changes
is performed if the AlarmUseHdbHa function has been invoked. Note that this only applies
to Hdb clients running on the primary machine (where the enabled Alarm server is running).
12.5 Number of Events per Transaction

The Alarm server processes only a specified number of events from the API before control is
returned to the PpmMainLoop. This is done to avoid starving other processes when a large
number of events are issued in a short period of time. Sizing this value properly is
important: A value that is too small does not allow the Alarm server to process the values
fast enough, introducing a delay in alarms being reported. This is a result of Alarm returning
to PpmMainLoop too often and losing processing time. However, a value that is too large
starves other processes and puts back-pressure on clients such as Scada.
The default value is 50, and it can be modified by setting the Events to Process per
Transaction value on the Miscellaneous tab of the Alarm Definition modeling display to a
value larger than 0, or by setting the ALARM_EVENTS_PER_TRANSACTION environment
variable to a value greater than 0. If both of these values are defined, the environment
variable is used for this setting.

13. Alarm API Descriptions
This chapter provides detailed descriptions of the Alarm API functions:
• alarm_acknowledge
• alarm_acknowledge_ex
• alarm_acknowledge_ex2
• alarm_acknowledge_ex3
• alarm_category_exists
• alarm_delete
• alarm_delete_ex
• alarm_delete_ex2
• alarm_dump_history
• alarm_enum_ack_objects
• alarm_enum_ack_objects_ex
• alarm_enum_ack_objects_ex2
• alarm_enum_unack_objects
• alarm_enum_unack_objects_ex
• alarm_enum_unack_objects_ex2
• alarm_exception_exists
• alarm_flush_acknowledgments
• alarm_flush_events
• alarm_get_event
• alarm_get_event_ex
• alarm_location_exists
• alarm_post_event
• alarm_post_event_ex
• alarm_post_event_ex2
• alarm_register_category
• alarm_register_client
• alarm_register_exception
• alarm_register_location
• alarm_reset_lists
• alarm_store_acknowledgment
• alarm_store_acknowledgment_ex
• alarm_store_acknowledgment_ex2
• alarm_store_acknowledgment_ex3
Proprietary – See Copyright Page 109 Alarm API Descriptions

• alarm_store_event
• alarm_store_event_ex
• alarm_store_event_ex2
• alarm_subscribe
• alarm_subscribe_ex
• alarm_subscribe_ex2
• alarm_unregister_client

alarm_acknowledge
Acknowledges all related alarms associated with a database object.
Syntax
status = alarm_acknowledge( object_name, object_handle, time, station )
Arguments Data Type Access

status SCF_STATUS write
object_name character string read
object_handle CCA_HANDLE read
time TIMEDATE_HABTIME read
station character string read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmAcknowledge(
const char object_name_str[],
CCA_HANDLE object_handle,
TIMEDATE_HABTIME time,
const char station_str );
Fortran Binding
INTEGER*4 ALARM_ACKNOWLEDGE(
CHARACTER*(*) OBJECT_DEF,
INTEGER*4 OBJECT_HANDLE,
TIMEDATE_HABTIME TIME,
CHARACTER*(*) STATION )
Arguments
object_name
A character string identifying the object definition in the Alarm database. The maximum length of the
string is defined by the ALARM_OBJECT_NAME_MAXLEN constant.
object_handle
A handle identifying an instance of the object definition. This handle is passed at the time the event is
posted.
time
A TIMEDATE time indicating when the alarms on the object have been acknowledged. If a null value is
passed, the current time is assumed by the API.
station
A character string identifying the station where an operator executed the action that led to this
acknowledgment call. The maximum length of the string is defined by the

ALARM_STATION_NAME_MAXLEN constant. This argument is used for logging purposes only. A special
default name identified by the ALARM_DEFAULT_STATION can be used.
Description
This function acknowledges all the related alarms associated with a database object. Even if there
are no alarms on the object, the request goes to the Alarm server.
If some unacknowledged alarms are indeed associated with the object and if the client did an earlier
call to the alarm_enum_unack_objects function, the “ack” callback will be invoked once the Alarm
server has performed the acknowledgment operation.
If no unacknowledged alarm is associated with the object and if the client did an earlier call to the
alarm_enum_unack_objects function, the “ack” callback will be invoked with the
ALARM_W_NOUNACKFOUND status.
If an invalid object definition is specified, the request will be discarded and a message will be written
in the default application LOG.
Return Values
ALARM_S_NORMAL: The function completed normally and successfully.
ALARM_E_BADOBJ: Invalid object definition.
ALARM_E_SERVDOWN: The alarm server is not running.
See Also
alarm_store_acknowledgment

alarm_acknowledge_ex
Syntax
status = alarm_acknowledge_ex( object_name, object_identifier,
ack_time, station, user_id, permission_key )

object_identifier ALARM_64BIT_HANDLE read
ack_time TIMEDATE_HABTIME read
user_id character string read
permission_key character string read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmAcknowledgeEx(
ALARM_64BIT_HANDLE object_identifier,
TIMEDATE_HABTIME ack_timetime,
const char station_str,
const char user_id,
const char permission_key );
Fortran Binding
INTEGER*4 ALARM_ACKNOWLEDGE_EX( CHARACTER*(*) OBJECT_DEF,
OBJ_ID OBJECT_IDENTIFIER,
TIMEDATE_HABTIME ACK_TIME,
CHARACTER*(*) STATION,
CHARACTER*(*) USER_ID,
CHARACTER*(*) PERMISSION_KEY )
Arguments
object_name
object_identifier
posted.

ack_time
station
user_id
A character string that specifies either the OS user login ID or the subsystem permissions ID based on
how the system is configured.
permission_key
A character string that identifies the area under which the alarm is requested to be acknowledged.
An asterisk in this field will act as a wildcard and will acknowledge the alarm for all assigned
permission areas.
Description
call to the alarm_enum_unack_objects_ex function, the “ack” callback will be invoked once the Alarm
alarm_enum_unack_objects_ex function, the “ack” callback will be invoked with the
This extended function should be used for events that are posted using the extended functions.
Return Values
See Also
alarm_store_acknowledgment_ex
alarm_acknowledge

alarm_acknowledge_ex2
Syntax
status = alarm_acknowledge_ex2( object_name, composite_id,
ack_time, user_id, permission_key )

composite_id character string read
user_id USER_IDENTIFICATION read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmAcknowledgeEx2(
const char composite_id,
TIMEDATE_HABTIME ack_time,
USER_IDENTIFICATION user_id,
Fortran Binding
INTEGER*4 ALARM_ACKNOWLEDGE_EX2( CHARACTER*(*) OBJECT_DEF,
CHARACTER*(*) COMPOSITE_ID,
INTEGER*4 USER_ID,
Arguments
object_name
composite_id
Represents a string identifying the object to acknowledge. This string is passed at the time the event
is posted. It could be either a composite id or an MRID.
ack_time

user_id
This structure contains the user information for the event. This information includes the user name,
the PC name, and the station name. This is used for logging purposes only when filling in proxies in
the alarm text.
permission_key
Represents a character string that identifies the area under which the alarm will be deleted.
Description
call to the alarm_enum_unack_objects_ex2 function, the “ack” callback will be invoked once the
Alarm server has performed the acknowledgment operation.
alarm_enum_unack_objects_ex2 function, the “ack” callback will be invoked with the
Return Values
See Also
alarm_acknowledge

Syntax
status = alarm_acknowledge_ex3( object_name, object_mrid,
object_comp_key, ack_time, user_id,
permission_key, application_name )

object_mrid AlarmMrid read
object_comp_key AlarmCompositeKey read
application_name character string read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmAcknowledgeEx3(
AlarmMrid object_mrid[],
AlarmCompositeKey object_comp_key,
const char permission_key,
const char application_name_str[] );
Fortran Binding
None
Arguments
object_name
object_mrid
is posted. The maximum length of the string is defined by the ALARM_MRID_MAXLEN constant. Either
object_mrid or object_comp_key must be provided.

object_comp_key
is posted. The maximum lengths of the strings are defined by the ALARM_DOMAIN_MAXLEN and
ALARM_COMPKEY_MAXLEN constants.
ack_time
user_id
the alarm text.
permission_key
application_name
A character string identifying the application for the object definition in the Alarm database. The
maximum length of the string is defined by the ALARM_APPLICATION_NAME_MAXLEN constant. It is
only used by the Replay application.
Description
Note: Acknowledge by composite key (object_comp_key) has not been implemented yet.
Return Values
See Also
alarm_store_acknowledgment_ex2
alarm_acknowledge


alarm_category_exists
Checks if the given category is known by the Alarm server.
Syntax
status = alarm_category_exists( category_name)

category_name character string read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmCategoryExists(
const char category_name_str[]);
Fortran Binding
INTEGER*4 FUNCTION ALARM_CATEGORY_EXISTS(
CHARACTER*(*) CATEGORY_NAME_STR)
Arguments
category_name
Name of the category needs to be checked.
Description
This function is provided to let clients of the Alarm verify if a specific category of the client(s) is known
by the Alarm server.
Return Values
ALARM_W_INVALIDCAT: Category not defined in the Alarm database.
ALARM_E_STRLONG: Category name is too long.
See Also
alarm_location_exists
alarm_exception_exists

alarm_delete
Requests that all alarms associated with the passed database object be deleted.
Syntax
alarm_delete( object_name, object_identifier, delete_time,
station, user_id, permission_key )

delete_time TIMEDATE_HABTIME read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmDelete( const char object_name_str[],
TIMEDATE_HABTIME delete_time,
const char user_id,
Fortran Binding
None
Arguments
object_name
string is defined by the ALARM_OBJECT_DEF_MAXLEN constant.
object_identifier
posted.
delete_time
station

user_id
permission_key
A character string that identifies the area under which the alarm is requested to be deleted. An
asterisk in this field will act as a wildcard and will delete the alarm for all assigned permission areas.
Description
This function allows for the deletion of an alarm for the specified permission area. If the alarm has not
been previously acknowledged for this permission area or if the alarm does not contain the
permission area, then the purge operation will not be performed.
When the wildcard value is passed to this function, the alarm will be purged for all permission areas
that have been previously acknowledged.
Return Values
See Also
alarm_delete

alarm_delete_ex
Syntax
alarm_delete_ex( object_name, object_identifier,
delete_time, user_id, permission_key )

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmDeleteEx( const char object_name_str[],
Fortran Binding
None
Arguments
object_name
composite_id
Represents a string identifying a particular instance of the object definition. This string is passed at
the time the event is posted. It could be either a composite id or an MRID.
delete_time
user_id
the alarm text.

permission_key
Description
This function allows for the deletion of an alarm that has been acknowledged by all users who have
permissions to the alarm. If five users have write access to a particular alarm and if each user
acknowledges the alarm, then the alarm will be deleted.
Prior to deletion, each alarm that is acknowledged by a single user is considered partially deleted and
each acknowledgment per user will be logged. Once the alarm has been acknowledged for all areas,
it will be considered deleted and removed from the alarm list.
Return Values
See Also
alarm_delete

alarm_delete_ex2
Syntax
alarm_delete_ex2( object_name, object_mrid,
object_comp_key, delete_time, user_id,
permission_key, application_name)

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmDeleteEx2(
AlarmMrid object_mrid,
const char permission_key_str[],
Fortran Binding
None
Arguments
object_name
object_mrid

object_comp_key
delete_time
user_id
the alarm text.
permission_key
application_name
Description
This function allows for the deletion of an alarm that has been acknowledged by all users who have
permissions to the alarm. If five users have write access to a particular alarm and if each user
acknowledges the alarm, then the alarm will be deleted.
Prior to deletion, each alarm that is acknowledged by a single user is considered partially deleted and
each acknowledgment per user will be logged. Once the alarm has been acknowledged for all areas,
it will be considered deleted and removed from the alarm list.
Note: Delete by composite key (object_comp_key) has not been implemented yet.
Return Values
See Also
alarm_delete
alarm_delete_ex

alarm_dump_history
Causes the history list maintained by the Alarm API to be formatted and output to a file.
Syntax
alarm_dump_history( output_file )

output_file FILE * read
C Binding
#include "alarm.h"
extern void AlarmDumpHistory(FILE * output_file_ptr);
Fortran Binding
ALARM_DUMP_HISTORY()
Arguments
output_file
Identifies where the output text is to be written. A value of zero is taken to mean that output should
be directed to standard output.
Description
This function formats and writes the history list maintained by the Alarm API to an output file.
This function may be invoked even before calling the AlarmRegisterClient function.
Return Value
None

alarm_enum_unack_objects
Searches through the objects in the Alarm database, calling the specified callback function for each
object that has at least one unacknowledged alarm and that belongs to the application of the caller.
Syntax
status = alarm_enum_unack_objects( ack_cb, userarg )

ack_cb ALARM_ACK_CB call
userarg CCA_USERARG read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmEnumUnackObjects(
ALARM_ACK_CB ack_cb,
CCA_USERARG userarg );
Fortran Binding
INTEGER*4 ALARM_ENUM_UNACK_OBJECTS(
INTEGER*4 ACK_CB,
INTEGER*4 USERARG )
Arguments
ack_cb
Specifies the address of the enumeration callback function. This function has the following prototype:
typedef void (*ALARM_ACK_CB)(
SCF_STATUS status,
ALARM_ACK_STATE state,
const char object_type_str[],
In Fortran, the callback should be declared as follows:
SUBROUTINE ACK_CB(INTEGER*4 STATUS,
INTEGER*4 STATE,
CHARACTER*(*) OBJECT_TYPE,
INTEGER*4 ACK_TIME,
INTEGER*4 USERARG )
Where:
• status: One of the following values:
– ALARM_S_MORE: There are more callbacks to come.

– ALARM_S_DONE: The enumeration has been completed. When this status is passed, the
other arguments are meaningless (blank or null). This status indicates the end of the
enumeration or that there are no unack objects for the application.
– ALARM_S_NORMAL: Subsequent updates.
– ALARM_E_NOCOMMS: The communication link with the Alarm server has been lost during the
download of the unacknowledged objects. This implies that the download could not be
completed. When the link is formed again, the ready callback will be invoked and the user
should call the alarm_enum_unack_objects again.
– ALARM_W_NOUNACKFOUND: A call to the alarm_acknowledge function was made for an
object that had no associated unacknowledged alarm at the time the request reached the
Alarm server. This call might have been valid at the time of the call, but the alarms on the
objects were acknowledged by an operator or another Alarm client before the request was
processed by the Alarm server. Alternatively, this indicates a mismatch between the client’s
internal lists and the Alarm server’s lists. When the callback is fired with this status, a
message is also written in the default application LOG.
• state: Indicates the state of the object from an Alarm perspective using one of the two following
values:
– ALARM_UNACK: There is at least one unacknowledged alarm on the object.
– ALARM_ACKED: There is no unacknowledged alarm on the object.
• object_type: Contains the name of the record type of the object being reported7.
• object_handle: Contains the handle of the object being reported. This handle is passed by the
client at the time the event is posted.
• ack_time: Time the alarm is acknowledged if the callback reports an acknowledgment.
• userarg: Specifies the user data to be passed to the enumeration callback when it is invoked.
userarg
Value that will be passed as an argument to the function invoked for the registration completion.
Description
This function queries the Alarm server for all the unack objects kept in the Alarm database for the
application the caller is running under. It can be called any time after the client registration callback
has been invoked.
This function is provided for clients that are maintaining a list of unacknowledged objects (such as the
exception list used by Scada). Calling this function implies that the client wants to be notified about
the unacknowledged state of the objects the client manages. The provided callback will be
subsequently used to notify the caller about any change of state (ack vs. unack) of any of the objects
of the caller’s application.
If this function is used, it should be called every time the “ready” callback is invoked, since it probably
indicates that a failover occurred.
The callback function will be invoked as a different PPM event because the Alarm server must be
queried.
7
It is assumed that the number of object definitions for a given application is small enough (13 for Scada in
EMP 1.5) that it is acceptable for the user to rely on string comparisons when processing an ACK/UNACK
notification.

Return Values
• ALARM_S_NORMAL: The query went to the Alarm server.
• ALARM_E_SERVDOWN: The Alarm server is not running.
• ALARM_E_NOCOMMS: No connection with the Alarm server.
See Also
alarm_register_client
alarm_enum_unack_objects_ex
alarm_enum_unack_objects_ex2

Syntax
status = alarm_enum_unack_objects_ex( ack_cb, userarg )

ack_cb ALARM_ACK_CB_EX call
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmEnumUnackObjectsEx(
ALARM_ACK_CB_EX ack_cb,
Fortran Binding
INTEGER*4 ALARM_ENUM_UNACK_OBJECTS_EX(
INTEGER*4 ACK_CB,
INTEGER*4 USERARG )
Arguments
ack_cb
typedef void (*ALARM_ACK_CB_EX)(
SCF_STATUS status,
ACK_INFO_BLOCK ack_info,
SUBROUTINE ACK_CB_EX( INTEGER*4 STATUS,
INTEGER*4 ACK_INFO,
INTEGER*4 USERARG )
Where:

should call the alarm_enum_unack_objects_ex again.
– ALARM_W_NOUNACKFOUND: A call to the alarm_acknowledge_ex function was made for an
object that had no associated unacknowledged alarm at the time the request reached the
Alarm server. This call might have been valid at the time of the call, but the alarms on the
• ack_info: Contains the information required for the acknowledge callback.
– C structure definition for ack_info callback:
typedef struct
{
ALARM_ACK_STATE state;
char object_type_str[ALARM_OBJECT_NAME_MAXLEN + 1];
CCA_HANDLE object_handle;
ALARM_64BIT_HANDLE object_identifier;
TIMEDATE_HABTIME ack_time;
char area1_str[ ALARM_PERMISSION_KEY_MAXLEN + 1];
CCA_HANDLE area1_handle;
} ACK_INFO_BLOCK;
– Fortran structure definition for ack_info callback:
STRUCTURE /ACK_INFO_BLOCK/
INTEGER*4 STATE
CHARACTER*8 OBJECT_TYPE_STR
INTEGER*4 OBJECT_HANDLE
OBJ_ID OBJECT_IDENTIFIER
INTEGER*4 ACK_TIME
CHARACTER*8 AREA1_STR
INTEGER*4 AREA1_HANDLE
END STRUCTURE

userarg
Description
has been invoked.
The callback function will be invoked as a different PPM event since the Alarm server must be queried.
The extended functionality allows for the use of 64-bit object handle names inside the acknowledge
callback. The original function only allowed 32-bit object handle names and therefore will not allow
e-terramodeler OID object handles to be attached to the event. The extended function is added for
this purpose.
Return Values
See Also

Syntax
status = alarm_enum_unack_objects_ex2( ack_cb, userarg )

ack_cb ALARM_ACK_CB_EX2 call
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmEnumUnackObjectsEx2(
ALARM_ACK_CB_EX2 ack_cb,
Fortran Binding
INTEGER*4 ALARM_ENUM_UNACK_OBJECTS_EX2(
INTEGER*4 ACK_CB,
INTEGER*4 USERARG )
Arguments
ack_cb
typedef void (*ALARM_ACK_CB_EX2)(
SCF_STATUS status,
ACK_INFO_BLOCK2 ack_info,
SUBROUTINE ACK_CB_EX2( INTEGER*4 STATUS,
INTEGER*4 ACK_INFO,
INTEGER*4 USERARG )
Where:

should call the alarm_enum_unack_objects_ex2 again.
– ALARM_W_NOUNACKFOUND: A call to the alarm_acknowledge_ex2 function was made for
an object that had no associated unacknowledged alarm at the time the request reached the
Alarm server. This call may have been valid at the time of the call, but the alarms on the
typedef struct
{
char record_name_str[ALARM_RECORD_NAME_MAXLEN + 1];
char database_name_str[ALARM_DATABASE_NAME_MAXLEN + 1];
ALARM_64BIT_HANDLE group_identifier;
char composite_id[ ALARM_COMPOSITE_ID_MAXLEN + 1];
} ACK_INFO_BLOCK2;
– Fortran structure definition for ack_info callback:
TYPE ACK_INFO_BLOCK2
INTEGER*4 STATE
CHARACTER*8 OBJECT_TYPE_STR
CHARACTER*6 RECORD_NAME_STR
CHARACTER*8 DATABASE_NAME_STR
INTEGER*4 OBJECT_HANDLE
TYPE (OBJ_ID) OBJECT_IDENTIFIER
TYPE (OBJ_ID) GROUP_IDENTIFIER
CHARACTER*56 COMPOSITE_ID
INTEGER*4 ACK_TIME

END TYPE ACK_INFO_BLOCK2
userarg
Description
has been invoked.
The extended functionality allows for the use of the composite ID to associate related alarms to one
another. The composite ID is a string value that is generated in Hdb.
Return Values
See Also

Syntax

C Binding
#include "alarm.h"
CCA_USERARG userarg);
Fortran Binding
There is no Fortran binding for this function.
Arguments
ack_cb
SCF_STATUS status,
Where:

typedef struct
{
CCA_BOOL inhibit_alarm;
char station_name_str[ ALARM_STATION_NAME_MAXLEN + 1];
} ACK_INFO_BLOCK3;
userarg
Description
has been invoked.
The extended functionality is used to notify the client to inhibit alarms.

Return Values
See Also

Syntax

C Binding
#include "alarm.h"
Fortran Binding
Arguments
ack_cb
SCF_STATUS status,
Where:

typedef struct
{
} ACK_INFO_BLOCK4;
userarg
Description
has been invoked.

The extended functionality allows for the use of the MRID and Full Composite Key.
Return Values
See Also

Syntax

C Binding
#include "alarm.h"
Fortran Binding
Arguments
ack_cb
SCF_STATUS status,
Where:

typedef struct
{
char user_id_str[ ALARM_USER_ID_MAXLEN + 1];
char computer_name_str[ ALARM_COMPUTER_MAXLEN + 1];
} ACK_INFO_BLOCK5;
userarg
Description
has been invoked.

Return Values
See Also

alarm_enum_ack_objects
object that has at least one acknowledged alarm and that belongs to the application of the caller.
Syntax
status = alarm_enum_ack_objects( ack_cb, userarg )

ack_cb ALARM_ENUM_ACK_CB call
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmEnumAckObjects(
ALARM_ENUM_ACK_CB ack_cb,
Fortran Binding
Arguments
ack_cb
typedef void (*ALARM_ENUM_ACK_CB)(
SCF_STATUS status,
Where:
enumeration or that there are no ack objects for the application.
download of the acknowledged objects. This implies that the download could not be
should call the alarm_enum_ack_objects again.

typedef struct
{
} ACK_INFO_BLOCK3;
userarg
Description
This function queries the Alarm server for all the ack objects kept in the Alarm database for the
has been invoked.
This function is provided for clients that are maintaining a list of acknowledged objects. Calling this
function implies that the client wants to be notified about the acknowledged state of the objects the
client manages. The provided callback will be subsequently used to notify the caller about any
change of state (ack vs. unack) of any of the objects of the caller’s application.
queried.
Return Values
See Also

alarm_enum_ack_objects_ex
Syntax
status = alarm_enum_ack_objects_ex( ack_cb, userarg )

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmEnumAckObjectsEx(
Fortran Binding
Arguments
ack_cb
SCF_STATUS status,
Where:
should call the alarm_enum_ack_objects_ex again.

typedef struct
{
} ACK_INFO_BLOCK4;
userarg
Description
has been invoked.
queried.
Return Values

See Also
alarm_enum_ack_objects_ex2

alarm_enum_ack_objects_ex2
Syntax
status = alarm_enum_ack_objects_ex2( ack_cb, userarg )

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmEnumAckObjectsEx2(
Fortran Binding
Arguments
ack_cb
SCF_STATUS status,
Where:
should call the alarm_enum_ack_objects_ex2 again.

typedef struct
{
char user_id_str[ ALARM_USER_ID_MAXLEN + 1];
char computer_name_str[ ALARM_COMPUTER_MAXLEN + 1];
} ACK_INFO_BLOCK5;
userarg
Description
has been invoked.
queried.
Return Values

See Also
alarm_enum_ack_objects_ex

Checks if the given exception definition is known by the Alarm server.
Syntax
status = alarm_exception_exists( exception_name)

exception_name character string read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmExceptionExists(
const char exception_name_str[]);
Fortran Binding
INTEGER*4 FUNCTION ALARM_EXCEPTION_EXISTS(
CHARACTER*(*) EXCEPTION_NAME_STR)
Arguments
exception_name
Name of the exception definition needs to be checked.
Description
This function is provided to let clients of the Alarm verify if a specific exception definition of the
client(s) is known by the Alarm server.
Return Values
ALARM_W_INVALIDEXC: Exception not defined in the Alarm database.
ALARM_E_STRLONG: Exception definition name is too long.
See Also

alarm_flush_acknowledgments
Sends the buffer built by calls to the alarm_store_acknowledgment function to the alarm server.
Syntax
status = alarm_flush_acknowledgments()

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmFlushAcknowledgments();
Fortran Binding
INTEGER*4 ALARM_FLUSH_ACKNOWLEDGMENTS()
Arguments
None
Description
This function sends the buffer built by earlier calls to the alarm_store_acknowledgment function to
the Alarm server.
If the communication path with the Alarm server is not up, the requests in the buffer will not be sent
until a communication path is re-established.
Return Values
See Also
alarm_acknowledge

alarm_flush_events
Sends the buffer built by calls to the alarm_store_event function to the Alarm server.
Syntax
status = alarm_flush_events( )
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmFlushEvents()
Fortran Binding
INTEGER*4 ALARM_FLUSH_EVENTS()
Arguments
None
Description
This function sends the buffer built by earlier calls to the alarm_store_event function to the Alarm
server. Calling this function when the buffer is empty is allowed and is a no-op.
If the client is using Hdb High Availability for replicating the events with the database objects
changes, this function can only be called from within an Hdb update transaction that is issuing an
Hdbwrite (an Hdb transaction with no related Hdbwrite will cause an abort in the MRS API).
If the communication path with the Alarm server is not up, the events in the buffer will not be
processed until a communication path is re-established.
Return Values
See Also
alarm_post_event

alarm_get_event
Returns information for the required event.
Syntax
status = alarm_get_event( event_cb, event_mrid, userarg )

event_cb ALARM_GETEVENT_CALLBACK read
event_mrid AlarmMrid read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmGetEvent( ALARM_GETEVENT_CALLBACK event_cb,
AlarmMRID event_mrid,
Fortran Binding
None
Arguments
event_cb
A callback function that is executed when the information for the event is returned.
typedef void ( *ALARM_GETEVENT_CALLBACK ) (
ALARM_SUBSCRIBE_EVENT_BLOCK_EX *event_ptr,
Where:
• event_ptr: Contains the information for the event required.
• ALARM_SUBSCRIBE_EVENT_BLOCK_EX structure is as follows:
See the description for the alarm_subscribe_ex function.
event_mrid
Represents a string identifying the required event. The maximum length of the string is defined by the
ALARM_MRID_MAXLEN constant.
userarg
Description
This function returns information about the required event, which is found in the alarm list or any
formatted log. All items in the return structure of ALARM_SUBSCRIBE_EVENT_BLOCK_EX will be empty
or 0 if the event is not found.

Return Value
ALARM_E_NOCOMMS: Communication with the Alarm server has been lost.

alarm_get_event_ex
Returns information for the required event.
Syntax
status = alarm_get_event_ex( event_cb, event_mrid, userarg )

event_cb ALARM_GETEVENT_CALLBACK_EX read
event_mrid AlarmMrid read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmGetEventEx( ALARM_GETEVENT_CALLBACK_EX event_cb,
AlarmMRID event_mrid,
Fortran Binding
None
Arguments
event_cb
A callback function that is executed when the information for the event is returned.
typedef void ( *ALARM_GETEVENT_CALLBACK_EX ) (
ALARM_SUBSCRIBE_EVENT_BLOCK_EX2 *event_ptr,
Where:
• event_ptr: Contains the information about the required event.
• ALARM_SUBSCRIBE_EVENT_BLOCK_EX2
See the description for the alarm_subscribe_ex2 function.
event_mrid
Represents a string identifying the required event. The maximum length of the string is defined by the
ALARM_MRID_MAXLEN constant.
userarg
Description
This function returns information about the required event, which is found in the alarm list or any
formatted log. All items in the return structure of ALARM_SUBSCRIBE_EVENT_BLOCK_EX2 will be
empty or 0 if the event is not found.

Return Value

Checks if the given location name is known by the Alarm server.
Syntax
status = alarm_location_exists( location_name)

location_name character string read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmLocationExists(
const char location_name_str[]);
Fortran Binding
INTEGER*4 FUNCTION ALARM_LOCATION_EXISTS(
CHARACTER*(*) LOCATION_NAME_STR)
Arguments
location_name
Name of the location needs to be checked.
Description
This function is provided to let clients of the Alarm verify if a specific location name of the client(s) is
known by the Alarm server.
Return Values
ALARM_W_INVALIDLOC: Location not defined in the Alarm database.
ALARM_E_STRLONG: Location name is too long.
See Also

alarm_post_event
Sends an event to the enabled Alarm server.
Syntax
status = alarm_post_event ( event_block, version )

event_block ALARM_EVENT_BLOCK * read
version int read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmPostEvent(
ALARM_EVENT_BLOCK *event_block_ptr,
int version );
Fortran Binding
INTEGER*4 ALARM_POST_EVENT( INTEGER*4 EVENT_BLOCK,
INTEGER*4 VERSION )
Arguments
event_block
The event description that uses the following typedef:
typedef struct
{
/*
** Name of the exception definition in the ALARM database associated
** with the database object which is the subject of the event. May not
** be specified if the handle is provided.
*/
char exception_name_str[ ALARM_EXCEPTION_NAME_MAXLEN + 1];
/*
** Handle for the exception previously obtained through a call to
** the AlarmRegisterException() function. If the handle if specified
** the exception name field is not used.
*/
ALARM_EXCEPTION_HANDLE exception_handle;
/*
** A handle that identifies the instance of the object definition
** associated with the event. This handle will be returned to the user
** as an argument of the ack callback.
** A null handle is valid and implicitly implies that there is only
** one object for the associated object definition.
*/

/*
** A mask that can be built using the following value:
** - ALARM_NOTONE: This option indicates that the event should not result
** in a tone being sounded regardless of what is defined in the ALARM
** database.
**
** - ALARM_NOWABNORNAL: This option indicates that the database object is
** in the abnormal state as a result of this event.
**
** - ALARM_NOWUNACK: This option indicates that the database object is in
** the unacknowledged state as a result of this event.
**
** - ALARM_NOLIST: This option indicates that the event is not an alarm.
** It should not be inserted in the alarm list and should only be
** logged.
**
** - ALARM_NOLOG: This event should not be inserted in any formatted LOG.
** Note that it will be written in the archiving file and may be
** printed.
*/
int options;
/*
** Name of the category in the ALARM database associated with the
** database object which is the subject of the event. It does not
** need to be specified if the handle is provided.
*/
char category_name_str[ ALARM_CATEGORY_NAME_MAXLEN + 1 ];
/*
** Handle for the category previously obtained through a call to
** the AlarmRegisterCategory() function. If the handle if specified
** the category name field is not used.
*/
ALARM_CATEGORY_HANDLE category_handle;
/*
** Name of the location associated with the database object which
** is the subject of the event. It does not need to be specified
** if the handle is provided.
*/
char location_name_str[ ALARM_LOCATION_NAME_MAXLEN + 1 ];
/*
** Handle for the location previously obtained through a call to
** the AlarmRegisterLocation() function. If the handle if specified
** the location name field is not used.
*/
ALARM_LOCATION_HANDLE location_handle;
/*
** The permission key (a PERMIT area) attached to the event.
*/
char permission_key[ ALARM_PERMISSION_KEY_MAXLEN + 1];
/*
** Timestamp attached to the event. Although a Timedate
** DTIME is used, the Alarm server only processes the first
** int (seconds) and ignore the second int (nanoseconds).
** This format is used to allow future use of a higher
** resolution.

*/
TIMEDATE_HABDTIME time;
/*
** Field timestamp. Some devices in the field are capable to timestamp
** status changes at the time they occur with sometimes a very good
** precision (milliseconds). This time may be specified and will be
** passed to the Alarm server but will not be used. The server will
** only write it in the database.
*/
TIMEDATE_HABDTIME field_time;
/*
** All the following fields are provided to convey information about
** the database object which the subject of the event. The time field
** and the fields that follow are used to create the character string
** that appears in the formatted LOGs as defined in the message
** definition (in a .ALMMSG file) attached to the exception.
*/
char text_string_str[ ALARM_STRING_MAXLEN + 1];
float real1;
float real2;
float real3;
float real4;
float real5;
float real6;
CCA_BOOL flag1;
CCA_BOOL flag2;
CCA_INT32 intval1;
CCA_INT32 intval2;
} ALARM_EVENT_BLOCK;
The same structure has the following members in Fortran:

STRUCTURE /ALARM_EVENT_BLOCK/
CHARACTER*8 EXCEPTION_NAME ! EXCDEF name

INTEGER*4 EXCEPTION_HANDLE
INTEGER*4 OBJECT_HANDLE ! User provided handle
INTEGER*4 OPTIONS ! Processing options
CHARACTER*10 CATEGORY_NAME ! CATEGORY name

CHARACTER*2 %FILL ! for alignment purpose
INTEGER*4 CATEGORY_HANDLE
CHARACTER*8 LOCATION_NAME ! LOCATION name

INTEGER*4 LOCATION_HANDLE
CHARACTER*8 PERMISSION_KEY
RECORD /TIMEDATE_HABDTIME/ TIME ! Event timestamp.

RECORD /TIMEDATE_HABDTIME/ FILED_TIME ! Not used in version 2.0
CHARACTER*128 TEXT_STRING ! Character string
REAL*4 REAL1 ! Real variable 1


INTEGER*4 FLAG1 ! BITMASK - 4 bytes

INTEGER*4 INTVAL1 ! Integer variable 1

END STRUCTURE
version
Should have the value ALARM_API_VERSION directly from alarm.h or alarm.inc. This argument
identifies the version of the interface definition. If the structure that is part of the API changes in the
future, the ALARM_API_VERSION will change so that it will be possible for the API to determine
whether it must convert an old structure being referenced by the user into the latest structure prior to
processing.
Description
This function allows a client to notify the Alarm server about an event or an alarm that occurred in
the system. Some validation and lookup operations are performed on the structure passed by the
client, and the event is sent to the Alarm server for processing.
If the alarm_use_hdbha function has been called, then this function can only be called from within an
Hdb update transaction. Failure to do so will cause the task to abort.
A default location and category handle can be used by clients that do not know about locations and
categories.
If the Alarm server goes down after the client task has successfully registered with Alarm,
ALARM_S_NORMAL is returned (instead of ALARM_E_SERVDOWN), and the posted event is buffered
until Alarm comes back up and the connection is restored.
Return Values
See Also
alarm_flush_events

alarm_post_event_ex
Syntax
status = alarm_post_event_ex ( event_block, version )

event_block ALARM_EVENT_BLOCK _EX* read
version Int read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmPostEventEx(
ALARM_EVENT_BLOCK_EX *event_block_ptr,
int version );
Fortran Binding
INTEGER*4 ALARM_POST_EVENT_EX( INTEGER*4 EVENT_BLOCK,
INTEGER*4 VERSION )
Arguments
event_block_ex
typedef struct
{
/*
*/
/*
** If a null handle is specified, the exception name must be provided.
*/
/*
** A handle and an identifier in order to uniquely identify the instance
** of the object definition associated with the event.
**
** Why two and how are they used?
**
** The "object_identifier" is provided to make it possible for
** an application to use Hdb OIDs to uniquely identify a record.

** But using OIDs could be costly for an application to find the
** record the OID is identifying which is why the "object_handle"
** is provided. For example the "object_handle" can be used to
** contain a record subscript while the "object_identifier" stores
** the OID. When a Ack callback fires, the application can get to the
** record using the "object_handle" and should verify that the OIDs
** are matching. Only a lookup will have to be done if they are not
** matching which should be the exception.
**
** The Alarm server will correlate alarms using the object identifier.
** If a zero object identifier is used and a non-zero object handle
** is used, Alarm will copy the object handle into the identifier.
**
** Both can be zero. this would implies that there is only
*/
/*
** A mask that can be built using the following values:
**
** database.
*/
#define ALARM_NOTONE 1
/*
*/
#define ALARM_NOWABNORMAL 2
/*
*/
#define ALARM_NOWUNACK 4
/*
** logged.
*/
#define ALARM_NOLIST 8
/*
** printed.
*/
#define ALARM_NOLOG 16
/*
** - ALARM_NOFIRST: This event is just posted to complement a previous
** one.
*/
#define ALARM_NOFIRST 32
/*
** - ALARM_NONOTIFY: This event should not trigger any notification
** (e-mail/pager).
*/
#define ALARM_NONOTIFY 64

/*
** A zero value is valid.
*/
int options;
/*
** If neither the category name nor the handle are specified, the
** default category defined in the ALARM database will be used.
*/
/*
**
** A default category can be used when posting an event by using the
** default category handle: ALARM_DEFAULT_CATEGORY_HANDLE
**
*/
/*
**
** A default location can be used when posting an event by using the
** default location handle: ALARM_DEFAULT_LOCATION_HANDLE
*/
/*
*/
/*
** The permission keys (areas of responsibility) attached to the event.
** One or more (up to 5) can be specified.
** The area handle is optional and can be used for performance optimization
** for applications that are tracking the unack objects on a per area
** basis. These handles will be passed back in the unack callback but
** they are not used by Alarm.
*/
char permission_key2[ ALARM_PERMISSION_KEY_MAXLEN + 1];

/*
** resolution.
*/
/*
*/
/*
** the database object which is the subject of the event. The time field
** definition attached to the exception.
** All the following fields are optional, but should match the message
** definition.
*/
float real1;
float real2;
float real3;
float real4;
float real5;
float real6;
CCA_UINT32 flag1;
CCA_UINT32 flag2;
CCA_UINT32 flag3; // Third flag introduced in HABITAT 5.2.1
CCA_INT32 intval1;
CCA_INT32 intval2;
/*
** The following field is considered as an URL that can be used to obtain
** information about the object being alarmed. The Alarm server will store
** this URL and the event/alarm will have a pointer to the record storing
** the URL so that it can be used by operators with just a mouse click
** (generating a DISPLAY/URL command)
*/
char url_str[ ALARM_URL_MAXLEN + 1];
} ALARM_EVENT_BLOCK_EX;

STRUCTURE /ALARM_EVENT_BLOCK_EX/

INTEGER*4 OBJECT_IDENTIFIER

CHARACTER*2 FILL ! for alignment purpose
INTEGER*4 CATEGORY_HANDLE

INTEGER*4 LOCATION_HANDLE
CHARACTER*8 PERMISSION_KEY2
RECORD /ALARM_TIME/ TIME ! Event timestamp.

RECORD /ALARM_TIME/ FIELD_TIME ! Not used in version 2.0



CHARACTER*81 URL_STR ! Url String
END STRUCTURE
version
processing.
Description
categories.
Allows for use with the extended event structure.

Return Values
See Also
alarm_store_event_ex

alarm_post_event_ex2
Syntax
status = alarm_post_event_ex2 ( event_block, user identification,
version )

event_block ALARM_EVENT_BLOCK _EX2* read
user_identification USER_IDENTIFICATION read
version int read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmPostEventEx2(
ALARM_EVENT_BLOCK_EX_EX *event_block_ptr,
int version );
Fortran Binding
INTEGER*4 ALARM_POST_EVENT_EX2( INTEGER*4 EVENT_BLOCK,
INTEGER*4 USER_ID,
INTEGER*4 VERSION )
Arguments
event_block_ex2
typedef struct
{
/*
*/
/*
*/
/*
** A handle and an identifier in order to uniquely identify the instance
** of the object definition associated with the event.

**
**
** record the OID is identifying which is why the "object_handle"
** the OID. When a Ack callback fires, the application can get to the
** matching which should be the exception.
**
**
** Both can be zero. this would implies that there is only
*/
/*
** The Composite ID is used to relate alarms to one another instead of
** using the object identifier
*/
char composite_id[ ALARM_COMPOSITE_ID_MAXLEN + 1 ];
/*
** The group Identifier is used to associate a subset of alarms together
** based on their relation to one another.
*/
/*
**
** database.
*/
/*
*/
/*
*/
/*
** logged.
*/

/*
** printed.
*/
/*
** one.
*/
/*
** (e-mail/pager).
*/
/*
** - ALARM_CUSTOM: These 10 flags are provided for customization purposes
*/
#define ALARM_CUSTOM1 128

/*
** - ALARM_BADFIELDTIME: The Field Time associated with this event
** is invalid. Used when the time value of the device supplying
** the value is not trusted.
*/
#define ALARM_BADFIELDTIME 131072
/*
*/
int options;
/*
*/
/*
**

**
*/
/*
**
*/
/*
*/
/*
** One or more (up to 5) can be specified. The area handle is optional
** and can be used for performance optimization for applications that
** are tracking the unack objects on a per area basis. These handles will
** be passed back in the unack callback but they are not used by Alarm.
*/
/*
** resolution.
*/
/*
*/
/*
** the database object which is the subject of the event. The time field

** All the following fields are optional, but should match the message
** definition.
*/
float real1;
float real2;
float real3;
float real4;
float real5;
float real6;
CCA_UINT32 flag1;
CCA_UINT32 flag2;
CCA_UINT32 flag4; // Fourth flag introduced in HABITAT 5.4
CCA_UINT32 flag5; // Fifth flag introduced in HABITAT 5.4
CCA_INT32 intval1;
CCA_INT32 intval2;
/*
** information about the object being alarmed. The Alarm server will store
*/
} ALARM_EVENT_BLOCK_EX2;

STRUCTURE /ALARM_EVENT_BLOCK_EX2/

INTEGER*8 OBJECT_IDENTIFIER
INTEGER*8 GROUP_IDENTIFIER
CHARACTER*56 COMPOSITE_ID

CHARACTER*2 FILL ! for alignment purpose
NTEGER*4 CATEGORY_HANDLE

NTEGER*4 LOCATION_HANDLE
RECORD /ALARM_TIME/ TIME ! Event timestamp.

RECORD /ALARM_TIME/ FIELD_TIME ! Not used in version 2.0




CHARACTER*81 URL_STR ! Url String
END STRUCTURE
user_id
the alarm text.
version
processing.
Description
categories.
Allows for use with the extended event structure.
Return Values

See Also

Sends an event to the enabled Alarm server with support for long name and MRID.
Syntax
version )

version Int read
C Binding
#include "alarm.h"
ALARM_EVENT_BLOCK_EX3 *event_block_ptr,
int version );
Fortran Binding
Not Supported
Arguments
event_block_ex3
{
/*
** A handle and an identifier are used to uniquely identify the instance
** of the object definition associated to the event.
**
**
** record the OID is identifying, which is why the "object_handle"
** the OID. When an Ack callback fires, the application can get to the
** matching, which should be the exception.
**

**
** Both can be zero. This would imply that there is only
*/
/*
** This OID is used as a generic identifier to link certain alarms
** together on a broader scale then the object_identifier.
** The proposed use is to link all alarms from a device together.
*/
/*
**
** database.
*/
/*
*/
/*
*/
/*
** logged.
*/
/*
** printed.
*/
/*
** one.
*/
/*
** (e-mail/pager).
*/
/*
*/

/*
** - ALARM_BADFIELDTIME: The Field Time associated with this event is
** invalid. Used when the time value of the device supplying the value
** is not trusted.
*/
#define ALARM_BADFLDTIME 131072
/*
*/
int options;
/*
*/
/*
**
**
*/
/*
*/
CCA_UINT32 flag1;
CCA_UINT32 flag2;

CCA_INT32 intval1;
CCA_INT32 intval2;
float real1;
float real2;
float real3;
float real4;
float real5;
float real6;
/*
** resolution.
*/
/*
*/
/*
*/
/*
**
*/
/*
** and can be used for performance optimization for applications that are
** tracking the unack objects on a per area basis. These handles will be
** passed back in the unack callback but they are not used by Alarm.
*/
/*

** All the following fields are optional.
*/
/*
** This character string is used to identify related alarms from a particular
** device to replace the object identifier as a way to associate related alarms
** together. The object identifier can still be used as it was in the past.
*/
/*
** There are two ways to identify the object of the alarm to the ALARM Server.
** These are the object's composite key and its MRID.
** When an alarm client calls AlarmPostEventEx3 or AlarmStoreEventEx3
** it can supply either the full composite key or its MRID. If only
** one or the other is specified the IMS can be used to look up the other.
** If both are specified then the MRID is used preferentially.
** Note that these identifiers are used for more than just long names.
** For example, Historian uses the MRID to preserve historical values
** in case a composite key or LongName is renamed.
** Replay uses on the MRID to allow ACK and DEL of alarms between sites which
** may be running different power system models. ETNAV will depend on the full
** composite key to locate displays containing the object being alarmed.
*/
/*
*/
/*
** information on the object being alarmed. The Alarm server will store
*/
/*
** -----------------------
**
** else if (2) exists, use mrid_list and ask IMS to translate MRIDs to LongNames

** else if (3) exists, use composite_key_list and ask IMS to translate CompKeys to
LongNames
** else no long name translation.
*/
};
user_id
the alarm text.
version
This argument has the value ALARM_API_VERSION directly from alarm.h. It identifies the version of
the interface definition. If the structure that is part of the API changes in the future,
ALARM_API_VERSION changes so that it is possible for the API to determine whether it must convert
an old structure, being referenced by the user, into the latest structure prior to processing.
Description
If the alarm_use_hdbha function is called, this function can only be called from within an Hdb update
transaction. Failure to do so causes the task to abort.
categories.
ALARM_S_NORMAL is returned (instead of ALARM_E_SERVDOWN) and the posted event is buffered
The EX3 version of this function is an extension of the EX2 version of the same function with added
support for entering MRIDs, a composite key list, or a long-name list.
The ALARM_EVENT_BLOCK_EX3 block structure provides additional fields and data types to support
the different ways to specify long name parameters. These new types are:
• AlarmLongNameList: A list of string objects representing the actual long names. This is used
when the Alarm client already has the long names available.
• AlarmMridList: A list of string objects where each represents an MRID. Alarm translates this MRID
to the equivalent long names.
• AlarmCompositeKeyList: A list of AlarmCompositeKey objects, where each object contains a
domain/composite key pair. Together, the domain and composite key is used by Alarm to locate
the MRID, which translates to a long name string.
• AlarmCompositeKey: A structure to hold the “domain” string and “composite key” string. The
“domain” identifies the name of the domain in which the “composite key” has meaning. For
example, the same Substation in SCADA and in NETWORK have different composite keys. The
AlarmCompositeKey in the SCADA domain may be { “hdb-scadamom”,
“SCADEK=SUBSTN;SUBSTN=KINCARD”}, and the same object in the NETWORK domain may be

{“hdb-netmom”, “DECK=TOPOLOGY;CO=NEPOOL;DV=EAST;ST=KINCARD”}. This field is needed to
support ETNAV.
• AlarmMrid: A string object that represents the MRID of the items being alarmed. Although the
same substation might have different composite keys in different domains, it will have the same
MRID. This field is needed to support REPLAY and Historian.
Note: Do not use memcpy, memmove, or memset on it. It contains C++ objects.
Return Values
See Also
alarm_store_event_ex3

Sends an event to the enabled Alarm server with support for Safety flag and State name.
Syntax
version )

version Int read
C Binding
#include "alarm.h"
int version );
Fortran Binding
Not Supported
Arguments
event_block_ex4
{
/*
**
**
**

**
*/
/*
*/
/*
**
** database.
*/
/*
*/
/*
*/
/*
** logged.
*/
/*
** printed.
*/
/*
** one.
*/
/*
** (e-mail/pager).
*/
/*
*/

/*
** is not trusted.
*/
/*
** - ALARM_SAFETY: The option indicates that the event is safety related
*/
#define ALARM_SAFETY 262144
/*
*/
int options;
/*
*/
/*
**
**
*/
/*
*/
CCA_UINT32 flag1;

CCA_UINT32 flag2;
CCA_INT32 intval1;
CCA_INT32 intval2;
float real1;
float real2;
float real3;
float real4;
float real5;
float real6;
/*
** resolution.
*/
/*
*/
/*
*/
/*
**
*/
char location_name_str[ ALARM_LOCATION_NAME_MAXLEN_V6 + 1 ];
/*
*/

/*
*/
/*
*/
/*
*/
/*
*/
/*
*/
char state_str[ ALARM_STATE_NAME_MAXLEN + 1];
/*
** The 4 strings are for future use.
*/
char string1[ ALARM_EXTRA_STRING_MAXLEN + 1];

/*
** -----------------------
**
** else if (3) exists, use composite_key_list and ask IMS to translate CompKeys
** to LongNames else no long name translation.
*/
};
user_id
the alarm text.
version
Description
categories.
support for safety flag and state string, and increased size for the location name.
These new types are:
• ALARM_SAFETY: A flag to indicate that the event is safety related.

• state_str: A string to hold a state name.
• string1: A string for future use.
Return Values
See Also

Sends an event to the enabled Alarm server with support for the alarm’s own MRID.
Syntax
version )

version Int read
C Binding
#include "alarm.h"
int version );
Fortran Binding
Not Supported
Arguments
event_block_ex5
{
/*
**
**
**

**
*/
/*
*/
/*
**
** database.
*/
/*
*/
/*
*/
/*
** logged.
*/
/*
** printed.
*/
/*
** one.
*/
/*
** (e-mail/pager).
*/
/*
*/

/*
** is not trusted.
*/
/*
** - ALARM_SAFETY: The option indicates that the event is safety related
*/
#define ALARM_SAFETY 262144
/*
*/
int options;
/*
*/
/*
**
**
*/
/*
*/
CCA_UINT32 flag1;

CCA_UINT32 flag2;
CCA_INT32 intval1;
CCA_INT32 intval2;
float real1;
float real2;
float real3;
float real4;
float real5;
float real6;
/*
** resolution.
*/
/*
*/
/*
*/
/*
**
*/
char location_name_str[ ALARM_LOCATION_NAME_MAXLEN_V6 + 1 ];
/*
*/

/*
*/
/*
*/
/*
*/
/*
*/
/*
** The 4 strings are for future use.
*/
/*
*/

/*
** -----------------------
**
** else if (3) exists, use composite_key_list and ask IMS to translate CompKeys
** to LongNames else no long name translation.
*/
// alarm’s own mrid

AlarmMrid alarm_mrid;
};
user_id
the alarm text.
version
Description
categories.
support for the alarm’s own MRID.

These new types are:
• ALARM_SAFETY: A flag to indicate that the event is safety related.
• state_str: A string to hold a state name.
Return Values
See Also

alarm_register_category
Validates and registers a category.
Syntax
status = alarm_register_category( category_name, category_handle_ptr )

category_name character string read
category_handle_ptr ALARM_CATEGORY_HANDLE * write
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmRegisterCategory(
const char category_name_str[],
ALARM_CATEGORY_HANDLE *category_handle_ptr);
Fortran Binding
INTEGER*4 ALARM_REGISTER_CATEGORY(
CHARACTER*(*) CATEGORY_NAME
INTEGER*4 CATEGORY_HANDLE )
Arguments
category_name
Name of the category as defined in the Alarm database.
category_handle
Location where the handle to the category will be returned. The handle should be retained for future
use (when posting an event). If the category was not found, the handle will be NULL.
Description
This function has two purposes:
• Verifies that the category is valid and known by the Alarm server.
• Provides a handle that the client can use when posting events. If the handle is retained and used,
the Alarm API does not need to perform a lookup at the time the client posts an event since the
handle will allow the Alarm server to quickly locate the category in its internal database.
The registration performed by this function is only valid for the Alarm server that the API is connected
to. If the API loses its connection and then re-establishes it (with the same server or not), the
registration is considered lost and should be done again.
Return Values
ALARM_E_BADCAT: Category not defined in the Alarm database.

See Also

Initializes the Alarm interface and identifies the caller to Alarm.
Syntax
status = alarm_register_client ( client_name, ready_cb, userarg)

client_name character string read
ready_cb ALARM_READY_CB call
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmRegisterClient(
const char client_name_str[],
ALARM_READY_CB ready_cb,
Fortran Binding
INTEGER*4 ALARM_REGISTER_CLIENT( CHARACTER*(*) CLIENT_NAME,
INTEGER*4 READY_CB,
INTEGER*4 USERARG )
Arguments
client_name
Name of the client to be registered with Alarm. This name is used by the Alarm server to display
statistics for each client. It should not duplicate the name used by another task using the same Alarm
server. Underscore (“_”) characters are not allowed in the client name.
ready_cb
Address of the function to be called when initialization is done, meaning that data about the client’s
application has been downloaded from the Alarm server into the API.
The function has two arguments:
typedef void (*ALARM_READY_CB ) (SCF_STATUS status,
SUBROUTINE ALARM_READY_CB( INTEGER*4 STATUS,
INTEGER*4 USERARG )
The possible SCF statuses are:
• ALARM_S_NORMAL: Normal successful completion.
• ALARM_E_NOSUCHAPP: The application the user is running under is not defined in the Alarm
server.
• ALARM_E_DUPCLIENT: The client name duplicates an already registered client.

userarg
Description
This function initializes the Alarm API. It must be called after the ppm_init function and before any
other Alarm functions.
This function establishes a communication path with the Alarm server using the NIOSOCK API. It is
assumed that, within the site and for a given family, only one Alarm server is enabled at a given time.
The Alarm server that the API should connect to is identified according to the following rule:
• If the caller is started by PROCMAN, its PROCMAN family is assumed to be the family used by the
Alarm server.
• Otherwise, the caller’s family is used.
Once the communication path is established, the client is registered under this application. The Alarm
server downloads all the data related to this application and, once the download is complete, the
ready callback is invoked. Every time the communication path gets lost and is re-established (during a
failover, for example), a download is performed and the client callback is invoked.
Once the ready callback is invoked, the client can call the AlarmRegisterException,
AlarmRegisterCategory, and AlarmRegisterLocation functions. If the Alarm server is not running, the
user is notified. The connection attempt needs to be implemented on the user side. If the client is not
running on the computer where either the enabled or the standby Alarm server is running, the
ALARM_REMOTE_SERVER environment variable should be defined to prevent this call from returning a
SERVDOWN status.
By default, the API is set so that every client does NOT require bundling of the replication of database
object changes with the replication of the associated events. Therefore, by default, the API does not
use the Hdb High Availability services, but lets the Alarm server take care of the replication of the
events. If this is not the desired behavior, the client should call the alarm_use_hdbha function.
By default, it is assumed that the client does not need the acknowledged/unacknowledged state of a
database object. However, if a client needs to maintain its own list of unacknowledged objects, the
alarm_enum_unack_objects function should be called once the ready callback routine is invoked.
Calling this function more than once within the same process and without calling the
AlarmUnregisterClient function is a fatal error that causes the process to abort.
Environment
The caller must be a PPM-compliant application.
Return Values
• ALARM_S_NORMAL: Normal successful completion.
See Also
ppm_init

alarm_register_exception
Validates and registers an exception definition.
Syntax
status = alarm_register_exception( exception_id, exception_handle_ptr )

exception_id character string read
exception_handle_ptr ALARM_EXCEPTION_HANDLE * write
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmRegisterException(
const char exception_id_str[],
ALARM_EXCEPTION_HANDLE *exception_handle_ptr);
Fortran Binding
INTEGER*4 ALARM_REGISTER_EXCEPTION(
CHARACTER*(*) EXCEPTION_ID,
INTEGER*4 EXCEPTION_HANDLE )
Arguments
exception_id
Identifier of the exception definition as defined in the Alarm database.
exception_handle
Location where the handle to the exception will be returned. The handle should be retained for future
use (when posting an event). If the exception was not found, the handle will be NULL.
Description
• Verifies that the exception ID is valid and known by the Alarm server.
then the Alarm API does not need to perform a lookup at the time the client posts an event, since
the handle will allow the Alarm server to quickly locate the exception definition in its internal
database.
The registration performed by this function is only valid for the Alarm server the API is connected to. If
the API loses its connection and then re-establishes it (with the same server or not), the registration is
considered lost and should be done again.
Return Values

ALARM_E_BADEXC: Exception not defined in the Alarm database.
See Also

alarm_register_location
Validates and registers a location.
Syntax
status = alarm_register_location( location_name, location_handle_ptr )

location_name character string read
location_handle_ptr ALARM_LOCATION_HANDLE * write
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmRegisterLocation(
const char location_name_str[],
ALARM_LOCATION_HANDLE *location_handle_ptr);
Fortran Binding
INTEGER*4 ALARM_REGISTER_LOCATION(
CHARACTER*(*) LOCATION_NAME
INTEGER*4 LOCATION_HANDLE )
Arguments
location_name
Name of the location as defined in the Alarm database.
location_handle
Location where the handle to the location will be returned. The handle should be retained for future
use (when posting an event). If the location was not found, the handle will be NULL.
Description
• Verifies that the location is valid and known by the Alarm server.
then the Alarm API does not need to perform a lookup at the time the client posts an event, since
the handle will allow the Alarm server to quickly locate the location in its internal database.
The registration performed by this function is only valid for the Alarm server the API is connected to. If
the API loses its connection and then re-establishes it (with the same server or not), the registration is
considered lost and should be done again.
Return Values
ALARM_E_BADLOC: Location not defined in the Alarm database.

See Also

alarm_reset_lists
Resets the alarm list and the formatted logs maintained by the Alarm server.
Syntax
status = alarm_reset_lists()

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmResetLists();
Fortran Binding
INTEGER*4 ALARM_RESET_LISTS()
Arguments
None
Description
This function resets the alarm list and the formatted LOGs maintained by the Alarm server. It is
intended to be used for testing purposes, and possibly by Grid Simulation when it is restarting or
when it is initializing to a new start time.
Return Values
ALARM_E_NOCOMMS: No connection with the Alarm server.
ALARM_E_SERVDOWN: The Alarm server is not running.

Stores an acknowledgment request in a buffer managed by the Alarm API.
Syntax
status = alarm_store_acknowledgment( object_name, object_handle,
time, station )

object_handle CCA_HANDLE read
time TIMEDATE_HABTIME read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmStoreAcknowledgment(
TIMEDATE_HABTIME time,
const char station_str );
Fortran Binding
INTEGER*4 ALARM_STORE_ACKNOWLEDGMENT(
TIMEDATE_HABTIME TIME,
CHARACTER*(*) STATION )
Arguments
object_name
object_handle
posted.
time
station

ALARM_STATION_NAME_MAXLEN constant. This argument is mandatory since it may be used for
logging purposes. A special default name identified by the ALARM_DEFAULT_STATION can be used
and will cause Alarm to perform the acknowledgment request without checking for permissions.
Description
This function stores an acknowledgment request of all the related alarms associated with a database
object. It is assumed that the client will at some point invoke the alarm_flush_acknowledgments
function to send to the Alarm server all the requests that have been previously stored.
call to the alarm_enum_unack_objects function, the “ack” callback will be invoked once the Alarm
alarm_enum_unack_objects function, the “ack” callback will be invoked with the
Return Values
See Also
alarm_acknowledge

Syntax
status = alarm_store_acknowledgment_ex( object_name, object_identifier,
ack_time, station, user_id,
permission_key )

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmStoreAcknowledgmentEx(
const char user_id,
Fortran Binding
INTEGER*4 ALARM_STORE_ACKNOWLEDGMENT_EX(
OBJ_ID OBJECT_IDENTIFIER,
CHARACTER*(*) STATION,
CHARACTER*(*) USER_ID,
Arguments
object_name
object_identifier
posted.

ack_time
station
user_id
permission_key
A character string that identifies the area under which the alarm is requested to be acknowledged.
An asterisk in this field will act as a wildcard and will acknowledge the alarm for all assigned
permission areas.
Description
Return Values
See Also
alarm_acknowledge

Syntax
status = alarm_store_acknowledgment_ex2( object_name, composite_id,
ack_time, user_id,
permission_key )

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmStoreAcknowledgmentEx2 (
Fortran Binding
INTEGER*4 ALARM_STORE_ACKNOWLEDGMENT_EX2(
CHARACTER*(*) COMPOSITE_ID,
INTEGER*4 USER_ID,
Arguments
object_name
composite_id
Represents a string identifying a particular instance of the object definition. This string is passed at
the time the event is posted.

ack_time
user_id
the alarm text.
permission_key
A character string that identifies the area under which the alarm is requested to be deleted.
Description
Return Values
See Also
alarm_acknowledge

Syntax
status = alarm_store_acknowledgment_ex3( object_name, object_mrid,
object_comp_key, ack_time,
user_id, permission_key,
application_name )

C Binding
#include "alarm.h"
extern SCF_STATUS AlarmStoreAcknowledgmentEx3 (
AlarmMrid object_mrid[],
const char permission_key,
Fortran Binding
None
Arguments
object_name
object_mrid

object_comp_key
ack_time
user_id
the alarm text.
permission_key
A character string that identifies the area under which the alarm is requested to be deleted.
application_name
Description
Return Values
See Also
alarm_acknowledge


alarm_store_event
Stores an event intended for the Alarm server in a buffer managed by the Alarm API.
Syntax
status = alarm_store_event ( event_block, version )

event_block ALARM_EVENT_BLOCK * read
version int read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmStoreEvent(
ALARM_EVENT_BLOCK event_block,
version );
Fortran Binding
INTEGER*4 ALARM_STORE_EVENT( INTEGER*4 EVENT_BLOCK,
INTEGER*4 VERSION )
Arguments
event_block
See the description for the alarm_post_event function.
version
processing.
Description
This function stores an event in an internal buffer managed by the Alarm API. Multiple events can be
stored in this buffer and can then be sent to the Alarm server with a call to the alarm_flush_events
function. By default, the maximum number of events stored is 4000. If the environment variable
alarm_events_buffered_max is defined, the API will use this value instead.
This function should be used by clients that have called the alarm_use_hdbha function when they
detect an event outside of an Hdb update transaction. It can also be used by a regular client for
optimization purposes, since the number of I/O operations is reduced compared to multiple calls to
the alarm_post_event function.
A “sanity check” and a lookup for exceptions, categories, and locations will be performed before
storing the buffer.

Return Values
See Also
alarm_post_event

alarm_store_event_ex
Syntax
status = alarm_store_event_ex ( event_block, version )

event_block ALARM_EVENT_BLOCK_EX * read
version Int read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmStoreEventEx(
ALARM_EVENT_BLOCK_EX event_block,
int version );
Fortran Binding
INTEGER*4 ALARM_STORE_EVENT_EX( INTEGER*4 EVENT_BLOCK,
INTEGER*4 VERSION )
Arguments
event_block_ex
See the description for the alarm_post_event_ex function.
version
processing.
Description
the alarm_post_event_ex function.
storing the buffer.

The extended functionality allows for the use of 64-bit object handle names inside the acknowledge
callback. The original function only allowed 32-bit object handle names and therefore will not allow
Browser object handles to be attached to the event. The extended function is added for this purpose.
Return Values
See Also
alarm_post_event_ex
alarm_post_event

Syntax
status = alarm_store_event_ex2 ( event_block, user_id, version )

event_block ALARM_EVENT_BLOCK_EX2 * read
version Int read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmStoreEventEx2(
ALARM_EVENT_BLOCK_EX2 event_block,
int version );
Fortran Binding
INTEGER*4 ALARM_STORE_EVENT_EX2( INTEGER*4 EVENT_BLOCK,
INTEGER*4 USER_ID,
INTEGER*4 VERSION )
Arguments
event_block_ex2
See the description for the alarm_post_event_ex2 function.
user_id
the alarm text.
version
processing.
Description

the alarm_post_event_ex2 function.
storing the buffer.
Return Values
See Also
alarm_post_event
alarm_post_event_ex

Stores an event intended for the Alarm server in a buffer managed by the Alarm API with long name
and MRID support.
Syntax

version Int read
C Binding
#include "alarm.h"
ALARM_EVENT_BLOCK_EX3* event_block,
int version );
Fortran Binding
Not supported
Arguments
event_block_ex3
user_id
the alarm text.
version
Description
function. By default, the maximum number of stored events is 4000. If the environment variable
alarm_events_buffered_max is defined, the API uses this value instead.

optimization purposes since the number of I/O operations is reduced compared to multiple calls to
A “sanity check” and a lookup for exceptions, categories, and locations is performed before storing
the buffer.
support for entering MRIDs, a composite key list, or a long-name list.
the different ways to specify long name parameters. For more information about these data types,
see alarm_post_event_ex3.
Return Values
See Also

Stores an event intended for the Alarm server in a buffer managed by the Alarm API with safety flag
and state name.
Syntax

version Int read
C Binding
#include "alarm.h"
int version );
Fortran Binding
Not supported.
Arguments
event_block_ex4
user_id
This structure contains user information for the event. This information includes the user name, the
PC name, and the station name. This is used for logging purposes only when filling in proxies in the
alarm text.
version
Description
function. By default, the maximum number of stored events is 4,000. If the environment variable

the buffer.
support for safety flag and state name, and increased size for the location name.
Return Values
See Also

Stores an event intended for the Alarm server in a buffer managed by the Alarm API with the alarm’s
own MRID.
Syntax

event_block ALARM_EVENT_BLOCK_EX5* read
version Int read
C Binding
#include "alarm.h"
int version );
Fortran Binding
Not supported.
Arguments
event_block_ex5
user_id
This structure contains user information for the event. This information includes the user name, the
PC name, and the station name. This is used for logging purposes only when filling in proxies in the
alarm text.
version
Description
function. By default, the maximum number of stored events is 4,000. If the environment variable

the buffer.
support for safety flag and state name, and increased size for the location name.
Return Values
ALARM_E_SERVDOWN: The Alarm server is not running.
See Also

alarm_subscribe
Subscribes to all events processed by the Alarm server.
Syntax
alarm_subscribe( event_cb, ack_cb, del_cb, options, userarg )

event_cb ALARM_SUBSCRIBE_EVENT_CALLBACK read
ack_cb ALARM_SUBSCRIBE_ACK_CALLBACK read
del_cb ALARM_SUBSCRIBE_EL_CALLBACK read
options int read
C Binding
#include "alarm.h"
void AlarmSubscribe( ALARM_SUBSCRIBE_EVENT_CALLBACK event_cb,
ALARM_SUBSCRIBE_ACK_CALLBACK ack_cb,
ALARM_SUBSCRIBE_DEL_CALLBACK del_cb,
int options,
Fortran Binding
None
Arguments
event_cb
A callback function to be executed when the alarm has been signaled. If the address of this function is
set to 0, then no callback will be sent.
typedef void ( *ALARM_SUBSCRIBE_EVENT_CALLBACK ) (
ALARM_SUBSCRIBE_EVENT_BLOCK *event_ptr,
Where:
• Event_ptr: Contains the information required for the acknowledge callback.
• ALARM_SUBSCRIBE_EVENT_BLOCK structure:
typedef struct
{
char category_name_str[ ALARM_CATEGORY_NAME_MAXLEN + 1];
char location_name_str[ ALARM_LOCATION_NAME_MAXLEN + 1];
char objdef_name_str[ ALARM_OBJECT_NAME_MAXLEN + 1];
int priority;
CCA_UINT16 ackdel_state; // This is what should
// used by the Alarm
// viewer

// Note that only one of
// the first 4 bits
// should
// ever be set but the
// fifth is independent
// of the others.
#define ALARM_UNACK_ALARM 1 // Should show up in the
// event
// and alarm lists
#define ALARM_ACKED_ALARM 2 // Should show up in the
// event
// and alarm lists
#define ALARM_DELETED_ALARM 4 // A deleted Alarm
// appears in
// the event list
// but not in the alarm
// lists
#define ALARM_EVENT 8 // Only in the event
// lists.
#define ALARM_AUDIBLE 16 // This bit indicates
// whether
// or not the event
// could generate a
// tone.
CCA_UINT16 object_state;
#define ALARM_OBJECT_NORMAL 1
#define ALARM_OBJECT_ABNORMAL 2
CCA_UINT32 color_flags;
#define ALARM_CAT_WHITE 1
#define ALARM_CAT_GREEN 2
#define ALARM_CAT_YELLOW 4
#define ALARM_CAT_ORANGE 8
#define ALARM_CAT_MAGENTA 16
#define ALARM_CAT_RED 32
#define ALARM_CAT_CYAN 64
#define ALARM_CAT_BLUE 128
ALARM_64BIT_HANDLE object_handle;
CCA_UINT32 sequence_number; // Sequence number of the event.

CCA_INT32 options; // Those specified by the caller.
char msgset_name_str[ ALARM_MSGSET_NAME_MAXLEN + 1];

char mlf_msg_str[ ALARM_MLF_MESSAGE_MAXLEN + 1];
float real1;
float real2;
float real3;

float real4;
float real5;
float real6;
CCA_BOOL flag1;
CCA_BOOL flag2;
CCA_BOOL flag3;
CCA_INT32 intval1;
CCA_INT32 intval2;
/*
** The following field is used by the Callout server.
** (it contains the notification list ID),
*/
char additional_info[ 8 + 1];
} ALARM_SUBSCRIBE_EVENT_BLOCK;
Where:
ack_cb
A callback function to be executed when the alarm has been acknowledged. If the address of this
function is set to 0, then no callback will be sent.
typedef void ( *ALARM_SUBSCRIBE_ACK_CALLBACK ) (
CCA_UINT32 sequence_number,
const char area_str[ ALARM_PERMISSION_KEY_MAXLEN + 1],
const char area2_str[ ALARM_PERMISSION_KEY_MAXLEN + 1],
Where:
• sequence_number: An unsigned 32-bit integer that corresponds to a particular event.
• area_str(n): Areas under which the alarm is requested to be deleted.
del_cb
A callback function to be executed when the alarm has been selected for deletion. If the address of
this function is set to 0, then no callback will be sent.
typedef void ( *ALARM_SUBSCRIBE_DEL_CALLBACK ) (
Where:
• area_str(s): Areas under which the alarm is requested to be deleted.

options
An integer argument that can have one of two values.
ALARM_SUBSCRIBE_ALL 1
Subscribe all alarms and events available.
ALARM_SUBSCRIBE_CALLOUT 2
Subscribe only those events that will trigger an e-mail or pager message.
userarg
Description
This function allows an application to subscribe to all events processed by the Alarm server. In
addition, it allows an application to acknowledge and delete notifications generated by the Alarm
server. When the subscription is complete, the Alarm server will return all of the events to the client in
the past x minutes specified by the ALARM_SUBSCRIBE_TIME environment variable. When this
variable is not defined, then no events are returned until an incoming event is detected.
Return Value
None
See Also
alarm_subscribe_ex
alarm_subscribe_ex2

alarm_subscribe_ex
Syntax
alarm_subscribe_ex( event_cb, ack_cb, del_cb, options, userarg )

event_cb ALARM_SUBSCRIBE_EVENT_CALLBACK_EX read
options int read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmSubscribeEx(
ALARM_SUBSCRIBE_EVENT_CALLBACK_EX event_cb,
int options,
Fortran Binding
None
Arguments
event_cb
typedef void ( *ALARM_SUBSCRIBE_EVENT_CALLBACK_EX ) (
ALARM_SUBSCRIBE_EVENT_BLOCK_EX *event_ptr,
Where:
• ALARM_SUBSCRIBE_EVENT_BLOCK_EX structure:
typedef struct
{
char location_name_str[ ALARM_LOCATION_NAME_MAXLEN + 1];
int priority;

// viewer
// the first 4 bits
// should
// of the others.
// event
// and alarm lists
// event
// and alarm lists
// appears in
// the event list
// lists
// lists.
// whether
// or not the event
// could generate a
// tone.


float real1;
float real2;

float real3;
float real4;
float real5;
float real6;
CCA_BOOL flag1;
CCA_BOOL flag2;
CCA_BOOL flag3;
CCA_INT32 intval1;
CCA_INT32 intval2;
/*
*/
char guid_str[ ALARM_GUID_MAXLEN + 1];
} ALARM_SUBSCRIBE_EVENT_BLOCK_EX;
Where:
ack_cb
Where:
del_cb

Where:
options
ALARM_SUBSCRIBE_ALL 1
Subscribe all alarms and events available.
ALARM_SUBSCRIBE_CALLOUT 2
Subscribe only those events that will trigger an e-mail or pager message.
userarg
Description
variable is not defined, no events are returned until an incoming event is detected.
Return Value
See Also
alarm_subscribe
alarm_subscribe_ex2

alarm_subscribe_ex2
Syntax
alarm_subscribe_ex2( event_cb, ack_cb, del_cb, options, userarg )

event_cb ALARM_SUBSCRIBE_EVENT_CALLBACK_EX2 read
options int read
C Binding
#include "alarm.h"
extern SCF_STATUS AlarmSubscribeEx2(
ALARM_SUBSCRIBE_EVENT_CALLBACK_EX2 event_cb,
int options,
Fortran Binding
None
Arguments
event_cb
typedef void ( *ALARM_SUBSCRIBE_EVENT_CALLBACK_EX2 ) (
ALARM_SUBSCRIBE_EVENT_BLOCK_EX2 *event_ptr,
Where:
• ALARM_SUBSCRIBE_EVENT_BLOCK_EX2 structure:
typedef struct
{
char location_name_str[ ALARM_LOCATION_NAME_MAXLEN_V6 + 1];
int priority;

// viewer
// the first 4 bits should
// of the others.
// event
// and alarm lists
// event
// and alarm lists
// appears in
// the event list
// lists
// lists.
// whether
// or not the event
// could generate a
// tone.


float real1;
float real2;
float real3;

float real4;
float real5;
float real6;
CCA_BOOL flag1;
CCA_BOOL flag2;
CCA_BOOL flag3;
CCA_INT32 intval1;
CCA_INT32 intval2;
/*
*/
char guid_str[ ALARM_GUID_MAXLEN + 1];

} ALARM_SUBSCRIBE_EVENT_BLOCK_EX2;
Where:
ack_cb
Where:
del_cb

Where:
options
ALARM_SUBSCRIBE_ALL 1: Subscribe all alarms and events available.
ALARM_SUBSCRIBE_CALLOUT 2: Subscribe only those events that will trigger an e-mail or pager
message.
userarg
Description
variable is not defined, no events are returned until an incoming event is detected.
Return Value
See Also
alarm_subscribe
alarm_subscribe_ex

alarm_unregister_client
This function un-initializes the Alarm API and guarantees the caller that no Alarm-related callbacks
will be invoked after calling this function.
Syntax
alarm_unregister_client ( )
C Binding
#include "alarm.h"
extern void AlarmUnregisterClient();
Fortran Binding
SUBROUTINE ALARM_UNREGISTER_CLIENT()
Arguments
None
Description
This function un-initializes the Alarm API and guarantees the caller that no Alarm-related callbacks
will be invoked after calling this function.
This function is intended to be used by clients that are running on the standby machine in an idle
state and that only want to deal with Alarm callbacks when they are running on the primary machine.
Such clients are typically running under Cfgman control and would only register with Alarm once they
received the enable role. It also allows clients to not connect to the enabled Alarm server when they
are running on the standby with a different database than the one currently used on the primary and
it would not make sense to try to register exceptions, categories, or locations with this Alarm server.
If a client uses the alarm_store_event or alarm_store_ack function, all buffers must be flushed prior
to unregister with Alarm.
The only Alarm API function that can be called after invoking this function is the alarm_register_client
function.
Environment
The caller must be a PPM-compliant application.
Return Value
None
See Also

alarm_use_hdbha
Notifies the Alarm API that Hdb High Availability services should be used to bundle the events
replication with the database object state replication.
Note: This function has no effect if the caller is not running in the real-time environment (if
HulInRealtimeEnvironment() returns false).
Syntax
alarm_use_hdbha()
C Binding
#include "alarm.h"
extern void AlarmUseHdbha();
Fortran Binding
SUBROUTINE ALARM_USE_HDBHA()
Arguments
None
Description
A client should only call this function if the client has a need to bundle the replication of each event
with the replication of the associated database object. For example, it is critical that a change of state
for a point and the event signaling that change are both replicated on the standby machine. If only
the state were going to the standby before a failover occurs, the alarm would be lost. (However, if
neither of the two reaches the standby machine before a failover, then the alarm will be reissued by
Scada.)
This function should be called before posting any events.
Calling this function has the following implications:
• The client must be an Hdb user.
• Replication only occurs as a result of an Hdb update transaction. To replicate the events, the
alarm client should store its events when outside of an Hdb transaction using the
alarm_store_event function and can only call the alarm_flush_events function from within an
update transaction; failure to do so will result in the task aborting. A single event posting can still
be done using the alarm_post_event function as long as it is invoked from within an update
transaction.
It is possible to disable the calls to the MRS API by defining the ALMAPI_DONT_USE_MRSAPI
environment variable. This should only be used for testing purposes or within a single-computer
environment (such as Grid Simulation).
Return Value
None
See Also

14. The Alarm Test Program
The objective of this chapter is to present the Alarm test program, which can be used for
the following purposes:
• To test the Alarm API and the Alarm server
• To generate a flow of alarms to evaluate the server’s performance
• To serve as a debugging tool in some situations
14.1 Running the Alarm Test Program

The Alarm test program is an APITEST8 program delivered in the ALARM codeset. The
executable is named “alarm_test” and can be run from any interactive terminal. The
program requires a Habitat context, and it should be run in the same family as the Alarm
server; otherwise, no connection can be established.
Figure 31. Alarm API Test Menu
8
Refer to the document Introduction to Habitat Programming.
Proprietary – See Copyright Page 244 The Alarm Test Program

The application can be any application defined with an APP record in the Alarm database.
For example, you can invoke the Alarm test program as follows:
context my_app my_fam
alarm_test
The test program opens with the Alarm API Test menu (Figure 31). Any of the Alarm API
functions can be invoked from this menu, and two other menus can also be activated:
• The Alarm Performance menu provides the ability to generate a given number of events
over a period of time.
• The Backup-Replication API menu provides the ability to test some of the API functions
used by the MRS subsystem. This menu should be used only by people who have a
detailed knowledge of Alarm and MRS.
14.2 The Alarm Performance Test Menu

By default, the Alarm test program starts with the Alarm API Test menu, from which the
Alarm Performance Test menu (Figure 32) can be invoked.
Figure 32. Alarm Performance Test Menu
The purpose of the functions provided in the Alarm Performance Test menu is to register
exceptions, categories, and locations to the Alarm API, and then to direct the test program
so that it posts a number of events over a period of time using the exceptions, categories,
and locations that have been registered.
To streamline the registration of exceptions, categories, and locations, an /ALL option is
provided. It instructs the test program to register all the exceptions or categories that are
defined under the application that has been chosen to run the test program. The same

applies to locations, except that all the locations defined in the Alarm database are
registered.
After at least one exception, one category, and one location have been registered, the Run
performance test function can be invoked. It prompts the user for the following:
• Test type: Events are generated one by one using the AlarmPostEvent function, or they
are first stored using the AlarmStoreEvent function and flushed at the end of the run.
• Number of minutes: Defines the period of time used to generate events.
• Event distribution: If YES is chosen, the test program only prompts the user once for the
number of events to generate per minute. Otherwise, the test program prompts the user
for a number of events for every minute.
• Number of alarms per minute
• Starting object handle: Instructs the test program to generate the first event with the
specified number. This number is then incremented for the next event.
• Use handles: The test program can either use handles for the exceptions, categories,
and locations, or the program can pass strings instead. This allows for measurement of
the Alarm API performance.
14.3 The Alarm Backup-Replication API Menu

Alarm Backup-Replication API menu can be invoked.
The purpose of the Alarm Backup-Replication API menu is to test the functionality that
sends alarms to the backup Energy Management System (EMS) for redundancy. With these
commands, a user can test to make certain that the backup EMS is running and is receiving
the replicated events and logging them correctly.
Figure 33. Alarm Replication API Test Menu

14.4 The Alarm API Validation Test Menu
Alarm API Validation Test menu (Figure 34) can be invoked.
Figure 34. Alarm API Validation Test Menu
The Alarm API Validation Test menu allows the user to verify whether the specified entries
for the exception, category, or location are valid. The entire list of valid exceptions,
categories, or locations can also be checked.

14.5 The Alarm Extended Function Test Menu
Alarm Extended Function Test menu (Figure 35) can be invoked.
Figure 35. Alarm Extended Function Test Menu
The purpose of the Alarm Extended Function Test menu is to allow the user to test functions
in addition to those tested on the Alarm API Test menu. These tests allow the user to specify
that a 64-bit object identifier for the alarm be used instead of the object handle. With the
extended functions, it is possible to enter up to five permission areas for each alarm to test
the multiple areas that are now available in Alarm.

14.6 The Alarm Subscribe Function Test Menu
Alarm Subscribe Function Test menu (Figure 36) can be invoked.
Figure 36. Alarm Subscribe Function Test Menu
The purpose of the Alarm Subscribe Function Test menu is to allow the testing of single
alarm functionality. These functions allow alarms to be deleted, formatted, and
acknowledged, bypassing any displays.

14.7 The Alarm Extended Ex3 Function Test Menu
Alarm Extended Ex3 Function Test menu (Figure 37) can be invoked.
Figure 37. Alarm Extended Ex3 Function Test Menu
The purpose of the Alarm Extended Ex3 Function Test is to allow users to test functions that
post or store an event with an MRID or a long name.


post or store an event with safety and state flags.

post or store an event with safety and state flags.
14.10 The Test Program as a Debugging Tool

The test program can be a handy tool for programmers or system integrators when they
have doubts about an Alarm client or about the Alarm server.
The following list provides some examples of situations where the test program can help:
• Is the Alarm server working? Use the test program to generate an alarm and verify that
it is showing up on the Alarm displays.
• An Alarm client cannot register with the Alarm server: Use the Alarm test program to
“fake” this particular client and check if it can or cannot register with the Alarm server.
The test program should determine whether the problem is with the client or with the
server.
• Event formatting: Use the test program to check the formatting of any particular event.

15. Frequently Asked Questions
The objective of this chapter is to provide answers to some common questions, and to
provide possible explanations and solutions for common problems that you may encounter
when using Alarm.
Suggestions for new additions to the chapter are invited via the Software Problem Report
(SPR) mechanism.
15.1 An Event Cannot Be Found in the System Activity Log

Problem:
A particular alarm appears in the alarm lists, but it cannot be found in the system activity
log.
Possible Causes:
• The event is posted by the Alarm client using the NOLOG option.
• The exception used to post the event has an override log (OVLOG record) that directs the
event to a different formatted log.
• The Alarm client application does not have a default log (DEFLOG record), or its default
log is not the system activity log.
Solutions:
Based on the cause, modify either the Alarm database or the code of the Alarm client.
15.2 A Client Does Not Connect to the Alarm Server

Problem:
An Alarm client is up and running and has invoked the AlarmRegisterClient function, but the
connection with the Alarm server has not been formed. As a result, the registration callback
is not firing.
Possible Causes:
Alarm uses NETIO to establish the connections with its clients. This implies that the client
must run in the same NETIO NNI as the Alarm server, and that all the NETIO processes
(NIOARC, NIOCLERK, and NIOSERVE) must be running with an enabled NETIO server at the
site. In addition, an enabled Alarm server must be running within the site so that it accepts
incoming connections.
Solutions:
Verify that the client and the server are both running in the same NETIO NNI, and check the
NETIO User’s Guide for further details about reasons for a path not being formed.
Verify that the Alarm server is enabled.
Proprietary – See Copyright Page 252 Frequently Asked Questions

Eventually, use the Alarm test program to simulate the client registration and isolate the
problem. If the client is not running in the same family as the Alarm server, see
alarm_register_client in chapter 13 Alarm API Descriptions.
15.3 Tones Are Not Sounding

Problem:
An alarm is inserted into the alarm list with the horn symbol, but no tone is sounded.
Possible Causes:
There are two aspects required for a tone to be sounded for an audible alarm:
• Proper modeling of the horn and tone records in the Alarm database, and their
relationship to the exception and category assignments.
• Proper audible permissions for the areas assigned to the alarm that is generating the
tone.
When Alarm has established that a tone should be sounded, it is sent to every Browser
client currently logged on. When the Browser viewer receives the tone via the OLEAUTO
interface, it checks whether the current user has audible permissions to hear the tone. The
command sent to Browser includes the permission areas assigned to the alarm that
originated the tone. The audible command received by the Browser client is displayed on
the Messages tab of the Browser viewer, where assigned permission areas can be viewed
and verified. The current user must have audible permissions for at least one area; only
then is the tone sounded.
Solutions:
Based on the cause, the solution may require either some modification to the Alarm
database, or simply a permission change in the PERMIT database, which can be
accomplished without stopping the Alarm server.
15.4 Acknowledging an Alarm Does Not Silence the Tone

Problem:
A continuous tone is sounding, but when the alarm that caused the tone to be sounded is
acknowledged, the tone continues to sound.
Possible Cause:
Because silencing a tone and acknowledging an alarm are independent requests, an alarm
acknowledgment never stops a tone from sounding.
Solution:
The only way to stop a tone is to click the Silence button, available on most Alarm displays.

15.5 There Is a Need to Customize the Alarm Source Code
Problem:
Some customers may desire to customize the Alarm application in terms of displays,
database sizes, or even functionality. This is achievable because Alarm is delivered with all
the source code in the ALARM and ALMAPI codesets.
At first glance, it might be tempting to modify the content of the ALARM codeset in the
delivered version; however, there are several issues associated with this course of action:
• It is not possible to easily revert to the product version. This is often desirable for testing
purposes, to compare the Habitat–delivered version against the customized one.
• Habitat files (or a subset) need to be managed in SourceSafe.
• The HABUSER system build now needs to work on non-HABUSER codesets.
• Propagation tools of a HABUSER build become more complicated because they have to
deal with modified pieces of Habitat.
• Future automated Habitat patch scripts and upgrades will override the customized files.
Solutions:
The first thing that must be done before embarking on an Alarm customization is to check
with GE about the possibility of customizing the delivered product to include the desired
changes, and/or having the customizations implemented by the Habitat staff. Alarm is a
complex application; customizations are often difficult and may have unforeseen side
effects.
Once it has been established that there is indeed a need to modify the Alarm source code,
the following approach is recommended:
1. Create an ALARM codeset9 under the HABUSER\SPECIAL subsystem, and copy the
contents of the Habitat Alarm codeset there. Add this codeset as a project in the
HABUSER SourceSafe library.
2. A few files need to be modified in the custom ALARM codeset:
– In Linux and Windows, in the ALARM.MK file, the CODESET_LEVEL directive must be
commented out.
– In Windows, the vcproj files must be updated to create files under HABUSER_LIBDIR
and HABUSER_BINDIR. References to habitat_resource.rc should be excluded from
the build.
9
In this discussion, it is assumed that only the ALARM codeset needs to be customized. GE recommends that
the ALMAPI codeset not be customized, since it could have ramifications deep into some Habitat tasks that
use the ALARM API.

– The ALARM.APPDEF file needs to be modified so that all executables are taken out of
HABUSER_BINDIR instead of HABITAT_BINDIR.
$ LISTEVENT :== $HABUSER_BINDIR:LISTEVENT.EXE
The custom ALARM codeset is built as part of the HABUSER system build. However, the
remaining problem is to make sure that the Habitat Alarm codeset does not interfere in
the build.
3. Two Perl scripts are provided to hide the standard Alarm code and related files, and to
restore them if they are needed later. These scripts are provided to help avoid conflicts
between the delivered Alarm application and the customized one. These scripts are
located in the habsrc/habitat/rcse/alarm directory, and they need to be run from this
directory.
– alarm_hide.pl: The hide script zips the entire codeset, except for the restore script,
and the Alarm-related binary files, i.e., executables, library, and objects. It also
removes the header files of the ALARM codeset from HABITAT_INCDIR.
– alarm_restore.pl: The restore script unzips the zipped codeset and restores the files
removed by the hide script.
This approach makes it relatively easy to rebuild the delivered version of Alarm when
needed, and it makes system builds safe as long as one does not forget to hide the
codeset.
The Alarm executable writes the following message to stdout at startup:
C:\Eterra\habsrc60\habitat\rcse\alarm\alarm_main.cxx was compiled on Feb 7 2003 at
19:39:37
In this case, it indicates that the main module — and thus, very likely, all the others — was
built out of the Habitat directories. This is written to stdout, as opposed to the Habitat log,
so that the information does not get lost when the circular log wraps around.
15.6 There Is a Need to Rebuild the ALARM Codeset

Problem:
If customization is required in the Alarm application, follow the steps described in section
15.5 There Is a Need to Customize the Alarm Source Code.
However, you may still want to rebuild the Alarm source code without intending to
customize anything.
Solutions:
All of the files making up the Alarm application are delivered during the Habitat installation,
in two different codesets:
• The ALMAPI codeset contains the Alarm API implementation.
• The ALARM codeset contains all the source code for the Alarm executables.

Note that the Alarm API is provided, but in most cases only the Alarm server codeset should
be rebuilt (which implies that only the ALARM codeset requires rebuilding). The steps
required to build Alarm are described below for each operating system.
Linux
1. The files are in two locations:
– The alarm source files are in the eterra\habsrcXX\habitat\rcse\alarm directory.
– The alarm API library source files are in the eterra\habsrcXX\habitat\rcse\almapi
directory.
2. To rebuild Alarm, use the getenv command to navigate to the ALARM codeset and type:
% build
at the prompt. Once the compiler returns control to the prompt, the alarm application
has been rebuilt.
3. Make certain that there are no errors during the build.
Windows
1. The Eterra\habsrcXX\habitat\rcse\alarm\workspace directory contains the necessary
solution files (.sln) that are required to rebuild the alarm application.
2. Using Microsoft Visual Studio .NET, the alarm_libs.sln file should be opened, and all the
necessary build options and files are loaded. Use the build menu option to build the
alarm_libs first, which builds all of the related alarm static libraries. Then the alarm_exes
can be built using the alarm_exes.sln, which builds the related alarm executables.
The loaded projects can each be built individually if need be, but the above-mentioned
steps do them all automatically.
3. The alarm_all can also be used to build everything in one step using the alarm_all.sln.
However, if there is a problem, it may be easier to do them separately. If any errors are
encountered about missing .h (header) files, copy them from the source directories into
the Eterra\habitatXX\habitat\inc directory.
4. Make certain that there are no errors during the build.
15.7 Alarm Text Does Not Line Up Properly on Displays

Problem:
Similar alarms line up differently on the Alarm Summary displays, based on the text that is
contained in the alarms.
Possible Cause:
The font being used by the Alarm displays is a proportional font, which means that the
amount of space a character takes on the screen is dependent on the character being
printed (the majority of fonts available are proportional fonts). So, for example, using these
fonts results in the letter “W” taking up more space than the letter “I”.

Solution:
To fix this problem, change the font used for the Alarm text to a non-proportional font (for
example, Courier New or Lucida Console). These fonts ensure that the letter “I” takes up as
much space as the letter “W”, and this results in proper spacing on the Alarm Summary
displays.
The font used is set as an attribute on the Shared Gab that is placed on the text in the
Display Builder.
15.8 Alarm Archive Files Not Readable by Alarm Viewer

Problem:
Alarm archiving does not work properly. Either expected messages do not get archived or,
when they do, Alarm Viewer cannot display the archive.
Possible Cause:
Alarm can support the old (e-terrahabitat 5.2) human-readable archive file format. This was
done in e-terrahabitat 5.3 to support customers who might have had software that
depended on the version 5.2 format.
With the advent of Alarm Viewer, the archive format needed to be changed for the Alarm
Viewer to perform its filtering and sorting operations on the archive.
Solutions:
To fix this problem, use hdbrio to inspect the “old format” archive flag in the database. This
flag is ORIGARCH_ITEMS. Ensure that this flag is set to FALSE and exit hdbrio.
If you have any ALARM savecases, you can use hdbrio with the archive option to inspect
and upgrade the flag there, if necessary. For example:
D:>hdbrio -archive case_alarm_dts.emp60 alarm
[case_alarm_dts.emp60:ALARM]
$rio> /ORIGARCH_ITEMS(1)
Bit: 1 ORIGARCH_ITEMS(1) = False
$rio> exit

Appendix A. Version Modification History
The following modifications have been made to Alarm that may cause unexpected results
when using existing functionality on an older system.
This is not a complete list of the changes that have been made from one version to the next.
It is a list of changes that represent a loss of existing functionality or changes to core Alarm
functionality.
A.1 Changes from 5.3 to 5.4

Alarm customization: Two Perl scripts have been added to the Alarm codeset, to facilitate
the customizing of the Alarm application:
• alarm_hide.pl: This script hides the contents of the Alarm codeset and the related Alarm
file from the Habitat space. This script should be used when a customized version of the
Alarm codeset is placed under the HABUSER space. Hiding the Habitat–delivered version
guarantees that there is no collision between the two versions.
• alarm_restore.pl: This script restores the content of the Alarm codeset and its
associated files.
Important Note: These two scripts require Perl and zip/unzip to be available from the
command line.

Alarm consoles: Consoles have been removed from the ALARM application entirely, since
they are no longer required with Browser. Consoles in ALARM were used to display ALARM
data in Rapport-FG, which is no longer supported. As a result, the CONSOLE and
CONSOLE/HORN assignment modeling displays have been removed.
LOGMAN print filtering: With the removal of consoles, the LOGMAN queue no longer checks
READ permissions for the computer the logger is attached to. Instead, all events are sent to
the LOGMAN queue and, ultimately, to the logger/printer. As a result, the related
CONSOLE/LOGMAN queue display has been removed.
Time Search displays: The Time Search displays have been removed, since they were based
on Console records and alarm lists that are now maintained by the Browser data server. To
perform time searches on the real-time alarm data, the Alarm Viewer should be used
instead.
Proprietary – See Copyright Page 258 Version Modification History

In the e-terrahabitat 5.8 release, the SPR described below has been fixed.
PD31140:
After a new database is onlined, the ALARM database does not replicate to the standby
on a full recovery.
When new databases are brought online as part of the modeler archive, the ALARM
database (alarm.dbdef) is the only database that does not recover upon the submission
of a full recovery.
If there have been modifications made to the ALARM database, such as new/updated
locations or exception definitions, the same archive must be onlined to both EMS
systems.
Simply marking one of the partitions “replicate” in the ALARM database causes
problems with the systems that have an emergency backup site, because a few global
flags must be set in the ALARM database to force Alarm to take the standby role while
running on the emergency backup system.
To resolve this SPR, a new Alarmdef database (alarmdef.dbdef) has been added, which
contains only one record (ITEMS) with the following configuration flags:
• CFGMAN_ITEMS
• NOROLE_ITEMS
• STANDBY_ITEMS
• NOPERM_ITEMS
• LOGMAN_ITEMS
• NOMRS_ITEMS
These flags were previously part of the Alarm database (alarm.dbdef). They have been
moved to the new Alarmdef database (alarmdef.dbdef).
Note: The “old” flags in alarm.dbdef have been renamed to start with an “X”. They are
unused in the latest Alarm code.
For more information about changes in Alarm behavior when onlining a new Alarm model,
see section 7.9 Onlining the Alarm Database.
Proprietary – See Copyright Page 259 Version Modification History

Appendix B. Changing APF Audible Profiles
For instances of Platform with APF, the APF Audible Management and Configuration
applications were introduced to configure and interact with the Audible Service. When the
Audible profiles are created in APF, they are created only for the user who is logged in to
APF when the profiles are created. The APF Audible Profiles should be changed from a
single user to all users. This allows all users who log in to APF to have the same set of
Audible profiles.
To change the Audible profiles from a single user to all users:
1. Find the configuration file. The Audible profiles are typically located in:
C:\ProgramData\GE\APF\Configuration\apf.services.user.<fully_qualified_username>.co
nfig
2. Open the configuration file in a text editor.
The Audible profiles are part of this configuration file. All of the defined Audible profiles
are contained between the <audibleService> tags in this file.
3. Copy the Audible profiles by selecting the text between (but not including) the
<audibleService> and </audibleService> tags.
Proprietary – See Copyright Page 260 Changing APF Audible Profiles

4. Use Windows Explorer to navigate to the directory where the APF default configuration
file is located (typically, C:\Program Files (x86)\GE\APF 4.2 DEV\Configuration).
5. Open the apf.service.default.config file in a text editor.
This file has the default settings for audible services.
Note: You will need to edit the file from a command prompt with administrator
privileges or you will not be able to save your changes at the end of the editing
session.
6. Once in the editor, locate the <audibleService> tag that designates the beginning of the
default Audible profiles available to all APF users on the console. Paste the Audible
profiles previously copied after the <audibleService> tag.
7. Save the file with these changes.
8. Restart APF and log in.

9. From the APF console, select the Audible Management tab to verify that all of the
Audible profiles copied into the default configuration file are observed.
Proprietary – See Copyright Page 261 Changing APF Audible Profiles

Index
debugging, 244
A default log, 19, 252
definition, 25
acknowledgment, 1, 24, 30
deletion, 1, 19, 24, 27, 29, 30, 47
alarms, 24
duplicated hour, 10
automatic, 9
defined, 5
logging, 27 E
notifications, 26
event, 121, 163, 209, 211
acknowledgment activity log, 19
event replication, 19, 104
Alarm Acknowledge, 59
events, defined, 4
alarm acknowledgment
exception, 5
AUTOACK, 25
exception definition, 1, 5, 8, 9, 11, 48, 51
related alarms, 25
external interfaces
Alarm API, 106
Configuration Manager, 103
Alarm Delete, 59
Hdb/Mrs, 104
Alarm server, 103
Logman, 104
alarm synopsis display, 6
MLF message daemon, 103
Alarm test program, 244
NETIO, 102
as a debugging tool, 251
Permit, 102
running, 244
Procman, 104
Alarm Viewer, 68, 70, 71, 72, 73, 75, 76, 79, 80, 81
alarm_hide script, 255
ALARM_NOLIST, 8 F
ALARM_NOWUNACK, 8
family, 43
alarm_restore script, 255
formatting, 10
ALARMS index, 60
text format, 11
alarms, defined, 4
time format, 10
ALMMSG file, 16
application, 6, 19
archive file, 32 H
archiving format, 10, 34
Habitat, 102
assignments, 103
Hdb, 102
associations, 51
Hdb interface, 102
AudioAlarm, 35
Help system, Alarm Viewer, 82
AudioAlarm command, 38
horn, 6
AUTOACK flag, 9
B L
list full, 21, 22, 25, 27, 28, 29
Browser viewer, 38
log, 27
BUILDLST Command, 16
logging of acknowledgments, 27
C M
category, 5
Memory Replication Service, 104
CIRCLG record, 19
MLF Daemon, 103
client, defined, 4
MLFDMN. See MLF Daemon
Configuration Manager, 103
MLFDMN task, 103
console, 30
MRS, 102
customizing the Alarm source code, 254
MRS task, 20, 21
D N
database object, 5
NIOSOCK, 102
Daylight Saving Time, 10
NOLOG, 8, 9
Proprietary – See Copyright Page 262 Index

O S
object definition, 1, 5 severity, 17, 46
overlay, 47 silencing tones, 35, 37, 38
override log, 18, 19, 252 Standard Time, 10
subscript, 27
P
T
performance
Alarm Performance Menu, 245, 246 TELL command, with PROCMAN interface, 104
performance improvements, 107 time change, 10
permission checks, 22, 30, 38, 102 time format, 10
priority, 6 tokens, 10, 32
Procman, 252 tones, 3, 6, 7, 25, 35, 36, 38, 46, 51, 253
Running in non-Hdb env, 103
V
Q
validating the Alarm database, 43
queues, 104
R
replication, 4, 19, 20, 21, 106, 107, 108, 203, 243, 245
Proprietary – See Copyright Page 263 Index


Habitat Alarm User Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Habitat Alarm User Guide

Uploaded by

Copyright:

Available Formats

Digital Energy

Version: Habitat 5.11

2. Alarm Server Event Processing ................................................................................... 7

Proprietary – See Copyright Page iii

3. Acknowledging and Deleting ..................................................................................... 24

4. Printing and Archiving ................................................................................................. 31

5. Sounding and Silencing Tones .................................................................................. 35

6. Adding Notes to an Alarm .......................................................................................... 40

7. Setting Up the ALARM Database .............................................................................. 43

Proprietary – See Copyright Page iv

8. Creating Indexed Browser Displays ......................................................................... 60

Proprietary – See Copyright Page v

9. Alarm Viewer .................................................................................................................. 68

10. Alarm Pager.................................................................................................................. 85

Proprietary – See Copyright Page vi

11. Interfaces to Other Subsystems .......................................................................... 102

12. Using the Alarm API ................................................................................................ 106

13. Alarm API Descriptions .......................................................................................... 109

Proprietary – See Copyright Page vii

Proprietary – See Copyright Page viii

15. Frequently Asked Questions ................................................................................. 252

Appendix A. Version Modification History ............................................................... 258

Appendix B. Changing APF Audible Profiles ............................................................ 260

Proprietary – See Copyright Page ix

Proprietary – See Copyright Page x

Purpose of This Document

Who Should Use This Document

Structure of This Document

Proprietary – See Copyright Page xi

For More Information

Proprietary – See Copyright Page xii

Proprietary – See Copyright Page xiii

Proprietary – See Copyright Page xiv

1.1 What Is Alarm?

Proprietary – See Copyright Page 1 Introduction

Proprietary – See Copyright Page 2 Introduction

Figure 2. Life Cycle of an Event

The following describes in detail each of the steps shown in Figure 2:

Proprietary – See Copyright Page 3 Introduction

6. An operator acknowledges the alarm.

Proprietary – See Copyright Page 4 Introduction

Proprietary – See Copyright Page 5 Introduction

1.5 Alarm Health Timer

Proprietary – See Copyright Page 6 Introduction

Figure 3. Overview of Event Processing

Proprietary – See Copyright Page 7 Alarm Server Event Processing

2.1.1 Unacknowledged Alarm or Log-Only Event?

Proprietary – See Copyright Page 8 Alarm Server Event Processing

Table 1. Event Processing Options

Proprietary – See Copyright Page 9 Alarm Server Event Processing

2.1.3 Abnormal State

2.2.1 The Time Format

Proprietary – See Copyright Page 10 Alarm Server Event Processing

2.2.2 The Text Format

2.3 Long-Name and MRID Support

Proprietary – See Copyright Page 11 Alarm Server Event Processing

2.3.2 Alarm Event Block

Proprietary – See Copyright Page 12 Alarm Server Event Processing

Proprietary – See Copyright Page 13 Alarm Server Event Processing

2.3.3 Processing New Alarm Event Block Fields

2.3.3.1 Long Name Look Up

2.3.3.2 Errors Reported if the Long Name Lookup Fails

Proprietary – See Copyright Page 14 Alarm Server Event Processing

2.3.3.4 Getting the Full Composite Key of the Object