                                                                   Page 6-1
                               Chapter 6 - Alarms

OVERVIEW

The Monitor II is designed to receive unsolicited alarm 
messages. A controller can issue alarms at any time and The 
Monitor II will see them and, optionally, store them on disk 
or print them to a printer. An alarm can also activate a 
user-written script file that can do a number of different 
tasks, from calling out to another controller or computer, 
to executing other DOS programs.

With an AC256/AC8 controller, the alarm messages can be 
placed into message drum lines and then simply displayed. 
With the Infinity the process is more complex, and is 
detailed later in this chapter.

There are two levels of alarms: ALARM messages and 
MAINTENANCE messages. Alarms are for important messages that 
need immediate attention. Maintenance messages should be 
used for less important messages (runtime exceeded, etc.). 
Both types of messages will be referred to as alarms in the 
rest of this chapter. The Monitor II can also poll for
alarms on the Infinity controller.

Alarms that are stored on disk are placed in a disk file
that you can view by selecting ALARM REPORT from the VIEW
menu.

IMPORTANT NOTES

* Alarms must be enabled or they will be ignored by The
  Monitor II. You can enable/disable them in the
  SYSTEM/SETUP/ALARMS menu.

* The Infinity controller will not display alarm messages
  if someone is logged on to it with an Administrative
  level password (if you are using the alarm system
  presented later in this chapter).

* Be sure to disable alarms if you need to go into terminal
  mode and add or edit an alarm message. If you do not
  disable them, The Monitor II will think it is a genuine
  alarm, even if you just print the message line that has
  an alarm in it.

* An alarm may not always be processed as soon as it is
  received. If you are using the system and are doing
  something that should not be disturbed, The Monitor II
  will wait for you to finish, but the alarm box on the
  status line will flash as soon as the alarm is received.

                                                                   Page 6-2

6.1   Alarm Message Format

The format of an alarm messages is:

{A # TEXT <SCRIPT> [>DATE }

Where:
    {       = start of message marker
    A or a  = an alarm message (M or m=maintenance message)
              (lowercase A or M will not cause the alarm box
              on the status line to flash or increment the
              number of alarms. Use this if you only wish to
              execute a script file or print something to
              the printer, but don't want to make anyone
              think there is an alarm.)
       #    = destination of message
              0 = none
              1 = alarm printer
              2 = disk file (add to alarm report)
              3 = alarm printer and disk file
   TEXT     = the actual text of the message
   <SCRIPT> = the name of a script file to run (optional)
   [>DATE   = the date and time of the message (optional)
       }    = end of message marker


Example:  {A1Zone 1 Temperature is Out of Range (78.5
           Deg.f)<floor1>[>04/11/92 12:34:23}

This will send an alarm to the printer and then execute the
script file FLOOR1.SCR (which might display a graphic or
initiate an alarm call-out routine.

Example:  {M3Airhandler #1 has Exceeded 300 Hours of
           Runtime[>05/19/92 22:54:23}

This will send the maintenance message to the printer and
store it in a disk file that may be viewed later in the
maintenance report.

The maximum length of an entire alarm message is 170
characters. The actual text of the message may be no longer
than 120 characters. The Monitor II will split the text of
the message into two lines of 60 characters each.

If setup to poll for alarms, The Monitor II will issue the
command "MON_PRINT_ALARM" to the controller once every 60
seconds. It is the users responsibility to program the
controller to respond to this command.

SEE EXAMPLE PROGRAMS FOR INFINITY AT THE END OF THIS CHAPTER

                                                                   Page 6-3

6.2   Alarm & Maintenance Report

The alarm report will display all alarm messages received
for a given month that were stored on disk. The user may
select NEXT, PREVIOUS or press the UP, DOWN, HOME, END,
PgUp, and PgDn keys to view other alarm messages.

The information displayed is:

* TEXT - The actual text of the alarm message.

* DATE - The date the alarm was generated.

* ACKNOWLEDGED BY - If no COMMENT has been entered, this
  will hold the username of the first person to look at
  this alarm. If someone then adds a COMMENT, their
  username will be placed here.

* COMMENT - The text that a user may have entered when the
  alarm was acknowledged. This could be a record of what
  action was taken, etc.

* COMM PORT - The communications port that the alarm was
  received on. This will be 1 - 4.

The user options are:

* ACKNOWLEDGE - Allows the user to enter a comment about
  the alarm, such as why it occurred, what actions were
  taken, etc.

* SEARCH - Allows the user to search through all alarm
  messages for the occurrence of a string of characters.
  Each alarm will be search, in order, starting with the
  alarm currently displayed. All fields of the alarm will
  be searched (TEXT, DATE, COMMENT, etc.)

* MONTH - Allows the user to select a different month to
  view.

* NEXT - Will display the next alarm in the file. After the
  last alarm is viewed, it will roll over to the first
  alarm.

* PREVIOUS - Will display the previous alarm in the file.
  After the first alarm is viewed, it will roll over to the
  last alarm.

* DONE - This will remove the alarm report window, and
  close the disk file.

                                                                   Page 6-4

6.3   Infinity Alarm Example Programs

============================================================

THE FOLLOWING INFORMATION IS PROVIDED AS EXAMPLES ONLY. NO
GUARANTEE IS MADE AS TO IT'S ACCURACY OR RELIABILITY. USE
THIS INFORMATION AT YOUR OWN RISK.

============================================================

The main problem with alarms on the Infinity is that it is
difficult to send messages directly to the COMM ports. Using
the PRINT command will normally send messages to the message
window of the controller. A COMM port must be OPENed in
"raw" mode and then PRINTed to. If the COMM port is not
CLOSEd properly, the system may appear to lock up, possibly
requiring a complete hardware reset.

There are examples of opening COMM ports in "raw" mode in
the Infinity Plain English Language Reference. The following
programs are provided as examples only. They have been
written and used by Custom Software Engineering, but NO
GUARANTEES ARE EXPRESSED OR IMPLIED. The intention here is
not to scare you out of using the examples. It is simply to
be sure that you realize that they MUST be thoroughly tested
by YOU.

The basic idea behind this example is to store messages in a
data file that The Monitor II can retrieve when it polls the
controller.

This is done by creating a data file containing 25 entries 
that each hold an alarm message (and the date, destination, 
etc.). A numeric variable (MON_ALARM_COUNT) is used to point 
to the next unused entry. Your programs in the controller
add messages to the data file with the "MON_STORE_ALARM" 
function. The format of the function call is:

MON_ALARM_STORE(message,type,destination)

Where:

message     = the actual text of the alarm message (can
              contain a script file I.E. <FLOOR1>)
type        = 1 for alarm message, 2 for maintenance message
destination = 0 for none, 1 for printer, 2 for disk, 3 for
              both

The date is stored automatically.

                                                                   Page 6-5

Example: MON_ALARM_STORE("Zone 1 is Out of Range",1,3)

If more than 25 message have been stored but not retrieved
by The Monitor II, a new message will overwrite the oldest
message.

The number of entries in the data file can be increased, but
don't set it too high (not more than 50) because the
Infinity may time-out and abort a program if it stays on one
line too long. If you change the number of entries, don't
forget to change the 25 in the "MON_PRINT_ALARM" program
also.

First, a variable must be created to help keep track of the 
position in the data file.

Object : mon_alarm_count
 Type : Numeric
 LastChange :  2-22-92  2:01:59 pm
 LogType : Instantaneous
 SetPoint : True
 LogInterval :   0  00:01:00
 Value :   1.000
EndObject


Next, the data file must be created.


Object : mon_alarm_data
 Type : Data
 LastChange :  2-25-92  5:07:43 pm
 Code :
  Record 25                    'this specifies how many 
                               'messages to store
     String alarm_str 120      'the actual text of the 
                               'message is stored here
     Datetime alarm_date 20    'the date is stored here
     Numeric type 15           'this is the type (alarm or
                               'maintenance)
     Numeric dest_flag 15      'this is the destination
                               '(printer,disk,etc)
     Numeric in_use 15         'tells the controller if this
                               'record is used
 EndCode
EndObject


                           CONTINUED ON NEXT PAGE

                                                                   Page 6-6


Next, a function to store the message in the data file.


Object : mon_alarm_store
 Type : Function
 LastChange :  2-22-92  2:11:17 pm
 Code :
  Arg 1 message
  Arg 2 type
  Arg 3 dest_flag

  Numeric result

  result = write(mon_alarm_data, mon_alarm_count, message,
                 Date, type,dest_flag, 1)
  mon_alarm_count = mon_alarm_count + 1
  If mon_alarm_count > 25 then mon_alarm_count = 1

  Return result

 EndCode
EndObject

Finally, a program to display the messages to the "raw"
comport.

Object : mon_alarm_print
 Type : Program
 LastChange :  2-22-92  2:14:17 pm
 CommandLine : True
 FlowType : FallThru
 DefaultPort : INFINITY17 COMM3
 Code :
  Numeric result
  Numeric loop

  Line opening
    result = Open(COMM3)
  Line testing
    If result = Success then
      For loop = 1 to 25
        If mon_alarm_data[loop].in_use = 1 then
          Print "|123"; to COMM3
          If mon_alarm_data[loop].type = 1 then Print "A";
             to COMM3
          Else Print "M"; to COMM3

                           CONTINUED ON NEXT PAGE

                                                                   Page 6-7

          If mon_alarm_data[loop].dest_flag = 0 then Print
             "0"; to COMM3
          If mon_alarm_data[loop].dest_flag = 1 then Print
             "1"; to COMM3
          If mon_alarm_data[loop].dest_flag = 2 then Print
             "2"; to COMM3
          If mon_alarm_data[loop].dest_flag = 3 then Print
             "3"; to COMM3
          Print mon_alarm_data[loop].alarm_str; to COMM3
          Print "[>"; to COMM3
          Print mon_alarm_data[loop].alarm_date; to COMM3
          Print "|125"; to COMM3
          mon_alarm_data[loop].in_use=0
        Endif
      Next loop
    Endif

  Line closing
    result = Close(COMM3)
  Line ending
    If result = Success then Stop mon_alarm_print

 EndCode
EndObject


All of these examples are fairly simple. but please, TEST
THEM!!!

A ready-to-load file has been provided for you. It is on
your original disk and the filename is 'ALARMS.PRG'


