EPICURE Software Release Note 105.2<P> <b> DAE-Event-Monitor Server and Services</b>

EPICURE Software Release Note 105.2

DAE-Event-Monitor Server and Services

David M. Kline

Exceptions which occur on the Data Acquisition Engines (DAE) can be communicated to the upper levels of the EPICURE control system by inserting messages into the HERMES return queue. The DAE-Event-Monitor Server (DEMServer) is a process which executes in the VMS operating system as a detached process, and responds to messages when they appear on the return queue. This document will focus on the descriptions of the process internals, and the User-Task-Interface service routines which were implemented to retrieve information from the server.

Introduction

The primary purpose of the process is to remove messages from the HERMES return queue when the appear. Messages received contain information provided by the VME processors about exceptions and other conditions that occurred. The information is inserted into an internal queue, translated, and written to the message, error, and event files.

The User-Task-Interface (UTI) provides a simple and consistent set of services which allow clients to retrieve information maintained by the DEMServer. The services allow applications to retrieve information about clients, events, and statistics. Complete descriptions of the services are provided in later sections.

DAE-Event-Monitor Server

The currently executes as a detached process on both Qbus and TURBOchannel front ends. It responds to messages from the HERMES return queue, inbound network requests, and internal event timers. The EPICURE services provide the mechanism to notify that one of the above events occurred. Incoming events are inserted into the command event queue (evtq_) and are dispatched to the appropriate routine. Dispatching is accomplished by associating a particular event with an identifier, and an internal service routine.

The EPICURE network services are used to declare the as a network object, and handle non-transparent task-to-task DECnet operations over a logical link. The services are able to process multiple inbound connections for multiple network objects . The server, however, imposes a limit on the number of clients who can be connected at any given time. Messages received from the network trigger an that inserts the associated identifier into the command event queue. The event is removed from the queue, and the appropriate service routine is called.

Internal event timers are used to perform periodic operations to flush the file buffers associated with and . Two timers are implemented to perform this operation. One occurs every two (2) seconds, and another every twenty-four (24) hours. Both insert the identifier into the command event queue that request the flush. The event is removed from the queue and the appropriate service routines are called. In the future, the later event (24hr.) will be augmented to perform additional operations.

The maintains a to track clients who are currently connected. When a connection is made to the network object using either transparent or non-transparent DECnet, the request is accepted or rejected based upon the number of users currently connected. If the limit hasn't been exceeded, the client is inserted into the otherwise, the request is rejected. Additional information is kept about the client which includes the connect time, user name, remote node name, and the task connection identifier returned by the services. When the connection is broken between the and a remote client, the task connection identifier is used to remove the entry from the and release any dynamic memory to the free pool. Client connects and disconnects are also tracked through the message file. A message indicating a connect or disconnect is written to the message file including date/time information. Applications can retrieve the data with the service routine. Consult with section ``User-Task-Interface Services'' for a complete description of the service routine.

Messages which appear on the return queue trigger an that inserts the associated identifier into the command event queue. The event is removed from the queue and the appropriate service routine is called. Information provided by the VME processors is related to exceptions and status which occurred at the DAE level. The message contains a VMS status code that gets translated and written either to the message or error files. The event is written to the message file if the status code severity is informational or successful; otherwise, it's written to the error file. Additionally, the event is written to the event file as a record-oriented structure. The event file is a history of the events which occurred on the VME processors. Events are appended to the event file until it's removed from the disk directory (deleted), or renamed by a system programmer. Events can, therefore, be separated logically into physics runs, yearly quarters, or a monthly basis. In addition, events are inserted at the tail of the queue. The queue consists of the last one-thousand (1000) events which have appeared on the HERMES return queue. When this limit is reached, the event at the head of the queue is removed, making room for the new one. Applications can retrieve the data with the service routine. Consult the section on ``User-Task-Interface Services'' for a complete description of the service routine.

The is started as part of the EPICURE front end procedures after the Common Memory initialization, and before downloading the VME processors TIMER, CAMAC, and LISTENER. This is done to trap various types of error and status messages that can result from VME processor initialization.

Internal Routines

The calls its internal service routines to allocate and release dynamic memory; manage and entries; receive and respond to network messages; remove and process messages from the HERMES return queue; and update the message, error, and event files.

User-Task-Interface Services

Applications call the services provided by the User-Task-Interface (UTI) to connect to individual or multiple processes, to retrieve data held in the or , or to retrieve statistical information maintained by the server. Connections are made to the remote processes using transparent DECnet to establish the logical link. Communications over the logical link are synchronous.

The service routines begin with the prefix and are separated into User-Service (US) and Core-Service (CS) routines. The services are identified by the ``___'' (triple-underscore) characters and are available only to services. service routines are available to applications, and some allow for optional parameters. These parameters are identified by enclosed brackets []. Refer to Appendix A for programming examples.

Core-Services (CS)

dem___connect

(int)status = dem___connect( id, node ) This core service routine creates a task connection string and attempts to establish a logical link between the application and the remote DEMServer specified by the node parameter. The necessary dynamic memory to maintain the link is allocated and inserted into the internal Connection-Block (CB) list. id integer returning the DEMServer process identifier. Passed by reference. node null-terminated string of the node name to attempt the connection with. Passed by reference. status returns a VMS condition code: SS$_NORMAL success others as returned by VMS system services

dem___translate

(int)status = dem___translate( id, count ) This core service routine translates the RDCS$DEM_SERVER_NODE logical for node names that are executing DEMServer processes. The dem___connect() core service is then called to attempt a connection with the DEMServer network object, and to allocate the necessary dynamic memory in order to maintain the link. If the connection was successful, the address of the dynamic memory is assigned to the id parameter. id array of integers returning identifiers to the DEMServer processes. Passed by reference. count integer returning the number of successful connections that were established. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_NOSUCHOBJ fatal, network object is unknown at remote node others as returned by VMS system services

User-Services (US)

dem_connect

(int)status = dem_connect( id, [count,] [node] ) This routine attempts to establish a logical link between the application and the remote DEMServer process specified by the node parameter. If the node parameter isn't passed, the id parameter is treated as an array of integers consisting of identifiers to node names listed in the logical RDCS$DEM_SERVER_NODE. The specific node name can be found by using the dem_get_stats() routine. In addition, the VMS times used to implement since and yesterday search modes are converted into their binary equivalent. id integer returning the DEMServer process identifier. However, if the node parameter isn't passed, the id parameter is passed as an array of integers. Passed by reference. count optional integer returning the number of successful connections that were established. Passed by reference. node optional parameter that is a null-terminated string of the node name to attempt the connection with. Passed by reference. status returns a VMS condition code: SS$_NORMAL success SS$_INSFARG fatal, insufficient call arguments SS$_BADPARAM fatal, bad parameter value others as returned by VMS system services

dem_disconnect

(int)status = dem_disconnect( ) The logical links setup by the dem_connect() service routine are disconnected and the dynamic memory is released to the free pool. status returns a VMS condition code: SS$_NORMAL success others as returned by VMS system services

dem_get_eventlist

(int)status = dem_get_eventlist( id, evtlst, evtcnt, [cntrl,] [date] ) This routine performs a synchronous operation over the logical link to retrieve the events that are held by the DEMServer. The data is retrieved from the server specified with the id parameter. id integer used to access the DEMServer process. Passed by value. evtlst returned data containing the event information. This parameter is an array of EVENT data structures as defined in the DEMUTI.H header file. Passed by reference. evtcnt integer returning the number of events currently held by the DEMServer process. Passed by reference. cntrl optional integer parameter specifying the search mode. The valid modes that can be processed are defined as symbols in the DEMUTI.H header file and are below. Passed by value. SINCE events which have occurred since the date parameter. BEFORE events which have occurred before the date parameter. TODAY events which have occurred since 12AM today. YESTERDAY events which have occurred since 12AM yesterday. date optional quadword time in VMS time format specifying the search date. This parameter is used only with the SINCE or BEFORE search modes. Passed by reference. status returned VMS status codes: SS$_NORMAL success SS$_INSFARG fatal, insufficient call arguments SS$_BADPARAM fatal, bad parameter value DEM__NODATA error, no return data available for the request DEM__IVRPY fatal, invalid reply message data type others as returned by VMS system services and the server

dem_get_stats

(int)status = dem_get_stats( id, stats ) This routine performs a synchronous operation over the logical link to retrieve the statistics maintained by the DEMServer. The data is retrieved from the server specified with the id parameter. id integer used to access the DEMServer process. Passed by value. stats returned data containing the statistics information. This is the address of the STAT data structure as defined in the DEMUTI.H header file. Passed by reference. status returns a VMS condition code: SS$_NORMAL success DEM__IVRPY fatal, invalid reply message data type others as returned by VMS system services and the server

dem_get_userlist

(int)status = dem_get_userlist( id, userlist, usercount ) This routine performs a synchronous operation over the logical link to retrieve who is currently connected to the DEMServer. The data is retrieved from the server specified with the id parameter. id integer used to access the DEMServer process. Passed by value. userlist returned data containing the user information. This parameter is an array of USER data structures as defined in the DEMUTI.H header file. Passed by reference. usercount integer returning the number of users currently connected. Passed by reference. status returns VMS condition code: SS$_NORMAL success DEM__IVRPY fatal, invalid reply message data type others as returned by VMS system services and the server

Internals

Logical Names

A set of logicals are used by the and to specify the location of the message, error, event files; and the list of node names where servers are executing. The service routine fully translates the RDCS$DEM_SERVER_NODE logical when the ``node'' parameter isn't passed to find processes. The logical RDCS$DEM_EVENT_FILE is used by the to locate the message, error, and event files. Both logicals are defined by the process startup command procedure. The logical RDCS$DEM_SERVER_NODE points to all front ends and test stands, and the logical RDCS$DEM_EVENT_FILE points to the RDCS_LOGS directory.

Data Structures for Applications

This section describes the data structure formats and fields which are available to applications that want to access services. The structure definitions are used by programmers, operators, and experimenters. The header file is located in . In addition, there are symbols which are defined in the header file which indicate the maximum number of clients in the , maximum number of events in the , maximum number of identifiers that can be passed to the service routine, and valid search modes passed to the service routine.

The symbols are defined as follows:

#define SINCE      0X100
#define BEFORE     0X101
#define TODAY      0X102
#define YESTERDAY  0X103

#define MAXUSERS 10 #define MAXEVENTS 1000 #define MAXIDS 10

The symbols can be described as follows:

list [SINCE] This symbol indicates to return events that have occurred , and including, the specified date in VMS quadword format. [BEFORE] This symbol indicates to return events that have occurred the specified date in VMS quadword format. [TODAY] This symbol indicates to return events that have occurred since midnight. [YESTERDAY] This symbol indicates to return events that have occurred since midnight yesterday. [MAXUSERS] This symbol is the maximum number of clients that can be connected to the . [MAXEVENTS] This symbol is the maximum number of events that are held by the . [MAXIDS] This symbols is the maximum number of identifiers that can be passed, at one time, to the routine. Refer to section ``User-Task-Interface Services'' for further details.

User-List Block

The contains fields which pertain to client information and are assigned when a connection is accepted. The structure displays the format of the data which tracks who is currently connected to the . Applications pass an array of these blocks when calling the routine.

The structure format can be described as follows:

struct USER {
    int tcid;
    int connect_time[2];
    char node[8];
    char name[16];
    };

The structure fields can be described as follows:

list [tcid] This field is the Task-Connection-Identifier that is passed to the user connect routine called from the service routines. The provides a unique value which identifies clients when identical user names are present. [connect_time] This field is the date and time the client connected. It is in VMS time units and can be converted to a character string with the SYS$ASCTIM() VMS system service. [node] This field is a null-terminated character string indicating the node from which the connection originated. [name] This field is a null-terminated character string indicating the user who requested the connection.

Event-List Block

The contains fields which are related to an event that occurred in the VME processor. The structure is composed of a time stamp in VMS quadword time units and the structure . Combining these structures describes the particulars of the event. Applications pass an array of structures when calling the routine.

The structure format can be described as follows:

struct DAEMSG {
    unsigned int vms_status;
    struct TimeStamp dae_timestamp;
    unsigned int length;
    unsigned int dae_status;
    unsigned int fnc_addr;
    unsigned int cmb_addr;
    };

The structure fields can be described as follows:

list [vms_status] This field contains the VMS status code inserted by the VME processor indicating the type of exception which occurred. [dae_timestamp] This field includes the time stamp in ``clinks'' of when the event occurred in the VME processor and the micro-seconds since the last accelerator cycle reset . [length] This field is the length (in bytes) of the message. [dae_status] This field is the status returned by the routine . [fnc_addr] This field indicates the function where the error occurred. [cmb_addr] This field is the address of the Common Memory block.

The structure format can be described as follows:

struct EVENT {
    unsigned int vms_timestamp[2];
    struct DAEMSG daemsg;
    };

The structure fields can be described as follows:

list [vms_timestamp] This field is the time stamp in VMS units of when the message was removed from the HERMES return queue. [daemsg] This field is the structure and is described above.

Statistics Block

The doesn't maintain any statistics at this time but will in the future. The structure contains the ``node'' field that is a null-terminated character string on the node which the is executing. Applications pass the address of the structure when calling the routine.

The structure can be described as follows:

struct STAT {
    unsigned char node[8];
    };

Data Structures for DEMserver and UTI

The structures described in the previous section are available to the and services. Additionally, other data structure formats and fields are available and are described in this section. The header file that defines the structures and other symbols is located in .

Event-Log Block

The is composed of a record identifier and the structure. It is written to the event file and provides archiving for historical reference. This section describes the structure format and fields.

The structure can be described as follows:

struct EVENTLOG {
    unsigned int id;
    struct EVENT event;
    };

The structure fields can be described as follows:

list [id] This field identifies the record. [event] This field is the structure and is described above.

Network-Request

The is constructed by the and sent over the logical link to the . It is currently composed of a single field (req_l_fc) but can be extended if necessary. This section describes the structure format and the field.

The structure can be described as follows:

struct NETREQ {
    unsigned int req_l_fc;
    };

The structure fields can be described as follows:

list [req_l_fc] This field is the function code requesting some particular information from the . Valid requests are defined in the header file as symbols and are described below: list [RETEVT] Returns the . [RETSTS] Returns the statistics. [RETUSERS] Returns the . []

Network-Reply

The is constructed by the in response to a . It is formatted and sent to the application by means of the service routines. This section describes the structure and the fields which compose it.

The structure can be described as follows:

struct NETRPY {
    unsigned int status;
    unsigned int dtype;
    unsigned int count;
    variant_union {
        struct STAT stats;
        struct USER users[MAXUSERS];
        struct EVENT events[MAXEVENTS];
        } $msg_overlay;
    };

The structure fields can be described as follows:

list [status] This field is the return status to the request. [dtype] This field is the data type that is being sent back to the application. The matches this field with the request type and returns the DEM__IVRPY status error code if they don't match. This provides a method of verifying message integrity. [count] This field is the number of or structure items returned to the application. The value is set to one when the structure is returned. [stats] This is the returned structure. [users] This is the returned structures containing the clients who are currently connected to the . The limit to the number of clients who can be connected is defined by the MAXUSERS symbol defined in . [events] This is the returned structures containing the events which have occurred. The limit to the number of events that can be held in is defined by the MAXEVENTS symbol defined in .

Network-Message

The structure is used by the and serving for programming convenience. It overlays the and structures providing a easy method to access either type of structure .

The structure can be described as follows:

struct NETMSG {
    variant_union {
        struct NETREQ request;
        struct NETRPY reply;
        } $msg_overlay;
    };

The structure fields can be described as follows:

list [request] This field is the structure. [reply] This field is the structure.

SNS-Message

The structure is for both programming convenience and the service routines. The first five (5) integers is the network message header and are used by services for its internal processing. The remainder of the structure is used by the to receive and respond to messages from the network .

The structure can be described as follows:

struct SNSMSG {
    variant_union {
        int links[2];
        unsigned short iostatus;
        } $link_overlay;
    int alloclen;
    int tcid;
    int usedlen;
    variant_union {
        struct NETREQ request;
        struct NETRPY reply;
        } $msg_overlay;
    };

The structure fields can be described as follows:

list [links/iostatus] These fields are used by the services for internal queue links (links), or when the message is involved in an I/O operation (iostatus). [alloclen] This field includes the size (in bytes) of the network message header plus the larger of the or structures. [tcid] This field is the Task-Connection-Identifier and is used by services to access and maintain information about the logical link. [usedlen] This field is the larger of the or structures. [request] This field is the structure. [reply] This field is the structure.

Connection-Block

The maintains a Connection-Block (CB) list that contains all the connections that were established by the service routine. It's implemented as a singly linked list connecting structures together and contains information pertaining to the logical link.

The structure can be described as follows:

struct CB {
    struct CB *link;
    short channel;
    struct NETREQ request;
    struct NETRPY reply;
    };

The structure fields can be described as follows:

list [link] This field connects the blocks together. A non-zero value indicates that there's an adjacent structure. A zero value indicates that the end of the list has been reached. [channel] This field is the logical number associated with the logical link. [request] This field is the structure and contains the current request message sent to the . [reply] This field is the structure and contains the current reply message received from the .

Appendix A: Programming Examples

This page was intentionally left blank.

Keywords: EPICURE, QVI, TVI, VME, DEM

Distribution:

Normal

Security, Privacy, Legal

rwest@fsus04.fnal.gov