EPICURE Software Release Note 147.2<P> <b> EPICURE Alarm Monitoring Services</b>

EPICURE Software Release Note 147.2

EPICURE Alarm Monitoring Services

David M. Kline

General Description

The EPICURE control system supports alarm monitoring services to experimenters, operators, and EPICURE system programmers that include the capability of monitoring device properties at various levels and frequencies. Additional support is provided that allows users to collect which device properties are currently being monitored and their alarm state. Alarm states can be defined for the both analog and binary properties. Analog alarm states include the reading and setting properties, and can be defined for multiple users at various severity levels and Frequency-Time-Descriptors (FTD). Binary alarm states represent the status property, and can also be defined for multiple users at various FTDs. The task of servicing requests related to alarm states, reporting them, and initiating the necessary data acquisition to perform the monitoring is handled by the EPICURE ALARM_SERVER process (AMS). Users communicate with the server and request other services by calling AMS Application Programming Interface routines (API) . The API is primarily used by EPICURE system programmers and subsystems to maintain device property alarm states, and report the current status of them to users.

Beyond this point, the intention of this document is to provide a description of the ALARM_SERVER process, the calling sequences of the API, and present example programs that can act as a point of departure for EPICURE system programmers, and others who want to access server functions.

Monitoring Server

The ALARM_SERVER is a VMS-based process that resides on every EPICURE front end that executes the necessary EPICURE processes interfacing directly to the VMEbus hardware. This dependency is not inherent of the ALARM_SERVER but eliminates complexities associated with maintaining unique alarm states for a given device property. Otherwise, the ALARM_SERVER can be run on any node with EPICURE installed and that possesses the necessary memory and disk resources.

Integration with other EPICURE products

The ALARM_SERVER is integrated into other EPICURE products. The Data Acquisition Server (DAS) process uses the API to communicate alarm requests on behalf of the DAR process. It acts as an intermediate stage between the DAR and ALARM_SERVER processes. Responses to requests are sent by the ALARM_SERVER to the corresponding DAR through DAS.

Events and exceptions that occur on the front end at the DAE level are communicated through the alarm subsystem. DAE processors, such as CAMAC, TIMER, and LISTENER, insert messages into the HERMES common memory queue when abnormal conditions exist, such as when internal resources have been exhausted. The EPICURE Data acquisition Event Monitor (DEM) removes any messages that are inserted into the HERMES queue. DEM sends the message to the ALARM_SERVER where it is translated into an associated device name and status property bit number. The information is then passed to the ARD API where it is transmitted throughout the alarm subsystem.

The ALARM_SERVER communicates all alarms by using the Alarm Report Distributor (ARD) UTI. Alarms are packed into a report block and passed to the corresponding service call. ARD is responsible for transmitting the information through the alarm subsystem.

The reporting of the device properties which are currently being monitored is collected by the Alarm report application. The application uses the API to request that all device properties which are being monitored be sent to the application.

Supported Functions

The ALARM_SERVER supports alarm functions as well as report functions. Users call the appropriate API services to communicate alarm requests in the form of a DAR request message. The message is similar to a data acquisition request except that the message is processed by the ALARM_SERVER rather than the DAS process. It's contents specifies the limits and severity levels for analog alarm states and the particular bits for status alarm states . Additional offsets are present that specify the location of the data. Alarm states can be read in three ways. Device properties can be accessed by specific information given by the device and property index, acquisition frequency (i.e. FTD), and User Identification Code (UIC). Periodic reporting of alarm information can be automatically sent to applications at a specific FTD; however, the specified FTD is for data return and not for data retrieval. Since the FTD is not passed, the ALARM_SERVER returns the alarm state that is the most recent one in alarm. Otherwise, a status code is returned indicating that a suitable alarm doesn't exist.

The last method of retrieval provides an automatic way of collecting all the device properties and alarms that are currently being monitored. An API service routine is available that sends a message to the ALARM_SERVER to start sending all the alarm data sequentially. Termination of the transmission is indicated by a status code (discussed in a later section). This service is useful to reporting applications.

Alarm Database

The ALARM_SERVER maintains a fixed-length record database implemented using the VMS RMS system services. Contained in each record are the particulars related to a specific device property, FTD, alarm states, current and previous reads, and other properties and attributes related to the monitoring task. Data contained in the database can be accessed by using the reporting API service call as described in the above section. Further discussions related to this service can be found in the section on ``Application Programming Interface'' and the ``Programming Examples'' appendix.

Logging

Exceptions which occur within the ALARM_SERVER are logged to the standard error file (stderr) and can be reviewed by EPICURE system programmers when necessary. Exceptions include data acquisition failures and attempts being made to restart data acquisition lists for a particular device. Other exceptions are written, such as the traceback provided by the VMS operating system when error conditions are signalled, and ones when unpredictable circumstances occur.

Exit Handling

The ALARM_SERVER can exit by two means. The process can be forced to exit through a manual restart. This usually entails queuing an AST to the process that executes the EXE$EXIT() VMS executive entry point. Typically, this is performed by invoking the SYS$FORCEX() system service . Others reasons includes exceptions that were mentioned previously in the above section. The ALARM_SERVER traps the former by establishing a user-mode exit handler that performs cleanup operations before the final termination of the process. Some of these operations include a) completing any pending alarm database updates; b) closing standard output files, such as stdout and stderr. This flushes the contents of the RMS buffers to the output files (i.e. stdout, stdin); and c) sending messages to clients who are currently connected. Exit handlers pose a deficiency in that they are not invoked in all cases of process termination. Therefore, the server declares an image-rundown handler in addition to the exit handler to perform limited operations for those cases. The only operation of significance that can be performed under these circumstance is that a message is sent to the clients who are connected that the server is crashing. This is indicated by a status code (see the discussion in the API section).

Application Programming Interface (API)

Applications have at their disposal a set of well-defined service routines that request alarm state and reporting functions provided by the ALARM_SERVER. Below lists the calling sequences and provides descriptions of the interface routines used by an application to access these functions.

ams_connect

(int)status = ams_connect( irh, irhp, ccount )

This routine establishes a connection with the alarm server network objects and initializes internal data structures. An image rundown handler (IRH) is declared which notifies the alarm server that the caller process has terminated. The caller can specify another routine to be part of the termination procedure by specifying the ``irh'' parameter. The alarm server IRH executes the user specified ``irh'' before is sends the termination notification to the alarm server. Furthermore, the IRH is executed regardless of the method used to terminate the process. irh address of the image rundown handler that is executed as part of process termination. Passed by reference. irhp value to be passed to the image rundown handler. Passed by value. ccount number of connections made to remote alarm servers. Passed by reference. status returns a condition value: SS$_NORMAL success SS$_NOSUCHOBJ fatal, network object is unknown at remote node AMS__INIT warning, interface already initialized others as returned by EPICURE and VMS system services

ams_disconnect

(int)status = ams_disconnect( )

This routine cancels pending IOs, disconnects from the AMS network object, restores the previous image rundown handler routine, and releases dynamic memory allocated from previous calls to AMS UTI routine. No termination notification is sent to the alarm server. Applications and processes that do not want to notify the alarm server of their termination MUST call this procedure before exiting. status returns a condition value: SS$_NORMAL success SS$_NOSUCHOBJ fatal, no connection established others as returned by EPICURE and VMS system services

ams_flush_queued

(void)ams_flush_queued( )

This routine is used to flush messages which are queued to be sent to the alarm server without performing a disconnect.

ams_get_status

(int)status = ams_get_status( ast [,astp] )

This routine requests the current status block that is maintained by the alarm server. Notification of the return data is accomplished through a user-provided AST routine (see ast) specified by the ``ast'' parameter. The parameters passed to the AST routine include: completion status, node name string (source of data), return data, return data length, and the user-specified parameter (``astp''). If an error occurs on the logical link, the completion status, node name, and user-provided parameters are valid. Furthermore, the AST routine is called for each logical link that exists with an alarm server. ast address of a routine that is called when the status block has returned (see ast). Passed by reference. astp option parameter that is passed to the routine specified by the ``ast'' parameter (see ast). Passed by value. status returns a condition value: SS$_NORMAL success AMS__QUEUED success, message queued but not sent SS$_BADPARAM fatal, bad parameter value SS$_INSFMEM fatal, insufficient virtual memory SS$_NOSUCHOBJ fatal, no connection established AMS__OVRFLOW warning, too many outstanding messages others as returned by EPICURE and VMS system services

ams_get_users

(int)status = ams_get_users( ast [,astp] )

This routine requests the current user list that is maintained by the alarm server. Notification of the return data is accomplished through a user-provided AST routine (see ast) specified by the ``ast'' parameter. The parameters passed to the AST routine include: completion status, node name string (source of data), return data, return data length, and the user-specified parameter (``astp''). If an error occurs on the logical link, the completion status, node name, and user-provided parameters are valid. Furthermore, the AST routine is called for each logical link that exists with an alarm server. ast address of a routine that is called when the status block has returned (see ast). Passed by reference. astp option parameter that is passed to the routine specified by the ``ast'' parameter (see ast). Passed by value. status returns a condition value: SS$_NORMAL success AMS__QUEUED success, message queued but not sent SS$_BADPARAM fatal, bad parameter value SS$_INSFMEM fatal, insufficient virtual memory SS$_NOSUCHOBJ fatal, no connection established AMS__OVRFLOW warning, too many outstanding messages others as returned by EPICURE and VMS system services

ams_read_alarm

(int)status = ams_read_alarm( dar, ast [,astp] )

This routine requests alarm reads for the list specified by the ``dar'' parameter. Notification of the return data is accomplished through a user-provided AST routine (see ast) specified by the ``ast'' parameter. The parameters passed to the AST routine include: completion status, node name string (source of data), return data, return data length, and the user-provided parameter (``astp''). If an error occurs on the logical link, the completion status, node name, and user-provided parameters are valid. dar address of the request message (alarm read). Passed by reference. ast address of the routine called when a list returns. (see ast). Passed by reference. astp parameter passed to the AST routine (see ast). Passed by value. status returns a condition value: SS$_NORMAL success AMS__QUEUED success, message queued but not sent SS$_BADPARAM fatal, bad parameter value SS$_NOPRIV fatal, no privilege for attempted operation SS$_NOSUCHOBJ fatal, no connection established AMS__TOOMANY fatal, too many connections AMS__INVFTD warning, invalid FTD specified AMS__INVREQ warning, invalid request type AMS__OVRFLOW warning, too many outstanding messages others as returned by EPICURE and VMS system services

ams_read_device_records

(int)status = ams_read_device_records( ast [,astp] [,ftd] [,dipi] [,uic] )

This routine requests the current list of Alarm Status Blocks that are maintained by each alarm server. Notification of the return data is accomplished through a user-provided AST routine (see ast) specified by the ``ast'' parameter. The parameters passed to the AST routine include: completion status, node name string (source of data), return data, return data length, and the user-provided parameter (``astp''). If an error occurs on the logical link, the completion status, node name, and user-provided parameters are valid. Furthermore, the AST routine is called for each logical link that exists with an alarm server. The status code of AMS__NOMORE will be passed to the AST routine when the end of the Alarm Status Block list is reached. Another feature of this routine is the ability to filter return data records given the optional parameters ``ftd'', ``dipi'', and ``uic''. The user can tailor the return data by passing combinations of these parameters. The ALARM_SERVER will return only ones which satify the criteria. ast address of a routine that is called when an Alarm Status Block returns (see ast). Passed by reference. astp optional parameter that is passed to the routine specified by the ``ast'' parameter (see ast). Passed by value. ftd optional parameter used to filter by frequency time descriptor. Passed by value. dipi optional parameter used to filter by device index (di) and property index (pi) combinations. Passed by value. uic optional parameter used to filter user identification codes. Passed by value. status returns a condition value: SS$_NORMAL success AMS__NOMORE success, no more data AMS__QUEUED success, message queued but not sent SS$_BADPARAM fatal, bad parameter value SS$_NOSUCHOBJ fatal, no connection established AMS__OVRFLOW warning, too many outstanding messages others as returned by EPICURE and VMS system services

ams_repeat_read_alarm

(int)status = ams_repeat_read_alarm( dar, ast [,astp] )

This routine requests repeat read alarm for the list specified by the ``dar'' parameter. Notification of the return data is accomplished through a user-provided AST routine (see ast) specified by the ``ast'' parameter. The parameters passed to the AST routine include: completion status, node name string (source of data), return data, return data length, and the user-provided parameter (``astp''). If an error occurs on the logical link, the completion status, node name, and user-provided parameters are valid. dar address of the request message (alarm repeat read). Passed by reference. ast address of the routine called when a list returns. (see ast). Passed by reference. astp parameter passed to the AST routine (see ast). Passed by value. status returns a condition value: SS$_NORMAL success AMS__QUEUED success, message queued but not sent SS$_BADPARAM fatal, bad parameter value SS$_NOPRIV fatal, no privilege for attempted operation SS$_NOSUCHOBJ fatal, no connection established AMS__INVRQDATA fatal, invalid request data AMS__TOOMANY fatal, too many connections AMS__INVFTD warning, invalid FTD specified AMS__INVREQ warning, invalid request type AMS__OVRFLOW warning, too many outstanding messages others as returned by EPICURE and VMS system services

ams_request_alarm

(int)status = ams_request_alarm( darm, ast [,astp] )

This routine requests alarm sets or reads given the list specified by the ``dar'' parameter. Notification of the return data is accomplished through a user-provided AST routine (see ast) specified by the ``ast'' parameter. The AST routine is executed for every list contained in the request list. The parameters passed to the AST routine include: completion status, node name string (source of data), return data, return data length, and the user-provided parameter (``astp''). If an error occurs on the logical link, the completion status, node name, and user-provided parameters are valid. darm address of the alarm request message. Passed by reference. ast address of the routine called when a list returns. (see ast). Passed by reference. astp parameter passed to the AST routine (see ast). Passed by value. status returns a condition value: SS$_NORMAL success AMS__QUEUED success, message queued but not sent SS$_NOPRIV fatal, no privilege for attempted operation SS$_NOSUCHOBJ fatal, no connection established AMS__TOOMANY fatal, too many connections AMS__OVRFLOW warning, too many outstanding messages others as returned by EPICURE and VMS system services

ams_send_dae_status

(int)status = ams_send_dae_status( code )

This routine is specifically used by the DEMServer process and others which monitor exceptions received from the DAE. The code retrieved from the HERMES queue is hashed to a particular bit number and communicated to the AMS. The source node name and message facility codes are used to derive a device name. The bit number of the device represents the specific message code. If the bit number exceeds the maximum number of allowable bits, an overflow message is communicated. code value of the status code received from the dae. Passed by value. status returns a condition value: SS$_NORMAL success AMS__QUEUED success, message queued but not sent SS$_NOSUCHOBJ fatal, no connection established SS$_NOPRIV fatal, no privilege for attempted operation AMS__OVRFLOW warning, too many outstanding messages others as returned by EPICURE and VMS system services

ams_set_alarm

(int)status = ams_set_alarm( dar, ast [,astp] )

This routine requests alarm sets for the list specified by the ``dar'' parameter. Notification of the return data is accomplished through a user-provided AST routine (see ast) specified by the ``ast'' parameter. The parameters passed to the AST routine include: completion status, node name string (source of data), return data, return data length, and the user-provided parameter (``astp''). If an error occurs on the logical link, the completion status, node name, and user-provided parameters are valid. dar address of the request message (alarm set). Passed by reference. ast address of the routine called when a list returns. (see ast). Passed by reference. astp parameter passed to the AST routine (see ast). Passed by value. status returns a condition value: SS$_NORMAL success AMS__QUEUED success, message queued but not sent SS$_BADPARAM fatal, bad parameter value SS$_NOPRIV fatal, no privilege for attempted operation SS$_NOSUCHOBJ fatal, no connection established AMS__TOOMANY fatal, too many connections AMS__INVFTD warning, invalid FTD specified AMS__INVREQ warning, invalid request type AMS__OVRFLOW warning, too many outstanding messages others as returned by EPICURE and VMS system services

ast

(void)ast(status, node, data, datalen, usrprm )

This user-provided routine is called at AST level (IPL 2) on behalf of the user and indicates that return data has arrived for the corresponding UTI routine. The routine is called with the above parameters and below provides a description. In addition, this routine is called when failures occur related to the network or when the alarm server crashes or is forced to exit due to restart. status completion status of the operation. Passed by value. The returned status codes are listed below: SS$_NORMAL success AMS__NOMORE success, no more data SS$_UNSUPPORTED error, unsupported operation or function AMS__NODATA warning, no data returned AMS__CRASH warning, alarm server crashing AMS__FORCED warning, alarm server forced to exit AMS__NOSERVER warning, alarm server unavailable AMS__INVMSG fatal, invalid message received others as returned by EPICURE and VMS system services node a character string of the source node name. Passed by reference. data address of the return data. Passed by reference. datalen size of the return data. Passed by value. usrprm user parameter. Passed by value.

Appendix A: Programming Examples

This page was intentionally left blank.

Keywords: EPICURE, AMS, ALARM

Distribution:

Normal

Security, Privacy, Legal

rwest@fsus04.fnal.gov