Contents This chapter contains the following sections. Section Title Page “Introduction? 1-1 “Problems Being Addressed? 1-3 “Problems Not Being Addressed? 1-5 “Design Rationale? 1-5 “Conformance to the DAIS? 1-7 The purpose of the DAIS Application Program Interface (API) is to support efficient real time transfer of large amounts of data from an industrial process to a wide range of clients. It supports discovery of parameters and update of parameter values. The DAIS is intended for on-line data transfer and cannot be used to configure servers implementing the API. Control systems used to monitor and control industrial processes consist of the following major pieces: • Process instrumentation making sensor data and actuation capabilities available. • Process stations or remote terminal units (RTUs) reading sensor data and controlling actuators. • Supervisory Control and Data Acquisition (SCADA) system making processed sensor data and control capabilities available to operators, applications, or other systems. • Management systems using SCADA data to make further processing and control. SCADA and management systems can be regarded having a server part where data processing is performed and a Human Machine Interface (HMI) part where visualization and command dialogs are made. The SCADA and management system may have common or different HMI. This results in a hierarchical structure shown below. SCADA Management system Instrumentation RTU/ Process station Server Server HMI HMI Data transfer for APIs concerned with Process data Data written to process Figure 1-1 Control system structure The solid arrows in Figure 1-1 correspond to transfer of data from servers to clients. The data can be state variables and parameters (for example, measured values, calculated values, limit values, dead bands, scan rates, engineering units). The dashed arrows correspond to data written to servers by clients. The data can be control variables and parameters. The API support simple writes operations. More complex controls like select and execute (for example, breaker on/off) or raise lower commands can be implemented combining multiple write and read operations. As indicated in Figure 1-1 the DAIS API can be used at several levels in a system. For example, a DAIS server can be an RTU/Process station communication unit, a SCADA server, or even a Management system. DAIS support both subscription and read/write operations. A subscription means server has no a priori knowledge of clients and it is clients that establish connection with servers. Once connection is established a server calls the clients back when data becomes available or updated. The callbacks mean the DAIS API also defines an interface that the client has to implement. Server Client Establish connection Callback data transfer Figure 1-2 Data subscription Figure 1-2 shows the bi-directional subscription with connection establishment and callback interfaces. For historical reasons SCADA systems for different industrial processes has evolved along different lines. SCADA for power systems has evolved onto a UNIX base and SCADA for most other industrial processes has evolved onto a Windows NT base. For UNIX based systems APIs formulated in CORBA (Common Object Request Broker Architecture) IDL (Interface Definition Language) are now emerging (for example, DAIS RFP [1] and UMS DAF [2]). For Windows NT based systems, such as OLE for Process Control (OPC) [3], has become the dominating standard. OPC defines three different APIs; measurement data access [4], alarms & events [5], and history [6]. OPC is based on Microsoft COM. OPC is focused on the interfaces and does not explicitly describe the information model behind the interface. The information model is however implicit and can be derived from the OPC specifications. This specification describes both the API and information model expressed in UML. Within the CCAPI project an information model Common Information Model (CIM) [7] has been developed. This model is now evolving into the IEC 61970-30x draft standard [8]. The CIM contains a SCADA information model (61970-303) with its roots in power transmission and generation. The DAIS API supports the CIM. The DAIS API is intended for transfer of process data on subscription basis as indicated in Figure 1-1 and Figure 1-2. Process data consists of quality tagged and time stamped scalar values. The API is intended to efficiently transfer large amounts of data simultaneously to many clients (subscribers). Clients and servers involved in data exchange can be of many kinds (for example, HMI or management systems as indicated in Figure 1-1). A client may also appear as a server (for example, aggregating data from other servers or performing calculations as indicated in Figure 1-3). This creates hierarchical structures of DAIS servers. Serv er Server Server Serv er Serv er Serv er Server Clien t DA IS D A IS D A IS Figure 1-3 Using DAIS as interface between multiple servers As an example the servers in the leftmost layer in Figure 1-3 might be OPC compliant RTUs (or IEDs), next right might be communication front ends, and the rightmost server may provide both telemetered and estimated data. The DAIS API is intended to be used for a wide range of industrial processes. For example: • power transmission • power generation • power distribution • water and sewage management• oil and gas • district heating • pulp and paper • food manufacturing The kinds of data that can be reached through the DAIS API are: • measurement data access • alarms & events access This data is typically available from hardware units in the process (for example, RTUs, PLCs, distributed controllers) or other control centers (for example, SCADA systems). Refined or calculated data, parameters, and alarms & events might also come from applications (for example, custom calculations, state estimation, optimization) in SCADA or Management systems. These data might be provided through the DAIS API as well. This specification provides interfaces for data access including: • Discovery of data available in a server. • Discovery of the information model supported by a server (for example, available types and their properties). • Synchronous and asynchronous read or write of server data. • Creation and maintenance of subscriptions at the server. • Client side subscription callback interfaces for event driven data transfer. There are no explicit means to synchronize clients. Time stamping of data is provided so that clients can judge the age. Data is hierarchically organized in trees of nodes and items where the items are the leafs. The nodes in the hierarchy have a type (for example, substation, pump, breaker, or any collection of items). The type is transparent to the interface. An item is an instance of a property belonging to a type. Properties can describe any kind of state variables, control variables, or parameters existing in a control system. Data transferred by reads or callbacks are time stamped and quality coded. The problem of configuring a server or control system with nodes, items, areas, sources, reasons, condition spaces, and source conditions is outside the scope of this specification. The problem of supervising the control system equipment (for example, communication lines, computers, hard disks) and provide specific interfaces for this is outside the scope of this specification. It is however possible for a DAIS server to provide control system statuses as measurements. Besides meeting the requirements spelled out in the RFP there are a number of design goals that have shaped solutions. OPC has been in use for a number of years and this specification leverages on the experience gained by OPC. There are a large number of OPC based products in the market place and cases where DAIS and OPC will be bridged are likely. Adherence to OPC is important to facilitate simple bridging and porting DAIS software to/from OPC. Some design principles used when creating OPC were: • Method behavior is sometimes controlled by an input parameter. • Related data is transferred in multiple parallel vectors. • Outputs are always returned in one or more output parameters. To simplify and get a more uniform interface these principles have been replaced by the following: • A method has one single behavior resulting in some OPC methods being replaced by more than one DAIS method. • Related data is kept together in structs resulting in reduction of the number of parameters compared to OPC. • Outputs are returned as method return results resulting in the OPC HRESULT parameter being replaced by exceptions and reduced number of output parameters compared to OPC. A DAIS server is a real-time system required to deliver data in high rates and volumes. The performance requirements mean that a typical DAIS server does not use a relational database management system for on-line operation but some kind of real-time database. The DAIS API efficiently encapsulates such real-time databases from clients. To be effectively delivering data DAIS must not introduce performance bottlenecks of its own. This has influenced the design in several ways, listed below. The subscription mechanism consists of two phases. In the first the client negotiates with the server on what data items to subscribe for and in the second the actual data transfer takes place. This minimizes the amount of transferred data between the server and the client during on-line operation. DAIS support to use sequences of data in calls rather than having calls requiring single valued parameters. This allows clients to ask for processing of multiple data in a single call rather than making multiple calls thus reducing the number of LAN round trips. Large volumes of data are not efficiently transferred in one method call. For this reason many methods return an iterator that is used to transfer optimal volumes of data in each call. The basic unit of data is a union type: SimpleValue. SimpleValue exploits our knowledge of the basic data types needed and eliminates CORBA any from the highest bandwidth part of the interface. This can make a significant impact on performance when accumulated across large amounts of data. The DAIS has three major conformance points: 1. The DAIS Server 2. The DAIS Data Access 3. The DAIS Alarms and Events. An implementation • shall conform to point 1. • shall conform to either point 2 or point 3. • may conform to both point 2 and point 3. The DAIS interface as defined in Section 3.2, “Server,? on page 3-30 is a mandatory conformance point for a DAIS Server with the exception of the following optional methods: • DAIS::Server::find_views() • DAIS::Server::create_data_access_session_for_view() • DAIS::Server::create_alarms_and_events_session_for_view() • DAIS::Server::inspect() A server shall also conform to • Section 3.1.1, “Character Encoding,? on page 3-1. The use of XPath as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25, Section 5.2.4.2, “IDL,? on page 5-14, and Section 5.2.7.3, “Condition Logic,? on page 5-38 is an optional conformance point. The DAIS interface as defined in Section 3.1, “Common Declarations,? on page 3-1 and Section 4.2, “API,? on page 4-8 is a mandatory conformance point for Data Access. The DAIS interface as defined in Section 3.1, “Common Declarations,? on page 3-1 and Section 5.2, “API,? on page 5-6 is a mandatory conformance point for Alarms and Events. The purpose of the DAIS Application Program Interface (API) is to support efficient real time transfer of large amounts of data from an industrial process to a wide range of clients. It supports discovery of parameters and update of parameter values. The DAIS is intended for on-line data transfer and cannot be used to configure servers implementing the API. Control systems used to monitor and control industrial processes consist of the following major pieces: • Process instrumentation making sensor data and actuation capabilities available. • Process stations or remote terminal units (RTUs) reading sensor data and controlling actuators. • Supervisory Control and Data Acquisition (SCADA) system making processed sensor data and control capabilities available to operators, applications, or other systems. • Management systems using SCADA data to make further processing and control. SCADA and management systems can be regarded having a server part where data processing is performed and a Human Machine Interface (HMI) part where visualization and command dialogs are made. The SCADA and management system may have common or different HMI. This results in a hierarchical structure shown below. SCADA Management system Instrumentation RTU/ Process station Server Server HMI HMI Data transfer for APIs concerned with Process data Data written to process Figure 1-1 Control system structure The solid arrows in Figure 1-1 correspond to transfer of data from servers to clients. The data can be state variables and parameters (for example, measured values, calculated values, limit values, dead bands, scan rates, engineering units). The dashed arrows correspond to data written to servers by clients. The data can be control variables and parameters. The API support simple writes operations. More complex controls like select and execute (for example, breaker on/off) or raise lower commands can be implemented combining multiple write and read operations. As indicated in Figure 1-1 the DAIS API can be used at several levels in a system. For example, a DAIS server can be an RTU/Process station communication unit, a SCADA server, or even a Management system. DAIS support both subscription and read/write operations. A subscription means server has no a priori knowledge of clients and it is clients that establish connection with servers. Once connection is established a server calls the clients back when data becomes available or updated. The callbacks mean the DAIS API also defines an interface that the client has to implement. Server Client Establish connection Callback data transfer Figure 1-2 Data subscription Figure 1-2 shows the bi-directional subscription with connection establishment and callback interfaces. For historical reasons SCADA systems for different industrial processes has evolved along different lines. SCADA for power systems has evolved onto a UNIX base and SCADA for most other industrial processes has evolved onto a Windows NT base. For UNIX based systems APIs formulated in CORBA (Common Object Request Broker Architecture) IDL (Interface Definition Language) are now emerging (for example, DAIS RFP [1] and UMS DAF [2]). For Windows NT based systems, such as OLE for Process Control (OPC) [3], has become the dominating standard. OPC defines three different APIs; measurement data access [4], alarms & events [5], and history [6]. OPC is based on Microsoft COM. OPC is focused on the interfaces and does not explicitly describe the information model behind the interface. The information model is however implicit and can be derived from the OPC specifications. This specification describes both the API and information model expressed in UML. Within the CCAPI project an information model Common Information Model (CIM) [7] has been developed. This model is now evolving into the IEC 61970-30x draft standard [8]. The CIM contains a SCADA information model (61970-303) with its roots in power transmission and generation. The DAIS API supports the CIM. The DAIS API is intended for transfer of process data on subscription basis as indicated in Figure 1-1 and Figure 1-2. Process data consists of quality tagged and time stamped scalar values. The API is intended to efficiently transfer large amounts of data simultaneously to many clients (subscribers). Clients and servers involved in data exchange can be of many kinds (for example, HMI or management systems as indicated in Figure 1-1). A client may also appear as a server (for example, aggregating data from other servers or performing calculations as indicated in Figure 1-3). This creates hierarchical structures of DAIS servers. Serv er Server Server Serv er Serv er Serv er Server Clien t DA IS D A IS D A IS Figure 1-3 Using DAIS as interface between multiple servers As an example the servers in the leftmost layer in Figure 1-3 might be OPC compliant RTUs (or IEDs), next right might be communication front ends, and the rightmost server may provide both telemetered and estimated data. The DAIS API is intended to be used for a wide range of industrial processes. For example: • power transmission • power generation • power distribution • water and sewage management• oil and gas • district heating • pulp and paper • food manufacturing The kinds of data that can be reached through the DAIS API are: • measurement data access • alarms & events access This data is typically available from hardware units in the process (for example, RTUs, PLCs, distributed controllers) or other control centers (for example, SCADA systems). Refined or calculated data, parameters, and alarms & events might also come from applications (for example, custom calculations, state estimation, optimization) in SCADA or Management systems. These data might be provided through the DAIS API as well. This specification provides interfaces for data access including: • Discovery of data available in a server. • Discovery of the information model supported by a server (for example, available types and their properties). • Synchronous and asynchronous read or write of server data. • Creation and maintenance of subscriptions at the server. • Client side subscription callback interfaces for event driven data transfer. There are no explicit means to synchronize clients. Time stamping of data is provided so that clients can judge the age. Data is hierarchically organized in trees of nodes and items where the items are the leafs. The nodes in the hierarchy have a type (for example, substation, pump, breaker, or any collection of items). The type is transparent to the interface. An item is an instance of a property belonging to a type. Properties can describe any kind of state variables, control variables, or parameters existing in a control system. Data transferred by reads or callbacks are time stamped and quality coded. This specification provides interfaces for data access including: • Discovery of data available in a server. • Discovery of the information model supported by a server (for example, available types and their properties). • Synchronous and asynchronous read or write of server data. • Creation and maintenance of subscriptions at the server. • Client side subscription callback interfaces for event driven data transfer. There are no explicit means to synchronize clients. Time stamping of data is provided so that clients can judge the age. Data is hierarchically organized in trees of nodes and items where the items are the leafs. The nodes in the hierarchy have a type (for example, substation, pump, breaker, or any collection of items). The type is transparent to the interface. An item is an instance of a property belonging to a type. Properties can describe any kind of state variables, control variables, or parameters existing in a control system. Data transferred by reads or callbacks are time stamped and quality coded. The problem of configuring a server or control system with nodes, items, areas, sources, reasons, condition spaces, and source conditions is outside the scope of this specification. The problem of supervising the control system equipment (for example, communication lines, computers, hard disks) and provide specific interfaces for this is outside the scope of this specification. It is however possible for a DAIS server to provide control system statuses as measurements. Besides meeting the requirements spelled out in the RFP there are a number of design goals that have shaped solutions. OPC has been in use for a number of years and this specification leverages on the experience gained by OPC. There are a large number of OPC based products in the market place and cases where DAIS and OPC will be bridged are likely. Adherence to OPC is important to facilitate simple bridging and porting DAIS software to/from OPC. Some design principles used when creating OPC were: • Method behavior is sometimes controlled by an input parameter. • Related data is transferred in multiple parallel vectors. • Outputs are always returned in one or more output parameters. To simplify and get a more uniform interface these principles have been replaced by the following: • A method has one single behavior resulting in some OPC methods being replaced by more than one DAIS method. • Related data is kept together in structs resulting in reduction of the number of parameters compared to OPC. • Outputs are returned as method return results resulting in the OPC HRESULT parameter being replaced by exceptions and reduced number of output parameters compared to OPC. A DAIS server is a real-time system required to deliver data in high rates and volumes. The performance requirements mean that a typical DAIS server does not use a relational database management system for on-line operation but some kind of real-time database. The DAIS API efficiently encapsulates such real-time databases from clients. To be effectively delivering data DAIS must not introduce performance bottlenecks of its own. This has influenced the design in several ways, listed below. The subscription mechanism consists of two phases. In the first the client negotiates with the server on what data items to subscribe for and in the second the actual data transfer takes place. This minimizes the amount of transferred data between the server and the client during on-line operation. DAIS support to use sequences of data in calls rather than having calls requiring single valued parameters. This allows clients to ask for processing of multiple data in a single call rather than making multiple calls thus reducing the number of LAN round trips. Large volumes of data are not efficiently transferred in one method call. For this reason many methods return an iterator that is used to transfer optimal volumes of data in each call. The basic unit of data is a union type: SimpleValue. SimpleValue exploits our knowledge of the basic data types needed and eliminates CORBA any from the highest bandwidth part of the interface. This can make a significant impact on performance when accumulated across large amounts of data. OPC has been in use for a number of years and this specification leverages on the experience gained by OPC. There are a large number of OPC based products in the market place and cases where DAIS and OPC will be bridged are likely. Adherence to OPC is important to facilitate simple bridging and porting DAIS software to/from OPC. Some design principles used when creating OPC were: • Method behavior is sometimes controlled by an input parameter. • Related data is transferred in multiple parallel vectors. • Outputs are always returned in one or more output parameters. To simplify and get a more uniform interface these principles have been replaced by the following: • A method has one single behavior resulting in some OPC methods being replaced by more than one DAIS method. • Related data is kept together in structs resulting in reduction of the number of parameters compared to OPC. • Outputs are returned as method return results resulting in the OPC HRESULT parameter being replaced by exceptions and reduced number of output parameters compared to OPC. A DAIS server is a real-time system required to deliver data in high rates and volumes. The performance requirements mean that a typical DAIS server does not use a relational database management system for on-line operation but some kind of real-time database. The DAIS API efficiently encapsulates such real-time databases from clients. To be effectively delivering data DAIS must not introduce performance bottlenecks of its own. This has influenced the design in several ways, listed below. The subscription mechanism consists of two phases. In the first the client negotiates with the server on what data items to subscribe for and in the second the actual data transfer takes place. This minimizes the amount of transferred data between the server and the client during on-line operation. DAIS support to use sequences of data in calls rather than having calls requiring single valued parameters. This allows clients to ask for processing of multiple data in a single call rather than making multiple calls thus reducing the number of LAN round trips. Large volumes of data are not efficiently transferred in one method call. For this reason many methods return an iterator that is used to transfer optimal volumes of data in each call. The basic unit of data is a union type: SimpleValue. SimpleValue exploits our knowledge of the basic data types needed and eliminates CORBA any from the highest bandwidth part of the interface. This can make a significant impact on performance when accumulated across large amounts of data. The DAIS has three major conformance points: 1. The DAIS Server 2. The DAIS Data Access 3. The DAIS Alarms and Events. An implementation • shall conform to point 1. • shall conform to either point 2 or point 3. • may conform to both point 2 and point 3. The DAIS interface as defined in Section 3.2, “Server,? on page 3-30 is a mandatory conformance point for a DAIS Server with the exception of the following optional methods: • DAIS::Server::find_views() • DAIS::Server::create_data_access_session_for_view() • DAIS::Server::create_alarms_and_events_session_for_view() • DAIS::Server::inspect() A server shall also conform to • Section 3.1.1, “Character Encoding,? on page 3-1. The use of XPath as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25, Section 5.2.4.2, “IDL,? on page 5-14, and Section 5.2.7.3, “Condition Logic,? on page 5-38 is an optional conformance point. The DAIS interface as defined in Section 3.1, “Common Declarations,? on page 3-1 and Section 4.2, “API,? on page 4-8 is a mandatory conformance point for Data Access. The DAIS interface as defined in Section 3.1, “Common Declarations,? on page 3-1 and Section 5.2, “API,? on page 5-6 is a mandatory conformance point for Alarms and Events. The DAIS interface as defined in Section 3.2, “Server,? on page 3-30 is a mandatory conformance point for a DAIS Server with the exception of the following optional methods: • DAIS::Server::find_views() • DAIS::Server::create_data_access_session_for_view() • DAIS::Server::create_alarms_and_events_session_for_view() • DAIS::Server::inspect() A server shall also conform to • Section 3.1.1, “Character Encoding,? on page 3-1. The use of XPath as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25, Section 5.2.4.2, “IDL,? on page 5-14, and Section 5.2.7.3, “Condition Logic,? on page 5-38 is an optional conformance point. The DAIS interface as defined in Section 3.1, “Common Declarations,? on page 3-1 and Section 4.2, “API,? on page 4-8 is a mandatory conformance point for Data Access. The DAIS interface as defined in Section 3.1, “Common Declarations,? on page 3-1 and Section 5.2, “API,? on page 5-6 is a mandatory conformance point for Alarms and Events. Contents This chapter contains the following sections. Section Title Page “OLE for Process Control (OPC)? 2-1 “Data Access Facility (DAF)? 2-4 “COM and CORBA IDL Differences? 2-6 “IEC 1346-1, Structuring and Naming? 2-7 “IEC 61970 EMS API? 2-7 “XPath? 2-8 Differences and similarities between OPC and DAIS are described in this chapter. OPC is a service API providing access to data managed by the server. The data (for example, nodes, items, areas, sources, conditions, reasons) are not instantiated as objects at the client. This means that OPC does not define any particular APIs for the data instances that a client can deal with directly. OPC has a few coarse objects like OPCGroup and OPCEventSubscription supporting the data access. DAIS has adopted this principle and is identical to OPC in this respect. In OPC each client has its own OPC server object. In DAIS there is only one DAIS server object shared by all clients. To support individual client sessions a new session interface is defined. There is one interface for data access session objects and one for alarms & events session objects. The session objects correspond to the OPC server object. The OPC server object has interfaces for browsing server data (for example, IOPCBrowseServerAddressSpace and IOPCEventAreaBrowser) and information model (for example, IOPCItemProperties). In DAIS each type of data has its own object for browsing, these objects are called “home? objects. The OPC browse interface methods are hence divided among the different home objects. Many OPC interface, method, and parameter names have been kept but recasted according to the CORBA style guide. But many OPC names have been replaced by new names to more clearly indicate the meaning. This is particularly the case for the browse and alarms & events APIs. In OPC it is common to return arrays of HRESULTs corresponding to arrays of data. In the case where the data did not contain any errors an array with “no error occurred? codes still is returned. In DAIS such error codes will be returned as a sequence of error structs identifying the erroneous data and an error code. In case of no errors the sequence of error structs is empty. OPC data accesses use both server and client side handles created based on identification texts for nodes and items. To make the translation from identification texts to handles fast and avoid repeated translation in OPC an intermediate server side identifier called the blob exists. In DAIS the server side handles and blobs are replaced by identifiers based on ResourceIDs (both for nodes and items). For a description of ResourceIDs refer to Section 2.2, “Data Access Facility (DAF),? on page 2-4. The OPC client side handles are still kept in DAIS. COM/OPC use the standard interfaces IConnectionPoint to set up callbacks. In DAIS callbacks are set up directly between server and client by updating an attribute holding the callback object. The COM style enumerators in OPC are replaced by CORBA style iterators in DAIS. In OPC multiple parallel vectors often pass data. In DAIS a single vector holding structs, thus reducing the number of parameters, replaces the parallel vectors. In OPC all methods return the HRESULT error value. In DAIS HRESULTs are replaced by exceptions and out parameters are returned as method results instead. Only in a few cases are there additional output parameters in DAIS. In OPC data is generally organized in hierarchical structures. In data access the leafs are called leaf nodes and the branches branch nodes or items. A leaf node or item is the same as an instance of property at an object. A branch node corresponds to an: • Object having properties. • Arbitrary organization of other branch nodes. • Object having both properties and other branch nodes as children. In DAIS data access the branch nodes are called nodes and the leaf nodes are called items. In DAIS alarms & events, the branch nodes are called areas and the leaf nodes sources. In OPC branch and leaf nodes have a name unique among the nodes or items that are children of the same node. A second name is formed by combining these names from each branch node in the path from the node or leaf to the root. Both names are called ItemIDs in OPC and the name created by following the path to the root is sometimes called a fully qualified ItemID. In DAIS the name unique among the child’s to the same node is called label and the name including the labels from all nodes in the path to the root is called pathname. Both DAIS branch nodes and leaf nodes have both a label and a pathname. A label is used in the same way as a name but the word label is preferred before the word name as it denotes something that is atomic; that is, it cannot be further divided. OPC provides a server side cursor from where browsing is made and the OPC interface provides methods to move the cursor. DAIS does not provide server side cursors and requires the client to keep track of browse positions themselves. The reason for removing server side cursors is it makes clean up after crashed clients easier and simplifies the server design. OPC does not support types meaning it is not possible in OPC to get information about the type of a node. OPC however supports properties, which means it is possible to browse the existing properties and what properties a particular node has. DAIS has extended this to also include types; that is, it is possible to browse existing types, the properties each type has and each node has a type. OPC defines the following property sets: • set 1 of OPC specific properties • set 2 of OPC recommended properties • set 3 of vendor specific properties In DAIS, OPC set 1 properties cannot be browsed through the property-browsing interface (Property). Instead access of set 1 properties is direct in the interfaces as parameters or struct members as is the case for OPC. This means that DAIS exposes only OPC set 2 and 3 properties through the property browse interface. The UMS DAF and DAIS are server APIs for access of object data rather than the data objects themselves. The DAF describes a generic interface for navigating and reading data from complex data structures including relations between objects. Both DAF and DAIS support navigation in a space of hierarchically structured objects (an object is called a node in DAIS and a resource in DAF). Both support identification of objects and properties at an object. In DAIS an instance of property at an object is called an item and an ItemID (item identifier) identifies an item. An ItemID consists of a ResourceID (resource identifier) for the node and a PropertyID (property identifier) for the property. The DAIS API uses ItemIDs to access data while the DAF uses ResourceIDs and PropertyIDs separated. A system may implement both a DAF server and a DAIS server. In such a system it shall be assumed that the same object will have the same ResourceID seen through either API. This means it shall be possible to navigate to an object, retrieve its ResourceID through one of the APIs, and use that ResourceID with the other API. In the same way PropertyIDs are the same. Textual identification of resources and properties in the DAF is by URIs (Uniform Resource Identifier). ResourceIDs and PropertyIDs have their own URIs. URIs can be translated into corresponding ResourceIDs and PropertyIDs and vice versa. A property name is a URI where the container part is a unique schema identifier and the fragment part is the property name. For example: http://www.epri.com/schema/CIM-07f.xml#Measurement.positiveFlowIn DAIS does not support URIs directly but has a textual representation for nodes, items, types, and properties. This textual representation may correspond to the fragment part of a URI. In the case where a system supports both the DAF and the DAIS interfaces it is expected that the same object will be identified by the same ResourceID through both interfaces and the same property by the same PropertyID. Sameness of objects and properties; however, depends on the information model exposed through the two interfaces and if the information models are different, then a mapping is required. In the case where a system supports both the DAF and the DAIS interfaces it is expected that the same objects will be identified by the same ResourceID and URI fragment through both interfaces and the same property by the same PropertyID and URI fragment. The exact mapping has to be described for each DAIS item – DAF property pair according to the underlying information models. Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5 elaborates on the information model and a detailed mapping between IEC 61970-30x and the DAIS can be found in Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. The foregoing concepts are fundamental enough that they should find equivalents in any data repository. Some, perhaps approximate, equivalents are given in Table 2-1 as a guide. Table 2-1 Mappings between modeling languages RDF DAF Relational Model UML DAIS Resource Resource, ResourceID Tuple (i.e., row) Object Node, ResourceID Property Property, PropertyID Attribute (i.e., column) or foreign key Attribute or association Property, PropertyID Class Class, ClassID Relation (i.e., table) Class Type, TypeID Resource Description Resource Description Tuple value - Sequence URI URI, ResourceID Key value - Value SimpleValue Field value - SimpleValue - ResourceID and PropertyID pair - - Item, ItemID DAIS uses the DAF SimpleValue type for data transferred over the API instead of the OPC type VARIANT. The data types used in OPC are Microsoft COM types and as DAIS is a CORBA API a mapping of the data types is needed. The translation of OPC/COM data types to DAF/CORBA data types is listed below. Table 2-2 Mappings between OPC and DAF data types OPC/COM basic types DAF Simple Value types - ResourceID (RESOURCE_TYPE) - URI (URI_TYPE) LPWSTR (VT_BSTR) string (STRING_TYPE) BOOL (VT_BOOL) boolean (BOOLEAN_TYPE) LONG (VT_R4) long (INT_TYPE) DWORD (VT_I4) unsigned long (UNSIGNED_TYPE) double (VT_R8) double (DOUBLE_TYPE) - Complex (COMPLEX_TYPE) FILETIME (VT_Date) DateTime (DATE_TIME_TYPE) - ULongLong (ULONG_LONG_TYPE) WORD (VT_I2) unsigned long (UNSIGNED_TYPE) FLOAT (VT_R4) double (DOUBLE_TYPE) BYTE (VT_UI1) - HRESULT (VT_ERROR) - VARIANT (VARTYPE) SimpleValue (SimpleValueType) Interfaces defined in COM and CORBA IDL differ in a number of ways. Important differences concerning interface definitions are • object referencing, • interface management, • error management, and • IDL. A detailed description of the mapping can be found in the CORBA 2.3 specification, chapters 17, 18, and 19. In CORBA each object is uniquely referenced in one step. In COM obtaining an object usually is a two step process. In the first step a stateless server object is obtained. In the second step the server object is loaded with state data. In CORBA an object is a unique individual that contains state from the very beginning. A CORBA object has a single interface. This interface can be built from several other interfaces through inheritance. The resulting interface might have many methods and hence become big. A COM object usually has multiple interfaces and supports the client to detect and navigate between these interfaces at run time. As a CORBA interface is defined by inheritance it has to be fully defined at compile time. As COM allows run time detection of interfaces (the IUnknown::QueryInterface() method) a full match between interfaces implemented by a server and interfaces known to a client is not required. Mapping OPC interfaces to DAIS interfaces can be done in two ways: 1. Inherit a number of OPC interfaces into one CORBA object. This may result in name clashes that require renaming of methods. 2. Instantiate an OPC interface as an own CORBA object referenced by a container object. Both techniques are used in the DAIS specification. CORBA provides exceptions for error handling and COM does not. COM provides error status through a return parameter called HRESULT. The caller has to explicitly test the HRESULT to decide if the operation was successful. HRESULT return parameters are replaced by CORBA exceptions. The COM and CORBA IDL have several syntactical differences and use different style guides. DAIS (as well as OPC) structure nodes and items hierarchically. Nodes and items have a label uniquely identifying child’s located at the same node. The labels from the nodes in the path from a node or item to the root form a pathname. The pathname uniquely identifies a node or item in the tree. The same principle for naming objects is described in the IEC 1346-1 standard. IEC 1346-1 call labels for single level designation and the pathname for multi level designation and supports multiple hierarchical structures. The DAIS supports multiple structures by allowing multiple views where each view exposes one structure. The IEC 61970-30x [8] draft standard (also named CIM) describes a specific organization of power system objects in a hierarchical structure. DAIS is transparent to the structure and hence supports the IEC 61970 structure. DAIS is also transparent to what attributes are defined as long as they can be reached through the hierarchy. DAIS however defines a set of attributes that a DAIS server is expected to support. Some of these attributes can also be found in IEC 61970-30x. A detailed attribute mapping is provided later in this specification and is further elaborated in Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. The W3C XPath [13] standard describes how navigation in a hierarchical structure (i.e., an XML document) is made using an expression. In DAIS, navigation is made using the various browse APIs. However in one place there is a need to describe navigation paths as expressions and that is for the condition logic in Alarms and Events. Differences and similarities between OPC and DAIS are described in this chapter. OPC is a service API providing access to data managed by the server. The data (for example, nodes, items, areas, sources, conditions, reasons) are not instantiated as objects at the client. This means that OPC does not define any particular APIs for the data instances that a client can deal with directly. OPC has a few coarse objects like OPCGroup and OPCEventSubscription supporting the data access. DAIS has adopted this principle and is identical to OPC in this respect. In OPC each client has its own OPC server object. In DAIS there is only one DAIS server object shared by all clients. To support individual client sessions a new session interface is defined. There is one interface for data access session objects and one for alarms & events session objects. The session objects correspond to the OPC server object. The OPC server object has interfaces for browsing server data (for example, IOPCBrowseServerAddressSpace and IOPCEventAreaBrowser) and information model (for example, IOPCItemProperties). In DAIS each type of data has its own object for browsing, these objects are called “home? objects. The OPC browse interface methods are hence divided among the different home objects. Many OPC interface, method, and parameter names have been kept but recasted according to the CORBA style guide. But many OPC names have been replaced by new names to more clearly indicate the meaning. This is particularly the case for the browse and alarms & events APIs. In OPC it is common to return arrays of HRESULTs corresponding to arrays of data. In the case where the data did not contain any errors an array with “no error occurred? codes still is returned. In DAIS such error codes will be returned as a sequence of error structs identifying the erroneous data and an error code. In case of no errors the sequence of error structs is empty. OPC data accesses use both server and client side handles created based on identification texts for nodes and items. To make the translation from identification texts to handles fast and avoid repeated translation in OPC an intermediate server side identifier called the blob exists. In DAIS the server side handles and blobs are replaced by identifiers based on ResourceIDs (both for nodes and items). For a description of ResourceIDs refer to Section 2.2, “Data Access Facility (DAF),? on page 2-4. The OPC client side handles are still kept in DAIS. COM/OPC use the standard interfaces IConnectionPoint to set up callbacks. In DAIS callbacks are set up directly between server and client by updating an attribute holding the callback object. The COM style enumerators in OPC are replaced by CORBA style iterators in DAIS. In OPC multiple parallel vectors often pass data. In DAIS a single vector holding structs, thus reducing the number of parameters, replaces the parallel vectors. In OPC all methods return the HRESULT error value. In DAIS HRESULTs are replaced by exceptions and out parameters are returned as method results instead. Only in a few cases are there additional output parameters in DAIS. In OPC data is generally organized in hierarchical structures. In data access the leafs are called leaf nodes and the branches branch nodes or items. A leaf node or item is the same as an instance of property at an object. A branch node corresponds to an: • Object having properties. • Arbitrary organization of other branch nodes. • Object having both properties and other branch nodes as children. In DAIS data access the branch nodes are called nodes and the leaf nodes are called items. In DAIS alarms & events, the branch nodes are called areas and the leaf nodes sources. In OPC branch and leaf nodes have a name unique among the nodes or items that are children of the same node. A second name is formed by combining these names from each branch node in the path from the node or leaf to the root. Both names are called ItemIDs in OPC and the name created by following the path to the root is sometimes called a fully qualified ItemID. In DAIS the name unique among the child’s to the same node is called label and the name including the labels from all nodes in the path to the root is called pathname. Both DAIS branch nodes and leaf nodes have both a label and a pathname. A label is used in the same way as a name but the word label is preferred before the word name as it denotes something that is atomic; that is, it cannot be further divided. OPC provides a server side cursor from where browsing is made and the OPC interface provides methods to move the cursor. DAIS does not provide server side cursors and requires the client to keep track of browse positions themselves. The reason for removing server side cursors is it makes clean up after crashed clients easier and simplifies the server design. OPC does not support types meaning it is not possible in OPC to get information about the type of a node. OPC however supports properties, which means it is possible to browse the existing properties and what properties a particular node has. DAIS has extended this to also include types; that is, it is possible to browse existing types, the properties each type has and each node has a type. OPC defines the following property sets: • set 1 of OPC specific properties • set 2 of OPC recommended properties • set 3 of vendor specific properties In DAIS, OPC set 1 properties cannot be browsed through the property-browsing interface (Property). Instead access of set 1 properties is direct in the interfaces as parameters or struct members as is the case for OPC. This means that DAIS exposes only OPC set 2 and 3 properties through the property browse interface. OPC is a service API providing access to data managed by the server. The data (for example, nodes, items, areas, sources, conditions, reasons) are not instantiated as objects at the client. This means that OPC does not define any particular APIs for the data instances that a client can deal with directly. OPC has a few coarse objects like OPCGroup and OPCEventSubscription supporting the data access. DAIS has adopted this principle and is identical to OPC in this respect. In OPC each client has its own OPC server object. In DAIS there is only one DAIS server object shared by all clients. To support individual client sessions a new session interface is defined. There is one interface for data access session objects and one for alarms & events session objects. The session objects correspond to the OPC server object. The OPC server object has interfaces for browsing server data (for example, IOPCBrowseServerAddressSpace and IOPCEventAreaBrowser) and information model (for example, IOPCItemProperties). In DAIS each type of data has its own object for browsing, these objects are called “home? objects. The OPC browse interface methods are hence divided among the different home objects. Many OPC interface, method, and parameter names have been kept but recasted according to the CORBA style guide. But many OPC names have been replaced by new names to more clearly indicate the meaning. This is particularly the case for the browse and alarms & events APIs. In OPC it is common to return arrays of HRESULTs corresponding to arrays of data. In the case where the data did not contain any errors an array with “no error occurred? codes still is returned. In DAIS such error codes will be returned as a sequence of error structs identifying the erroneous data and an error code. In case of no errors the sequence of error structs is empty. OPC data accesses use both server and client side handles created based on identification texts for nodes and items. To make the translation from identification texts to handles fast and avoid repeated translation in OPC an intermediate server side identifier called the blob exists. In DAIS the server side handles and blobs are replaced by identifiers based on ResourceIDs (both for nodes and items). For a description of ResourceIDs refer to Section 2.2, “Data Access Facility (DAF),? on page 2-4. The OPC client side handles are still kept in DAIS. COM/OPC use the standard interfaces IConnectionPoint to set up callbacks. In DAIS callbacks are set up directly between server and client by updating an attribute holding the callback object. The COM style enumerators in OPC are replaced by CORBA style iterators in DAIS. In OPC multiple parallel vectors often pass data. In DAIS a single vector holding structs, thus reducing the number of parameters, replaces the parallel vectors. In OPC all methods return the HRESULT error value. In DAIS HRESULTs are replaced by exceptions and out parameters are returned as method results instead. Only in a few cases are there additional output parameters in DAIS. In OPC data is generally organized in hierarchical structures. In data access the leafs are called leaf nodes and the branches branch nodes or items. A leaf node or item is the same as an instance of property at an object. A branch node corresponds to an: • Object having properties. • Arbitrary organization of other branch nodes. • Object having both properties and other branch nodes as children. In DAIS data access the branch nodes are called nodes and the leaf nodes are called items. In DAIS alarms & events, the branch nodes are called areas and the leaf nodes sources. In OPC branch and leaf nodes have a name unique among the nodes or items that are children of the same node. A second name is formed by combining these names from each branch node in the path from the node or leaf to the root. Both names are called ItemIDs in OPC and the name created by following the path to the root is sometimes called a fully qualified ItemID. In DAIS the name unique among the child’s to the same node is called label and the name including the labels from all nodes in the path to the root is called pathname. Both DAIS branch nodes and leaf nodes have both a label and a pathname. A label is used in the same way as a name but the word label is preferred before the word name as it denotes something that is atomic; that is, it cannot be further divided. OPC provides a server side cursor from where browsing is made and the OPC interface provides methods to move the cursor. DAIS does not provide server side cursors and requires the client to keep track of browse positions themselves. The reason for removing server side cursors is it makes clean up after crashed clients easier and simplifies the server design. OPC does not support types meaning it is not possible in OPC to get information about the type of a node. OPC however supports properties, which means it is possible to browse the existing properties and what properties a particular node has. DAIS has extended this to also include types; that is, it is possible to browse existing types, the properties each type has and each node has a type. OPC defines the following property sets: • set 1 of OPC specific properties • set 2 of OPC recommended properties • set 3 of vendor specific properties In DAIS, OPC set 1 properties cannot be browsed through the property-browsing interface (Property). Instead access of set 1 properties is direct in the interfaces as parameters or struct members as is the case for OPC. This means that DAIS exposes only OPC set 2 and 3 properties through the property browse interface. The UMS DAF and DAIS are server APIs for access of object data rather than the data objects themselves. The DAF describes a generic interface for navigating and reading data from complex data structures including relations between objects. Both DAF and DAIS support navigation in a space of hierarchically structured objects (an object is called a node in DAIS and a resource in DAF). Both support identification of objects and properties at an object. In DAIS an instance of property at an object is called an item and an ItemID (item identifier) identifies an item. An ItemID consists of a ResourceID (resource identifier) for the node and a PropertyID (property identifier) for the property. The DAIS API uses ItemIDs to access data while the DAF uses ResourceIDs and PropertyIDs separated. A system may implement both a DAF server and a DAIS server. In such a system it shall be assumed that the same object will have the same ResourceID seen through either API. This means it shall be possible to navigate to an object, retrieve its ResourceID through one of the APIs, and use that ResourceID with the other API. In the same way PropertyIDs are the same. Textual identification of resources and properties in the DAF is by URIs (Uniform Resource Identifier). ResourceIDs and PropertyIDs have their own URIs. URIs can be translated into corresponding ResourceIDs and PropertyIDs and vice versa. A property name is a URI where the container part is a unique schema identifier and the fragment part is the property name. For example: http://www.epri.com/schema/CIM-07f.xml#Measurement.positiveFlowIn DAIS does not support URIs directly but has a textual representation for nodes, items, types, and properties. This textual representation may correspond to the fragment part of a URI. In the case where a system supports both the DAF and the DAIS interfaces it is expected that the same object will be identified by the same ResourceID through both interfaces and the same property by the same PropertyID. Sameness of objects and properties; however, depends on the information model exposed through the two interfaces and if the information models are different, then a mapping is required. In the case where a system supports both the DAF and the DAIS interfaces it is expected that the same objects will be identified by the same ResourceID and URI fragment through both interfaces and the same property by the same PropertyID and URI fragment. The exact mapping has to be described for each DAIS item – DAF property pair according to the underlying information models. Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5 elaborates on the information model and a detailed mapping between IEC 61970-30x and the DAIS can be found in Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. The foregoing concepts are fundamental enough that they should find equivalents in any data repository. Some, perhaps approximate, equivalents are given in Table 2-1 as a guide. Table 2-1 Mappings between modeling languages RDF DAF Relational Model UML DAIS Resource Resource, ResourceID Tuple (i.e., row) Object Node, ResourceID Property Property, PropertyID Attribute (i.e., column) or foreign key Attribute or association Property, PropertyID Class Class, ClassID Relation (i.e., table) Class Type, TypeID Resource Description Resource Description Tuple value - Sequence URI URI, ResourceID Key value - Value SimpleValue Field value - SimpleValue - ResourceID and PropertyID pair - - Item, ItemID DAIS uses the DAF SimpleValue type for data transferred over the API instead of the OPC type VARIANT. The data types used in OPC are Microsoft COM types and as DAIS is a CORBA API a mapping of the data types is needed. The translation of OPC/COM data types to DAF/CORBA data types is listed below. Table 2-2 Mappings between OPC and DAF data types OPC/COM basic types DAF Simple Value types - ResourceID (RESOURCE_TYPE) - URI (URI_TYPE) LPWSTR (VT_BSTR) string (STRING_TYPE) BOOL (VT_BOOL) boolean (BOOLEAN_TYPE) LONG (VT_R4) long (INT_TYPE) DWORD (VT_I4) unsigned long (UNSIGNED_TYPE) double (VT_R8) double (DOUBLE_TYPE) - Complex (COMPLEX_TYPE) FILETIME (VT_Date) DateTime (DATE_TIME_TYPE) - ULongLong (ULONG_LONG_TYPE) WORD (VT_I2) unsigned long (UNSIGNED_TYPE) FLOAT (VT_R4) double (DOUBLE_TYPE) BYTE (VT_UI1) - HRESULT (VT_ERROR) - VARIANT (VARTYPE) SimpleValue (SimpleValueType) The DAF describes a generic interface for navigating and reading data from complex data structures including relations between objects. Both DAF and DAIS support navigation in a space of hierarchically structured objects (an object is called a node in DAIS and a resource in DAF). Both support identification of objects and properties at an object. In DAIS an instance of property at an object is called an item and an ItemID (item identifier) identifies an item. An ItemID consists of a ResourceID (resource identifier) for the node and a PropertyID (property identifier) for the property. The DAIS API uses ItemIDs to access data while the DAF uses ResourceIDs and PropertyIDs separated. A system may implement both a DAF server and a DAIS server. In such a system it shall be assumed that the same object will have the same ResourceID seen through either API. This means it shall be possible to navigate to an object, retrieve its ResourceID through one of the APIs, and use that ResourceID with the other API. In the same way PropertyIDs are the same. Textual identification of resources and properties in the DAF is by URIs (Uniform Resource Identifier). ResourceIDs and PropertyIDs have their own URIs. URIs can be translated into corresponding ResourceIDs and PropertyIDs and vice versa. A property name is a URI where the container part is a unique schema identifier and the fragment part is the property name. For example: http://www.epri.com/schema/CIM-07f.xml#Measurement.positiveFlowIn DAIS does not support URIs directly but has a textual representation for nodes, items, types, and properties. This textual representation may correspond to the fragment part of a URI. In the case where a system supports both the DAF and the DAIS interfaces it is expected that the same object will be identified by the same ResourceID through both interfaces and the same property by the same PropertyID. Sameness of objects and properties; however, depends on the information model exposed through the two interfaces and if the information models are different, then a mapping is required. In the case where a system supports both the DAF and the DAIS interfaces it is expected that the same objects will be identified by the same ResourceID and URI fragment through both interfaces and the same property by the same PropertyID and URI fragment. The exact mapping has to be described for each DAIS item – DAF property pair according to the underlying information models. Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5 elaborates on the information model and a detailed mapping between IEC 61970-30x and the DAIS can be found in Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. The foregoing concepts are fundamental enough that they should find equivalents in any data repository. Some, perhaps approximate, equivalents are given in Table 2-1 as a guide. Table 2-1 Mappings between modeling languages RDF DAF Relational Model UML DAIS Resource Resource, ResourceID Tuple (i.e., row) Object Node, ResourceID Property Property, PropertyID Attribute (i.e., column) or foreign key Attribute or association Property, PropertyID Class Class, ClassID Relation (i.e., table) Class Type, TypeID Resource Description Resource Description Tuple value - Sequence URI URI, ResourceID Key value - Value SimpleValue Field value - SimpleValue - ResourceID and PropertyID pair - - Item, ItemID DAIS uses the DAF SimpleValue type for data transferred over the API instead of the OPC type VARIANT. The data types used in OPC are Microsoft COM types and as DAIS is a CORBA API a mapping of the data types is needed. The translation of OPC/COM data types to DAF/CORBA data types is listed below. Table 2-2 Mappings between OPC and DAF data types OPC/COM basic types DAF Simple Value types - ResourceID (RESOURCE_TYPE) - URI (URI_TYPE) LPWSTR (VT_BSTR) string (STRING_TYPE) BOOL (VT_BOOL) boolean (BOOLEAN_TYPE) LONG (VT_R4) long (INT_TYPE) DWORD (VT_I4) unsigned long (UNSIGNED_TYPE) double (VT_R8) double (DOUBLE_TYPE) - Complex (COMPLEX_TYPE) FILETIME (VT_Date) DateTime (DATE_TIME_TYPE) - ULongLong (ULONG_LONG_TYPE) WORD (VT_I2) unsigned long (UNSIGNED_TYPE) FLOAT (VT_R4) double (DOUBLE_TYPE) BYTE (VT_UI1) - HRESULT (VT_ERROR) - VARIANT (VARTYPE) SimpleValue (SimpleValueType) Interfaces defined in COM and CORBA IDL differ in a number of ways. Important differences concerning interface definitions are • object referencing, • interface management, • error management, and • IDL. A detailed description of the mapping can be found in the CORBA 2.3 specification, chapters 17, 18, and 19. In CORBA each object is uniquely referenced in one step. In COM obtaining an object usually is a two step process. In the first step a stateless server object is obtained. In the second step the server object is loaded with state data. In CORBA an object is a unique individual that contains state from the very beginning. A CORBA object has a single interface. This interface can be built from several other interfaces through inheritance. The resulting interface might have many methods and hence become big. A COM object usually has multiple interfaces and supports the client to detect and navigate between these interfaces at run time. As a CORBA interface is defined by inheritance it has to be fully defined at compile time. As COM allows run time detection of interfaces (the IUnknown::QueryInterface() method) a full match between interfaces implemented by a server and interfaces known to a client is not required. Mapping OPC interfaces to DAIS interfaces can be done in two ways: 1. Inherit a number of OPC interfaces into one CORBA object. This may result in name clashes that require renaming of methods. 2. Instantiate an OPC interface as an own CORBA object referenced by a container object. Both techniques are used in the DAIS specification. CORBA provides exceptions for error handling and COM does not. COM provides error status through a return parameter called HRESULT. The caller has to explicitly test the HRESULT to decide if the operation was successful. HRESULT return parameters are replaced by CORBA exceptions. The COM and CORBA IDL have several syntactical differences and use different style guides. In CORBA each object is uniquely referenced in one step. In COM obtaining an object usually is a two step process. In the first step a stateless server object is obtained. In the second step the server object is loaded with state data. In CORBA an object is a unique individual that contains state from the very beginning. A CORBA object has a single interface. This interface can be built from several other interfaces through inheritance. The resulting interface might have many methods and hence become big. A COM object usually has multiple interfaces and supports the client to detect and navigate between these interfaces at run time. As a CORBA interface is defined by inheritance it has to be fully defined at compile time. As COM allows run time detection of interfaces (the IUnknown::QueryInterface() method) a full match between interfaces implemented by a server and interfaces known to a client is not required. Mapping OPC interfaces to DAIS interfaces can be done in two ways: 1. Inherit a number of OPC interfaces into one CORBA object. This may result in name clashes that require renaming of methods. 2. Instantiate an OPC interface as an own CORBA object referenced by a container object. Both techniques are used in the DAIS specification. CORBA provides exceptions for error handling and COM does not. COM provides error status through a return parameter called HRESULT. The caller has to explicitly test the HRESULT to decide if the operation was successful. HRESULT return parameters are replaced by CORBA exceptions. The COM and CORBA IDL have several syntactical differences and use different style guides. DAIS (as well as OPC) structure nodes and items hierarchically. Nodes and items have a label uniquely identifying child’s located at the same node. The labels from the nodes in the path from a node or item to the root form a pathname. The pathname uniquely identifies a node or item in the tree. The same principle for naming objects is described in the IEC 1346-1 standard. IEC 1346-1 call labels for single level designation and the pathname for multi level designation and supports multiple hierarchical structures. The DAIS supports multiple structures by allowing multiple views where each view exposes one structure. The IEC 61970-30x [8] draft standard (also named CIM) describes a specific organization of power system objects in a hierarchical structure. DAIS is transparent to the structure and hence supports the IEC 61970 structure. DAIS is also transparent to what attributes are defined as long as they can be reached through the hierarchy. DAIS however defines a set of attributes that a DAIS server is expected to support. Some of these attributes can also be found in IEC 61970-30x. A detailed attribute mapping is provided later in this specification and is further elaborated in Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. The W3C XPath [13] standard describes how navigation in a hierarchical structure (i.e., an XML document) is made using an expression. In DAIS, navigation is made using the various browse APIs. However in one place there is a need to describe navigation paths as expressions and that is for the condition logic in Alarms and Events. Contents This chapter contains the following sections. Section Title Page “Common Declarations? 3-1 “Server? 3-30 This section describes the DAISServer and IDL common to the server, data access, and alarms & events. To support universal character encodings the UTF-8 Unicode standard [12] shall be used for characters and strings. The DAIS relies on the Data Access Facility (DAF) for basic data type declarations and some DAF declarations (for example, ResourceID and SimpleValue) are included because of this. DAIS common declarations (for example, DAIS::Quality) are made in DAISCommon. Interfaces for nodes, types, properties, and sessions are also common between data access and alarms & events. The Interface Definition Language (IDL) files and dependencies listed in Figure 3-1 are defined. DAFIdentifiers DAFDescriptions DAISSession DAISCommon DAISNode DAISProperty DAISType Figure 3-1 Dependencies among common IDL files Refer to the Data Access Facility specification [2]. Refer to the Data Access Facility specification [2]. // File: DAISCommon.idl#ifndef _DAIS_COMMON_IDL#define _DAIS_COMMON_IDL#pragma prefix "omg.org"#include module DAIS{typedef unsigned short SupportedFunctions;const SuportedFunctions DAIS_DATA_ACCESS =0x0001;const SupportedFunctions DAIS_ALARMS_AND_EVENTS =0x0002; typedef DAFDescriptions::ResourceID ResourceID;typedef DAFDescriptions::SimpleValueType SimpleValueType;typedef DAFDescriptions::SimpleValue SimpleValue;typedef DAFDescriptions::DateTime DateTime;typedef DAFDescriptions::PropertyID PropertyID;typedef DAFDescriptions::PropertyValueSequence PropertyValues; // sequences of resource idstypedef sequence ResourceIDs;typedef sequence PropertyIDs; truct ItemID{ResourceID resource;PropertyID property;};typedef sequence ItemIDs; typedef unsigned long ClientItemHandle;typedef sequence ClientItemHandles;typedef unsigned long long ServerItemHandle;typedef sequence ServerItemHandles; typedef short ServerItemIdentificationType;const ServerItemIdentificationType ITEM_ID = 0;const ServerItemIdentificationType PATH_NAME = 1; union ServerItemIdentification switch( ServerItemIdentificationType ) { case ITEM_ID: ItemID item; case PATH_NAME: string pathname; }; typedef sequenceServerItemIdentifications; typedef unsigned short Error; struct ItemError { Error err; ClientItemHandle client_handle; ServerItemHandle server_handle; string pathname; string reason; }; typedef sequence ItemErrors; // error codes const Error ERROR_DAISOK = 0; const Error ERROR_BAD_RIGHTS = 1; const Error ERROR_UNKNOWN_ITEMID = 2; const Error ERROR_CLAMPED = 3; const Error ERROR_OUT_OF_RANGE = 4; const Error ERROR_UNKNOWN_PATHNAME = 5; const Error ERROR_BAD_TYPE = 6; const Error ERROR_UNKNOWN_ACCESS_PATH = 7; const Error ERROR_INTERNAL_SERVER = 8; const Error ERROR_INVALID_DAIS_HANDLE = 9; enum AccessRights { READABLE, WRITEABLE, READ_AND_WRITEABLE }; typedef unsigned long OPCQuality; typedef unsigned long UserQuality; struct Quality { OPCQuality opc_quality; UserQuality user_quality; }; // Masks for extracting quality subfields// (note 'status' mask also includes 'Quality' bits) const OPCQuality OPC_QUALITY_MASK = 0x000000C0; const OPCQuality OPC_STATUS_MASK = 0x000000FC; const OPCQuality OPC_LIMIT_MASK = 0x00000003; // Values for QUALITY_MASK bit field const OPCQualityOPC_QUALITY_BAD = 0x00000000; const OPCQuality OPC_QUALITY_UNCERTAIN = 0x00000040; const OPCQualityOPC_QUALITY_GOOD = 0x000000C0; // STATUS_MASK Values for Quality = BAD const OPCQuality OPC_QUALITY_CONFIG_ERROR = 0x00000004; const OPCQuality OPC_QUALITY_NOT_CONNECTED = 0x00000008; const OPCQuality OPC_QUALITY_DEVICE_FAILURE = 0x0000000C; const OPCQuality OPC_QUALITY_SENSOR_FAILURE = 0x00000010; const OPCQuality OPC_QUALITY_LAST_KNOWN = 0x00000014; const OPCQuality OPC_QUALITY_COMM_FAILURE = 0x00000018; const OPCQuality OPC_QUALITY_OUT_OF_SERVICE = 0x0000001C; // STATUS_MASK Values for Quality = UNCERTAIN const OPCQuality OPC_QUALITY_LAST_USABLE = 0x00000044; const OPCQuality OPC_QUALITY_SENSOR_CAL = 0x00000050; const OPCQuality OPC_QUALITY_EGU_EXCEEDED = 0x00000054; const OPCQuality OPC_QUALITY_SUB_NORMAL = 0x00000058; const OPCQuality DAIS_QUALITY_OCILLATORY = 0x0000005C; // STATUS_MASK Values for Quality = GOOD //const OPCQuality OPC_QUALITY_LOCAL_OVERRIDE= 0xD8; //use EXQ_Source_xxx instead of OPC_QUALITY_LOCAL_OVERRIDE // Values for Limit Bitfield const OPCQualityOPC_LIMIT_OK = 0x00000000; const OPCQualityOPC_LIMIT_LOW = 0x00000001; const OPCQualityOPC_LIMIT_HIGH = 0x00000002; const OPCQualityOPC_LIMIT_CONST = 0x00000003; //DAIS Quality extension masks const OPCQuality EXQ_SOURCE_MASK = 0x00000700;const OPCQuality EXQ_TEST_MASK = 0x00000800;const OPCQuality EXQ_OPERATOR_BLOCKED_MASK = 0x00001000;const OPCQuality EXQ_TIMESTAMP_ACCURACY_MASK = 0x00006000; //DAIS Quality source extensionconst OPCQuality EXQ_SOURCE_NONE = 0x00000000;const OPCQuality EXQ_SOURCE_PROCESS = 0x00000100;const OPCQuality EXQ_SOURCE_PRIMARY_SUBSTITUTED = 0x00000200;const OPCQuality EXQ_SOURCE_INHERITED_SUBSTITUTED= 0x00000300;const OPCQuality EXQ_SOURCE_CORRECTED = 0x00000400;const OPCQuality EXQ_SOURCE_DEFAULTED = 0x00000500; //DAIS Time stamp accuracyconst OPCQuality EXQ_TS_ACC_10_MSEC = 0x00000000;const OPCQuality EXQ_TS_ACC_100_MSEC = 0x00002000;const OPCQuality EXQ_TS_ACC_SECOND = 0x00004000;const OPCQuality EXQ_TS_ACC_BAD_TIME = 0x00006000;};#endif // _DAIS_COMMON_IDL SupportedFunctions This constant tells what functions the DAIS server (i.e., Data access, Alarms & Events, or both) supports. In case the server is extended with other functions they are included as well (e.g., Historical Data functionality (HDAIS)). DAF declarations These declarations (for example, ResourceID) import DAF declarations to DAIS. ItemID A pair of a ResourceID and a PropertyID. It uniquely identifies an item; that is, a property at a node. Member Description resource The ResourceID. property The PropertyID. ClientItemHandle A client created numeric handle used by the client to efficiently identify data coming from the server in callbacks. ServerItemHandle A server created numeric handle used by the server to efficiently identify items in client calls. ServerItemIdentification A union that holds either an ItemID or a pathname. Either can be used for identification of an item. Error Numeric error codes that are returned by ItemError. EnumValue Description ERROR_DAISOK Used to indicate an error free result. ERROR_BAD_RIGHTS The Items AccessRights do not allow the operation. ERROR_UNKNOWN_ITEMID The resource or property in the ItemID is unknown. ERROR_CLAMPED A value passed to WRITE was accepted but the output was clamped. ERROR_OUT_OF_RANGE The value was out of range. ERROR_UNKNOWN_PATHNAME The pathname was not recognised. ERROR_BAD_TYPE The server cannot convert the data between the specified format/ requested data type and the canonical data type. ERROR_UNKNOWN_ACCESS_PATH The item's access path is unknown. ERROR_INTERNAL_SERVER An error has appeared in the server due to some server internal problem. ERROR_INVALID_DAIS_HANDLE A client or server handle was invalid. ItemError A struct for reporting of item related errors. Member Description err An error code as described below. client_handle The client side handle identifying the item. server_handle The server side handle identifying the item. pathname The pathname for display or presentation purposes. reason An additional text explaining the error. AccessRights Numeric access rights supported per item. EnumValue Description READABLE Read only data. WRITEABLE Write only data. READ_AND_WRITABLE Both read and write data. OPCQuality A flag word giving the OPC quality. Each flag has a specific meaning as described below. Four groups of flags exist: 1. Main quality telling if a value is good, bad, or suspected. 2. Detailed quality. 3. Limits telling if the value is stuck. 4. Historical data access flags. Those flags are described in the HDAIS specification. Bit masks are defined to extract these flags. Quality, status, and limit bit masks Mask Description OPC_QUALITY_MASK Bit mask for main quality. OPC_STATUS_MASK Bit mask for detailed quality. OPC_LIMIT_MASK Bit mask for the limits. Main quality enumeration numbers Enum Description OPC_QUALITY_BAD The number for bad quality. OPC_QUALITY_UNCERTAIN The number for uncertain quality. OPC_QUALITY_GOOD The number for good quality. After application of the OPC_QUALITY_MASK the quality shall be compared directly to the enumeration numbers to decide the quality. Detailed quality flags for bad quality Flag Description OPC_QUALITY_CONFIG_ERROR There is a server configuration error concerning this value. OPC_QUALITY_NOT_CONNECTED The source of the value is not connected. OPC_QUALITY_DEVICE_FAILURE A device failure has been detected. OPC_QUALITY_SENSOR_FAILURE A sensor failure has been detected. OPC_QUALITY_LAST_KNOWN The updating has stopped but there is an old value available. OPC_QUALITY_COMM_FAILURE Communication has failed and no value available. OPC_QUALITY_OUT_OF_SERVICE The updating of the value is manually blocked for update (the item is not active). Detailed quality flags for uncertain quality Flag Description OPC_QUALITY_LAST_USABLE The value is old. The time stamp gives the age. OPC_QUALITY_EGU_EXCEEDED The value is beyond the capability of representation (for example, counter overflow). OPC_QUALITY_SENSOR_CAL The sensor calibration is bad. OPC_QUALITY_SUB_NORMAL Value is derived from multiple sources where the majority has less than required good quality. DAIS_QUALITY_OCILLATORY If a binary value changes cyclically with a frequency higher than a specific threshold, it is oscillating. This quality compliant with IEC 61850-7-3. Definition of limit flags Flag Description OPC_LIMIT_OK The value is not limited; that is, it moves freely up or down. OPC_LIMIT_LOW The value is stuck at a low limit. OPC_LIMIT_HIGH The value is stuck at a high limit. OPC_LIMIT_CONST The value is stuck constant. DAIS Quality extension masks The part of the flag word giving the DAIS extended quality. Each flag has a specific meaning as described below. These quality definitions are based on the revised IEC 61850-7-3 definitions of quality. The following masks are defined. Mask Description EXQ_SOURCE_MASK Bit mask for the source. EXQ_TEST_MASK Bit mask for the test status. The test status indicates that the value is generated by a test and shall not be regarded as an operational value. EXQ_OPERATOR_BLOCKED_MASK Bit mask for the operator blocked status. The status indicates that the value has been blocked for update and is old. The OPC_QUALITY_LAST_USABLE quality shall be set as well. EXQ_TIMESTAMP_ACCURACY_MASK Bit mask for the time stamp accuracy. Flags defining source Flag Description EXQ_SOURCE_NONE There is no source for this data item. The code is used for spare items not yet allocated. EXQ_SOURCE_PROCESS The source for this value is the process. EXQ__SOURCE_PRIMARY_ SUBSTITUTED The value is manually substituted. EXQ_SOURCE_INHERITED_ SUBSTITUTED A substituted value has been copied or used as input to some calculation. The result value is then marked with EXQ_SOURCE_INHERITED_ SUBSTITUTED. EXQ_SOURCE_CORRECTED An alternate and more accurate value has been calculated by some application (e.g., a State Estimator). If this value has been used to correct the original value, it shall be indicated EXQ_SOURCE_CORRECTED. EXQ_REMOTE_DEFAULTED The value is initialized by a default value. Flags defining time stamp quality Flag Description EXQ_LOCAL_NONEEXQ_TS_ACC_ 10_MSEC The value is not updated locally (i.e., it has a remote source specification). The flags (=0) indicate that the accuracy is 10 milliseconds or better (IEC61850-7-2 performance class T0). EXQ_LOCAL_SUBSTITUTEDEXQ_TS_ ACC_100_MSEC The value is locally substituted (manually). The flags (=1) indicate that the accuracy is 100 milliseconds or better. EXQ_LOCAL_SE_REPLACEDEXQ_TS_ ACC_SECOND The value is locally substituted by State Estimator. The flags (=2) indicate that the accuracy is in the range of seconds or better. EXQ_TS_ACC_BAD_TIME The flags (=3) indicate that the time stamp is bad. QualityThe DAIS quality consists of OPCQuality and ExtendedQuality. Member Description opc_quality The quality as specified by OPC including extensions from DAIS. user_quality A user specific quality. Methods that return information about more than one resource may return an iterator. The resource description iterator allows a client to access a large query result sequentially, several resources at a time. This is necessary where the ORB limits message sizes. It also enables implementations to overlap the client and server processing of query results, if necessary. The client and the data provider should cooperate to manage the lifetime of the iterator and the resources it consumes. The destroy() and next_n() methods allow the client and data provider respectively to indicate that the iterator may be destroyed. In addition, the data provider may autonomously destroy the iterator at any time (for resource management or other reasons). If a client detects that an iterator has been destroyed, it will not interpret this condition in itself as either an indication that the end of the iteration has been reached, or as a permanent failure of the data provider. next_n() This operation returns possibly 0 and at most n resource descriptions in the form of a resource description sequence. In all cases the state of the iteration is indicated by the Boolean return value. • True means that there may be more resource descriptions beyond those returned so far. • False means all the resource descriptions have now been returned. No further calls are expected for this iterator and the data provider may destroy the iterator at any time after the call returns. reset() This operation resets the iterator to the first element. clone() This operation returns a copy of the iterator. destroy() This operation is used to terminate iteration before all the resource descriptions have been returned. After destroy() is invoked no further calls are expected for this iterator. The data provider may destroy the iterator at any time after the call returns. A node may represent a real world object such as a location or a piece of equipment. A node may also represent a schema item such as a type or property. Nodes correspond to “branches? in the IOPCBrowseServerAddressSpace or IOPCEventAreaBrowser interfaces. Nodes correspond to Resources in the RDF model and the DAF interface. Each node has a universal identity given by its ResourceID. The ResourceID of a node is the same in all views provided by a DAIS server. DAIS servers may be coordinated with DAF servers so that a node has the same ResourceID as the corresponding resource. Each node has zero or more child(s). A child may be another node or any other type of object (for example, data access items or alarms & event sources). Each node has a type. The type determines what other types of child objects a node has. Nodes are arranged in a strict hierarchy for naming purposes. A DAIS server may provide more than one such hierarchy, each is called a view. (The view is selected when the session is initiated.) Within a view, each node, except for the root node, has a single parent node, a label that is unique among all nodes with the same parent, and a unique pathname. A node’s pathname is a string that contains its label and the pathname of its parent. The pathname must be a valid URI, but apart from that the syntax of pathnames is implementation dependent. The Node IDL defines a main interface DAIS::Node::IHome for browsing among the hierarchically structured nodes. Nodes are described by DAIS::Node::Description struct. DAIS::Node::Iterator max_left() next_n() reset() clone() destroy() <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() <> 0..n 1 0..n1Node id : ResourceID label : string type : ResourceID 0..n0.1 .n1NodeItemComponent pathname : string 1 0..* +parent 10..* Figure 3-2 DAIS node IDL in UML //File: DAISNode.idl #ifndef _DAIS_NODE_IDL #define _DAIS_NODE_IDL #pragma prefix "omg.org" #include module DAIS { module Node { struct Description { ResourceID id; ResourceID parent; string label; string descrip; ResourceID type; boolean is_leaf; }; typedef sequence< Description > Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions nodes ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; exception InvalidFilter {string reason;}; exception UnkownTypeID {string reason;}; Description find ( in ResourceID node ) raises (UnknownResourceID); Descriptions find_each ( in ResourceIDs nodes ) raises (UnknownResourceID); Iterator find_by_parent ( in ResourceID node, in string filter_criteria ) raises (UnknownResourceID, InvalidFilter); Iterator find_by_type ( in ResourceID node, in string filter_criteria, in ResourceIDs type_filter ) raises (UnknownResourceID, InvalidFilter, UnknownTypeID); Strings get_pathnames ( in ResourceIDs nodes ); ResourceIDs get_ids ( in Strings pathnames ); };};}; #endif // _DAIS_NODE_IDL Description A struct describing a node. Member Description id The identification of this node. parent The identification of the parent node. label The label (single level designation) of the node. descrip A descriptive text for the node. type A reference to the type of the node. is_leaf Indicate if the node is a leaf (i.e., it has no child nodes). Iterator Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. This interface corresponds to the OPC interface EnumString with the difference that the Iterator returns the Description struct instead of a string. IHome An interface used for browsing nodes. The interface corresponds to the IOPCBrowseServerAddressSpace with the BrowseFilterType set to OPC_BRANCH or the IOPCEventAreaBrowser. A major difference to OPC is that the server does not provide a cursor for clients. Instead clients have to provide the browse position in each call. UnknownResourceID An exception telling that the ResourceID is unknown. For methods taking a sequence of resource ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. InvalidFilter An exception telling the filter_criteria string is not correct. The likely reason behind this exception is an erroneously entered string. UnknownTypeID An exception telling one or more TypeIDs does not exist. find() For a given node, return information about that node. Parameter Description node A node identification. return The node description. find_each () For a sequence of nodes, return information about each node. Parameter Description nodes A sequence of node identifications. return An iterator holding the node descriptions. find_by_parent () For a given node, return all child nodes at that node. Hence to reach leaf nodes using this method repeated calls must be made for each level. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_BRANCH.. Parameter Description node The parent node identification. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects nodes with a pathname matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. return An iterator holding the child node descriptions. find_by_type() For a sub-tree given by the node parameter, return all child nodes of the specified type. This will return all leaf nodes under the given sub-tree root node. There is no corresponding operation in OPC. Refer to Section 4.2.4.1, “DAIS::Item Overview,? on page 4-15 for a description of how item browsing is mapped to OPC. Parameter Description node The identification of the node defining the sub-tree. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects nodes with a pathname matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. type_filter A list of TypeIDs. Nodes matching any of the TypeIDs will be held by the returned iterator. return An iterator holding descriptions for the found nodes. get_pathnames() Translate a sequence of node identifications to the corresponding sequence of pathnames. If a node fails to translate to a pathname (due to an unknown node identification), the corresponding pathname is an empty string. Parameter Description nodes The sequence of nodes. return The corresponding sequence of pathnames. get_ids() Translate a sequence of pathnames to the corresponding sequence of node identifications. If a pathname fails to translate to a node identification (due to an unrecognized pathname), the corresponding node identification is NULL. Parameter Description pathnames The sequence of pathnames. return The corresponding sequence of node identifications. A type represents a set of related properties and associations. Each node has a type and all the properties represented by that type apply to the node. Each type is identified by a ResourceID and has a label and description. A type may be obtained for any node using the node’s TypeID. Related types may be grouped into a schema. A ResourceID identifies each schema. All the types in a schema may be obtained given the schema ResourceID. A schema and its type may be represented as nodes in one or more of views provided by a DAIS server. When a schema is represented as a node, the node’s ResourceID and the schema ResourceID are identical. Similarly, when a type is represented as a node, the node’s ResourceID and the type’s ResourceID are identical. The type’s parent is always the node representing its schema, the type’s label is identical to the node label and the type’s description is identical to the node description. The type IDL defines a main interface DAIS::Type::IHome for browsing supported types. DAIS::Type::IHome find() find_by_schema() <> +aggregated_types 11 0..n0..n 0..n0..n 11 0..n0..n Type id : ResourceID schema : ResourceID label : string description : string DAIS::Type::Iterator max_left() next_n() destroy() <> Figure 3-3 DAIS type IDL in UML //File DAISType.idl #ifndef _DAIS_TYPE_IDL #define _DAIS_TYPE_IDL #pragma prefix "omg.org" #include "DAISCommon.idl" module DAIS { module Type { struct Description { ResourceID id; ResourceID schema; string label; string descrip; ResourceIDs aggregated_types; }; typedef sequence Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions types ); void reset();Iterator clone();void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; Description find (in ResourceID type) raises (UnknownResourceID); Iterator find_by_schema ( in ResourceID schema ) raises (UnknownResourceID); };};}; #endif // _DAIS_TYPE_IDL Description A struct describing a type. Member Description id The identification of this type. schema The identification of the schema where the type is defined. label The label of the type. descrip A description of the type. aggregated_types A sequence of type identifications that a node of this type may contain. This information is intended as a guide when the type filter is specified for the find_by_type() methods. IHome An object used to browse the types. There is no corresponding interface in OPC. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find() For a given type, return information about that type. Parameter Description type A type identification. return The type description. find_by_schema() For a given schema, find all types defined by that schema. Parameter Description schema The identification of the schema. return A sequence of type descriptions. A property represents a characteristic of a node that can be described with a value. A given property may apply to many nodes, for each such node there will be an item corresponding to the property. (See Section 4.2.4, “DAISItem IDL,? on page 4-15). A DAIS property corresponds to a property in RDF and the DAF. A DAIS property corresponds to the concept of a property in OPC accessed with the IOPCItemProperties::QueryAvailableProperties() method. However, the six core OPC properties (timestamp, quality, value) do not correspond to properties in DAIS. They are given special treatment in OPC (they are not the same as other OPC properties). See Section 4.2.4, “DAISItem IDL,? on page 4-15 for interfaces to handle these. Each property is identified by a ResourceID and has a label, description, and canonical data type. The canonical data type is a member of the SimpleType enumeration and indicates the preferred CORBA atomic data type for values of this property. Every item of a given property has an identical canonical data type. A property may be obtained for any item via the property member of the ItemID. All properties that apply to a given node may be obtained, given the node’s ResourceID. All properties that apply to the nodes of a given type may be obtained, given the TypeID. A property may be represented as a node in one or more of views provided by a DAIS server. In this case the node’s ResourceID and the property’s ResourceID are identical. The property’s parent is always the node representing the type to which it belongs. The property’s label is identical to the node label and the property’s description is identical to the node description. The property IDL defines a main interface DAIS::Property::IHome for browsing properties. The information model describing how the properties are related to nodes and items is found in Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 . Property id : PropertyID label : string description : string canonical_data_type : SimpleValueType DAIS::Property::IHome <> find() find_each() find_by_node() find_by_type() 0..n.1 0. n1 Figure 3-4 DAIS property IDL in UML //File: DAISProperty.idl#ifndef _DAIS_PROPERTY_IDL#define _DAIS_PROPERTY_IDL#pragma prefix "omg.org"#include module DAIS {module Property { struct Description { PropertyID id; string label; string descrip; SimpleValueType canonical_data_type; };typedef sequence Descriptions; interface IHome { exception UnknownResourceID {string reason;}; Description find ( in PropertyID property ) raises (UnknownResourceID); Descriptions find_each ( in PropertyIDs properties ) raises (UnknownResourceID); Descriptions find_by_node ( in ResourceID node ) raises (UnknownResourceID); Descriptions find_by_type ( in ResourceID type ) raises (UnknownResourceID); };};}; #endif // _DAIS_PROPERTY_IDL Description Describe a property. Member Description id The identification of this property. label The label (single level designation) of the property. descrip A description of the property. canonical_data_type The data type used for the property in the server. Home An object used for browsing properties defined for a type or existing at a node. It corresponds to the OPC interface IOPCItemProperties. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find() For a given property, return information about that property. Parameter Description property A property identification. return The property description. find_each() For a given property, return information about that property. Parameter Description properties A sequence of property identifications. return The sequence of property descriptions. find_by_node () For a node, return information about each property describing its items. This method corresponds to IOPCItemProperties::QueryAvailableProperties(). Parameter Description node A node identification. return A sequence of property descriptions. find_by_type () For a given type, return all property descriptions. Parameter Description type A type identification. return A sequence of property descriptions. The session is an interface inherited by data access and alarms & events sessions. A session represents a single conversation with the DAIS service. A session has a connection to a shut down callback used by a server to shut down clients in the case of an ordered shut down of the server. If the session object is destroyed or a failure is detected by the server when invoking an operation on any callback objects, then the session is terminated. A session object corresponds to the OPC server object; hence each OPC server object will be represented by a session object in DAIS. Client (fro m DA ISServ er) DAIS::ShutdownCallback <> shutdown_notify() 1 0..1 10..1DAIS::Session <> status() : DAIS::SessionStatus callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() 0..1.1 0. 11 Figure 3-5 DAIS session IDL in UML The status() method corresponds to the read only SessionStatus attribute in the IDL. The callback() get and set methods correspond to the ShutDownCallback attribute. //File DAISSession.idl #ifndef _DAIS_SESSION_IDL #define _DAIS_SESSION_IDL #pragma prefix "omg.org" #include module DAIS { struct SessionStatus { string name; DateTime start_time; DateTime current_time; DateTime last_update_time; unsigned long group_count; long band_width; }; interface ShutdownCallback { void shutdown_notify ( in string reason ); }; interface Session { readonly attribute SessionStatusstatus; attribute ShutdownCallback callback; void destroy(); };}; #endif // _DAIS_SESSION_IDL SessionStatus A struct holding session status. Parameter Description name Within the server unique name of the session. start_time The time when the session was started. This time is not reset during the session lifetime. current_time The current time as known by the server. last_update_time The time when the server sent an event notification for this session. group_count The current number of groups for a data access session or the number of event subscriptions for an alarms & event session. band_width If held updated by the server the percentage bandwidth in use for communication with underlying RTUs or devices. A value of 100 or more indicates that more bandwidth for communication with devices is required than available. A value of -1 indicates the value is unknown by the server. ShutdownCallback An object implemented by clients and used by the server to indicate that it will shutdown soon. No further calls should be made and no further data callbacks should be expected. shutdown_notify() Parameter Description reason An explanation of why the server is shutting down. Session An interface representing a single conversation with the DAIS service. The interface is inherited into interfaces representing sessions supporting specific services, (for example, data access or alarms & events). status A read only attribute holding the SessionStatus. callback An attribute holding a reference to a ShutDownCallback object. A client that wants to receive shut down callbacks from a server shall update the attribute with a reference to a ShutDownCallback object. destroy() A method for deletion of the session object. Some methods have a filter string (for example, the browse methods find_by_type() and find_by_parent() in DAISNode and DAISItem). The filter string shall contain a pattern that is used to match a text string (e.g., the pathname). The text strings matching the pattern are passing the filter. The strings that may appear in the filter string pattern are listed below. Characters in pattern Matches in string ? Any single character. * Zero or more characters. # Any single digit (0-9). substring The specified substring [charlist] Any single character in charlist. [!charlist] Any single character not in charlist. Some examples of patterns and strings are given below. Pattern String String pass filter a*a aBBBa Yes [A-Z] F Yes [!A-Z] F No a#a a2a Yes a[L-P]#[!c-e] aM5b Yes B?T* BAT123khg Yes B?T* CAT123khg No This section defines a little language that is used to describe logical expressions and navigation in structures. A logical expression evaluates to true or false and can be used in filters for collection of data or definition of states, etc. The condition_logic described in Section 5.2.7, “DAISConditionSpace IDL,? on page 5-32 is used to define states. In DAIS the data model seen through the API is a hierarchical structure of typed nodes. A typed node may contain other typed nodes and/or property values (called items). This data model is described in more detail in Section 4.1, “Information Model,? on page 4-1. In addition to this hierarchy DAIS supports data models where a property value may refer to one or more other nodes. Hence navigation via such references is needed as well. An information model that includes both hierarchy and references is the IEC 61970 briefly described in Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. To be able to navigate to nodes in the structure the little language shall include support for describing paths. XML Path Language (XPath) [13] is a language that supports navigation in structures and this specification uses a subset of XPath as the logical expression language. XPath requires the exposed data model to be hierarchical (even though a model is exposed as hierarchical it may internally be organized in other ways). A logical expression in XPath is called “PredicateExpr? (statement 9 in the XPath specification [13]). A PredicateExpr evaluates to true or false. A logical expression in DAIS is called DAIS_Expression. The rules for a DAIS_expression are: • DAIS_Expression ::= PredicateExpr The following restrictions of the functionality described in the XPath specification are defined for DAIS_Expression: • The union operator "|" is not supported, refer to statement 18 in [13]. • The arithmetic operators "+", "-", "div", "*" and "mod" are not supported, refer to statements 25, 26 and 27 in [13]. • unabbreviated location paths is not supported. • abbreviated location paths is supported. • the following axes are supported; child, parent, descendant, attribute, and self. • the following XPath functions are supported; id(), position(), not(), true(), false(). The mapping between DAIS and XML data models is listed below. Table 3-1 Mapping between DAIS and XML data models DAIS entity XML entity Comment Node A DAIS Node element that may be contained by another DAIS node element. The DAIS Node element name is the DAIS::Type name (DAIS::Type::Description.label) referenced by DAIS::Node::Description.type. If the DAIS Node element has a parent element, the parent is given by Node::Description.parent. Node::Description.id An id attribute of type ID at a DAIS Node element. Accessed by the id() function Node::Description.label A child element of a DAIS Node element. The element name is “label.? The value is Node::Description.label. Table 3-1 Mapping between DAIS and XML data models DAIS entity XML entity Comment Node::Description. descrip A child element of a DAIS Node element. The element name is “description.? The value is Node::Description.descrip. Item A DAIS Item element that is child of a DAIS Node element. The element name is the DAIS::Property name (DAIS::Property:: Description.label) concatenated with the DAIS Node element name separated by a “.?. The DAIS::Property is given by Item::Description.id.property. The DAIS Node parent element is given by Item::Description.id.resource. Item::Description.value The value of the DAIS Item element. XML data example _200 30 _400 50 -50 The XML data example is based on the UML schema in Figure 4-3 on page 4-6 and the mapping from Table 3-1. Through DAIS an operator gets access to data in a control system. The operator can: • Read data (Data Access) and alarms and events (Alarms & Events). • Write data (Data Access) • Acknowledge alarms (Alarms & Events). Many control systems implement an authorization scheme where it checks if an operator is allowed to read, write, or acknowledge. A DAIS server exposes many data objects. If authorization is supported, checks must be made by the server. The server must then know who the operator is. An interface that can be used by the server to get this information is described in the Security Service Specification [14]. The Security Service Specification includes a rich interface supporting extensive security comprising: • Identification and authentication • Authorization and access control • Security auditing • Security of communication • Non-repudiation • Administration The smallest need for a DAIS server is to be able to identify an operator (a principal in Security language) so that access control can be made from within the DAIS server. Authentication is assumed taken care of at the operating system login. The control of access to a DAIS server itself within the scope of a secure system is not necessarily a requirement. The other functions (auditing, secure communication, non-repudiation, and administration) supported by the Security Service are not necessarily required for a DAIS server. For a DAIS server the following requirement levels for support by the system are defined: 0 - No authorization and no requirements. 1 - Identification of principal requiring SecurityLevel1 interfaces, refer to [14] appendix A. 2 - Security levels as described in [14] appendix C, mainly Security Functionality Level 1. The DAISServer IDL describes the DAIS server interface and depends on the types of session interfaces (for example, data access or alarms & events) it implements. A server not implementing a session type (data access or alarms & events) shall still be capable of reporting the type as not implemented. The IDL files and dependencies in Figure 3-6 are defined below. DAISServer DAISDASession (from Data Access) DAISAES ession (from EventAndAlarm s) DAISSession (from Com m on) Figure 3-6 Dependencies between server IDL files The fundamental DAIS service from which session objects may be obtained. DAIS::Server would normally be implemented as a persistent object accessed via the naming service or the trader service. From the DAIS::Server object, the session objects for data access or alarms & events are created. A client may create as many session objects as wanted. A session can be created for a view. A view corresponds to a specific hierarchical organization of objects (also called nodes in this specification). The same object may appear in multiple views and hence in different hierarchical structures. An example is a breaker appearing in a functional structure (having the function of breaking current) and in a location structure (the place where it is located), refer also to [10]. Another example is the same object appearing in different areas of authority. A DAIS server supporting data access may have a number of persistent public groups. Public groups can be used and managed through the group interface, refer to Section 4.2.7, “DAISGroup IDL,? on page 4-40. Services that are not implemented will raise the CORBA standard exception NO_IMPLEMENT. Not implemented exceptions can be expected for a data accesssession, an alarms & event session, and inspection. DAIS::AlarmsAndEvents::Session (from DAISAESession ) <> DAIS::Server <> status() : DAISServerStatus create_data_access_session() create_data_access_session_for_view() 11create_alarms_and_events_session() create_alarms_and_events_session_for_view() find_views() 110..0.n 1 n.111 0. .n.n 0. Client 0..n0..n PublicGroup id : ResourceID status : DAIS::DataAccess::Group::State 0..n0..n11 0..0.n.n DAIS::DataAccess::Session (fro m DA IS DA Session) <> GroupEntry (from DAISG roupEntry) Figure 3-7 DAIS server IDL in UML //File: DAISServer.idl#ifndef _DAIS_SERVER_IDL#define _DAIS_SERVER_IDL#pragma prefix "omg.org"#include #include module DAIS { enum ServerState {SERVER_STATE_RUNNING,SERVER_STATE_FAILED,SERVER_STATE_NOCONFIG,SERVER_STATE_SUSPENDED,SERVER_STATE_TEST }; struct ServerStatus { DateTime start_time; DateTime current_time; ServerState server_state; unsigned long session_count; unsigned long major_version; unsigned long minor_version; unsigned long build_number; string vendor_info; }; interface Inspection {}; interface Server { exception DuplicateName {string reason;}; exception InvalidView {string reason;}; readonly attribute ServerStatusstatus;readonly attribute SupportedFunctions supported_functions; DataAccess::Session create_data_access_session(in string session_name) raises (DuplicateName); DataAccess::Session create_data_access_session_for_view( in string session_name, in string view_name ) raises (DuplicateName, InvalidView); AlarmsAndEvents::Session create_alarms_and_events_session( in string session_name ) raises (DuplicateName); AlarmsAndEvents::Session create_alarms_and_events_session_for_view( in string session_name, in string view_name ) raises (DuplicateName, InvalidView); Strings find_views(); Inspection inspect(); };}; #endif // _DAIS_SERVER_IDL ServerState An enumeration of the states a Server may have. EnumValue Description SERVER_STATE_RUNNING The server is running normally. This is the usual state for a server. SERVER_STATE_FAILED A vendor specific fatal error has occurred within the server. The server is no longer functioning. The recovery procedure from this situation is vendor specific. SERVER_STATE_NOCONFIG The server is running but has no configuration information loaded and thus cannot function normally. This state implies that the server needs configuration information in order to function. Servers that do not require configuration information should not return this state. SERVER_STATE_SUSPENDED The server has been temporarily suspended via some vendor specific method and is not getting or sending data. Note that Quality will be returned as OPC_QUALITY_OUT_OF_SERVICE. SERVER_STATE_TEST The server is in Test Mode. The outputs are disconnected from the real hardware but the server will otherwise behave normally. Inputs may be real or may be simulated depending on the vendor implementation. Quality will generally be returned normally. ServerStatus Member Description start_time Time the server was started. This is constant for the server instance and is not reset when the server changes states. Each instance of a server should keep the time when the process started. current_time The current time as known by the server. server_state The current status of the server. Refer to ServerState enumeration. session_count The total number of sessions created by clients for this server. major_version The major version of the server software. minor_version The minor version of the server software. build_number The ‘build number’ of the server software. vendor_info Vendor specific string providing additional information about the server. It is recommended that this mention the name of the company and the type of device(s) supported. supported_functions A constant that tells what functions are implemented by the DAIS server (e.g., Data Access, Alarms & Events or both.) Inspection An optional interface intended to be specialized into a vendor specific inspection object. The inspection object is intended to expose server internal details for debugging and inspection purposes. Server An object implementing the DAIS server. A DAIS server might provide more than one view on nodes. A view is a specific hierarchical organization of nodes and nodes may appear in more than one hierarchical structure (for example, a functional structure or a location structure as defined by IEC 1346-1), refer also to Section 2.4, “IEC 1346-1, Structuring and Naming,? on page 2-7. DuplicateName An exception raised when an object is created and the name already exists. No object is created if the exception is raised. Is used for session and group manager objects. InvalidView An exception raised when an invalid view is specified. An invalid view is if the view name does not exist or a view not intended for the type of session is used (for example, a view for data access is used for alarms & events). statusAn attribute holding the ServerStatus.create_data_access_session() A method for creation of a data access session object. The default view will be used. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. return A reference to the created DAIS::DataAccess::Session object. create_data_access_session_for_view() A method for creation of a data access session object using a view of nodes. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. view_name The name of the view to open. If no name is supplied, the default view will be used. return A reference to the created DAIS::DataAccess::Session object. create_alarms_and_events_session() A method for creation of an alarms & events session object. The default view will be used. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. return A reference to the created DAIS::DataAccess::Session object. create_alarms_and_events_session_for_view() A method for creation of an alarms & events session object using a view of areas. This allows a server to support different area structures for different purposes (for example, operational responsibility, workorder management). Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. view_name The name of the view to open. return A reference to the created DAIS::DataAccess::Session object. find_views() A method to get the names for the server supported views. Parameter Description return A sequence of view names. inspect() A method for creation of an inspection object. Parameter Description return The inspection object. Session Management : Client: Client : DAIS::Server:DAIS::ServerDataAccess : DAIS::DataAccess::Session DataAccess : DAIS::DataAccess::SessionA&E :A&EDAIS::AlarmsAndEvents::SessionD :AIS::AlarmsAndEvents::SessionCreate a data access session for a specific structure and do work, e.g. create groups and subscribe find_views( ) create_alarms_and_events_session( ) Do work with alarms & events session e.g. create an AESubscription create_data_access_session_for_view( ) Get the available views destroy( ) destroy( ) Figure 3-8 Session management interaction To support universal character encodings the UTF-8 Unicode standard [12] shall be used for characters and strings. The DAIS relies on the Data Access Facility (DAF) for basic data type declarations and some DAF declarations (for example, ResourceID and SimpleValue) are included because of this. DAIS common declarations (for example, DAIS::Quality) are made in DAISCommon. Interfaces for nodes, types, properties, and sessions are also common between data access and alarms & events. The Interface Definition Language (IDL) files and dependencies listed in Figure 3-1 are defined. DAFIdentifiers DAFDescriptions DAISSession DAISCommon DAISNode DAISProperty DAISType Figure 3-1 Dependencies among common IDL files Refer to the Data Access Facility specification [2]. Refer to the Data Access Facility specification [2]. // File: DAISCommon.idl#ifndef _DAIS_COMMON_IDL#define _DAIS_COMMON_IDL#pragma prefix "omg.org"#include module DAIS{typedef unsigned short SupportedFunctions;const SuportedFunctions DAIS_DATA_ACCESS =0x0001;const SupportedFunctions DAIS_ALARMS_AND_EVENTS =0x0002; typedef DAFDescriptions::ResourceID ResourceID;typedef DAFDescriptions::SimpleValueType SimpleValueType;typedef DAFDescriptions::SimpleValue SimpleValue;typedef DAFDescriptions::DateTime DateTime;typedef DAFDescriptions::PropertyID PropertyID;typedef DAFDescriptions::PropertyValueSequence PropertyValues; // sequences of resource idstypedef sequence ResourceIDs;typedef sequence PropertyIDs; truct ItemID{ResourceID resource;PropertyID property;};typedef sequence ItemIDs; typedef unsigned long ClientItemHandle;typedef sequence ClientItemHandles;typedef unsigned long long ServerItemHandle;typedef sequence ServerItemHandles; typedef short ServerItemIdentificationType;const ServerItemIdentificationType ITEM_ID = 0;const ServerItemIdentificationType PATH_NAME = 1; union ServerItemIdentification switch( ServerItemIdentificationType ) { case ITEM_ID: ItemID item; case PATH_NAME: string pathname; }; typedef sequenceServerItemIdentifications; typedef unsigned short Error; struct ItemError { Error err; ClientItemHandle client_handle; ServerItemHandle server_handle; string pathname; string reason; }; typedef sequence ItemErrors; // error codes const Error ERROR_DAISOK = 0; const Error ERROR_BAD_RIGHTS = 1; const Error ERROR_UNKNOWN_ITEMID = 2; const Error ERROR_CLAMPED = 3; const Error ERROR_OUT_OF_RANGE = 4; const Error ERROR_UNKNOWN_PATHNAME = 5; const Error ERROR_BAD_TYPE = 6; const Error ERROR_UNKNOWN_ACCESS_PATH = 7; const Error ERROR_INTERNAL_SERVER = 8; const Error ERROR_INVALID_DAIS_HANDLE = 9; enum AccessRights { READABLE, WRITEABLE, READ_AND_WRITEABLE }; typedef unsigned long OPCQuality; typedef unsigned long UserQuality; struct Quality { OPCQuality opc_quality; UserQuality user_quality; }; // Masks for extracting quality subfields// (note 'status' mask also includes 'Quality' bits) const OPCQuality OPC_QUALITY_MASK = 0x000000C0; const OPCQuality OPC_STATUS_MASK = 0x000000FC; const OPCQuality OPC_LIMIT_MASK = 0x00000003; // Values for QUALITY_MASK bit field const OPCQualityOPC_QUALITY_BAD = 0x00000000; const OPCQuality OPC_QUALITY_UNCERTAIN = 0x00000040; const OPCQualityOPC_QUALITY_GOOD = 0x000000C0; // STATUS_MASK Values for Quality = BAD const OPCQuality OPC_QUALITY_CONFIG_ERROR = 0x00000004; const OPCQuality OPC_QUALITY_NOT_CONNECTED = 0x00000008; const OPCQuality OPC_QUALITY_DEVICE_FAILURE = 0x0000000C; const OPCQuality OPC_QUALITY_SENSOR_FAILURE = 0x00000010; const OPCQuality OPC_QUALITY_LAST_KNOWN = 0x00000014; const OPCQuality OPC_QUALITY_COMM_FAILURE = 0x00000018; const OPCQuality OPC_QUALITY_OUT_OF_SERVICE = 0x0000001C; // STATUS_MASK Values for Quality = UNCERTAIN const OPCQuality OPC_QUALITY_LAST_USABLE = 0x00000044; const OPCQuality OPC_QUALITY_SENSOR_CAL = 0x00000050; const OPCQuality OPC_QUALITY_EGU_EXCEEDED = 0x00000054; const OPCQuality OPC_QUALITY_SUB_NORMAL = 0x00000058; const OPCQuality DAIS_QUALITY_OCILLATORY = 0x0000005C; // STATUS_MASK Values for Quality = GOOD //const OPCQuality OPC_QUALITY_LOCAL_OVERRIDE= 0xD8; //use EXQ_Source_xxx instead of OPC_QUALITY_LOCAL_OVERRIDE // Values for Limit Bitfield const OPCQualityOPC_LIMIT_OK = 0x00000000; const OPCQualityOPC_LIMIT_LOW = 0x00000001; const OPCQualityOPC_LIMIT_HIGH = 0x00000002; const OPCQualityOPC_LIMIT_CONST = 0x00000003; //DAIS Quality extension masks const OPCQuality EXQ_SOURCE_MASK = 0x00000700;const OPCQuality EXQ_TEST_MASK = 0x00000800;const OPCQuality EXQ_OPERATOR_BLOCKED_MASK = 0x00001000;const OPCQuality EXQ_TIMESTAMP_ACCURACY_MASK = 0x00006000; //DAIS Quality source extensionconst OPCQuality EXQ_SOURCE_NONE = 0x00000000;const OPCQuality EXQ_SOURCE_PROCESS = 0x00000100;const OPCQuality EXQ_SOURCE_PRIMARY_SUBSTITUTED = 0x00000200;const OPCQuality EXQ_SOURCE_INHERITED_SUBSTITUTED= 0x00000300;const OPCQuality EXQ_SOURCE_CORRECTED = 0x00000400;const OPCQuality EXQ_SOURCE_DEFAULTED = 0x00000500; //DAIS Time stamp accuracyconst OPCQuality EXQ_TS_ACC_10_MSEC = 0x00000000;const OPCQuality EXQ_TS_ACC_100_MSEC = 0x00002000;const OPCQuality EXQ_TS_ACC_SECOND = 0x00004000;const OPCQuality EXQ_TS_ACC_BAD_TIME = 0x00006000;};#endif // _DAIS_COMMON_IDL SupportedFunctions This constant tells what functions the DAIS server (i.e., Data access, Alarms & Events, or both) supports. In case the server is extended with other functions they are included as well (e.g., Historical Data functionality (HDAIS)). DAF declarations These declarations (for example, ResourceID) import DAF declarations to DAIS. ItemID A pair of a ResourceID and a PropertyID. It uniquely identifies an item; that is, a property at a node. Member Description resource The ResourceID. property The PropertyID. ClientItemHandle A client created numeric handle used by the client to efficiently identify data coming from the server in callbacks. ServerItemHandle A server created numeric handle used by the server to efficiently identify items in client calls. ServerItemIdentification A union that holds either an ItemID or a pathname. Either can be used for identification of an item. Error Numeric error codes that are returned by ItemError. EnumValue Description ERROR_DAISOK Used to indicate an error free result. ERROR_BAD_RIGHTS The Items AccessRights do not allow the operation. ERROR_UNKNOWN_ITEMID The resource or property in the ItemID is unknown. ERROR_CLAMPED A value passed to WRITE was accepted but the output was clamped. ERROR_OUT_OF_RANGE The value was out of range. ERROR_UNKNOWN_PATHNAME The pathname was not recognised. ERROR_BAD_TYPE The server cannot convert the data between the specified format/ requested data type and the canonical data type. ERROR_UNKNOWN_ACCESS_PATH The item's access path is unknown. ERROR_INTERNAL_SERVER An error has appeared in the server due to some server internal problem. ERROR_INVALID_DAIS_HANDLE A client or server handle was invalid. ItemError A struct for reporting of item related errors. Member Description err An error code as described below. client_handle The client side handle identifying the item. server_handle The server side handle identifying the item. pathname The pathname for display or presentation purposes. reason An additional text explaining the error. AccessRights Numeric access rights supported per item. EnumValue Description READABLE Read only data. WRITEABLE Write only data. READ_AND_WRITABLE Both read and write data. OPCQuality A flag word giving the OPC quality. Each flag has a specific meaning as described below. Four groups of flags exist: 1. Main quality telling if a value is good, bad, or suspected. 2. Detailed quality. 3. Limits telling if the value is stuck. 4. Historical data access flags. Those flags are described in the HDAIS specification. Bit masks are defined to extract these flags. Quality, status, and limit bit masks Mask Description OPC_QUALITY_MASK Bit mask for main quality. OPC_STATUS_MASK Bit mask for detailed quality. OPC_LIMIT_MASK Bit mask for the limits. Main quality enumeration numbers Enum Description OPC_QUALITY_BAD The number for bad quality. OPC_QUALITY_UNCERTAIN The number for uncertain quality. OPC_QUALITY_GOOD The number for good quality. After application of the OPC_QUALITY_MASK the quality shall be compared directly to the enumeration numbers to decide the quality. Detailed quality flags for bad quality Flag Description OPC_QUALITY_CONFIG_ERROR There is a server configuration error concerning this value. OPC_QUALITY_NOT_CONNECTED The source of the value is not connected. OPC_QUALITY_DEVICE_FAILURE A device failure has been detected. OPC_QUALITY_SENSOR_FAILURE A sensor failure has been detected. OPC_QUALITY_LAST_KNOWN The updating has stopped but there is an old value available. OPC_QUALITY_COMM_FAILURE Communication has failed and no value available. OPC_QUALITY_OUT_OF_SERVICE The updating of the value is manually blocked for update (the item is not active). Detailed quality flags for uncertain quality Flag Description OPC_QUALITY_LAST_USABLE The value is old. The time stamp gives the age. OPC_QUALITY_EGU_EXCEEDED The value is beyond the capability of representation (for example, counter overflow). OPC_QUALITY_SENSOR_CAL The sensor calibration is bad. OPC_QUALITY_SUB_NORMAL Value is derived from multiple sources where the majority has less than required good quality. DAIS_QUALITY_OCILLATORY If a binary value changes cyclically with a frequency higher than a specific threshold, it is oscillating. This quality compliant with IEC 61850-7-3. Definition of limit flags Flag Description OPC_LIMIT_OK The value is not limited; that is, it moves freely up or down. OPC_LIMIT_LOW The value is stuck at a low limit. OPC_LIMIT_HIGH The value is stuck at a high limit. OPC_LIMIT_CONST The value is stuck constant. DAIS Quality extension masks The part of the flag word giving the DAIS extended quality. Each flag has a specific meaning as described below. These quality definitions are based on the revised IEC 61850-7-3 definitions of quality. The following masks are defined. Mask Description EXQ_SOURCE_MASK Bit mask for the source. EXQ_TEST_MASK Bit mask for the test status. The test status indicates that the value is generated by a test and shall not be regarded as an operational value. EXQ_OPERATOR_BLOCKED_MASK Bit mask for the operator blocked status. The status indicates that the value has been blocked for update and is old. The OPC_QUALITY_LAST_USABLE quality shall be set as well. EXQ_TIMESTAMP_ACCURACY_MASK Bit mask for the time stamp accuracy. Flags defining source Flag Description EXQ_SOURCE_NONE There is no source for this data item. The code is used for spare items not yet allocated. EXQ_SOURCE_PROCESS The source for this value is the process. EXQ__SOURCE_PRIMARY_ SUBSTITUTED The value is manually substituted. EXQ_SOURCE_INHERITED_ SUBSTITUTED A substituted value has been copied or used as input to some calculation. The result value is then marked with EXQ_SOURCE_INHERITED_ SUBSTITUTED. EXQ_SOURCE_CORRECTED An alternate and more accurate value has been calculated by some application (e.g., a State Estimator). If this value has been used to correct the original value, it shall be indicated EXQ_SOURCE_CORRECTED. EXQ_REMOTE_DEFAULTED The value is initialized by a default value. Flags defining time stamp quality Flag Description EXQ_LOCAL_NONEEXQ_TS_ACC_ 10_MSEC The value is not updated locally (i.e., it has a remote source specification). The flags (=0) indicate that the accuracy is 10 milliseconds or better (IEC61850-7-2 performance class T0). EXQ_LOCAL_SUBSTITUTEDEXQ_TS_ ACC_100_MSEC The value is locally substituted (manually). The flags (=1) indicate that the accuracy is 100 milliseconds or better. EXQ_LOCAL_SE_REPLACEDEXQ_TS_ ACC_SECOND The value is locally substituted by State Estimator. The flags (=2) indicate that the accuracy is in the range of seconds or better. EXQ_TS_ACC_BAD_TIME The flags (=3) indicate that the time stamp is bad. QualityThe DAIS quality consists of OPCQuality and ExtendedQuality. Member Description opc_quality The quality as specified by OPC including extensions from DAIS. user_quality A user specific quality. Methods that return information about more than one resource may return an iterator. The resource description iterator allows a client to access a large query result sequentially, several resources at a time. This is necessary where the ORB limits message sizes. It also enables implementations to overlap the client and server processing of query results, if necessary. The client and the data provider should cooperate to manage the lifetime of the iterator and the resources it consumes. The destroy() and next_n() methods allow the client and data provider respectively to indicate that the iterator may be destroyed. In addition, the data provider may autonomously destroy the iterator at any time (for resource management or other reasons). If a client detects that an iterator has been destroyed, it will not interpret this condition in itself as either an indication that the end of the iteration has been reached, or as a permanent failure of the data provider. next_n() This operation returns possibly 0 and at most n resource descriptions in the form of a resource description sequence. In all cases the state of the iteration is indicated by the Boolean return value. • True means that there may be more resource descriptions beyond those returned so far. • False means all the resource descriptions have now been returned. No further calls are expected for this iterator and the data provider may destroy the iterator at any time after the call returns. reset() This operation resets the iterator to the first element. clone() This operation returns a copy of the iterator. destroy() This operation is used to terminate iteration before all the resource descriptions have been returned. After destroy() is invoked no further calls are expected for this iterator. The data provider may destroy the iterator at any time after the call returns. A node may represent a real world object such as a location or a piece of equipment. A node may also represent a schema item such as a type or property. Nodes correspond to “branches? in the IOPCBrowseServerAddressSpace or IOPCEventAreaBrowser interfaces. Nodes correspond to Resources in the RDF model and the DAF interface. Each node has a universal identity given by its ResourceID. The ResourceID of a node is the same in all views provided by a DAIS server. DAIS servers may be coordinated with DAF servers so that a node has the same ResourceID as the corresponding resource. Each node has zero or more child(s). A child may be another node or any other type of object (for example, data access items or alarms & event sources). Each node has a type. The type determines what other types of child objects a node has. Nodes are arranged in a strict hierarchy for naming purposes. A DAIS server may provide more than one such hierarchy, each is called a view. (The view is selected when the session is initiated.) Within a view, each node, except for the root node, has a single parent node, a label that is unique among all nodes with the same parent, and a unique pathname. A node’s pathname is a string that contains its label and the pathname of its parent. The pathname must be a valid URI, but apart from that the syntax of pathnames is implementation dependent. The Node IDL defines a main interface DAIS::Node::IHome for browsing among the hierarchically structured nodes. Nodes are described by DAIS::Node::Description struct. DAIS::Node::Iterator max_left() next_n() reset() clone() destroy() <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() <> 0..n 1 0..n1Node id : ResourceID label : string type : ResourceID 0..n0.1 .n1NodeItemComponent pathname : string 1 0..* +parent 10..* Figure 3-2 DAIS node IDL in UML //File: DAISNode.idl #ifndef _DAIS_NODE_IDL #define _DAIS_NODE_IDL #pragma prefix "omg.org" #include module DAIS { module Node { struct Description { ResourceID id; ResourceID parent; string label; string descrip; ResourceID type; boolean is_leaf; }; typedef sequence< Description > Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions nodes ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; exception InvalidFilter {string reason;}; exception UnkownTypeID {string reason;}; Description find ( in ResourceID node ) raises (UnknownResourceID); Descriptions find_each ( in ResourceIDs nodes ) raises (UnknownResourceID); Iterator find_by_parent ( in ResourceID node, in string filter_criteria ) raises (UnknownResourceID, InvalidFilter); Iterator find_by_type ( in ResourceID node, in string filter_criteria, in ResourceIDs type_filter ) raises (UnknownResourceID, InvalidFilter, UnknownTypeID); Strings get_pathnames ( in ResourceIDs nodes ); ResourceIDs get_ids ( in Strings pathnames ); };};}; #endif // _DAIS_NODE_IDL Description A struct describing a node. Member Description id The identification of this node. parent The identification of the parent node. label The label (single level designation) of the node. descrip A descriptive text for the node. type A reference to the type of the node. is_leaf Indicate if the node is a leaf (i.e., it has no child nodes). Iterator Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. This interface corresponds to the OPC interface EnumString with the difference that the Iterator returns the Description struct instead of a string. IHome An interface used for browsing nodes. The interface corresponds to the IOPCBrowseServerAddressSpace with the BrowseFilterType set to OPC_BRANCH or the IOPCEventAreaBrowser. A major difference to OPC is that the server does not provide a cursor for clients. Instead clients have to provide the browse position in each call. UnknownResourceID An exception telling that the ResourceID is unknown. For methods taking a sequence of resource ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. InvalidFilter An exception telling the filter_criteria string is not correct. The likely reason behind this exception is an erroneously entered string. UnknownTypeID An exception telling one or more TypeIDs does not exist. find() For a given node, return information about that node. Parameter Description node A node identification. return The node description. find_each () For a sequence of nodes, return information about each node. Parameter Description nodes A sequence of node identifications. return An iterator holding the node descriptions. find_by_parent () For a given node, return all child nodes at that node. Hence to reach leaf nodes using this method repeated calls must be made for each level. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_BRANCH.. Parameter Description node The parent node identification. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects nodes with a pathname matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. return An iterator holding the child node descriptions. find_by_type() For a sub-tree given by the node parameter, return all child nodes of the specified type. This will return all leaf nodes under the given sub-tree root node. There is no corresponding operation in OPC. Refer to Section 4.2.4.1, “DAIS::Item Overview,? on page 4-15 for a description of how item browsing is mapped to OPC. Parameter Description node The identification of the node defining the sub-tree. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects nodes with a pathname matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. type_filter A list of TypeIDs. Nodes matching any of the TypeIDs will be held by the returned iterator. return An iterator holding descriptions for the found nodes. get_pathnames() Translate a sequence of node identifications to the corresponding sequence of pathnames. If a node fails to translate to a pathname (due to an unknown node identification), the corresponding pathname is an empty string. Parameter Description nodes The sequence of nodes. return The corresponding sequence of pathnames. get_ids() Translate a sequence of pathnames to the corresponding sequence of node identifications. If a pathname fails to translate to a node identification (due to an unrecognized pathname), the corresponding node identification is NULL. Parameter Description pathnames The sequence of pathnames. return The corresponding sequence of node identifications. A type represents a set of related properties and associations. Each node has a type and all the properties represented by that type apply to the node. Each type is identified by a ResourceID and has a label and description. A type may be obtained for any node using the node’s TypeID. Related types may be grouped into a schema. A ResourceID identifies each schema. All the types in a schema may be obtained given the schema ResourceID. A schema and its type may be represented as nodes in one or more of views provided by a DAIS server. When a schema is represented as a node, the node’s ResourceID and the schema ResourceID are identical. Similarly, when a type is represented as a node, the node’s ResourceID and the type’s ResourceID are identical. The type’s parent is always the node representing its schema, the type’s label is identical to the node label and the type’s description is identical to the node description. The type IDL defines a main interface DAIS::Type::IHome for browsing supported types. DAIS::Type::IHome find() find_by_schema() <> +aggregated_types 11 0..n0..n 0..n0..n 11 0..n0..n Type id : ResourceID schema : ResourceID label : string description : string DAIS::Type::Iterator max_left() next_n() destroy() <> Figure 3-3 DAIS type IDL in UML //File DAISType.idl #ifndef _DAIS_TYPE_IDL #define _DAIS_TYPE_IDL #pragma prefix "omg.org" #include "DAISCommon.idl" module DAIS { module Type { struct Description { ResourceID id; ResourceID schema; string label; string descrip; ResourceIDs aggregated_types; }; typedef sequence Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions types ); void reset();Iterator clone();void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; Description find (in ResourceID type) raises (UnknownResourceID); Iterator find_by_schema ( in ResourceID schema ) raises (UnknownResourceID); };};}; #endif // _DAIS_TYPE_IDL Description A struct describing a type. Member Description id The identification of this type. schema The identification of the schema where the type is defined. label The label of the type. descrip A description of the type. aggregated_types A sequence of type identifications that a node of this type may contain. This information is intended as a guide when the type filter is specified for the find_by_type() methods. IHome An object used to browse the types. There is no corresponding interface in OPC. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find() For a given type, return information about that type. Parameter Description type A type identification. return The type description. find_by_schema() For a given schema, find all types defined by that schema. Parameter Description schema The identification of the schema. return A sequence of type descriptions. A property represents a characteristic of a node that can be described with a value. A given property may apply to many nodes, for each such node there will be an item corresponding to the property. (See Section 4.2.4, “DAISItem IDL,? on page 4-15). A DAIS property corresponds to a property in RDF and the DAF. A DAIS property corresponds to the concept of a property in OPC accessed with the IOPCItemProperties::QueryAvailableProperties() method. However, the six core OPC properties (timestamp, quality, value) do not correspond to properties in DAIS. They are given special treatment in OPC (they are not the same as other OPC properties). See Section 4.2.4, “DAISItem IDL,? on page 4-15 for interfaces to handle these. Each property is identified by a ResourceID and has a label, description, and canonical data type. The canonical data type is a member of the SimpleType enumeration and indicates the preferred CORBA atomic data type for values of this property. Every item of a given property has an identical canonical data type. A property may be obtained for any item via the property member of the ItemID. All properties that apply to a given node may be obtained, given the node’s ResourceID. All properties that apply to the nodes of a given type may be obtained, given the TypeID. A property may be represented as a node in one or more of views provided by a DAIS server. In this case the node’s ResourceID and the property’s ResourceID are identical. The property’s parent is always the node representing the type to which it belongs. The property’s label is identical to the node label and the property’s description is identical to the node description. The property IDL defines a main interface DAIS::Property::IHome for browsing properties. The information model describing how the properties are related to nodes and items is found in Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 . Property id : PropertyID label : string description : string canonical_data_type : SimpleValueType DAIS::Property::IHome <> find() find_each() find_by_node() find_by_type() 0..n.1 0. n1 Figure 3-4 DAIS property IDL in UML //File: DAISProperty.idl#ifndef _DAIS_PROPERTY_IDL#define _DAIS_PROPERTY_IDL#pragma prefix "omg.org"#include module DAIS {module Property { struct Description { PropertyID id; string label; string descrip; SimpleValueType canonical_data_type; };typedef sequence Descriptions; interface IHome { exception UnknownResourceID {string reason;}; Description find ( in PropertyID property ) raises (UnknownResourceID); Descriptions find_each ( in PropertyIDs properties ) raises (UnknownResourceID); Descriptions find_by_node ( in ResourceID node ) raises (UnknownResourceID); Descriptions find_by_type ( in ResourceID type ) raises (UnknownResourceID); };};}; #endif // _DAIS_PROPERTY_IDL Description Describe a property. Member Description id The identification of this property. label The label (single level designation) of the property. descrip A description of the property. canonical_data_type The data type used for the property in the server. Home An object used for browsing properties defined for a type or existing at a node. It corresponds to the OPC interface IOPCItemProperties. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find() For a given property, return information about that property. Parameter Description property A property identification. return The property description. find_each() For a given property, return information about that property. Parameter Description properties A sequence of property identifications. return The sequence of property descriptions. find_by_node () For a node, return information about each property describing its items. This method corresponds to IOPCItemProperties::QueryAvailableProperties(). Parameter Description node A node identification. return A sequence of property descriptions. find_by_type () For a given type, return all property descriptions. Parameter Description type A type identification. return A sequence of property descriptions. The session is an interface inherited by data access and alarms & events sessions. A session represents a single conversation with the DAIS service. A session has a connection to a shut down callback used by a server to shut down clients in the case of an ordered shut down of the server. If the session object is destroyed or a failure is detected by the server when invoking an operation on any callback objects, then the session is terminated. A session object corresponds to the OPC server object; hence each OPC server object will be represented by a session object in DAIS. Client (fro m DA ISServ er) DAIS::ShutdownCallback <> shutdown_notify() 1 0..1 10..1DAIS::Session <> status() : DAIS::SessionStatus callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() 0..1.1 0. 11 Figure 3-5 DAIS session IDL in UML The status() method corresponds to the read only SessionStatus attribute in the IDL. The callback() get and set methods correspond to the ShutDownCallback attribute. //File DAISSession.idl #ifndef _DAIS_SESSION_IDL #define _DAIS_SESSION_IDL #pragma prefix "omg.org" #include module DAIS { struct SessionStatus { string name; DateTime start_time; DateTime current_time; DateTime last_update_time; unsigned long group_count; long band_width; }; interface ShutdownCallback { void shutdown_notify ( in string reason ); }; interface Session { readonly attribute SessionStatusstatus; attribute ShutdownCallback callback; void destroy(); };}; #endif // _DAIS_SESSION_IDL SessionStatus A struct holding session status. Parameter Description name Within the server unique name of the session. start_time The time when the session was started. This time is not reset during the session lifetime. current_time The current time as known by the server. last_update_time The time when the server sent an event notification for this session. group_count The current number of groups for a data access session or the number of event subscriptions for an alarms & event session. band_width If held updated by the server the percentage bandwidth in use for communication with underlying RTUs or devices. A value of 100 or more indicates that more bandwidth for communication with devices is required than available. A value of -1 indicates the value is unknown by the server. ShutdownCallback An object implemented by clients and used by the server to indicate that it will shutdown soon. No further calls should be made and no further data callbacks should be expected. shutdown_notify() Parameter Description reason An explanation of why the server is shutting down. Session An interface representing a single conversation with the DAIS service. The interface is inherited into interfaces representing sessions supporting specific services, (for example, data access or alarms & events). status A read only attribute holding the SessionStatus. callback An attribute holding a reference to a ShutDownCallback object. A client that wants to receive shut down callbacks from a server shall update the attribute with a reference to a ShutDownCallback object. destroy() A method for deletion of the session object. Some methods have a filter string (for example, the browse methods find_by_type() and find_by_parent() in DAISNode and DAISItem). The filter string shall contain a pattern that is used to match a text string (e.g., the pathname). The text strings matching the pattern are passing the filter. The strings that may appear in the filter string pattern are listed below. Characters in pattern Matches in string ? Any single character. * Zero or more characters. # Any single digit (0-9). substring The specified substring [charlist] Any single character in charlist. [!charlist] Any single character not in charlist. Some examples of patterns and strings are given below. Pattern String String pass filter a*a aBBBa Yes [A-Z] F Yes [!A-Z] F No a#a a2a Yes a[L-P]#[!c-e] aM5b Yes B?T* BAT123khg Yes B?T* CAT123khg No This section defines a little language that is used to describe logical expressions and navigation in structures. A logical expression evaluates to true or false and can be used in filters for collection of data or definition of states, etc. The condition_logic described in Section 5.2.7, “DAISConditionSpace IDL,? on page 5-32 is used to define states. In DAIS the data model seen through the API is a hierarchical structure of typed nodes. A typed node may contain other typed nodes and/or property values (called items). This data model is described in more detail in Section 4.1, “Information Model,? on page 4-1. In addition to this hierarchy DAIS supports data models where a property value may refer to one or more other nodes. Hence navigation via such references is needed as well. An information model that includes both hierarchy and references is the IEC 61970 briefly described in Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. To be able to navigate to nodes in the structure the little language shall include support for describing paths. XML Path Language (XPath) [13] is a language that supports navigation in structures and this specification uses a subset of XPath as the logical expression language. XPath requires the exposed data model to be hierarchical (even though a model is exposed as hierarchical it may internally be organized in other ways). A logical expression in XPath is called “PredicateExpr? (statement 9 in the XPath specification [13]). A PredicateExpr evaluates to true or false. A logical expression in DAIS is called DAIS_Expression. The rules for a DAIS_expression are: • DAIS_Expression ::= PredicateExpr The following restrictions of the functionality described in the XPath specification are defined for DAIS_Expression: • The union operator "|" is not supported, refer to statement 18 in [13]. • The arithmetic operators "+", "-", "div", "*" and "mod" are not supported, refer to statements 25, 26 and 27 in [13]. • unabbreviated location paths is not supported. • abbreviated location paths is supported. • the following axes are supported; child, parent, descendant, attribute, and self. • the following XPath functions are supported; id(), position(), not(), true(), false(). The mapping between DAIS and XML data models is listed below. Table 3-1 Mapping between DAIS and XML data models DAIS entity XML entity Comment Node A DAIS Node element that may be contained by another DAIS node element. The DAIS Node element name is the DAIS::Type name (DAIS::Type::Description.label) referenced by DAIS::Node::Description.type. If the DAIS Node element has a parent element, the parent is given by Node::Description.parent. Node::Description.id An id attribute of type ID at a DAIS Node element. Accessed by the id() function Node::Description.label A child element of a DAIS Node element. The element name is “label.? The value is Node::Description.label. Table 3-1 Mapping between DAIS and XML data models DAIS entity XML entity Comment Node::Description. descrip A child element of a DAIS Node element. The element name is “description.? The value is Node::Description.descrip. Item A DAIS Item element that is child of a DAIS Node element. The element name is the DAIS::Property name (DAIS::Property:: Description.label) concatenated with the DAIS Node element name separated by a “.?. The DAIS::Property is given by Item::Description.id.property. The DAIS Node parent element is given by Item::Description.id.resource. Item::Description.value The value of the DAIS Item element. XML data example _200 30 _400 50 -50 The XML data example is based on the UML schema in Figure 4-3 on page 4-6 and the mapping from Table 3-1. Through DAIS an operator gets access to data in a control system. The operator can: • Read data (Data Access) and alarms and events (Alarms & Events). • Write data (Data Access) • Acknowledge alarms (Alarms & Events). Many control systems implement an authorization scheme where it checks if an operator is allowed to read, write, or acknowledge. A DAIS server exposes many data objects. If authorization is supported, checks must be made by the server. The server must then know who the operator is. An interface that can be used by the server to get this information is described in the Security Service Specification [14]. The Security Service Specification includes a rich interface supporting extensive security comprising: • Identification and authentication • Authorization and access control • Security auditing • Security of communication • Non-repudiation • Administration The smallest need for a DAIS server is to be able to identify an operator (a principal in Security language) so that access control can be made from within the DAIS server. Authentication is assumed taken care of at the operating system login. The control of access to a DAIS server itself within the scope of a secure system is not necessarily a requirement. The other functions (auditing, secure communication, non-repudiation, and administration) supported by the Security Service are not necessarily required for a DAIS server. For a DAIS server the following requirement levels for support by the system are defined: 0 - No authorization and no requirements. 1 - Identification of principal requiring SecurityLevel1 interfaces, refer to [14] appendix A. 2 - Security levels as described in [14] appendix C, mainly Security Functionality Level 1. To support universal character encodings the UTF-8 Unicode standard [12] shall be used for characters and strings. The DAIS relies on the Data Access Facility (DAF) for basic data type declarations and some DAF declarations (for example, ResourceID and SimpleValue) are included because of this. DAIS common declarations (for example, DAIS::Quality) are made in DAISCommon. Interfaces for nodes, types, properties, and sessions are also common between data access and alarms & events. The Interface Definition Language (IDL) files and dependencies listed in Figure 3-1 are defined. DAFIdentifiers DAFDescriptions DAISSession DAISCommon DAISNode DAISProperty DAISType Figure 3-1 Dependencies among common IDL files Refer to the Data Access Facility specification [2]. Refer to the Data Access Facility specification [2]. // File: DAISCommon.idl#ifndef _DAIS_COMMON_IDL#define _DAIS_COMMON_IDL#pragma prefix "omg.org"#include module DAIS{typedef unsigned short SupportedFunctions;const SuportedFunctions DAIS_DATA_ACCESS =0x0001;const SupportedFunctions DAIS_ALARMS_AND_EVENTS =0x0002; typedef DAFDescriptions::ResourceID ResourceID;typedef DAFDescriptions::SimpleValueType SimpleValueType;typedef DAFDescriptions::SimpleValue SimpleValue;typedef DAFDescriptions::DateTime DateTime;typedef DAFDescriptions::PropertyID PropertyID;typedef DAFDescriptions::PropertyValueSequence PropertyValues; // sequences of resource idstypedef sequence ResourceIDs;typedef sequence PropertyIDs; truct ItemID{ResourceID resource;PropertyID property;};typedef sequence ItemIDs; typedef unsigned long ClientItemHandle;typedef sequence ClientItemHandles;typedef unsigned long long ServerItemHandle;typedef sequence ServerItemHandles; typedef short ServerItemIdentificationType;const ServerItemIdentificationType ITEM_ID = 0;const ServerItemIdentificationType PATH_NAME = 1; union ServerItemIdentification switch( ServerItemIdentificationType ) { case ITEM_ID: ItemID item; case PATH_NAME: string pathname; }; typedef sequenceServerItemIdentifications; typedef unsigned short Error; struct ItemError { Error err; ClientItemHandle client_handle; ServerItemHandle server_handle; string pathname; string reason; }; typedef sequence ItemErrors; // error codes const Error ERROR_DAISOK = 0; const Error ERROR_BAD_RIGHTS = 1; const Error ERROR_UNKNOWN_ITEMID = 2; const Error ERROR_CLAMPED = 3; const Error ERROR_OUT_OF_RANGE = 4; const Error ERROR_UNKNOWN_PATHNAME = 5; const Error ERROR_BAD_TYPE = 6; const Error ERROR_UNKNOWN_ACCESS_PATH = 7; const Error ERROR_INTERNAL_SERVER = 8; const Error ERROR_INVALID_DAIS_HANDLE = 9; enum AccessRights { READABLE, WRITEABLE, READ_AND_WRITEABLE }; typedef unsigned long OPCQuality; typedef unsigned long UserQuality; struct Quality { OPCQuality opc_quality; UserQuality user_quality; }; // Masks for extracting quality subfields// (note 'status' mask also includes 'Quality' bits) const OPCQuality OPC_QUALITY_MASK = 0x000000C0; const OPCQuality OPC_STATUS_MASK = 0x000000FC; const OPCQuality OPC_LIMIT_MASK = 0x00000003; // Values for QUALITY_MASK bit field const OPCQualityOPC_QUALITY_BAD = 0x00000000; const OPCQuality OPC_QUALITY_UNCERTAIN = 0x00000040; const OPCQualityOPC_QUALITY_GOOD = 0x000000C0; // STATUS_MASK Values for Quality = BAD const OPCQuality OPC_QUALITY_CONFIG_ERROR = 0x00000004; const OPCQuality OPC_QUALITY_NOT_CONNECTED = 0x00000008; const OPCQuality OPC_QUALITY_DEVICE_FAILURE = 0x0000000C; const OPCQuality OPC_QUALITY_SENSOR_FAILURE = 0x00000010; const OPCQuality OPC_QUALITY_LAST_KNOWN = 0x00000014; const OPCQuality OPC_QUALITY_COMM_FAILURE = 0x00000018; const OPCQuality OPC_QUALITY_OUT_OF_SERVICE = 0x0000001C; // STATUS_MASK Values for Quality = UNCERTAIN const OPCQuality OPC_QUALITY_LAST_USABLE = 0x00000044; const OPCQuality OPC_QUALITY_SENSOR_CAL = 0x00000050; const OPCQuality OPC_QUALITY_EGU_EXCEEDED = 0x00000054; const OPCQuality OPC_QUALITY_SUB_NORMAL = 0x00000058; const OPCQuality DAIS_QUALITY_OCILLATORY = 0x0000005C; // STATUS_MASK Values for Quality = GOOD //const OPCQuality OPC_QUALITY_LOCAL_OVERRIDE= 0xD8; //use EXQ_Source_xxx instead of OPC_QUALITY_LOCAL_OVERRIDE // Values for Limit Bitfield const OPCQualityOPC_LIMIT_OK = 0x00000000; const OPCQualityOPC_LIMIT_LOW = 0x00000001; const OPCQualityOPC_LIMIT_HIGH = 0x00000002; const OPCQualityOPC_LIMIT_CONST = 0x00000003; //DAIS Quality extension masks const OPCQuality EXQ_SOURCE_MASK = 0x00000700;const OPCQuality EXQ_TEST_MASK = 0x00000800;const OPCQuality EXQ_OPERATOR_BLOCKED_MASK = 0x00001000;const OPCQuality EXQ_TIMESTAMP_ACCURACY_MASK = 0x00006000; //DAIS Quality source extensionconst OPCQuality EXQ_SOURCE_NONE = 0x00000000;const OPCQuality EXQ_SOURCE_PROCESS = 0x00000100;const OPCQuality EXQ_SOURCE_PRIMARY_SUBSTITUTED = 0x00000200;const OPCQuality EXQ_SOURCE_INHERITED_SUBSTITUTED= 0x00000300;const OPCQuality EXQ_SOURCE_CORRECTED = 0x00000400;const OPCQuality EXQ_SOURCE_DEFAULTED = 0x00000500; //DAIS Time stamp accuracyconst OPCQuality EXQ_TS_ACC_10_MSEC = 0x00000000;const OPCQuality EXQ_TS_ACC_100_MSEC = 0x00002000;const OPCQuality EXQ_TS_ACC_SECOND = 0x00004000;const OPCQuality EXQ_TS_ACC_BAD_TIME = 0x00006000;};#endif // _DAIS_COMMON_IDL SupportedFunctions This constant tells what functions the DAIS server (i.e., Data access, Alarms & Events, or both) supports. In case the server is extended with other functions they are included as well (e.g., Historical Data functionality (HDAIS)). DAF declarations These declarations (for example, ResourceID) import DAF declarations to DAIS. ItemID A pair of a ResourceID and a PropertyID. It uniquely identifies an item; that is, a property at a node. Member Description resource The ResourceID. property The PropertyID. ClientItemHandle A client created numeric handle used by the client to efficiently identify data coming from the server in callbacks. ServerItemHandle A server created numeric handle used by the server to efficiently identify items in client calls. ServerItemIdentification A union that holds either an ItemID or a pathname. Either can be used for identification of an item. Error Numeric error codes that are returned by ItemError. EnumValue Description ERROR_DAISOK Used to indicate an error free result. ERROR_BAD_RIGHTS The Items AccessRights do not allow the operation. ERROR_UNKNOWN_ITEMID The resource or property in the ItemID is unknown. ERROR_CLAMPED A value passed to WRITE was accepted but the output was clamped. ERROR_OUT_OF_RANGE The value was out of range. ERROR_UNKNOWN_PATHNAME The pathname was not recognised. ERROR_BAD_TYPE The server cannot convert the data between the specified format/ requested data type and the canonical data type. ERROR_UNKNOWN_ACCESS_PATH The item's access path is unknown. ERROR_INTERNAL_SERVER An error has appeared in the server due to some server internal problem. ERROR_INVALID_DAIS_HANDLE A client or server handle was invalid. ItemError A struct for reporting of item related errors. Member Description err An error code as described below. client_handle The client side handle identifying the item. server_handle The server side handle identifying the item. pathname The pathname for display or presentation purposes. reason An additional text explaining the error. AccessRights Numeric access rights supported per item. EnumValue Description READABLE Read only data. WRITEABLE Write only data. READ_AND_WRITABLE Both read and write data. OPCQuality A flag word giving the OPC quality. Each flag has a specific meaning as described below. Four groups of flags exist: 1. Main quality telling if a value is good, bad, or suspected. 2. Detailed quality. 3. Limits telling if the value is stuck. 4. Historical data access flags. Those flags are described in the HDAIS specification. Bit masks are defined to extract these flags. Quality, status, and limit bit masks Mask Description OPC_QUALITY_MASK Bit mask for main quality. OPC_STATUS_MASK Bit mask for detailed quality. OPC_LIMIT_MASK Bit mask for the limits. Main quality enumeration numbers Enum Description OPC_QUALITY_BAD The number for bad quality. OPC_QUALITY_UNCERTAIN The number for uncertain quality. OPC_QUALITY_GOOD The number for good quality. After application of the OPC_QUALITY_MASK the quality shall be compared directly to the enumeration numbers to decide the quality. Detailed quality flags for bad quality Flag Description OPC_QUALITY_CONFIG_ERROR There is a server configuration error concerning this value. OPC_QUALITY_NOT_CONNECTED The source of the value is not connected. OPC_QUALITY_DEVICE_FAILURE A device failure has been detected. OPC_QUALITY_SENSOR_FAILURE A sensor failure has been detected. OPC_QUALITY_LAST_KNOWN The updating has stopped but there is an old value available. OPC_QUALITY_COMM_FAILURE Communication has failed and no value available. OPC_QUALITY_OUT_OF_SERVICE The updating of the value is manually blocked for update (the item is not active). Detailed quality flags for uncertain quality Flag Description OPC_QUALITY_LAST_USABLE The value is old. The time stamp gives the age. OPC_QUALITY_EGU_EXCEEDED The value is beyond the capability of representation (for example, counter overflow). OPC_QUALITY_SENSOR_CAL The sensor calibration is bad. OPC_QUALITY_SUB_NORMAL Value is derived from multiple sources where the majority has less than required good quality. DAIS_QUALITY_OCILLATORY If a binary value changes cyclically with a frequency higher than a specific threshold, it is oscillating. This quality compliant with IEC 61850-7-3. Definition of limit flags Flag Description OPC_LIMIT_OK The value is not limited; that is, it moves freely up or down. OPC_LIMIT_LOW The value is stuck at a low limit. OPC_LIMIT_HIGH The value is stuck at a high limit. OPC_LIMIT_CONST The value is stuck constant. DAIS Quality extension masks The part of the flag word giving the DAIS extended quality. Each flag has a specific meaning as described below. These quality definitions are based on the revised IEC 61850-7-3 definitions of quality. The following masks are defined. Mask Description EXQ_SOURCE_MASK Bit mask for the source. EXQ_TEST_MASK Bit mask for the test status. The test status indicates that the value is generated by a test and shall not be regarded as an operational value. EXQ_OPERATOR_BLOCKED_MASK Bit mask for the operator blocked status. The status indicates that the value has been blocked for update and is old. The OPC_QUALITY_LAST_USABLE quality shall be set as well. EXQ_TIMESTAMP_ACCURACY_MASK Bit mask for the time stamp accuracy. Flags defining source Flag Description EXQ_SOURCE_NONE There is no source for this data item. The code is used for spare items not yet allocated. EXQ_SOURCE_PROCESS The source for this value is the process. EXQ__SOURCE_PRIMARY_ SUBSTITUTED The value is manually substituted. EXQ_SOURCE_INHERITED_ SUBSTITUTED A substituted value has been copied or used as input to some calculation. The result value is then marked with EXQ_SOURCE_INHERITED_ SUBSTITUTED. EXQ_SOURCE_CORRECTED An alternate and more accurate value has been calculated by some application (e.g., a State Estimator). If this value has been used to correct the original value, it shall be indicated EXQ_SOURCE_CORRECTED. EXQ_REMOTE_DEFAULTED The value is initialized by a default value. Flags defining time stamp quality Flag Description EXQ_LOCAL_NONEEXQ_TS_ACC_ 10_MSEC The value is not updated locally (i.e., it has a remote source specification). The flags (=0) indicate that the accuracy is 10 milliseconds or better (IEC61850-7-2 performance class T0). EXQ_LOCAL_SUBSTITUTEDEXQ_TS_ ACC_100_MSEC The value is locally substituted (manually). The flags (=1) indicate that the accuracy is 100 milliseconds or better. EXQ_LOCAL_SE_REPLACEDEXQ_TS_ ACC_SECOND The value is locally substituted by State Estimator. The flags (=2) indicate that the accuracy is in the range of seconds or better. EXQ_TS_ACC_BAD_TIME The flags (=3) indicate that the time stamp is bad. QualityThe DAIS quality consists of OPCQuality and ExtendedQuality. Member Description opc_quality The quality as specified by OPC including extensions from DAIS. user_quality A user specific quality. Methods that return information about more than one resource may return an iterator. The resource description iterator allows a client to access a large query result sequentially, several resources at a time. This is necessary where the ORB limits message sizes. It also enables implementations to overlap the client and server processing of query results, if necessary. The client and the data provider should cooperate to manage the lifetime of the iterator and the resources it consumes. The destroy() and next_n() methods allow the client and data provider respectively to indicate that the iterator may be destroyed. In addition, the data provider may autonomously destroy the iterator at any time (for resource management or other reasons). If a client detects that an iterator has been destroyed, it will not interpret this condition in itself as either an indication that the end of the iteration has been reached, or as a permanent failure of the data provider. next_n() This operation returns possibly 0 and at most n resource descriptions in the form of a resource description sequence. In all cases the state of the iteration is indicated by the Boolean return value. • True means that there may be more resource descriptions beyond those returned so far. • False means all the resource descriptions have now been returned. No further calls are expected for this iterator and the data provider may destroy the iterator at any time after the call returns. reset() This operation resets the iterator to the first element. clone() This operation returns a copy of the iterator. destroy() This operation is used to terminate iteration before all the resource descriptions have been returned. After destroy() is invoked no further calls are expected for this iterator. The data provider may destroy the iterator at any time after the call returns. A node may represent a real world object such as a location or a piece of equipment. A node may also represent a schema item such as a type or property. Nodes correspond to “branches? in the IOPCBrowseServerAddressSpace or IOPCEventAreaBrowser interfaces. Nodes correspond to Resources in the RDF model and the DAF interface. Each node has a universal identity given by its ResourceID. The ResourceID of a node is the same in all views provided by a DAIS server. DAIS servers may be coordinated with DAF servers so that a node has the same ResourceID as the corresponding resource. Each node has zero or more child(s). A child may be another node or any other type of object (for example, data access items or alarms & event sources). Each node has a type. The type determines what other types of child objects a node has. Nodes are arranged in a strict hierarchy for naming purposes. A DAIS server may provide more than one such hierarchy, each is called a view. (The view is selected when the session is initiated.) Within a view, each node, except for the root node, has a single parent node, a label that is unique among all nodes with the same parent, and a unique pathname. A node’s pathname is a string that contains its label and the pathname of its parent. The pathname must be a valid URI, but apart from that the syntax of pathnames is implementation dependent. The Node IDL defines a main interface DAIS::Node::IHome for browsing among the hierarchically structured nodes. Nodes are described by DAIS::Node::Description struct. DAIS::Node::Iterator max_left() next_n() reset() clone() destroy() <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() <> 0..n 1 0..n1Node id : ResourceID label : string type : ResourceID 0..n0.1 .n1NodeItemComponent pathname : string 1 0..* +parent 10..* Figure 3-2 DAIS node IDL in UML //File: DAISNode.idl #ifndef _DAIS_NODE_IDL #define _DAIS_NODE_IDL #pragma prefix "omg.org" #include module DAIS { module Node { struct Description { ResourceID id; ResourceID parent; string label; string descrip; ResourceID type; boolean is_leaf; }; typedef sequence< Description > Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions nodes ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; exception InvalidFilter {string reason;}; exception UnkownTypeID {string reason;}; Description find ( in ResourceID node ) raises (UnknownResourceID); Descriptions find_each ( in ResourceIDs nodes ) raises (UnknownResourceID); Iterator find_by_parent ( in ResourceID node, in string filter_criteria ) raises (UnknownResourceID, InvalidFilter); Iterator find_by_type ( in ResourceID node, in string filter_criteria, in ResourceIDs type_filter ) raises (UnknownResourceID, InvalidFilter, UnknownTypeID); Strings get_pathnames ( in ResourceIDs nodes ); ResourceIDs get_ids ( in Strings pathnames ); };};}; #endif // _DAIS_NODE_IDL Description A struct describing a node. Member Description id The identification of this node. parent The identification of the parent node. label The label (single level designation) of the node. descrip A descriptive text for the node. type A reference to the type of the node. is_leaf Indicate if the node is a leaf (i.e., it has no child nodes). Iterator Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. This interface corresponds to the OPC interface EnumString with the difference that the Iterator returns the Description struct instead of a string. IHome An interface used for browsing nodes. The interface corresponds to the IOPCBrowseServerAddressSpace with the BrowseFilterType set to OPC_BRANCH or the IOPCEventAreaBrowser. A major difference to OPC is that the server does not provide a cursor for clients. Instead clients have to provide the browse position in each call. UnknownResourceID An exception telling that the ResourceID is unknown. For methods taking a sequence of resource ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. InvalidFilter An exception telling the filter_criteria string is not correct. The likely reason behind this exception is an erroneously entered string. UnknownTypeID An exception telling one or more TypeIDs does not exist. find() For a given node, return information about that node. Parameter Description node A node identification. return The node description. find_each () For a sequence of nodes, return information about each node. Parameter Description nodes A sequence of node identifications. return An iterator holding the node descriptions. find_by_parent () For a given node, return all child nodes at that node. Hence to reach leaf nodes using this method repeated calls must be made for each level. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_BRANCH.. Parameter Description node The parent node identification. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects nodes with a pathname matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. return An iterator holding the child node descriptions. find_by_type() For a sub-tree given by the node parameter, return all child nodes of the specified type. This will return all leaf nodes under the given sub-tree root node. There is no corresponding operation in OPC. Refer to Section 4.2.4.1, “DAIS::Item Overview,? on page 4-15 for a description of how item browsing is mapped to OPC. Parameter Description node The identification of the node defining the sub-tree. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects nodes with a pathname matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. type_filter A list of TypeIDs. Nodes matching any of the TypeIDs will be held by the returned iterator. return An iterator holding descriptions for the found nodes. get_pathnames() Translate a sequence of node identifications to the corresponding sequence of pathnames. If a node fails to translate to a pathname (due to an unknown node identification), the corresponding pathname is an empty string. Parameter Description nodes The sequence of nodes. return The corresponding sequence of pathnames. get_ids() Translate a sequence of pathnames to the corresponding sequence of node identifications. If a pathname fails to translate to a node identification (due to an unrecognized pathname), the corresponding node identification is NULL. Parameter Description pathnames The sequence of pathnames. return The corresponding sequence of node identifications. A type represents a set of related properties and associations. Each node has a type and all the properties represented by that type apply to the node. Each type is identified by a ResourceID and has a label and description. A type may be obtained for any node using the node’s TypeID. Related types may be grouped into a schema. A ResourceID identifies each schema. All the types in a schema may be obtained given the schema ResourceID. A schema and its type may be represented as nodes in one or more of views provided by a DAIS server. When a schema is represented as a node, the node’s ResourceID and the schema ResourceID are identical. Similarly, when a type is represented as a node, the node’s ResourceID and the type’s ResourceID are identical. The type’s parent is always the node representing its schema, the type’s label is identical to the node label and the type’s description is identical to the node description. The type IDL defines a main interface DAIS::Type::IHome for browsing supported types. DAIS::Type::IHome find() find_by_schema() <> +aggregated_types 11 0..n0..n 0..n0..n 11 0..n0..n Type id : ResourceID schema : ResourceID label : string description : string DAIS::Type::Iterator max_left() next_n() destroy() <> Figure 3-3 DAIS type IDL in UML //File DAISType.idl #ifndef _DAIS_TYPE_IDL #define _DAIS_TYPE_IDL #pragma prefix "omg.org" #include "DAISCommon.idl" module DAIS { module Type { struct Description { ResourceID id; ResourceID schema; string label; string descrip; ResourceIDs aggregated_types; }; typedef sequence Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions types ); void reset();Iterator clone();void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; Description find (in ResourceID type) raises (UnknownResourceID); Iterator find_by_schema ( in ResourceID schema ) raises (UnknownResourceID); };};}; #endif // _DAIS_TYPE_IDL Description A struct describing a type. Member Description id The identification of this type. schema The identification of the schema where the type is defined. label The label of the type. descrip A description of the type. aggregated_types A sequence of type identifications that a node of this type may contain. This information is intended as a guide when the type filter is specified for the find_by_type() methods. IHome An object used to browse the types. There is no corresponding interface in OPC. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find() For a given type, return information about that type. Parameter Description type A type identification. return The type description. find_by_schema() For a given schema, find all types defined by that schema. Parameter Description schema The identification of the schema. return A sequence of type descriptions. A property represents a characteristic of a node that can be described with a value. A given property may apply to many nodes, for each such node there will be an item corresponding to the property. (See Section 4.2.4, “DAISItem IDL,? on page 4-15). A DAIS property corresponds to a property in RDF and the DAF. A DAIS property corresponds to the concept of a property in OPC accessed with the IOPCItemProperties::QueryAvailableProperties() method. However, the six core OPC properties (timestamp, quality, value) do not correspond to properties in DAIS. They are given special treatment in OPC (they are not the same as other OPC properties). See Section 4.2.4, “DAISItem IDL,? on page 4-15 for interfaces to handle these. Each property is identified by a ResourceID and has a label, description, and canonical data type. The canonical data type is a member of the SimpleType enumeration and indicates the preferred CORBA atomic data type for values of this property. Every item of a given property has an identical canonical data type. A property may be obtained for any item via the property member of the ItemID. All properties that apply to a given node may be obtained, given the node’s ResourceID. All properties that apply to the nodes of a given type may be obtained, given the TypeID. A property may be represented as a node in one or more of views provided by a DAIS server. In this case the node’s ResourceID and the property’s ResourceID are identical. The property’s parent is always the node representing the type to which it belongs. The property’s label is identical to the node label and the property’s description is identical to the node description. The property IDL defines a main interface DAIS::Property::IHome for browsing properties. The information model describing how the properties are related to nodes and items is found in Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 . Property id : PropertyID label : string description : string canonical_data_type : SimpleValueType DAIS::Property::IHome <> find() find_each() find_by_node() find_by_type() 0..n.1 0. n1 Figure 3-4 DAIS property IDL in UML //File: DAISProperty.idl#ifndef _DAIS_PROPERTY_IDL#define _DAIS_PROPERTY_IDL#pragma prefix "omg.org"#include module DAIS {module Property { struct Description { PropertyID id; string label; string descrip; SimpleValueType canonical_data_type; };typedef sequence Descriptions; interface IHome { exception UnknownResourceID {string reason;}; Description find ( in PropertyID property ) raises (UnknownResourceID); Descriptions find_each ( in PropertyIDs properties ) raises (UnknownResourceID); Descriptions find_by_node ( in ResourceID node ) raises (UnknownResourceID); Descriptions find_by_type ( in ResourceID type ) raises (UnknownResourceID); };};}; #endif // _DAIS_PROPERTY_IDL Description Describe a property. Member Description id The identification of this property. label The label (single level designation) of the property. descrip A description of the property. canonical_data_type The data type used for the property in the server. Home An object used for browsing properties defined for a type or existing at a node. It corresponds to the OPC interface IOPCItemProperties. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find() For a given property, return information about that property. Parameter Description property A property identification. return The property description. find_each() For a given property, return information about that property. Parameter Description properties A sequence of property identifications. return The sequence of property descriptions. find_by_node () For a node, return information about each property describing its items. This method corresponds to IOPCItemProperties::QueryAvailableProperties(). Parameter Description node A node identification. return A sequence of property descriptions. find_by_type () For a given type, return all property descriptions. Parameter Description type A type identification. return A sequence of property descriptions. The session is an interface inherited by data access and alarms & events sessions. A session represents a single conversation with the DAIS service. A session has a connection to a shut down callback used by a server to shut down clients in the case of an ordered shut down of the server. If the session object is destroyed or a failure is detected by the server when invoking an operation on any callback objects, then the session is terminated. A session object corresponds to the OPC server object; hence each OPC server object will be represented by a session object in DAIS. Client (fro m DA ISServ er) DAIS::ShutdownCallback <> shutdown_notify() 1 0..1 10..1DAIS::Session <> status() : DAIS::SessionStatus callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() 0..1.1 0. 11 Figure 3-5 DAIS session IDL in UML The status() method corresponds to the read only SessionStatus attribute in the IDL. The callback() get and set methods correspond to the ShutDownCallback attribute. //File DAISSession.idl #ifndef _DAIS_SESSION_IDL #define _DAIS_SESSION_IDL #pragma prefix "omg.org" #include module DAIS { struct SessionStatus { string name; DateTime start_time; DateTime current_time; DateTime last_update_time; unsigned long group_count; long band_width; }; interface ShutdownCallback { void shutdown_notify ( in string reason ); }; interface Session { readonly attribute SessionStatusstatus; attribute ShutdownCallback callback; void destroy(); };}; #endif // _DAIS_SESSION_IDL SessionStatus A struct holding session status. Parameter Description name Within the server unique name of the session. start_time The time when the session was started. This time is not reset during the session lifetime. current_time The current time as known by the server. last_update_time The time when the server sent an event notification for this session. group_count The current number of groups for a data access session or the number of event subscriptions for an alarms & event session. band_width If held updated by the server the percentage bandwidth in use for communication with underlying RTUs or devices. A value of 100 or more indicates that more bandwidth for communication with devices is required than available. A value of -1 indicates the value is unknown by the server. ShutdownCallback An object implemented by clients and used by the server to indicate that it will shutdown soon. No further calls should be made and no further data callbacks should be expected. shutdown_notify() Parameter Description reason An explanation of why the server is shutting down. Session An interface representing a single conversation with the DAIS service. The interface is inherited into interfaces representing sessions supporting specific services, (for example, data access or alarms & events). status A read only attribute holding the SessionStatus. callback An attribute holding a reference to a ShutDownCallback object. A client that wants to receive shut down callbacks from a server shall update the attribute with a reference to a ShutDownCallback object. destroy() A method for deletion of the session object. Some methods have a filter string (for example, the browse methods find_by_type() and find_by_parent() in DAISNode and DAISItem). The filter string shall contain a pattern that is used to match a text string (e.g., the pathname). The text strings matching the pattern are passing the filter. The strings that may appear in the filter string pattern are listed below. Characters in pattern Matches in string ? Any single character. * Zero or more characters. # Any single digit (0-9). substring The specified substring [charlist] Any single character in charlist. [!charlist] Any single character not in charlist. Some examples of patterns and strings are given below. Pattern String String pass filter a*a aBBBa Yes [A-Z] F Yes [!A-Z] F No a#a a2a Yes a[L-P]#[!c-e] aM5b Yes B?T* BAT123khg Yes B?T* CAT123khg No This section defines a little language that is used to describe logical expressions and navigation in structures. A logical expression evaluates to true or false and can be used in filters for collection of data or definition of states, etc. The condition_logic described in Section 5.2.7, “DAISConditionSpace IDL,? on page 5-32 is used to define states. In DAIS the data model seen through the API is a hierarchical structure of typed nodes. A typed node may contain other typed nodes and/or property values (called items). This data model is described in more detail in Section 4.1, “Information Model,? on page 4-1. In addition to this hierarchy DAIS supports data models where a property value may refer to one or more other nodes. Hence navigation via such references is needed as well. An information model that includes both hierarchy and references is the IEC 61970 briefly described in Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. To be able to navigate to nodes in the structure the little language shall include support for describing paths. XML Path Language (XPath) [13] is a language that supports navigation in structures and this specification uses a subset of XPath as the logical expression language. XPath requires the exposed data model to be hierarchical (even though a model is exposed as hierarchical it may internally be organized in other ways). A logical expression in XPath is called “PredicateExpr? (statement 9 in the XPath specification [13]). A PredicateExpr evaluates to true or false. A logical expression in DAIS is called DAIS_Expression. The rules for a DAIS_expression are: • DAIS_Expression ::= PredicateExpr The following restrictions of the functionality described in the XPath specification are defined for DAIS_Expression: • The union operator "|" is not supported, refer to statement 18 in [13]. • The arithmetic operators "+", "-", "div", "*" and "mod" are not supported, refer to statements 25, 26 and 27 in [13]. • unabbreviated location paths is not supported. • abbreviated location paths is supported. • the following axes are supported; child, parent, descendant, attribute, and self. • the following XPath functions are supported; id(), position(), not(), true(), false(). The mapping between DAIS and XML data models is listed below. Table 3-1 Mapping between DAIS and XML data models DAIS entity XML entity Comment Node A DAIS Node element that may be contained by another DAIS node element. The DAIS Node element name is the DAIS::Type name (DAIS::Type::Description.label) referenced by DAIS::Node::Description.type. If the DAIS Node element has a parent element, the parent is given by Node::Description.parent. Node::Description.id An id attribute of type ID at a DAIS Node element. Accessed by the id() function Node::Description.label A child element of a DAIS Node element. The element name is “label.? The value is Node::Description.label. Table 3-1 Mapping between DAIS and XML data models DAIS entity XML entity Comment Node::Description. descrip A child element of a DAIS Node element. The element name is “description.? The value is Node::Description.descrip. Item A DAIS Item element that is child of a DAIS Node element. The element name is the DAIS::Property name (DAIS::Property:: Description.label) concatenated with the DAIS Node element name separated by a “.?. The DAIS::Property is given by Item::Description.id.property. The DAIS Node parent element is given by Item::Description.id.resource. Item::Description.value The value of the DAIS Item element. XML data example _200 30 _400 50 -50 The XML data example is based on the UML schema in Figure 4-3 on page 4-6 and the mapping from Table 3-1. Through DAIS an operator gets access to data in a control system. The operator can: • Read data (Data Access) and alarms and events (Alarms & Events). • Write data (Data Access) • Acknowledge alarms (Alarms & Events). Many control systems implement an authorization scheme where it checks if an operator is allowed to read, write, or acknowledge. A DAIS server exposes many data objects. If authorization is supported, checks must be made by the server. The server must then know who the operator is. An interface that can be used by the server to get this information is described in the Security Service Specification [14]. The Security Service Specification includes a rich interface supporting extensive security comprising: • Identification and authentication • Authorization and access control • Security auditing • Security of communication • Non-repudiation • Administration The smallest need for a DAIS server is to be able to identify an operator (a principal in Security language) so that access control can be made from within the DAIS server. Authentication is assumed taken care of at the operating system login. The control of access to a DAIS server itself within the scope of a secure system is not necessarily a requirement. The other functions (auditing, secure communication, non-repudiation, and administration) supported by the Security Service are not necessarily required for a DAIS server. For a DAIS server the following requirement levels for support by the system are defined: 0 - No authorization and no requirements. 1 - Identification of principal requiring SecurityLevel1 interfaces, refer to [14] appendix A. 2 - Security levels as described in [14] appendix C, mainly Security Functionality Level 1. The DAISServer IDL describes the DAIS server interface and depends on the types of session interfaces (for example, data access or alarms & events) it implements. A server not implementing a session type (data access or alarms & events) shall still be capable of reporting the type as not implemented. The IDL files and dependencies in Figure 3-6 are defined below. DAISServer DAISDASession (from Data Access) DAISAES ession (from EventAndAlarm s) DAISSession (from Com m on) Figure 3-6 Dependencies between server IDL files The fundamental DAIS service from which session objects may be obtained. DAIS::Server would normally be implemented as a persistent object accessed via the naming service or the trader service. From the DAIS::Server object, the session objects for data access or alarms & events are created. A client may create as many session objects as wanted. A session can be created for a view. A view corresponds to a specific hierarchical organization of objects (also called nodes in this specification). The same object may appear in multiple views and hence in different hierarchical structures. An example is a breaker appearing in a functional structure (having the function of breaking current) and in a location structure (the place where it is located), refer also to [10]. Another example is the same object appearing in different areas of authority. A DAIS server supporting data access may have a number of persistent public groups. Public groups can be used and managed through the group interface, refer to Section 4.2.7, “DAISGroup IDL,? on page 4-40. Services that are not implemented will raise the CORBA standard exception NO_IMPLEMENT. Not implemented exceptions can be expected for a data accesssession, an alarms & event session, and inspection. DAIS::AlarmsAndEvents::Session (from DAISAESession ) <> DAIS::Server <> status() : DAISServerStatus create_data_access_session() create_data_access_session_for_view() 11create_alarms_and_events_session() create_alarms_and_events_session_for_view() find_views() 110..0.n 1 n.111 0. .n.n 0. Client 0..n0..n PublicGroup id : ResourceID status : DAIS::DataAccess::Group::State 0..n0..n11 0..0.n.n DAIS::DataAccess::Session (fro m DA IS DA Session) <> GroupEntry (from DAISG roupEntry) Figure 3-7 DAIS server IDL in UML //File: DAISServer.idl#ifndef _DAIS_SERVER_IDL#define _DAIS_SERVER_IDL#pragma prefix "omg.org"#include #include module DAIS { enum ServerState {SERVER_STATE_RUNNING,SERVER_STATE_FAILED,SERVER_STATE_NOCONFIG,SERVER_STATE_SUSPENDED,SERVER_STATE_TEST }; struct ServerStatus { DateTime start_time; DateTime current_time; ServerState server_state; unsigned long session_count; unsigned long major_version; unsigned long minor_version; unsigned long build_number; string vendor_info; }; interface Inspection {}; interface Server { exception DuplicateName {string reason;}; exception InvalidView {string reason;}; readonly attribute ServerStatusstatus;readonly attribute SupportedFunctions supported_functions; DataAccess::Session create_data_access_session(in string session_name) raises (DuplicateName); DataAccess::Session create_data_access_session_for_view( in string session_name, in string view_name ) raises (DuplicateName, InvalidView); AlarmsAndEvents::Session create_alarms_and_events_session( in string session_name ) raises (DuplicateName); AlarmsAndEvents::Session create_alarms_and_events_session_for_view( in string session_name, in string view_name ) raises (DuplicateName, InvalidView); Strings find_views(); Inspection inspect(); };}; #endif // _DAIS_SERVER_IDL ServerState An enumeration of the states a Server may have. EnumValue Description SERVER_STATE_RUNNING The server is running normally. This is the usual state for a server. SERVER_STATE_FAILED A vendor specific fatal error has occurred within the server. The server is no longer functioning. The recovery procedure from this situation is vendor specific. SERVER_STATE_NOCONFIG The server is running but has no configuration information loaded and thus cannot function normally. This state implies that the server needs configuration information in order to function. Servers that do not require configuration information should not return this state. SERVER_STATE_SUSPENDED The server has been temporarily suspended via some vendor specific method and is not getting or sending data. Note that Quality will be returned as OPC_QUALITY_OUT_OF_SERVICE. SERVER_STATE_TEST The server is in Test Mode. The outputs are disconnected from the real hardware but the server will otherwise behave normally. Inputs may be real or may be simulated depending on the vendor implementation. Quality will generally be returned normally. ServerStatus Member Description start_time Time the server was started. This is constant for the server instance and is not reset when the server changes states. Each instance of a server should keep the time when the process started. current_time The current time as known by the server. server_state The current status of the server. Refer to ServerState enumeration. session_count The total number of sessions created by clients for this server. major_version The major version of the server software. minor_version The minor version of the server software. build_number The ‘build number’ of the server software. vendor_info Vendor specific string providing additional information about the server. It is recommended that this mention the name of the company and the type of device(s) supported. supported_functions A constant that tells what functions are implemented by the DAIS server (e.g., Data Access, Alarms & Events or both.) Inspection An optional interface intended to be specialized into a vendor specific inspection object. The inspection object is intended to expose server internal details for debugging and inspection purposes. Server An object implementing the DAIS server. A DAIS server might provide more than one view on nodes. A view is a specific hierarchical organization of nodes and nodes may appear in more than one hierarchical structure (for example, a functional structure or a location structure as defined by IEC 1346-1), refer also to Section 2.4, “IEC 1346-1, Structuring and Naming,? on page 2-7. DuplicateName An exception raised when an object is created and the name already exists. No object is created if the exception is raised. Is used for session and group manager objects. InvalidView An exception raised when an invalid view is specified. An invalid view is if the view name does not exist or a view not intended for the type of session is used (for example, a view for data access is used for alarms & events). statusAn attribute holding the ServerStatus.create_data_access_session() A method for creation of a data access session object. The default view will be used. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. return A reference to the created DAIS::DataAccess::Session object. create_data_access_session_for_view() A method for creation of a data access session object using a view of nodes. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. view_name The name of the view to open. If no name is supplied, the default view will be used. return A reference to the created DAIS::DataAccess::Session object. create_alarms_and_events_session() A method for creation of an alarms & events session object. The default view will be used. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. return A reference to the created DAIS::DataAccess::Session object. create_alarms_and_events_session_for_view() A method for creation of an alarms & events session object using a view of areas. This allows a server to support different area structures for different purposes (for example, operational responsibility, workorder management). Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. view_name The name of the view to open. return A reference to the created DAIS::DataAccess::Session object. find_views() A method to get the names for the server supported views. Parameter Description return A sequence of view names. inspect() A method for creation of an inspection object. Parameter Description return The inspection object. Session Management : Client: Client : DAIS::Server:DAIS::ServerDataAccess : DAIS::DataAccess::Session DataAccess : DAIS::DataAccess::SessionA&E :A&EDAIS::AlarmsAndEvents::SessionD :AIS::AlarmsAndEvents::SessionCreate a data access session for a specific structure and do work, e.g. create groups and subscribe find_views( ) create_alarms_and_events_session( ) Do work with alarms & events session e.g. create an AESubscription create_data_access_session_for_view( ) Get the available views destroy( ) destroy( ) Figure 3-8 Session management interaction The DAISServer IDL describes the DAIS server interface and depends on the types of session interfaces (for example, data access or alarms & events) it implements. A server not implementing a session type (data access or alarms & events) shall still be capable of reporting the type as not implemented. The IDL files and dependencies in Figure 3-6 are defined below. DAISServer DAISDASession (from Data Access) DAISAES ession (from EventAndAlarm s) DAISSession (from Com m on) Figure 3-6 Dependencies between server IDL files The fundamental DAIS service from which session objects may be obtained. DAIS::Server would normally be implemented as a persistent object accessed via the naming service or the trader service. From the DAIS::Server object, the session objects for data access or alarms & events are created. A client may create as many session objects as wanted. A session can be created for a view. A view corresponds to a specific hierarchical organization of objects (also called nodes in this specification). The same object may appear in multiple views and hence in different hierarchical structures. An example is a breaker appearing in a functional structure (having the function of breaking current) and in a location structure (the place where it is located), refer also to [10]. Another example is the same object appearing in different areas of authority. A DAIS server supporting data access may have a number of persistent public groups. Public groups can be used and managed through the group interface, refer to Section 4.2.7, “DAISGroup IDL,? on page 4-40. Services that are not implemented will raise the CORBA standard exception NO_IMPLEMENT. Not implemented exceptions can be expected for a data accesssession, an alarms & event session, and inspection. DAIS::AlarmsAndEvents::Session (from DAISAESession ) <> DAIS::Server <> status() : DAISServerStatus create_data_access_session() create_data_access_session_for_view() 11create_alarms_and_events_session() create_alarms_and_events_session_for_view() find_views() 110..0.n 1 n.111 0. .n.n 0. Client 0..n0..n PublicGroup id : ResourceID status : DAIS::DataAccess::Group::State 0..n0..n11 0..0.n.n DAIS::DataAccess::Session (fro m DA IS DA Session) <> GroupEntry (from DAISG roupEntry) Figure 3-7 DAIS server IDL in UML //File: DAISServer.idl#ifndef _DAIS_SERVER_IDL#define _DAIS_SERVER_IDL#pragma prefix "omg.org"#include #include module DAIS { enum ServerState {SERVER_STATE_RUNNING,SERVER_STATE_FAILED,SERVER_STATE_NOCONFIG,SERVER_STATE_SUSPENDED,SERVER_STATE_TEST }; struct ServerStatus { DateTime start_time; DateTime current_time; ServerState server_state; unsigned long session_count; unsigned long major_version; unsigned long minor_version; unsigned long build_number; string vendor_info; }; interface Inspection {}; interface Server { exception DuplicateName {string reason;}; exception InvalidView {string reason;}; readonly attribute ServerStatusstatus;readonly attribute SupportedFunctions supported_functions; DataAccess::Session create_data_access_session(in string session_name) raises (DuplicateName); DataAccess::Session create_data_access_session_for_view( in string session_name, in string view_name ) raises (DuplicateName, InvalidView); AlarmsAndEvents::Session create_alarms_and_events_session( in string session_name ) raises (DuplicateName); AlarmsAndEvents::Session create_alarms_and_events_session_for_view( in string session_name, in string view_name ) raises (DuplicateName, InvalidView); Strings find_views(); Inspection inspect(); };}; #endif // _DAIS_SERVER_IDL ServerState An enumeration of the states a Server may have. EnumValue Description SERVER_STATE_RUNNING The server is running normally. This is the usual state for a server. SERVER_STATE_FAILED A vendor specific fatal error has occurred within the server. The server is no longer functioning. The recovery procedure from this situation is vendor specific. SERVER_STATE_NOCONFIG The server is running but has no configuration information loaded and thus cannot function normally. This state implies that the server needs configuration information in order to function. Servers that do not require configuration information should not return this state. SERVER_STATE_SUSPENDED The server has been temporarily suspended via some vendor specific method and is not getting or sending data. Note that Quality will be returned as OPC_QUALITY_OUT_OF_SERVICE. SERVER_STATE_TEST The server is in Test Mode. The outputs are disconnected from the real hardware but the server will otherwise behave normally. Inputs may be real or may be simulated depending on the vendor implementation. Quality will generally be returned normally. ServerStatus Member Description start_time Time the server was started. This is constant for the server instance and is not reset when the server changes states. Each instance of a server should keep the time when the process started. current_time The current time as known by the server. server_state The current status of the server. Refer to ServerState enumeration. session_count The total number of sessions created by clients for this server. major_version The major version of the server software. minor_version The minor version of the server software. build_number The ‘build number’ of the server software. vendor_info Vendor specific string providing additional information about the server. It is recommended that this mention the name of the company and the type of device(s) supported. supported_functions A constant that tells what functions are implemented by the DAIS server (e.g., Data Access, Alarms & Events or both.) Inspection An optional interface intended to be specialized into a vendor specific inspection object. The inspection object is intended to expose server internal details for debugging and inspection purposes. Server An object implementing the DAIS server. A DAIS server might provide more than one view on nodes. A view is a specific hierarchical organization of nodes and nodes may appear in more than one hierarchical structure (for example, a functional structure or a location structure as defined by IEC 1346-1), refer also to Section 2.4, “IEC 1346-1, Structuring and Naming,? on page 2-7. DuplicateName An exception raised when an object is created and the name already exists. No object is created if the exception is raised. Is used for session and group manager objects. InvalidView An exception raised when an invalid view is specified. An invalid view is if the view name does not exist or a view not intended for the type of session is used (for example, a view for data access is used for alarms & events). statusAn attribute holding the ServerStatus.create_data_access_session() A method for creation of a data access session object. The default view will be used. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. return A reference to the created DAIS::DataAccess::Session object. create_data_access_session_for_view() A method for creation of a data access session object using a view of nodes. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. view_name The name of the view to open. If no name is supplied, the default view will be used. return A reference to the created DAIS::DataAccess::Session object. create_alarms_and_events_session() A method for creation of an alarms & events session object. The default view will be used. Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. return A reference to the created DAIS::DataAccess::Session object. create_alarms_and_events_session_for_view() A method for creation of an alarms & events session object using a view of areas. This allows a server to support different area structures for different purposes (for example, operational responsibility, workorder management). Parameter Description name The name of the session. If an empty name is supplied, the server will create a name for the session. If a duplicate name is supplied, no session is generated. view_name The name of the view to open. return A reference to the created DAIS::DataAccess::Session object. find_views() A method to get the names for the server supported views. Parameter Description return A sequence of view names. inspect() A method for creation of an inspection object. Parameter Description return The inspection object. Session Management : Client: Client : DAIS::Server:DAIS::ServerDataAccess : DAIS::DataAccess::Session DataAccess : DAIS::DataAccess::SessionA&E :A&EDAIS::AlarmsAndEvents::SessionD :AIS::AlarmsAndEvents::SessionCreate a data access session for a specific structure and do work, e.g. create groups and subscribe find_views( ) create_alarms_and_events_session( ) Do work with alarms & events session e.g. create an AESubscription create_data_access_session_for_view( ) Get the available views destroy( ) destroy( ) Figure 3-8 Session management interaction Contents This chapter contains the following sections. Section Title Page “Information Model? 4-1 “API? 4-8 The data access interface provides a client with a way to read, write, or subscribe for data (items) held by the server. It has a discovery interface where a client can browse and select available data. Selected data is used to compose groups and groups are used in read, write, or subscribe operations. To get subscribed data, a client has to connect a callback object to the server so that the server can notify the clients with changed data. Equipment in any industrial process is usually modeled as entities or classes in computerized systems. The class name usually reflects the type of equipment. Objects from such classes are called Real World Objects (RWOs) in this document. RWO classes have properties describing equipment characteristics (for example, size, length, geometries, material, nameplate data) as well as application specific data (for example, impedance parameters, state estimated values). Depending on the purpose of a system and the managed (industrial) process the RWOs are of different types and contain different properties. Some RWOs are common between systems and independent of industrial process like process variables; that is, measurement (state) and control variables. Other RWOs like transmission lines and breakers are specific to power transmission. RWO will typically have properties depending on the RWO type (for example, measurement, transformer) and what application or usage the RWO is involved in. Properties are defined per type of RWO. In DAIS RWOs are represented by Nodes. Property instances at a node are represented by Items. An item may represent a measurement value, a control output value, or any parameter (for example, a limit value, a unit, a name, a description). A Type and properties belonging to a type represent an RWO type by DAISProperties. Nodes are hierarchically structured and the leafs are Items. This is shown in Figure 4-1. Instance data, nodes and items Meta data, data about nodes and items Item cache_value : S impleV alue cache_value_last_updated : DateTime cache_value_quality : DAIS::Quality scan_rate : uns igned long access _rights : DAIS::Acc essRights (from DAISItem) Property id : PropertyID label : string description : string canonical_data_type : S impleValueType (from DAISProperty) 0..n01 ..n+property 1Type id : ResourceID schema : ResourceID label : string description : string (f rom DAI STy pe) 0..n0.1..n .n1..n0..n0.+aggregated_types .nNode id : Resourc eID label : s tring type : ResourceID (from DAISNode) 1 0..n +type 10..nNodeItemComponent pathname : string (from DAISNode) 1 0..* +parent 10..* Figure 4-1 DAIS data access server information model The Component class inherited by the Node and Item classes models the hierarchical structure. The Node may contain any number of Components as described by the Contains role having the cardinality many (role is a UML concept, refer to [9] for an explanation). A Component is a member of one Node as described by the MemberOf role having the cardinality of 1. A Component can be both a Node and an Item through the inheritance, which means a Node can contain other Nodes or Items. An Item cannot contain any Components as it only inherits the MemberOf role and not the Contains role. Node and item names follow OPC [4] and IEC 1346-1 [10]. Each Node has a label unique among other Nodes having the same parent; that is, are MemberOf the same Node. An Item does not have an own label but uses the label from the Property. Each Item in a Node is associated with different DAISProperties so that the label is unique among other items at the same node. The labels in the path from an item or node to the root form a pathname. Labels and pathnames are explained in Figure 4-2. Root label = Ceylon pathname = Ceylon type = Station label = Cobden pathname = Cobden type = Station label = Q1 pathname = Cobden.Q1 type = Breaker label = G1 pathname = Cobden.G1 type = Generator label = P pathname = Cobden.G1.P type = Measurement A Node An Item label = ActivePower pathname = Cobden.G1.P.ActivePower value = 50 time_stamp = 2000-11-17 14.28.05 quality = Good label = Unit pathname = Cobden.G1.P.Unit value = MW time_stamp = 2000-11-17 14.28.05 quality = Good label = HighLimit pathname = Cobden.G1.P. HighLimit value = MW time_stamp = 2000-11-17 14.28.05 quality = Good Figure 4-2 Labels and pathnames A delimiter, the label delimiter, might separate the labels in a pathname. Assuming the label delimiter is a “.? An example of an item pathname for a measurement value in Figure 4-2 is Cobden.G1.P.Value where the labels are: • station; Cobden • generator; G1 • active power measurement; P • the actual measurement value property; Value Exactly how the pathname is composed from the labels is server specific and outside the scope of this specification. Items are associated with values. Typically an item value provided by a DAIS server is read from a device and transferred to one or more clients. In a distributed control system involving remote devices (as indicated in Figure 4-3) communication failures might make item values not available. To cope with communication failures item values are associated with a quality. The quality indicates the reliability of the item value. Devices usually scan item values at a certain rate and item values will be transferred to the DAIS server at this rate or some other. In the server, item values will appear as time stamped and quality coded samples. A server that keeps item values in a local cache is expected to always hold the latest sample. Other item related informations are access-rights and scan-rate. This information is shown in Figure 4-4. The cache_value is the latest sample received from a device, the cache_value_last_updated the time when the cache_value was last updated or validated, and cache_value_quality when the value was last updated or validated. For items, a DAIS server exposes the following information to clients: • the value and its data type, • the quality of the value, • the time stamp for the value, • the fastest scan rate with which the value can be expected to be updated, and • the access rights. To make access of item values efficient and avoid reading the values from devices each time a client requests item values, a DAIS server is expected to have a local cache. The mechanism for keeping the cache up to date is server specific but a client shall expect the following from the server: • Values delivered from the cache reflect the latest value considering update rate and update dead bands. Based on the agreed update rate (between a client and a server) a client can expect that the server will validate the values with devices with the agreed update rate. • The dead band is expected to be checked at each update or validation. Values that don’t transgress the deadband will not be reported. • Time stamps delivered from the cache shall reflect when the values were updated or validated with the devices according to the agreed update rate. The time stamp gives the time for the latest successful update or validation. • The quality shall reflect how successful the server has been in keeping the values updated or validated. DAIS is flexible in terms of what types and properties may exist in a server. In OPC there is a recommendation of what properties are expected to be supported by a data access server. These recommended properties are shown in Table 4-1. The column names correspond to the attributes in the Property class seen in Figure 4-4. Table 4-1 Recommended Properties label id canonical_data_ type description engineeringUnit 100 STRING_TYPE Engineering unit. description 101 STRING_TYPE Description. maxValue 102 DOUBLE_TYPE Maximum value. minValue 103 DOUBLE_TYPE Minimum value. sensorMaximum 104 DOUBLE_TYPE Maximum value from an analog input sensor. sensorMinimum 105 DOUBLE_TYPE Minimum value from an analog input sensor. closedLabel 106 STRING_TYPE Text for the closed state for a discrete status input. openLabel 107 STRING_TYPE Text for the open state for a discrete status input. itemTimeZone 108 UNSIGNED_TYPE 109-4999 Reserved by OPC. For a system having data described by a particular schema (for example, the CIM for power systems) the implementation of that schema as seen through DAIS has to be decided. Either a mapping to the recommended OPC properties can be made or the schema can be exposed as is through DAIS. This is however outside the scope of this specification. The classes and properties defined in the IEC 61970-30x (the CIM) can be mapped onto the OPC recommended properties. As the CIM is highly structured, this will create a complicated mapping. An alternative is to expose CIM as is through the DAIS. This means that the CIM classes and their properties will appear the same as seen through the DAIS as through the DAF interfaces. As the DAIS requires a hierarchical structuring of nodes, the CIM equipment hierarchy is selected as the hierarchy exposed through the DAIS. Besides the equipment hierarchy the CIM also has a number of other associations. Such associations may be made visible through the DAIS interface as properties holding ResourceIDs. The CIM has several associations between RWOs and ways to structure RWOs. The requirement from DAIS on the equipment hierarchy is that it is strictly hierarchical, else DAIS is transparent to any information model. For RWOs in the equipment hierarchy its properties simply appear as items at the nodes representing the RWOs. The DAIS supports navigating across associations as ResourceIDs can be conveyed by SimpleValues. Utility SCADA/EMS systems have a number of different applications calculating alternate measurement values. In the IEC61970 draft standard this is modeled by Measurements containing one or more MeasurementValues, as shown in Figure 4-3. Limit value Lim itSet 0.*.0..*1Measurement <> 0.*.0.+LimitSets .*1MeasurementValueSource name MeasurementV alue value <> 1.*.1..*1+MeasurementValueSource 1 Figure 4-3 Utility SCADA Measurement Modeling The Measurement and the MeasurementValue appear as Nodes and their properties as Items. In the example from Section 4.1.2, “Naming,? on page 4-3, th e Measurement again is represented by the pathname: Cobden.G1.P Moving down to MeasurementValue will add its label to the pathname so that it may look like: Cobden.G1.P.Telem If the MeasurementValue property for the value has the label Value, finally the pathname for the item will be: Cobden.16kV.G1.P.Telem.Value In a system also having a State Estimated MeasurementValue, the pathname for state estimated value might be: Cobden.16kV.G1.P.SE.Value Finally if the state estimated value is to replace the telemetered, this can be implemented picking the “best? MeasurementValue from Measurement itself shortcutting the MeasurementValue resulting in the path. Cobden.G1.P.Value The CIM classes that shall be navigable and whose data is exposed through DAIS are listed in Table 4-2. Table 4-2 CIM Classes CIM class Properties and references Measurement All MeasurementValue All. MeasurementValues are expected to appear in the hierarchical structure so that all MeasurementValue instances are visible in the browser. MeasurementUnit All LimitSet All. The Measurement to LimitSet reference has a cardinality 1..*. It is expected that one LimitSet is the current used and exposed through DAIS. Limit As the LimitSet to Limit reference has the cardinality 1..* the mapping through DAIS is expected to be a number of properties where each property corresponds to one limit value. ValueAliasSet As the ValueAliasSet to ValueToAlias reference has cardinality 1..* the mapping through DAIS is expected to be a number of properties where each property corresponds to one translation from numeric to symbolic value. Classes in the hierarchical structure above Measurement An implementation is free to expose any hierarchical structure of classes above the Measurement. Multiple and different structures are allowed using different views (for views refer to Section 3.2.2, “DAIS Server IDL,? on page 3-30). An implementation is also free to expose any properties from these classes. The table is based on the CIM version given by [11]. The IDL is divided into files. Each file is modeled as a package in UML. A file that depends on declarations made in another file needs to include it. Figure 4-4 shows how the IDL files depend on each other. DAISCommon (from Common) DAISDAIO DAISGroupEntry DAISItem DAISNode (from Common) DAISProperty DAISType (from Common) (from Common) DAISGroup DAISDASimpleIO DAISDASession DAISDANode DAISSession (from Common) DAISServer (from Server) Figure 4-4 Dependencies between data access IDL files The DAIS::DataAccess::Session object implements the data access service on a per client basis. A data access session object has a number of services provided by one singleton home object each. Each home object provides methods for manipulation of the data of the specific type they provide. Rather than exposing data as objects with interfaces it is exposed as structs or sequences of structs. The reason is that a large number of data items will become a performance bottleneck if instantiated as objects over an interface. The DAIS::Group::IHome object is the only object to expose its data as objects; that is, the DAIS::Group::Manager. Each DAIS::Group::Manager is expected to connect to one callback object implemented by the client. Each client may instantiate one or more Sessions. The Session objects have one Type and Property Home object each. The client shall expect that all Type and Property Home objects expose the same types and properties. The session object corresponds to an OPCServer object. 1 0..1 10..1 DAIS::Session (from DAISSess ion) <> status() : DAIS::SessionStatus callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() DAIS::DataAccess::Session <> group_home() : DAIS::DataAccess::Group::IHome simple_io_home : DAIS::DataAccess::SimpleIO::IHome() node_home() : DAIS::DataAccess::Node::IHome item_home() : DAIS::DataAccess::Item::IHome type_home() : DAIS::Type::IHome property_home() : DAIS::Property::IHome DAIS::ShutdownCallback (from DAISSessi on) <> 0..10..1 11 Client (fro m DAISServer) 11 0..*0..* 11 DAIS::Type::IHome (f rom DAIST ype) <> DAIS::DataAccess::IO::Callback (from DAISDAIO) <> DAIS::Property::IHome (from DAISProperty) <> 0..10..1 11 11 11 DAIS::DataAccess::Node::IHome (from DAISDANode ) <> DAIS::DataAccess::IO::ConnectionPoint (from DAISDAIO) <> 11 DAIS::DataAccess::Group::IHome (from DAISGroup) <> DAIS::DataAccess::Item::IHome (from DAI SItem) <> 11 1 0.. n 10.. DAIS::DataAccess::Group::Manager (from DAISGroup) <> 11 DAIS::DataAccess::SimpleIO::IHome (from DAISDASi mp leIO) <> Figure 4-5 DAIS data access session IDL in UML //File: DAISDASession.idl #ifndef _DAIS_DA_SESSION_IDL #define _DAIS_DA_SESSION_IDL #pragma prefix "omg.org" // Common Information #include #include #include // Data Access interface #include #include #include #include #include module DAIS { module DataAccess { interface Session : DAIS::Session { readonly attribute Group::IHome group_home; readonly attribute SimpleIO::IHome simple_io_home; readonly attribute Node::IHome node_home; readonly attribute Item::IHome item_home; readonly attribute Type::IHome type_home; readonly attribute Property::IHome };};}; #endif // _DAIS_DA_SESSION_IDL property_home; Session Session is an object implementing the data access functions. It inherits common functionality as shut down callbacks and session status from DAIS::Session. group_home A read only attribute holding a reference to a singleton Group::IHome object. node_home A read only attribute holding a reference to a singleton Node::IHome object. item_home A read only attribute holding a reference to a singleton Item::IHome object. type_home A read only attribute holding a reference to a singleton Type::IHome object. property_home A read only attribute holding a reference to a singleton Property::IHome object. The DAIS::DataAccess::Node inherits most of the functionality from DAIS::Node. The only difference is that it supports to get the tree root node. 0..*0..* 11 +parent 1 01..n0..n Node id : ResourceID label : string type : Resourc eID (from DAISNode) NodeItemComponent pathname : string (from DAISNode) 11 0..n0..n DAIS::DataAccess::Node::IHome get_root() <> DAIS::Node::Iterator max_left() next_n() reset() clone() destroy() (from DAISNode) <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() (from DAISNode) <> Figure 4-6 DAIS data access node IDL in UML //File: DAISDANode.idl#ifndef _DAIS_DANODE_IDL#define _DAIS_DANODE_IDL#pragma prefix "omg.org"#include module DAIS {module DataAccess {module Node { interface IHome : DAIS::Node::IHome{ ResourceID get_root(); }; };};}; #endif // _DAIS_DANODE_IDL IHome An object used for browsing nodes. Most functionality is inherited from the DAIS::Node::IHome interface. get_root() Get the root node of the whole tree of nodes. Parameter Description return The root node identification. Hierarchical browsing : Client:Client : DAIS::DataAccess::Node::IHome:DAIS::DataAccess::Node::IHome : DAIS::Node::Iterator:DAIS::Node::Iterator: DAIS::DataAccess::Session:DAIS::DataAccess::Sessionnode_home( ) get_root( ) find_by_parent( ) next_n( ) find_by_parent( ) Get some nodes at the root Pick one of the nodes at the root and get it's children next_n( ) Get some nodes among the children to the node picked at the root Figure 4-7 Hierarchical browsing interaction Browsing by type : Client: Client : DAIS::DataAccess::Session:DAIS::DataAccess::SessioAcess::Node::IHomeAn : DAIS::Datac:DAIS::Dataccess::Node::IHome : DAIS::Node::Iterator: DAIS::Node::Iteratornode_home( ) find_by_type( ) next_n( ) Find all nodes of a certain type in sub-tree, in this case the root get_root( ) next_n( ) Figure 4-8 Browsing by type interaction An item is a property of a node. While a node generally represents a real-world object, an item represents some characteristic of that object (for example, measurement value, control variable, or parameter related to the measurement/control process). The concept of an item in DAIS corresponds to the item in OPC. More precisely, it corresponds to the “leafs? in the OPC IOPCBrowseServerAddressSpace interface. In the Resource Description Framework (RDF) data model, the item corresponds to a combination of a subject and a predicate; that is, a resource and a property. A node may have many items, each representing a different characteristic of the same real world object. An item might represent a measured variable, a calculated variable, a control variable, or a configuration parameter. An item will typically have many values where each value corresponds to a time stamped sample (a single item value corresponds to a single statement in the RDF model). Each sample will also have its own quality. An item value is then qualified by a time stamp and a quality. An item value and its qualifications are represented by six fixed attributes: • value - the value. • time_stamp - the time when the value was last updated. • quality - the quality of the value. • canonical_data_type - the data type of the value. This actually belongs to the property (see Property) but it is mirrored at the item. • access_rights - tells if the value is read only, write only, or both read/write. The access right is common for all item values and belongs to the item. • scan_rate - the fastest rate with which the value can be expected to be updated. The scan rate is common for all item values and belongs to the item. For an information model describing this refer to Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 and Section 4.1.3, “Item Values,? on page 4-4. Each item has a universal identity given by its ItemID. The ItemID is made up of the ResourceID of a node and the PropertyID of a property. The ItemID of an item is the same in all views provided by a DAIS server. Clients may construct ItemIDs given the identities of nodes and properties. DAIS servers may be coordinated with DAF servers so that valid ItemIDs can be constructed from DAF ResoureIDs. Within each view provided by the server, an item has a label that is unique among all items belonging to the same node. Within each view, an item has a unique pathname. The pathname is a string that contains the item’s label and the pathname of its node. The pathname must be a valid URI, but apart from that the syntax of pathnames is implementation dependent. Note – In OPC the pathname is the primary way to identify items and is called the ItemID. In DAIS the ResourceID, PropertyID pair is the primary identification and so it is called the ItemID. This is a potential point of confusion. The two ItemIDs play approximately the same role in OPC and DAIS respectively, but they are not the same type. The item interfaces permit the stock of items to be browsed. Once an item is located, the group interfaces are used to deliver its values, selected by source, at successive times. In addition, the item interfaces provide the most current value for the default source. In either case the item value and qualifications are represented by the six fundamental attributes listed above. The Item IDL defines a main interface Home for browsing among hierarchically structured items (leaf nodes). The information model describing the hierarchical structure is found in Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 . DAIS::DataAccess::Item::IHome <> find() find_each() find_by_parent() find_by_type() get_pathnam es() get_ids() get_access_paths() 11 11 0..0.n.n 0..0.n.n Item cache_value : SimpleV alue cache_value_last_updated : DateTim e cache_value_quality : DAIS::Quality scan_rate : unsigned long access_rights : DAIS::AccessRights NodeItem Component (fro m DA IS Nod e) pathname : string DAIS::DataAccess::Item::Iterator <> max_left() next_n() reset() clone() destroy() Figure 4-9 DAIS data access item IDL in UML //File: DAISItem.idl #ifndef _DAIS_ITEM_IDL #define _DAIS_ITEM_IDL #pragma prefix "omg.org" #include module DAIS { module DataAccess { module Item { struct Description { ItemID id; string label; SimpleValue value; //includes the canonical_data_type Quality dais_quality; DateTime time_stamp; AccessRights access_rights; unsigned long scan_rate; }; typedef sequence< Description >Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions items ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; exception UnknownItemID {string reason;}; exception InvalidFilter {string reason;}; exception InvalidValueType {string reason;}; exception UnkownTypeID {string reason;}; exception InvalidAccessRight {string reason;}; Description find ( in ItemID item ) raises (UnknownItemID); Descriptions find_each( in ItemIDs items ) raises (UnknownItemID); Iterator find_by_parent ( in ResourceID node, in string filter_criteria, in SimpleValueType data_type_filter, in AccessRights access_rights_filter ) raises (UnknownResourceID, InvalidFilter, InvalidValueType, InvalidAccessRight); Iterator find_by_type ( in ResourceID node, in ResourceIDs type_filter, in string filter_criteria, in SimpleValueType data_type_filter, in AccessRights access_rights_filter ) raises (UnknownResourceID, InvalidFilter, InvalidValueType, UnkownTypeID, InvalidAccessRight); Strings get_pathnames ( in ItemIDs items ); ItemIDs get_ids ( in Strings pathnames ); Strings get_access_paths ( in ItemID item ) raises (UnknownItemID); };};};}; #endif // _DAIS_ITEM_IDL Description A struct describing an item. Member Description id The identification of this item. label The label (single level designation) of the item. value The current value sample for the item. The SimpleValue also contains the data type. dais_quality The current quality of the value. time_stamp The time stamp for the value sample. access_rights States if the value is read, write, or both read and write. scan_rate States the highest update rate that can be expected. Iterator Refer to Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. This interface corresponds to the OPC interface EnumString with the difference that the Iterator return the Description struct instead of a single string. IHome An object used for browsing items and corresponds to the IOPCBrowseServerAddressSpace. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. UnknownItemID An exception stating that the resource or property in the ItemID is unknown. For methods taking a sequence of item ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. InvalidFilter An exception stating the filter_criteria string is not correct. The likely reason behind this exception is an erroneously entered string. InvalidValueType An exception stating that the SimpleValueType does not exist. UnknownTypeID An exception stating one or more TypeIDs does not exist. InvalidAccessRight An exception stating that the access rights do not exist. find() For a given item browse position, return information about that item. Parameter Description item An item identification. return The item description. find_each () For a sequence of items, return information about each item. Parameter Description items A sequence of item identifications. return An iterator holding the item descriptions. find_by_parent () For a given node identification, return child items to that node. Hence to reach all items using this method repeated calls must be made for each node level. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_LEAF. Parameter Description node The parent node identification. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects only items with pathnames matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. data_type_filter Select items having the specified canonical data type. access_rights_filter Select items having the specified access rights. return An iterator holding item descriptions for items • that are child to the parent node. • matching the filter_criteria, data_type_filter, and access_rights_filter. find_by_type() For a sub-tree given by the node parameter, return all child items matching the filter criteria. This will return all items under the given sub-tree root node. This will make the items in the sub-tree to appear flattened out. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_FLAT. Parameter Description node The identification for the node defining the sub-tree. type_filter Select nodes in the sub-tree having a type matching any of the types listed in the type_filter. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects only items with pathnames matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. data_type_filter Select items having the specified canonical data type. access_rights_filter Select items having the specified access rights. return An iterator holding item descriptions for items • that are child to nodes in the sub-tree and nodes having a type matching the type_filter. • matching the filter_criteria, data_type_filter, and access_rights_filter. get_pathnames() Translate a sequence of item identifications to the corresponding sequence of pathnames. If an item fails to translate to a pathname (due to an unknown identification), the corresponding pathname is an empty string. Parameter Description items The sequence of items. return The corresponding sequence of pathnames. get_ids() Translate a sequence of pathnames to the corresponding sequence of item identifications. If a pathname fails to translate to an item identification (due to an unrecognized pathname) the corresponding item identification is NULL. get_access_paths() Get the possible communication paths how data can be retrieved for the node. An access path is expected to be human readable so that a human can pick one and feed it back to the server as the preferred path (via other interfaces). Parameter Description item An item identification. return A sequence of possible access paths for the item. Browsing Items : Client: Client : DAIS::DataAccess::Item::IHome: DAIS::DataAccess::Item::IHome : DAIS::DataAccess::Item::Iterator: DAIS::DataAccess::Item::Iterator: DAIS::DataAccess::Session: DAIS::DataAccess::Sessionnode_home( ) find_by_parent( ) next_n( ) item_home( ) find_by_parent( ) Get the items for a particular node Get some item descriptions for the particular node Get the items for another node Get some node of interest, refer to browsing of Nodes Figure 4-10 Browsing items interaction Navigate across associations find_by_parent( ) : Client:Client : DAIS::DataAccess::Item::IHome: DAIS::DataAccess::Item::IHomeataccess::Node::IHomea: DAIS::DA: DAIS::DtaAccess::Node::IHomeGet information about each item at a known node find( ) Pick an item holding a ResourceID and get the node information for that ResourceID find_by_parent( ) Get the item information for the new node Figure 4-11 Navigating across associations interaction These are definitions for transmitting item values to clients. Interfaces are defined for server side read and write operations and client side callback operations. Clients shall implement the Callback object for the server to use at transfer of data. A client may have any number of callback objects. The client shall connect each callback object to a server object implementing ConnectionPoint. The IO interfaces support three different ways to read data and two different ways to write data. Read data • Synchronous read where the data is received at return from the sync_read() method. • Asynchronous read where the data is returned at the Callback object. • Subscription where data is sent spontaneously by the server at the callback object. Write data • Synchronous write returning to the client once all the written data has reached the devices. • Asynchronous write returning when the data is received by the DAIS server. A callback on Callback is sent by the server once the written data has reached the devices. Each item value is transmitted in a struct with a timestamp and quality indication. A sequence of this struct is either sent via the callback object or directly in read or write calls. In OPC the IO interface corresponds to the OPC interfaces IOPCSyncIO, IOPCAsyncIO, and IOPCDataCallback. DAIS::DataAccess::IO::SyncIO <> sync_read() sync_write() DAIS::DataAccess::IO::ConnectionPoint <> callback() : DAIS::DataAccess::IO::Callback callback(callback : DAIS::DataAccess::IO::Callback) 11 0..0.1.1 DAIS::DataAccess::IO::Callback <> on_data_change() on_read_complete() on_write_complete() on_cancel_complete() 0..*0..* 11 Client (from DAIS Server) DAIS::DataAccess::IO::AsyncIO <> async_read() async_write() refresh() cancel() set_enable() get_enable() DAIS::DataAccess::IO::ItemState <> client_handle : ClientItemHandle time_stamp : DateTime dais_quality : DAIS::Quality value : SimpleValue Figure 4-12 DAIS data access IO IDL in UML The DAISConnectionPoint callback() methods correspond to a get or set method for the callback attribute. //File: DAISDAIO.idl#ifndef _DAIS_DAIO_IDL#define _DAIS_DAIO_IDL#pragma prefix "omg.org"#include module DAIS { module DataAccess {module IO { enum DataSource { DS_CACHE, DS_DEVICE }; struct ItemState { SimpleValue value; DateTime time_stamp; Quality dais_quality; ClientItemHandle client_handle; };typedef sequence ItemStates; struct ItemUpdate { ServerItemHandle server_handle; SimpleValue value; };typedef sequence ItemUpdates; interface SyncIO{ ItemStates sync_read ( in DataSource data_source, in ServerItemHandles server_handles, out ItemErrors errors ); ItemErrors sync_write ( in ItemUpdates updates ); }; typede f unsi gned long CancelID; int erface AsyncIO { exception NotConnected{string reason;}; exception InvalidCancelID{string reason;}; exception NotActive{string reason;}; CancelID async_read ( in ServerItemHandles server_handles, in DataSource data_source, in unsigned long transaction_id ) raises (NotConnected, NotActive); CancelID async_write ( in ItemUpdates updates, in unsigned long transaction_id ) raises (NotConnected); CancelID refresh ( in DataSource data_source, ) raises (NotConnected,NotActive); void cancel ( in CancelID cancel_id in unsigned long transaction_id ) raises (InvalidCancelID); attribute boolean enabled; }; interface Callback { void on_data_change ( in unsigned long transaction_id, in boolean all_quality_good, in ItemStates states ); void on_read_complete ( in unsigned long transaction_id, in boolean all_quality_good, in ItemStates states, in ItemErrors errors ); void on_write_complete ( in unsigned long transaction_id, in ItemErrors errors ); void on_cancel_complete ( in unsigned long transaction_id ); }; interface ConnectionPoint { attribute Callback cllbck; };};};}; #endif // _DAIS_DAIO_IDL DataSource Member Description DS_CACHE Data cached in the server is requested. DS_DEVICE Data from the device is requested. This will force a read from the device or RTU. A read from device will be made regardless of the group or item active status and no group NotActive exception will be forced. ItemState The struct is the major carrier of data conveyed over the interface. It is the “message? holding the payload. Member Description value The value itself. time_stamp The time stamp when the value was last updated. quality The quality for the value. client_handle A client side handle enabling the client to make a quick look up of the item in its internal data structures. ItemUpdate The struct carry an update for an item. Member Description server_handle A server side handle enabling the server to make a quick look up of the item in its internal data structures. value The value that shall be used in the update. SyncIO An interface for the synchronous operations. sync_read() Synchronous read of items. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. Parameter Description data_source The source from where to read the data. server_handles A sequence specifying the whole or a subset of the server side handles as defined via the DAIS::GroupEntry::Manager interface. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • INVALID_DAIS_HANDLE return A sequence of ItemStates for the items. sync_write() Synchronous write of item values to devices (not the internal server cache). The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemUpdates specifying all or a subset of the items defined for a GroupEntry::Manager. The ItemUpdate::value member is used to update the items in devices. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_INVALID_DAIS_HANDLE • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE AsyncIO An interface for asynchronous read or write operations. NotConnected An exception telling that there is no callback object connected by the client. InvalidCancelID An exception telling that the supplied cancel id number is not recognized. NotActive An exception telling that the group or all items in the group is inactive. Only issued when read from cache. async_read() Asynchronous read of items from devices. OPC may report read errors both at return from async_read() and at on_read_complete(). DAIS will report all errors at on_read_complete().. Parameter Description server_handles A sequence specifying the whole or a subset of the server side handles, as defined via the DAIS::GroupEntry::Manager interface. data_source The source from where to read the data. When reading from cache, inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous read operation. async_write() Asynchronous write of item values to devices (not the internal server cache). OPC may report write errors both at return from async_write() and at on_write_complete(). DAIS will report all errors at on_write_complete(). Parameter Description updates A sequence of ItemUpdates specifying all or a subset of the items defined for a DAIS::GroupEntry::Manager. The ItemUpdate::value member is used to update the items in devices. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous write operation. refresh() Initiate a complete asynchronous read transfer for all item entries defined via the DAIS::DataAccess::GroupEntry::Manager interface. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. The cyclic on_data_change reporting continues unaffected by a refresh call. However, items still unchanged after a refresh will not be reported in a succeeding on_data_change call. Parameter Description data_source The source from where to read the data. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_data_change call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous refresh operation. cancel() Cancel on ongoing refresh, async read, or async write operations. The server is expected to acknowledge a successfully initiated cancel operation with an on_cancel_complete() callback. Parameter Description cancel_id The server generated cancellation number for the operation to cancel. enable An attribute used to enable or disable the spontaneous on_data_change() callbacks. The enable state does not affect on data change response to refresh calls. When a group is created it is enabled by default. Callback An interface implemented by the client and used by the server to send data to the client. on_data_change() The method is called by the server when spontaneous changes occur or when the client has requested an explicit refresh. Only active items are reported in spontaneous calls. Parameter Description transaction_id If the call is in response to a refresh, the transaction number for that refresh call. If the call is autonomous due to one or more spontaneous changes, the number is zero. all_quality_good All item quality values are good. item_states A sequence of requested or spontaneously changed ItemStates. on_read_complete() The method is used by the server to report data in response to an asynchronous read. Parameter Description transaction_id The transaction number for the corresponding read. all_quality_good All item quality values are good. This requires that no errors are reported in the error parameter below. item_states A sequence of ItemStates matching the read operation. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations initially succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • ERROR_INVALID_DAIS_HANDLE on_write_complete() The method is used to report the success of an asynchronous write operation. Parameter Description transaction_id The transaction number for the corresponding write. errors A sequence reporting items for which the write failed. An empty sequence indicates all write operations initially succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_INVALID_DAIS_HANDLE • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE on_cancel_complete() The method is used to acknowledge the completion of a successfully initiated cancel call. Parameter Description transaction_id The transaction number for the corresponding cancel. ConnectionPoint An interface used by the client to connect or disconnect a client callback object at the server. callback An attribute referencing the callback object. In an implementation one get and one set method will implement the callback attribute. Due to limitation in the UML tool used to draw the diagrams, the attribute is represented by the two methods connect and disconnect. A group has a collection of group entries. Each group entry associates the group with an item. An ItemID identifies a group entry within its group. The pathname of an item may be used as an alternative to the ItemID when the group entry is created (see Section 4.2.4, “DAISItem IDL,? on page 4-15). In OPC the GroupEntry interface corresponds to the interface IOPCItemMgt. . DAIS::DataAccess::GroupEntry::Manager <> create_entries() validate_entries() remove_entries() set_active_state() set_inactive_state() set_client_handles() set_data_types() create_group_entry_iterator() 11 0..0.n.n 11 0..0.*.* GroupEntry pathname : string item : DAIS::ItemID active : boolean access_path : string client_handle : ClientItemHandle requested_data_type : SimpleValueType access_rights : AccessRights canonical_data_type : SimpleValueType DAIS::DataAccess::GroupEntry::Iterator <> max_left() next_n() reset() clone() destroy() Figure 4-13 DAIS data access group entry IDL in UML //File: DAISGroupEntry.idl #ifndef _DAIS_GROUP_ENTRY_IDL #define _DAIS_GROUP_ENTRY_IDL #pragma prefix "omg.org" #include module DAIS { module DataAccess { module GroupEntry { struct Description { ServerItemIdentification server_item_id; string access_path; ClientItemHandle client_handle; SimpleValueType requested_data_type; boolean active; }; typedef sequence Descriptions; struct DetailedDescription { ItemID item; string pathname; string access_path; ServerItemHandle server_handle; ClientItemHandle client_handle;SimpleValueType requested_data_type;SimpleValueType canonical_data_type;AccessRights access_rights;boolean active; };typedef sequence DetailedDescriptions; struct Result { ServerItemHandle server_handle; ClientItemHandle client_handle; AccessRights access_rights; SimpleValueType canonical_data_type; };typedef sequence Results; struct HandleAssociation { ServerItemHandle server_handle; ClientItemHandle client_handle; }; typedef sequenceHandleAssociations; struct DataTypeDescription { ServerItemHandle server_handle; SimpleValueType requested_data_type; }; typedef sequenceDataTypeDescriptions; interface Iterator { boolean next_n (in unsigned long n,out DetailedDescriptions entries ); void reset(); Iterator clone(); void destroy(); }; interface Manager { Results create_entries (in Descriptions entries,out ItemErrors errors ); Results validate_entries ( in Descriptions entries, out ItemErrors errors ); ItemErrors remove_entries ( in ServerItemHandles server_handles ); ItemErrors set_active_state ( in ServerItemHandles server_handles ); ItemErrors set_inactive_state ( in ServerItemHandles server_handles ); ItemErrors set_client_handles ( in HandleAssociations handle_associations ); ItemErrors set_data_types ( in DataTypeDescriptions descriptions ); Iterator create_group_entry_iterator ();};};};};#endif // _DAIS_GROUP_ENTRY_IDL Description The struct describes a group entry for an item. The client to configure new entries in a group uses it. It directly corresponds to the OPCItemDef struct. Member Description server_item_id The identification of the item. access_path The access path used by the server to connect to the device and sensor. An empty string as input tells the server to select the access path. client_handle The client provided handle to the item. requested_data_type The data type requested by the client for the value. active Tells if the item is active and data from devices is updated in the cache. DetailedDescription The struct is used to deliver group entry information to the client. In OPC this is made with the struct OPCITEMATTRIBUTES. Description is used for both these OPC structs. Member Description item The item identification by an ItemID. pathname A string concatenating the labels for all nodes in the path from the item up to the root. access_path The access path used by the server to connect to the device and sensor. An empty string as input tells the server to select the access path. server_handle Server provided handle for the item. client_handle Client provided handle for the item. requested_data_type The data type requested by the client for the value. canonical_data_type The data type the server uses internally for the value. access_rights The access rights (read, write, and read-write) active Tells if the item is active and data from devices is updated in the cache. Result The struct is used to transfer the result from a create_entries() or validate_entries() call back to a client. In OPC the corresponding struct is OPCITEMRESULT. Member Description server_handle The handle given to the client for the item. client_handle The supplied client handle for the item. access_rights The access rights (read, write, and read-write) canonical_data_type The data type the server uses internally for the value. HandleAssociation The struct is used to change the association between server handles and client handles in the set_client_handle() method. Member Description server_handle The handle given to the client for the item. client_handle The new client handle wanted by the client. DataTypeDescription The struct is used to change the data type of the value delivered in the ItemState struct. Member Description server_handle The handle given to the client for the item. requested_data_type The new data type wanted by the client. Iterator Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. The interface directly corresponds to the EnumOPCItemAttributes interface. Manager An interface for creation and browsing of group entries. The interface directly corresponds to the IOPCItemMgt interface. create_entries() Adds one or more entries to a group. Parameter Description entries Group entry descriptions for entries to be created. errors A sequence of structs reporting the items that were not entered due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_UNKNOWN_PATHNAME • ERROR_BAD_TYPE • ERROR_UNKNOWN_ACCESS_PATH return A sequence of result descriptions for the entries that were entered in the group. validate_entries() Is used to determine if an item is valid (could it be added without error). Also returns information about the item such as canonical datatype. Does not affect the group in any way. Parameter Description entries Group entry descriptions for entries to be validated. errors A sequence of structs reporting the items that could not be validated due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_UNKNOWN_PATHNAME • ERROR_BAD_TYPE • ERROR_UNKNOWN_ACCESS_PATH return A sequence of result descriptions for the entries that were validated. remove_entries() Used to remove entries from a group. Parameter Description server_handles Server handles for entries that shall be removed. return A sequence of structs reporting the items that were not recognized or could not be removed due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_active_state() Used to activate individual items in a group. Activate state means that the server acquires data from devices. Inactive state means that the server does not acquire any data. The group enable state control if acquired data shall be sent further to subscribers via on_data_change. Parameter Description server_handles Server handles for items to activate. return A sequence of structs reporting the items that were not recognized or could not be activated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_inactive_state() Used to deactivate individual items in a group. Parameter Description server_handles Server handles for items to deactivate. return A sequence of structs reporting the items that were not recognized or could not be deactivated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_client_handles() Used to change the client handles for items. Parameter Description handle_associations Change descriptions for the items where to change the client handles. return A sequence of structs reporting the items that were not recognized or could not be updated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_data_types() Used to change the requested data types for items. Parameter Description descriptions Change descriptions for the items where to change the data types. return A sequence of structs reporting the items that were not recognized or could not be updated due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_BAD_TYPE create_group_entry_iterator() Used to create a group entry iterator. Used by clients to inspect existing group entries. Parameter Description return The GroupEntry Iterator. A group is a collection of items and a connection to one or more consumers of item values. Clients create groups and their lifetime is bounded by the session to which they belong. (See Section 4.2.2, “DAISDASession IDL,? on page 4-8). The purpose of a group is to convey selected item values to a client. A callback object may be connected to a group to receive item value information (see Section 4.2.5, “DAISDAIO IDL,? on page 4-23). Items may be added and removed from a group as group entries (see Section 4.2.6, “DAISGroupEntry IDL,? on page 4-32). A group has an update rate that determines how frequently updated values for its entries are notified to its connected callback objects. A group also has other states that control its notification behavior. A group may also be initialized with a predefined set of entries. A set of entries is called a public group and is identified by a ResourceID. A client can create or remove public groups. A server may represent a public group as a node such that the ResourceID of the public group and the node are identical. This would allow clients to locate public groups by name. The DAIS:: DataAccess::Group::Manager object implements interfaces from the DAISDAIO and DAISGroupEntry IDLs. This is specified by inheritance of interfaces as seen in Figure 4-14 . A DAIS::DataAccess::Group::Manager has a state given by the DAIS::DataAccess::Group::State struct and a DAIS::DataAccess::Group::Manager object is created from the DAIS::DataAccess::Group::IHome object. In OPC the Group interface corresponds to the interfaces IOPCGroupStateMgt and IOPCPublicGroupStateMgt. DAIS::DataAccess::IO::ConnectionPoint (from DAISDAIO) <> callback() : DAIS::DataAccess::IO::Callback callback(callback : DAIS::DataAccess::IO::Callback) 11 0..10..1 DAIS::DataAccess::IO::Callback (from DAISDAIO) <> DAIS::DataAccess::IO::SyncIO (from DAISDAIO) <> sync_read() sync_write() DAIS::DataAccess::IO::AsyncIO (fromDAISDAIO) <> async_read() async_write() refresh() cancel() set_enable() get_enable() DAIS::DataAccess::GroupEntry::Manager (from DAISGrou pEntry) <> create_entries() validate_entries() remove_entries() set_active_state() set_inactive_state() set_client_handles() set_data_types() create_group_entry_iterator() DAIS::DataAccess::GroupEntry::Iterator (from DAISGroupEntry) <> 0..*0..* 11 DAIS::DataAccess::Group::Manager <> get_state() set_state() clone() clone_group_to_public() destroy() 0..n0..n 11 DAIS::DataAccess::Group::IHome <> find_public_groups() find() create_group() clone_group_from_public() remove_public_group() 11 11 DAIS::DataAccess::Group::State update_rate : unsigned long active : boolean time_bias : long percent_dead_band : double locale_id : unsigned long name : string Figure 4-14 DAIS data access group IDL in UML //File: DAISGroup.idl #ifndef _DAIS_GROUP_IDL #define _DAIS_GROUP_IDL #pragma prefix "omg.org" #include #include #include module DAIS { module DataAccess { module Group { exception DuplicateName {string reason;}; struct State { string name; unsigned long update_rate; boolean active; long time_bias; double percent_deadband; unsigned long locale_id; }; struct PublicGroupDescription { ResourceID id; State group_state; }; typedef sequencePublicGroupDescriptions; interface Manager : GroupEntry::Manager ,IO::AsyncIO ,IO::SyncIO ,IO::ConnectionPoint { State get_state (); unsigned long set_state ( in State group_state ) raises (DuplicateName); Manager clone ( in string name ) raises (DuplicateName); PublicGroupDescription clone_group_to_public ( in string name ) raises (DuplicateName); void destroy (); }; interface IHome { exception UnknownResourceID {string reason;}; PublicGroupDescriptions find_public_groups(); PublicGroupDescription find (in ResourceID public_group ) raises (UnknownResourceID); Manager create_group ( in State group_state, out unsigned long revised_update_rate ) raises (DuplicateName); Manager clone_group_from_public ( in ResourceID public_group, in string name ) raises (DuplicateName, UnknownResourceID); void remove_public_group ( in ResourceID public_group ) raises (UnknownResourceID); };};};}; #endif // _DAIS_GROUP_IDL DuplicateName An exception raised when an object is created and the name already exists. No object is created if the exception is raised. Used for session and group manager objects. State The struct contains information about the group state. Members Description name Within the session and public groups, unique name of the group. update_rate Update rate for the group in milliseconds. When used as input it specifies the fastest rate at which data changes may be sent to on_data_change() for items in this group. This also indicates the desired accuracy of cached data. This is intended only to control the behavior at the interface. How the server deals with the update rate and how often it actually polls the hardware internally is an implementation detail. Passing 0 indicates the server should use the fastest practical rate. active Indicates if the group is active and data from devices is updated in the cache. time_bias The time bias in minutes for the group. A zero value when used as input will tell the server to use the default system time bias. This bias behaves like the Bias field in the Win32 TIME_ZONE_INFORMATION structure. percent_deadband The percent change for an item value that will cause a call back for that value. This parameter only applies to items in the group that are of analog type. If a client specifies a zero deadband, the value will be reported with the update rate. locale_id The localization number for the language used when returning string values. Manager An object used to manage a group. It has a set of methods related to the group itself. It also inherits methods from interfaces for group entry management and data transfer. For group entry management refer to Section 4.2.6, “DAISGroupEntry IDL,? on page 4-32 and for data transfer refer to Section 4.2.4, “DAISItem IDL,? on page 4-15. The DAIS::DataAccess::Group::Manager interface corresponds to the IOPCGroupStateMgt interface. get_state() The method gets the group status. Parameter Description return State set_state() The method sets the group status. Parameter Description group_state The State with the updates. All members will be updated. If the name already exists, a DuplicateName exception is raised and no update is made. return The closest update rate the server is able to provide for the group. clone() Create a copy of a group. Parameter Description name The name to be given for the new group. If the name already exists, a DuplicateName exception is raised and no clone is created. return A description of the public group. clone_group_to_public () Create a public copy of a group including all items and the group state. Parameter Description name The name to be given for the new group. If the name already exists, a DuplicateName exception is raised and no public group is created. return A description of the public group. destroy() Delete the group. PublicGroupDescription A struct describing public groups. Member Description id A ResourceID identifying the public group. group_state The group state struct including the group name. IHome The factory object for groups. The corresponding OPC interface is IOPCServer. UnknownResourceID An exception telling that the ResourceID is unknown. For methods taking a sequence of resource ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find_public_groups() Find all public groups defined in the server. Member Description return A sequence of public group descriptions. find() For a given public group, return information about that group. Member Description public_group A ResourceID identifying the public group. return A public group description. create_group() Create a new initially empty group. Parameter Description group_state The State to be set for the new group. revised_update_rate The closest update rate the server is able to provide for the group. return The new group. clone_group_from_public() Create a copy from a public group having an existing set of entries and state. Parameter Description public_group The identification of the public group. name The name of the new group. return The new group. remove_public_group() Remove a public group. Parameter Description public_group The identification of the public group. return None. Group management : Client:Client : DAIS::DataAccess::Session: DAIS::DataAcce:Grup::IHome:Gss::Session : DAIS::DataAccess:o: DAIS::DataAccess:roup::IHome : DAIS::DataAccess::Group::Manager: DAIS::DataAccess::Group::Managergroup_home( ) create_group( ) create_entries( ) Do work with group manager, e.g. activate subscription destroy( ) Figure 4-15 Group management interaction Activate subscription : Client: Client : DAIS::DataAccess::Group::Manager:DAIS::DataAccess::Group::Managerss:IO::Callbacks: DAIS::DataAcce::DAIS::DataAcces::IO::Callbackcallback(DAISDACallback) refresh( ) on_data_change( ) Forced by refresh on_data_change( ) Spontaneous on_data_change( ) Spontaneous Figure 4-16 Active subscription interaction Activate a subscription silently : Client: Client : DAIS::DataAccess::Group::Manager: DAIS::DataAccess::Group::Managerss:IO::Callbacks: DAIS::DataAcce:: DAIS::DataAcces::IO::Callbackset_inactive_state( ) callback( ) set_enable( ) set_active_state( ) Disable refresh( ) on_data_change( ) set_enable( ) Enable on_data_change( ) Figure 4-17 Activate a subscription silently interaction Cancel : DAIS::DataAccess::Group::M anager:DAIS::DataAccess::Group::Manager : DAIS::DataAccess::IO::Callback: DAIS::DataAccess::IO::CallbackCancel refresh operation Cancel async_read Cancel async_write : Client: Clienton_cancel_complete( ) on_cancel_complete( ) on_cancel_complete( ) refresh( ) cancel( ) async_read( ) cancel( ) async_write( ) cancel( ) Figure 4-18 Cancellation interaction The purpose of the interface is to provide a simple read and write of data. The functionality is the same as the synchronous read and write described in Section 4.2.5, “DAISDAIO IDL,? on page 4-23 but without having to create a group. //File: DAISDASimpleIO.idl#ifndef _DAIS_DA_SIMPLE_IO_IDL#define _DAIS_DA_SIMPLE_IO_IDL#include module DAIS {module DataAccess {module SimpleIO { enum DataSource { DS_CACHE, DS_DEVICE }; struct ItemError { }; typ Error ServerItemIdentification string edef sequence err; id; reason; ItemErrors; { str uct ItemState SimpleValue DateTime Quality ServerItemIdentification value; time_stamp; dais_quality; id; }; typedef sequenceItemStates; struct ItemUpdate { ServerItemIdentification id; SimpleValue value; };typedef sequence ItemUpdates; interface IHome { ItemStates read ( in DataSource data_source, in ServerItemIdentifications ids, out ItemErrors errors ); ItemErrors write_with_qt ( in ItemStates updates ); ItemErrors write ( in ItemUpdates updates ); };};};}; #endif // _DAIS_DA_SIMPLE_IO_IDL DataSource Find all public groups defined in the server. Member Description DS_CACHE Data cached in the server is requested. DS_DEVICE Data from the device is requested. This will force a read from the device or RTU. A read from device will be made regardless of the group or item active status and no group NotActive exception will be forced. ItemError A struct for reporting of item related errors. The struct is different from the DAIS::ItemError because no handles are used to identify the item in SimpleIO. Member Description err An error code as described for DAIS::ItemError. id The identification of the item. reason An additional text explaining the error. ItemState The struct is the carrier of data conveyed over the interface. It is the “message? holding the payload. This is basically the same struct as DataAccess::IO::ItemState with the difference that instead of a handle for identification the full server identification is used. Member Description value The value itself. time_stamp The time stamp when the value was last updated. quality The quality for the value. id The identification of the value in the server. ItemUpdate The struct carries an update for an item. Member Description id The identification of the value in the server. value The value that shall be used in the update. IHome The interface for simple IO operations. read Synchronous read of items. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. Parameter Description data_source The source from where to read the data, see DataSource above. ids A sequence specifying the server identifications to read. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID return A sequence of ItemStates for the items. write_with_qt Synchronous write of item values including quality and time stamp. The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemStates specifying the updates including time stamp and quality. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE write Synchronous write of item values only. The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemUpdates specifying the update values. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE. Equipment in any industrial process is usually modeled as entities or classes in computerized systems. The class name usually reflects the type of equipment. Objects from such classes are called Real World Objects (RWOs) in this document. RWO classes have properties describing equipment characteristics (for example, size, length, geometries, material, nameplate data) as well as application specific data (for example, impedance parameters, state estimated values). Depending on the purpose of a system and the managed (industrial) process the RWOs are of different types and contain different properties. Some RWOs are common between systems and independent of industrial process like process variables; that is, measurement (state) and control variables. Other RWOs like transmission lines and breakers are specific to power transmission. RWO will typically have properties depending on the RWO type (for example, measurement, transformer) and what application or usage the RWO is involved in. Properties are defined per type of RWO. In DAIS RWOs are represented by Nodes. Property instances at a node are represented by Items. An item may represent a measurement value, a control output value, or any parameter (for example, a limit value, a unit, a name, a description). A Type and properties belonging to a type represent an RWO type by DAISProperties. Nodes are hierarchically structured and the leafs are Items. This is shown in Figure 4-1. Instance data, nodes and items Meta data, data about nodes and items Item cache_value : S impleV alue cache_value_last_updated : DateTime cache_value_quality : DAIS::Quality scan_rate : uns igned long access _rights : DAIS::Acc essRights (from DAISItem) Property id : PropertyID label : string description : string canonical_data_type : S impleValueType (from DAISProperty) 0..n01 ..n+property 1Type id : ResourceID schema : ResourceID label : string description : string (f rom DAI STy pe) 0..n0.1..n .n1..n0..n0.+aggregated_types .nNode id : Resourc eID label : s tring type : ResourceID (from DAISNode) 1 0..n +type 10..nNodeItemComponent pathname : string (from DAISNode) 1 0..* +parent 10..* Figure 4-1 DAIS data access server information model The Component class inherited by the Node and Item classes models the hierarchical structure. The Node may contain any number of Components as described by the Contains role having the cardinality many (role is a UML concept, refer to [9] for an explanation). A Component is a member of one Node as described by the MemberOf role having the cardinality of 1. A Component can be both a Node and an Item through the inheritance, which means a Node can contain other Nodes or Items. An Item cannot contain any Components as it only inherits the MemberOf role and not the Contains role. Node and item names follow OPC [4] and IEC 1346-1 [10]. Each Node has a label unique among other Nodes having the same parent; that is, are MemberOf the same Node. An Item does not have an own label but uses the label from the Property. Each Item in a Node is associated with different DAISProperties so that the label is unique among other items at the same node. The labels in the path from an item or node to the root form a pathname. Labels and pathnames are explained in Figure 4-2. Root label = Ceylon pathname = Ceylon type = Station label = Cobden pathname = Cobden type = Station label = Q1 pathname = Cobden.Q1 type = Breaker label = G1 pathname = Cobden.G1 type = Generator label = P pathname = Cobden.G1.P type = Measurement A Node An Item label = ActivePower pathname = Cobden.G1.P.ActivePower value = 50 time_stamp = 2000-11-17 14.28.05 quality = Good label = Unit pathname = Cobden.G1.P.Unit value = MW time_stamp = 2000-11-17 14.28.05 quality = Good label = HighLimit pathname = Cobden.G1.P. HighLimit value = MW time_stamp = 2000-11-17 14.28.05 quality = Good Figure 4-2 Labels and pathnames A delimiter, the label delimiter, might separate the labels in a pathname. Assuming the label delimiter is a “.? An example of an item pathname for a measurement value in Figure 4-2 is Cobden.G1.P.Value where the labels are: • station; Cobden • generator; G1 • active power measurement; P • the actual measurement value property; Value Exactly how the pathname is composed from the labels is server specific and outside the scope of this specification. Items are associated with values. Typically an item value provided by a DAIS server is read from a device and transferred to one or more clients. In a distributed control system involving remote devices (as indicated in Figure 4-3) communication failures might make item values not available. To cope with communication failures item values are associated with a quality. The quality indicates the reliability of the item value. Devices usually scan item values at a certain rate and item values will be transferred to the DAIS server at this rate or some other. In the server, item values will appear as time stamped and quality coded samples. A server that keeps item values in a local cache is expected to always hold the latest sample. Other item related informations are access-rights and scan-rate. This information is shown in Figure 4-4. The cache_value is the latest sample received from a device, the cache_value_last_updated the time when the cache_value was last updated or validated, and cache_value_quality when the value was last updated or validated. For items, a DAIS server exposes the following information to clients: • the value and its data type, • the quality of the value, • the time stamp for the value, • the fastest scan rate with which the value can be expected to be updated, and • the access rights. To make access of item values efficient and avoid reading the values from devices each time a client requests item values, a DAIS server is expected to have a local cache. The mechanism for keeping the cache up to date is server specific but a client shall expect the following from the server: • Values delivered from the cache reflect the latest value considering update rate and update dead bands. Based on the agreed update rate (between a client and a server) a client can expect that the server will validate the values with devices with the agreed update rate. • The dead band is expected to be checked at each update or validation. Values that don’t transgress the deadband will not be reported. • Time stamps delivered from the cache shall reflect when the values were updated or validated with the devices according to the agreed update rate. The time stamp gives the time for the latest successful update or validation. • The quality shall reflect how successful the server has been in keeping the values updated or validated. DAIS is flexible in terms of what types and properties may exist in a server. In OPC there is a recommendation of what properties are expected to be supported by a data access server. These recommended properties are shown in Table 4-1. The column names correspond to the attributes in the Property class seen in Figure 4-4. Table 4-1 Recommended Properties label id canonical_data_ type description engineeringUnit 100 STRING_TYPE Engineering unit. description 101 STRING_TYPE Description. maxValue 102 DOUBLE_TYPE Maximum value. minValue 103 DOUBLE_TYPE Minimum value. sensorMaximum 104 DOUBLE_TYPE Maximum value from an analog input sensor. sensorMinimum 105 DOUBLE_TYPE Minimum value from an analog input sensor. closedLabel 106 STRING_TYPE Text for the closed state for a discrete status input. openLabel 107 STRING_TYPE Text for the open state for a discrete status input. itemTimeZone 108 UNSIGNED_TYPE 109-4999 Reserved by OPC. For a system having data described by a particular schema (for example, the CIM for power systems) the implementation of that schema as seen through DAIS has to be decided. Either a mapping to the recommended OPC properties can be made or the schema can be exposed as is through DAIS. This is however outside the scope of this specification. The classes and properties defined in the IEC 61970-30x (the CIM) can be mapped onto the OPC recommended properties. As the CIM is highly structured, this will create a complicated mapping. An alternative is to expose CIM as is through the DAIS. This means that the CIM classes and their properties will appear the same as seen through the DAIS as through the DAF interfaces. As the DAIS requires a hierarchical structuring of nodes, the CIM equipment hierarchy is selected as the hierarchy exposed through the DAIS. Besides the equipment hierarchy the CIM also has a number of other associations. Such associations may be made visible through the DAIS interface as properties holding ResourceIDs. The CIM has several associations between RWOs and ways to structure RWOs. The requirement from DAIS on the equipment hierarchy is that it is strictly hierarchical, else DAIS is transparent to any information model. For RWOs in the equipment hierarchy its properties simply appear as items at the nodes representing the RWOs. The DAIS supports navigating across associations as ResourceIDs can be conveyed by SimpleValues. Utility SCADA/EMS systems have a number of different applications calculating alternate measurement values. In the IEC61970 draft standard this is modeled by Measurements containing one or more MeasurementValues, as shown in Figure 4-3. Limit value Lim itSet 0.*.0..*1Measurement <> 0.*.0.+LimitSets .*1MeasurementValueSource name MeasurementV alue value <> 1.*.1..*1+MeasurementValueSource 1 Figure 4-3 Utility SCADA Measurement Modeling The Measurement and the MeasurementValue appear as Nodes and their properties as Items. In the example from Section 4.1.2, “Naming,? on page 4-3, th e Measurement again is represented by the pathname: Cobden.G1.P Moving down to MeasurementValue will add its label to the pathname so that it may look like: Cobden.G1.P.Telem If the MeasurementValue property for the value has the label Value, finally the pathname for the item will be: Cobden.16kV.G1.P.Telem.Value In a system also having a State Estimated MeasurementValue, the pathname for state estimated value might be: Cobden.16kV.G1.P.SE.Value Finally if the state estimated value is to replace the telemetered, this can be implemented picking the “best? MeasurementValue from Measurement itself shortcutting the MeasurementValue resulting in the path. Cobden.G1.P.Value The CIM classes that shall be navigable and whose data is exposed through DAIS are listed in Table 4-2. Table 4-2 CIM Classes CIM class Properties and references Measurement All MeasurementValue All. MeasurementValues are expected to appear in the hierarchical structure so that all MeasurementValue instances are visible in the browser. MeasurementUnit All LimitSet All. The Measurement to LimitSet reference has a cardinality 1..*. It is expected that one LimitSet is the current used and exposed through DAIS. Limit As the LimitSet to Limit reference has the cardinality 1..* the mapping through DAIS is expected to be a number of properties where each property corresponds to one limit value. ValueAliasSet As the ValueAliasSet to ValueToAlias reference has cardinality 1..* the mapping through DAIS is expected to be a number of properties where each property corresponds to one translation from numeric to symbolic value. Classes in the hierarchical structure above Measurement An implementation is free to expose any hierarchical structure of classes above the Measurement. Multiple and different structures are allowed using different views (for views refer to Section 3.2.2, “DAIS Server IDL,? on page 3-30). An implementation is also free to expose any properties from these classes. The table is based on the CIM version given by [11]. In DAIS RWOs are represented by Nodes. Property instances at a node are represented by Items. An item may represent a measurement value, a control output value, or any parameter (for example, a limit value, a unit, a name, a description). A Type and properties belonging to a type represent an RWO type by DAISProperties. Nodes are hierarchically structured and the leafs are Items. This is shown in Figure 4-1. Instance data, nodes and items Meta data, data about nodes and items Item cache_value : S impleV alue cache_value_last_updated : DateTime cache_value_quality : DAIS::Quality scan_rate : uns igned long access _rights : DAIS::Acc essRights (from DAISItem) Property id : PropertyID label : string description : string canonical_data_type : S impleValueType (from DAISProperty) 0..n01 ..n+property 1Type id : ResourceID schema : ResourceID label : string description : string (f rom DAI STy pe) 0..n0.1..n .n1..n0..n0.+aggregated_types .nNode id : Resourc eID label : s tring type : ResourceID (from DAISNode) 1 0..n +type 10..nNodeItemComponent pathname : string (from DAISNode) 1 0..* +parent 10..* Figure 4-1 DAIS data access server information model The Component class inherited by the Node and Item classes models the hierarchical structure. The Node may contain any number of Components as described by the Contains role having the cardinality many (role is a UML concept, refer to [9] for an explanation). A Component is a member of one Node as described by the MemberOf role having the cardinality of 1. A Component can be both a Node and an Item through the inheritance, which means a Node can contain other Nodes or Items. An Item cannot contain any Components as it only inherits the MemberOf role and not the Contains role. Node and item names follow OPC [4] and IEC 1346-1 [10]. Each Node has a label unique among other Nodes having the same parent; that is, are MemberOf the same Node. An Item does not have an own label but uses the label from the Property. Each Item in a Node is associated with different DAISProperties so that the label is unique among other items at the same node. The labels in the path from an item or node to the root form a pathname. Labels and pathnames are explained in Figure 4-2. Root label = Ceylon pathname = Ceylon type = Station label = Cobden pathname = Cobden type = Station label = Q1 pathname = Cobden.Q1 type = Breaker label = G1 pathname = Cobden.G1 type = Generator label = P pathname = Cobden.G1.P type = Measurement A Node An Item label = ActivePower pathname = Cobden.G1.P.ActivePower value = 50 time_stamp = 2000-11-17 14.28.05 quality = Good label = Unit pathname = Cobden.G1.P.Unit value = MW time_stamp = 2000-11-17 14.28.05 quality = Good label = HighLimit pathname = Cobden.G1.P. HighLimit value = MW time_stamp = 2000-11-17 14.28.05 quality = Good Figure 4-2 Labels and pathnames A delimiter, the label delimiter, might separate the labels in a pathname. Assuming the label delimiter is a “.? An example of an item pathname for a measurement value in Figure 4-2 is Cobden.G1.P.Value where the labels are: • station; Cobden • generator; G1 • active power measurement; P • the actual measurement value property; Value Exactly how the pathname is composed from the labels is server specific and outside the scope of this specification. Items are associated with values. Typically an item value provided by a DAIS server is read from a device and transferred to one or more clients. In a distributed control system involving remote devices (as indicated in Figure 4-3) communication failures might make item values not available. To cope with communication failures item values are associated with a quality. The quality indicates the reliability of the item value. Devices usually scan item values at a certain rate and item values will be transferred to the DAIS server at this rate or some other. In the server, item values will appear as time stamped and quality coded samples. A server that keeps item values in a local cache is expected to always hold the latest sample. Other item related informations are access-rights and scan-rate. This information is shown in Figure 4-4. The cache_value is the latest sample received from a device, the cache_value_last_updated the time when the cache_value was last updated or validated, and cache_value_quality when the value was last updated or validated. For items, a DAIS server exposes the following information to clients: • the value and its data type, • the quality of the value, • the time stamp for the value, • the fastest scan rate with which the value can be expected to be updated, and • the access rights. To make access of item values efficient and avoid reading the values from devices each time a client requests item values, a DAIS server is expected to have a local cache. The mechanism for keeping the cache up to date is server specific but a client shall expect the following from the server: • Values delivered from the cache reflect the latest value considering update rate and update dead bands. Based on the agreed update rate (between a client and a server) a client can expect that the server will validate the values with devices with the agreed update rate. • The dead band is expected to be checked at each update or validation. Values that don’t transgress the deadband will not be reported. • Time stamps delivered from the cache shall reflect when the values were updated or validated with the devices according to the agreed update rate. The time stamp gives the time for the latest successful update or validation. • The quality shall reflect how successful the server has been in keeping the values updated or validated. DAIS is flexible in terms of what types and properties may exist in a server. In OPC there is a recommendation of what properties are expected to be supported by a data access server. These recommended properties are shown in Table 4-1. The column names correspond to the attributes in the Property class seen in Figure 4-4. Table 4-1 Recommended Properties label id canonical_data_ type description engineeringUnit 100 STRING_TYPE Engineering unit. description 101 STRING_TYPE Description. maxValue 102 DOUBLE_TYPE Maximum value. minValue 103 DOUBLE_TYPE Minimum value. sensorMaximum 104 DOUBLE_TYPE Maximum value from an analog input sensor. sensorMinimum 105 DOUBLE_TYPE Minimum value from an analog input sensor. closedLabel 106 STRING_TYPE Text for the closed state for a discrete status input. openLabel 107 STRING_TYPE Text for the open state for a discrete status input. itemTimeZone 108 UNSIGNED_TYPE 109-4999 Reserved by OPC. For a system having data described by a particular schema (for example, the CIM for power systems) the implementation of that schema as seen through DAIS has to be decided. Either a mapping to the recommended OPC properties can be made or the schema can be exposed as is through DAIS. This is however outside the scope of this specification. The classes and properties defined in the IEC 61970-30x (the CIM) can be mapped onto the OPC recommended properties. As the CIM is highly structured, this will create a complicated mapping. An alternative is to expose CIM as is through the DAIS. This means that the CIM classes and their properties will appear the same as seen through the DAIS as through the DAF interfaces. As the DAIS requires a hierarchical structuring of nodes, the CIM equipment hierarchy is selected as the hierarchy exposed through the DAIS. Besides the equipment hierarchy the CIM also has a number of other associations. Such associations may be made visible through the DAIS interface as properties holding ResourceIDs. The CIM has several associations between RWOs and ways to structure RWOs. The requirement from DAIS on the equipment hierarchy is that it is strictly hierarchical, else DAIS is transparent to any information model. For RWOs in the equipment hierarchy its properties simply appear as items at the nodes representing the RWOs. The DAIS supports navigating across associations as ResourceIDs can be conveyed by SimpleValues. Utility SCADA/EMS systems have a number of different applications calculating alternate measurement values. In the IEC61970 draft standard this is modeled by Measurements containing one or more MeasurementValues, as shown in Figure 4-3. Limit value Lim itSet 0.*.0..*1Measurement <> 0.*.0.+LimitSets .*1MeasurementValueSource name MeasurementV alue value <> 1.*.1..*1+MeasurementValueSource 1 Figure 4-3 Utility SCADA Measurement Modeling The Measurement and the MeasurementValue appear as Nodes and their properties as Items. In the example from Section 4.1.2, “Naming,? on page 4-3, th e Measurement again is represented by the pathname: Cobden.G1.P Moving down to MeasurementValue will add its label to the pathname so that it may look like: Cobden.G1.P.Telem If the MeasurementValue property for the value has the label Value, finally the pathname for the item will be: Cobden.16kV.G1.P.Telem.Value In a system also having a State Estimated MeasurementValue, the pathname for state estimated value might be: Cobden.16kV.G1.P.SE.Value Finally if the state estimated value is to replace the telemetered, this can be implemented picking the “best? MeasurementValue from Measurement itself shortcutting the MeasurementValue resulting in the path. Cobden.G1.P.Value The CIM classes that shall be navigable and whose data is exposed through DAIS are listed in Table 4-2. Table 4-2 CIM Classes CIM class Properties and references Measurement All MeasurementValue All. MeasurementValues are expected to appear in the hierarchical structure so that all MeasurementValue instances are visible in the browser. MeasurementUnit All LimitSet All. The Measurement to LimitSet reference has a cardinality 1..*. It is expected that one LimitSet is the current used and exposed through DAIS. Limit As the LimitSet to Limit reference has the cardinality 1..* the mapping through DAIS is expected to be a number of properties where each property corresponds to one limit value. ValueAliasSet As the ValueAliasSet to ValueToAlias reference has cardinality 1..* the mapping through DAIS is expected to be a number of properties where each property corresponds to one translation from numeric to symbolic value. Classes in the hierarchical structure above Measurement An implementation is free to expose any hierarchical structure of classes above the Measurement. Multiple and different structures are allowed using different views (for views refer to Section 3.2.2, “DAIS Server IDL,? on page 3-30). An implementation is also free to expose any properties from these classes. The table is based on the CIM version given by [11]. The IDL is divided into files. Each file is modeled as a package in UML. A file that depends on declarations made in another file needs to include it. Figure 4-4 shows how the IDL files depend on each other. DAISCommon (from Common) DAISDAIO DAISGroupEntry DAISItem DAISNode (from Common) DAISProperty DAISType (from Common) (from Common) DAISGroup DAISDASimpleIO DAISDASession DAISDANode DAISSession (from Common) DAISServer (from Server) Figure 4-4 Dependencies between data access IDL files The DAIS::DataAccess::Session object implements the data access service on a per client basis. A data access session object has a number of services provided by one singleton home object each. Each home object provides methods for manipulation of the data of the specific type they provide. Rather than exposing data as objects with interfaces it is exposed as structs or sequences of structs. The reason is that a large number of data items will become a performance bottleneck if instantiated as objects over an interface. The DAIS::Group::IHome object is the only object to expose its data as objects; that is, the DAIS::Group::Manager. Each DAIS::Group::Manager is expected to connect to one callback object implemented by the client. Each client may instantiate one or more Sessions. The Session objects have one Type and Property Home object each. The client shall expect that all Type and Property Home objects expose the same types and properties. The session object corresponds to an OPCServer object. 1 0..1 10..1 DAIS::Session (from DAISSess ion) <> status() : DAIS::SessionStatus callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() DAIS::DataAccess::Session <> group_home() : DAIS::DataAccess::Group::IHome simple_io_home : DAIS::DataAccess::SimpleIO::IHome() node_home() : DAIS::DataAccess::Node::IHome item_home() : DAIS::DataAccess::Item::IHome type_home() : DAIS::Type::IHome property_home() : DAIS::Property::IHome DAIS::ShutdownCallback (from DAISSessi on) <> 0..10..1 11 Client (fro m DAISServer) 11 0..*0..* 11 DAIS::Type::IHome (f rom DAIST ype) <> DAIS::DataAccess::IO::Callback (from DAISDAIO) <> DAIS::Property::IHome (from DAISProperty) <> 0..10..1 11 11 11 DAIS::DataAccess::Node::IHome (from DAISDANode ) <> DAIS::DataAccess::IO::ConnectionPoint (from DAISDAIO) <> 11 DAIS::DataAccess::Group::IHome (from DAISGroup) <> DAIS::DataAccess::Item::IHome (from DAI SItem) <> 11 1 0.. n 10.. DAIS::DataAccess::Group::Manager (from DAISGroup) <> 11 DAIS::DataAccess::SimpleIO::IHome (from DAISDASi mp leIO) <> Figure 4-5 DAIS data access session IDL in UML //File: DAISDASession.idl #ifndef _DAIS_DA_SESSION_IDL #define _DAIS_DA_SESSION_IDL #pragma prefix "omg.org" // Common Information #include #include #include // Data Access interface #include #include #include #include #include module DAIS { module DataAccess { interface Session : DAIS::Session { readonly attribute Group::IHome group_home; readonly attribute SimpleIO::IHome simple_io_home; readonly attribute Node::IHome node_home; readonly attribute Item::IHome item_home; readonly attribute Type::IHome type_home; readonly attribute Property::IHome };};}; #endif // _DAIS_DA_SESSION_IDL property_home; Session Session is an object implementing the data access functions. It inherits common functionality as shut down callbacks and session status from DAIS::Session. group_home A read only attribute holding a reference to a singleton Group::IHome object. node_home A read only attribute holding a reference to a singleton Node::IHome object. item_home A read only attribute holding a reference to a singleton Item::IHome object. type_home A read only attribute holding a reference to a singleton Type::IHome object. property_home A read only attribute holding a reference to a singleton Property::IHome object. The DAIS::DataAccess::Node inherits most of the functionality from DAIS::Node. The only difference is that it supports to get the tree root node. 0..*0..* 11 +parent 1 01..n0..n Node id : ResourceID label : string type : Resourc eID (from DAISNode) NodeItemComponent pathname : string (from DAISNode) 11 0..n0..n DAIS::DataAccess::Node::IHome get_root() <> DAIS::Node::Iterator max_left() next_n() reset() clone() destroy() (from DAISNode) <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() (from DAISNode) <> Figure 4-6 DAIS data access node IDL in UML //File: DAISDANode.idl#ifndef _DAIS_DANODE_IDL#define _DAIS_DANODE_IDL#pragma prefix "omg.org"#include module DAIS {module DataAccess {module Node { interface IHome : DAIS::Node::IHome{ ResourceID get_root(); }; };};}; #endif // _DAIS_DANODE_IDL IHome An object used for browsing nodes. Most functionality is inherited from the DAIS::Node::IHome interface. get_root() Get the root node of the whole tree of nodes. Parameter Description return The root node identification. Hierarchical browsing : Client:Client : DAIS::DataAccess::Node::IHome:DAIS::DataAccess::Node::IHome : DAIS::Node::Iterator:DAIS::Node::Iterator: DAIS::DataAccess::Session:DAIS::DataAccess::Sessionnode_home( ) get_root( ) find_by_parent( ) next_n( ) find_by_parent( ) Get some nodes at the root Pick one of the nodes at the root and get it's children next_n( ) Get some nodes among the children to the node picked at the root Figure 4-7 Hierarchical browsing interaction Browsing by type : Client: Client : DAIS::DataAccess::Session:DAIS::DataAccess::SessioAcess::Node::IHomeAn : DAIS::Datac:DAIS::Dataccess::Node::IHome : DAIS::Node::Iterator: DAIS::Node::Iteratornode_home( ) find_by_type( ) next_n( ) Find all nodes of a certain type in sub-tree, in this case the root get_root( ) next_n( ) Figure 4-8 Browsing by type interaction An item is a property of a node. While a node generally represents a real-world object, an item represents some characteristic of that object (for example, measurement value, control variable, or parameter related to the measurement/control process). The concept of an item in DAIS corresponds to the item in OPC. More precisely, it corresponds to the “leafs? in the OPC IOPCBrowseServerAddressSpace interface. In the Resource Description Framework (RDF) data model, the item corresponds to a combination of a subject and a predicate; that is, a resource and a property. A node may have many items, each representing a different characteristic of the same real world object. An item might represent a measured variable, a calculated variable, a control variable, or a configuration parameter. An item will typically have many values where each value corresponds to a time stamped sample (a single item value corresponds to a single statement in the RDF model). Each sample will also have its own quality. An item value is then qualified by a time stamp and a quality. An item value and its qualifications are represented by six fixed attributes: • value - the value. • time_stamp - the time when the value was last updated. • quality - the quality of the value. • canonical_data_type - the data type of the value. This actually belongs to the property (see Property) but it is mirrored at the item. • access_rights - tells if the value is read only, write only, or both read/write. The access right is common for all item values and belongs to the item. • scan_rate - the fastest rate with which the value can be expected to be updated. The scan rate is common for all item values and belongs to the item. For an information model describing this refer to Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 and Section 4.1.3, “Item Values,? on page 4-4. Each item has a universal identity given by its ItemID. The ItemID is made up of the ResourceID of a node and the PropertyID of a property. The ItemID of an item is the same in all views provided by a DAIS server. Clients may construct ItemIDs given the identities of nodes and properties. DAIS servers may be coordinated with DAF servers so that valid ItemIDs can be constructed from DAF ResoureIDs. Within each view provided by the server, an item has a label that is unique among all items belonging to the same node. Within each view, an item has a unique pathname. The pathname is a string that contains the item’s label and the pathname of its node. The pathname must be a valid URI, but apart from that the syntax of pathnames is implementation dependent. Note – In OPC the pathname is the primary way to identify items and is called the ItemID. In DAIS the ResourceID, PropertyID pair is the primary identification and so it is called the ItemID. This is a potential point of confusion. The two ItemIDs play approximately the same role in OPC and DAIS respectively, but they are not the same type. The item interfaces permit the stock of items to be browsed. Once an item is located, the group interfaces are used to deliver its values, selected by source, at successive times. In addition, the item interfaces provide the most current value for the default source. In either case the item value and qualifications are represented by the six fundamental attributes listed above. The Item IDL defines a main interface Home for browsing among hierarchically structured items (leaf nodes). The information model describing the hierarchical structure is found in Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 . DAIS::DataAccess::Item::IHome <> find() find_each() find_by_parent() find_by_type() get_pathnam es() get_ids() get_access_paths() 11 11 0..0.n.n 0..0.n.n Item cache_value : SimpleV alue cache_value_last_updated : DateTim e cache_value_quality : DAIS::Quality scan_rate : unsigned long access_rights : DAIS::AccessRights NodeItem Component (fro m DA IS Nod e) pathname : string DAIS::DataAccess::Item::Iterator <> max_left() next_n() reset() clone() destroy() Figure 4-9 DAIS data access item IDL in UML //File: DAISItem.idl #ifndef _DAIS_ITEM_IDL #define _DAIS_ITEM_IDL #pragma prefix "omg.org" #include module DAIS { module DataAccess { module Item { struct Description { ItemID id; string label; SimpleValue value; //includes the canonical_data_type Quality dais_quality; DateTime time_stamp; AccessRights access_rights; unsigned long scan_rate; }; typedef sequence< Description >Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions items ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; exception UnknownItemID {string reason;}; exception InvalidFilter {string reason;}; exception InvalidValueType {string reason;}; exception UnkownTypeID {string reason;}; exception InvalidAccessRight {string reason;}; Description find ( in ItemID item ) raises (UnknownItemID); Descriptions find_each( in ItemIDs items ) raises (UnknownItemID); Iterator find_by_parent ( in ResourceID node, in string filter_criteria, in SimpleValueType data_type_filter, in AccessRights access_rights_filter ) raises (UnknownResourceID, InvalidFilter, InvalidValueType, InvalidAccessRight); Iterator find_by_type ( in ResourceID node, in ResourceIDs type_filter, in string filter_criteria, in SimpleValueType data_type_filter, in AccessRights access_rights_filter ) raises (UnknownResourceID, InvalidFilter, InvalidValueType, UnkownTypeID, InvalidAccessRight); Strings get_pathnames ( in ItemIDs items ); ItemIDs get_ids ( in Strings pathnames ); Strings get_access_paths ( in ItemID item ) raises (UnknownItemID); };};};}; #endif // _DAIS_ITEM_IDL Description A struct describing an item. Member Description id The identification of this item. label The label (single level designation) of the item. value The current value sample for the item. The SimpleValue also contains the data type. dais_quality The current quality of the value. time_stamp The time stamp for the value sample. access_rights States if the value is read, write, or both read and write. scan_rate States the highest update rate that can be expected. Iterator Refer to Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. This interface corresponds to the OPC interface EnumString with the difference that the Iterator return the Description struct instead of a single string. IHome An object used for browsing items and corresponds to the IOPCBrowseServerAddressSpace. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. UnknownItemID An exception stating that the resource or property in the ItemID is unknown. For methods taking a sequence of item ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. InvalidFilter An exception stating the filter_criteria string is not correct. The likely reason behind this exception is an erroneously entered string. InvalidValueType An exception stating that the SimpleValueType does not exist. UnknownTypeID An exception stating one or more TypeIDs does not exist. InvalidAccessRight An exception stating that the access rights do not exist. find() For a given item browse position, return information about that item. Parameter Description item An item identification. return The item description. find_each () For a sequence of items, return information about each item. Parameter Description items A sequence of item identifications. return An iterator holding the item descriptions. find_by_parent () For a given node identification, return child items to that node. Hence to reach all items using this method repeated calls must be made for each node level. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_LEAF. Parameter Description node The parent node identification. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects only items with pathnames matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. data_type_filter Select items having the specified canonical data type. access_rights_filter Select items having the specified access rights. return An iterator holding item descriptions for items • that are child to the parent node. • matching the filter_criteria, data_type_filter, and access_rights_filter. find_by_type() For a sub-tree given by the node parameter, return all child items matching the filter criteria. This will return all items under the given sub-tree root node. This will make the items in the sub-tree to appear flattened out. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_FLAT. Parameter Description node The identification for the node defining the sub-tree. type_filter Select nodes in the sub-tree having a type matching any of the types listed in the type_filter. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects only items with pathnames matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. data_type_filter Select items having the specified canonical data type. access_rights_filter Select items having the specified access rights. return An iterator holding item descriptions for items • that are child to nodes in the sub-tree and nodes having a type matching the type_filter. • matching the filter_criteria, data_type_filter, and access_rights_filter. get_pathnames() Translate a sequence of item identifications to the corresponding sequence of pathnames. If an item fails to translate to a pathname (due to an unknown identification), the corresponding pathname is an empty string. Parameter Description items The sequence of items. return The corresponding sequence of pathnames. get_ids() Translate a sequence of pathnames to the corresponding sequence of item identifications. If a pathname fails to translate to an item identification (due to an unrecognized pathname) the corresponding item identification is NULL. get_access_paths() Get the possible communication paths how data can be retrieved for the node. An access path is expected to be human readable so that a human can pick one and feed it back to the server as the preferred path (via other interfaces). Parameter Description item An item identification. return A sequence of possible access paths for the item. Browsing Items : Client: Client : DAIS::DataAccess::Item::IHome: DAIS::DataAccess::Item::IHome : DAIS::DataAccess::Item::Iterator: DAIS::DataAccess::Item::Iterator: DAIS::DataAccess::Session: DAIS::DataAccess::Sessionnode_home( ) find_by_parent( ) next_n( ) item_home( ) find_by_parent( ) Get the items for a particular node Get some item descriptions for the particular node Get the items for another node Get some node of interest, refer to browsing of Nodes Figure 4-10 Browsing items interaction Navigate across associations find_by_parent( ) : Client:Client : DAIS::DataAccess::Item::IHome: DAIS::DataAccess::Item::IHomeataccess::Node::IHomea: DAIS::DA: DAIS::DtaAccess::Node::IHomeGet information about each item at a known node find( ) Pick an item holding a ResourceID and get the node information for that ResourceID find_by_parent( ) Get the item information for the new node Figure 4-11 Navigating across associations interaction These are definitions for transmitting item values to clients. Interfaces are defined for server side read and write operations and client side callback operations. Clients shall implement the Callback object for the server to use at transfer of data. A client may have any number of callback objects. The client shall connect each callback object to a server object implementing ConnectionPoint. The IO interfaces support three different ways to read data and two different ways to write data. Read data • Synchronous read where the data is received at return from the sync_read() method. • Asynchronous read where the data is returned at the Callback object. • Subscription where data is sent spontaneously by the server at the callback object. Write data • Synchronous write returning to the client once all the written data has reached the devices. • Asynchronous write returning when the data is received by the DAIS server. A callback on Callback is sent by the server once the written data has reached the devices. Each item value is transmitted in a struct with a timestamp and quality indication. A sequence of this struct is either sent via the callback object or directly in read or write calls. In OPC the IO interface corresponds to the OPC interfaces IOPCSyncIO, IOPCAsyncIO, and IOPCDataCallback. DAIS::DataAccess::IO::SyncIO <> sync_read() sync_write() DAIS::DataAccess::IO::ConnectionPoint <> callback() : DAIS::DataAccess::IO::Callback callback(callback : DAIS::DataAccess::IO::Callback) 11 0..0.1.1 DAIS::DataAccess::IO::Callback <> on_data_change() on_read_complete() on_write_complete() on_cancel_complete() 0..*0..* 11 Client (from DAIS Server) DAIS::DataAccess::IO::AsyncIO <> async_read() async_write() refresh() cancel() set_enable() get_enable() DAIS::DataAccess::IO::ItemState <> client_handle : ClientItemHandle time_stamp : DateTime dais_quality : DAIS::Quality value : SimpleValue Figure 4-12 DAIS data access IO IDL in UML The DAISConnectionPoint callback() methods correspond to a get or set method for the callback attribute. //File: DAISDAIO.idl#ifndef _DAIS_DAIO_IDL#define _DAIS_DAIO_IDL#pragma prefix "omg.org"#include module DAIS { module DataAccess {module IO { enum DataSource { DS_CACHE, DS_DEVICE }; struct ItemState { SimpleValue value; DateTime time_stamp; Quality dais_quality; ClientItemHandle client_handle; };typedef sequence ItemStates; struct ItemUpdate { ServerItemHandle server_handle; SimpleValue value; };typedef sequence ItemUpdates; interface SyncIO{ ItemStates sync_read ( in DataSource data_source, in ServerItemHandles server_handles, out ItemErrors errors ); ItemErrors sync_write ( in ItemUpdates updates ); }; typede f unsi gned long CancelID; int erface AsyncIO { exception NotConnected{string reason;}; exception InvalidCancelID{string reason;}; exception NotActive{string reason;}; CancelID async_read ( in ServerItemHandles server_handles, in DataSource data_source, in unsigned long transaction_id ) raises (NotConnected, NotActive); CancelID async_write ( in ItemUpdates updates, in unsigned long transaction_id ) raises (NotConnected); CancelID refresh ( in DataSource data_source, ) raises (NotConnected,NotActive); void cancel ( in CancelID cancel_id in unsigned long transaction_id ) raises (InvalidCancelID); attribute boolean enabled; }; interface Callback { void on_data_change ( in unsigned long transaction_id, in boolean all_quality_good, in ItemStates states ); void on_read_complete ( in unsigned long transaction_id, in boolean all_quality_good, in ItemStates states, in ItemErrors errors ); void on_write_complete ( in unsigned long transaction_id, in ItemErrors errors ); void on_cancel_complete ( in unsigned long transaction_id ); }; interface ConnectionPoint { attribute Callback cllbck; };};};}; #endif // _DAIS_DAIO_IDL DataSource Member Description DS_CACHE Data cached in the server is requested. DS_DEVICE Data from the device is requested. This will force a read from the device or RTU. A read from device will be made regardless of the group or item active status and no group NotActive exception will be forced. ItemState The struct is the major carrier of data conveyed over the interface. It is the “message? holding the payload. Member Description value The value itself. time_stamp The time stamp when the value was last updated. quality The quality for the value. client_handle A client side handle enabling the client to make a quick look up of the item in its internal data structures. ItemUpdate The struct carry an update for an item. Member Description server_handle A server side handle enabling the server to make a quick look up of the item in its internal data structures. value The value that shall be used in the update. SyncIO An interface for the synchronous operations. sync_read() Synchronous read of items. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. Parameter Description data_source The source from where to read the data. server_handles A sequence specifying the whole or a subset of the server side handles as defined via the DAIS::GroupEntry::Manager interface. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • INVALID_DAIS_HANDLE return A sequence of ItemStates for the items. sync_write() Synchronous write of item values to devices (not the internal server cache). The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemUpdates specifying all or a subset of the items defined for a GroupEntry::Manager. The ItemUpdate::value member is used to update the items in devices. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_INVALID_DAIS_HANDLE • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE AsyncIO An interface for asynchronous read or write operations. NotConnected An exception telling that there is no callback object connected by the client. InvalidCancelID An exception telling that the supplied cancel id number is not recognized. NotActive An exception telling that the group or all items in the group is inactive. Only issued when read from cache. async_read() Asynchronous read of items from devices. OPC may report read errors both at return from async_read() and at on_read_complete(). DAIS will report all errors at on_read_complete().. Parameter Description server_handles A sequence specifying the whole or a subset of the server side handles, as defined via the DAIS::GroupEntry::Manager interface. data_source The source from where to read the data. When reading from cache, inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous read operation. async_write() Asynchronous write of item values to devices (not the internal server cache). OPC may report write errors both at return from async_write() and at on_write_complete(). DAIS will report all errors at on_write_complete(). Parameter Description updates A sequence of ItemUpdates specifying all or a subset of the items defined for a DAIS::GroupEntry::Manager. The ItemUpdate::value member is used to update the items in devices. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous write operation. refresh() Initiate a complete asynchronous read transfer for all item entries defined via the DAIS::DataAccess::GroupEntry::Manager interface. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. The cyclic on_data_change reporting continues unaffected by a refresh call. However, items still unchanged after a refresh will not be reported in a succeeding on_data_change call. Parameter Description data_source The source from where to read the data. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_data_change call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous refresh operation. cancel() Cancel on ongoing refresh, async read, or async write operations. The server is expected to acknowledge a successfully initiated cancel operation with an on_cancel_complete() callback. Parameter Description cancel_id The server generated cancellation number for the operation to cancel. enable An attribute used to enable or disable the spontaneous on_data_change() callbacks. The enable state does not affect on data change response to refresh calls. When a group is created it is enabled by default. Callback An interface implemented by the client and used by the server to send data to the client. on_data_change() The method is called by the server when spontaneous changes occur or when the client has requested an explicit refresh. Only active items are reported in spontaneous calls. Parameter Description transaction_id If the call is in response to a refresh, the transaction number for that refresh call. If the call is autonomous due to one or more spontaneous changes, the number is zero. all_quality_good All item quality values are good. item_states A sequence of requested or spontaneously changed ItemStates. on_read_complete() The method is used by the server to report data in response to an asynchronous read. Parameter Description transaction_id The transaction number for the corresponding read. all_quality_good All item quality values are good. This requires that no errors are reported in the error parameter below. item_states A sequence of ItemStates matching the read operation. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations initially succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • ERROR_INVALID_DAIS_HANDLE on_write_complete() The method is used to report the success of an asynchronous write operation. Parameter Description transaction_id The transaction number for the corresponding write. errors A sequence reporting items for which the write failed. An empty sequence indicates all write operations initially succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_INVALID_DAIS_HANDLE • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE on_cancel_complete() The method is used to acknowledge the completion of a successfully initiated cancel call. Parameter Description transaction_id The transaction number for the corresponding cancel. ConnectionPoint An interface used by the client to connect or disconnect a client callback object at the server. callback An attribute referencing the callback object. In an implementation one get and one set method will implement the callback attribute. Due to limitation in the UML tool used to draw the diagrams, the attribute is represented by the two methods connect and disconnect. A group has a collection of group entries. Each group entry associates the group with an item. An ItemID identifies a group entry within its group. The pathname of an item may be used as an alternative to the ItemID when the group entry is created (see Section 4.2.4, “DAISItem IDL,? on page 4-15). In OPC the GroupEntry interface corresponds to the interface IOPCItemMgt. . DAIS::DataAccess::GroupEntry::Manager <> create_entries() validate_entries() remove_entries() set_active_state() set_inactive_state() set_client_handles() set_data_types() create_group_entry_iterator() 11 0..0.n.n 11 0..0.*.* GroupEntry pathname : string item : DAIS::ItemID active : boolean access_path : string client_handle : ClientItemHandle requested_data_type : SimpleValueType access_rights : AccessRights canonical_data_type : SimpleValueType DAIS::DataAccess::GroupEntry::Iterator <> max_left() next_n() reset() clone() destroy() Figure 4-13 DAIS data access group entry IDL in UML //File: DAISGroupEntry.idl #ifndef _DAIS_GROUP_ENTRY_IDL #define _DAIS_GROUP_ENTRY_IDL #pragma prefix "omg.org" #include module DAIS { module DataAccess { module GroupEntry { struct Description { ServerItemIdentification server_item_id; string access_path; ClientItemHandle client_handle; SimpleValueType requested_data_type; boolean active; }; typedef sequence Descriptions; struct DetailedDescription { ItemID item; string pathname; string access_path; ServerItemHandle server_handle; ClientItemHandle client_handle;SimpleValueType requested_data_type;SimpleValueType canonical_data_type;AccessRights access_rights;boolean active; };typedef sequence DetailedDescriptions; struct Result { ServerItemHandle server_handle; ClientItemHandle client_handle; AccessRights access_rights; SimpleValueType canonical_data_type; };typedef sequence Results; struct HandleAssociation { ServerItemHandle server_handle; ClientItemHandle client_handle; }; typedef sequenceHandleAssociations; struct DataTypeDescription { ServerItemHandle server_handle; SimpleValueType requested_data_type; }; typedef sequenceDataTypeDescriptions; interface Iterator { boolean next_n (in unsigned long n,out DetailedDescriptions entries ); void reset(); Iterator clone(); void destroy(); }; interface Manager { Results create_entries (in Descriptions entries,out ItemErrors errors ); Results validate_entries ( in Descriptions entries, out ItemErrors errors ); ItemErrors remove_entries ( in ServerItemHandles server_handles ); ItemErrors set_active_state ( in ServerItemHandles server_handles ); ItemErrors set_inactive_state ( in ServerItemHandles server_handles ); ItemErrors set_client_handles ( in HandleAssociations handle_associations ); ItemErrors set_data_types ( in DataTypeDescriptions descriptions ); Iterator create_group_entry_iterator ();};};};};#endif // _DAIS_GROUP_ENTRY_IDL Description The struct describes a group entry for an item. The client to configure new entries in a group uses it. It directly corresponds to the OPCItemDef struct. Member Description server_item_id The identification of the item. access_path The access path used by the server to connect to the device and sensor. An empty string as input tells the server to select the access path. client_handle The client provided handle to the item. requested_data_type The data type requested by the client for the value. active Tells if the item is active and data from devices is updated in the cache. DetailedDescription The struct is used to deliver group entry information to the client. In OPC this is made with the struct OPCITEMATTRIBUTES. Description is used for both these OPC structs. Member Description item The item identification by an ItemID. pathname A string concatenating the labels for all nodes in the path from the item up to the root. access_path The access path used by the server to connect to the device and sensor. An empty string as input tells the server to select the access path. server_handle Server provided handle for the item. client_handle Client provided handle for the item. requested_data_type The data type requested by the client for the value. canonical_data_type The data type the server uses internally for the value. access_rights The access rights (read, write, and read-write) active Tells if the item is active and data from devices is updated in the cache. Result The struct is used to transfer the result from a create_entries() or validate_entries() call back to a client. In OPC the corresponding struct is OPCITEMRESULT. Member Description server_handle The handle given to the client for the item. client_handle The supplied client handle for the item. access_rights The access rights (read, write, and read-write) canonical_data_type The data type the server uses internally for the value. HandleAssociation The struct is used to change the association between server handles and client handles in the set_client_handle() method. Member Description server_handle The handle given to the client for the item. client_handle The new client handle wanted by the client. DataTypeDescription The struct is used to change the data type of the value delivered in the ItemState struct. Member Description server_handle The handle given to the client for the item. requested_data_type The new data type wanted by the client. Iterator Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. The interface directly corresponds to the EnumOPCItemAttributes interface. Manager An interface for creation and browsing of group entries. The interface directly corresponds to the IOPCItemMgt interface. create_entries() Adds one or more entries to a group. Parameter Description entries Group entry descriptions for entries to be created. errors A sequence of structs reporting the items that were not entered due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_UNKNOWN_PATHNAME • ERROR_BAD_TYPE • ERROR_UNKNOWN_ACCESS_PATH return A sequence of result descriptions for the entries that were entered in the group. validate_entries() Is used to determine if an item is valid (could it be added without error). Also returns information about the item such as canonical datatype. Does not affect the group in any way. Parameter Description entries Group entry descriptions for entries to be validated. errors A sequence of structs reporting the items that could not be validated due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_UNKNOWN_PATHNAME • ERROR_BAD_TYPE • ERROR_UNKNOWN_ACCESS_PATH return A sequence of result descriptions for the entries that were validated. remove_entries() Used to remove entries from a group. Parameter Description server_handles Server handles for entries that shall be removed. return A sequence of structs reporting the items that were not recognized or could not be removed due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_active_state() Used to activate individual items in a group. Activate state means that the server acquires data from devices. Inactive state means that the server does not acquire any data. The group enable state control if acquired data shall be sent further to subscribers via on_data_change. Parameter Description server_handles Server handles for items to activate. return A sequence of structs reporting the items that were not recognized or could not be activated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_inactive_state() Used to deactivate individual items in a group. Parameter Description server_handles Server handles for items to deactivate. return A sequence of structs reporting the items that were not recognized or could not be deactivated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_client_handles() Used to change the client handles for items. Parameter Description handle_associations Change descriptions for the items where to change the client handles. return A sequence of structs reporting the items that were not recognized or could not be updated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_data_types() Used to change the requested data types for items. Parameter Description descriptions Change descriptions for the items where to change the data types. return A sequence of structs reporting the items that were not recognized or could not be updated due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_BAD_TYPE create_group_entry_iterator() Used to create a group entry iterator. Used by clients to inspect existing group entries. Parameter Description return The GroupEntry Iterator. A group is a collection of items and a connection to one or more consumers of item values. Clients create groups and their lifetime is bounded by the session to which they belong. (See Section 4.2.2, “DAISDASession IDL,? on page 4-8). The purpose of a group is to convey selected item values to a client. A callback object may be connected to a group to receive item value information (see Section 4.2.5, “DAISDAIO IDL,? on page 4-23). Items may be added and removed from a group as group entries (see Section 4.2.6, “DAISGroupEntry IDL,? on page 4-32). A group has an update rate that determines how frequently updated values for its entries are notified to its connected callback objects. A group also has other states that control its notification behavior. A group may also be initialized with a predefined set of entries. A set of entries is called a public group and is identified by a ResourceID. A client can create or remove public groups. A server may represent a public group as a node such that the ResourceID of the public group and the node are identical. This would allow clients to locate public groups by name. The DAIS:: DataAccess::Group::Manager object implements interfaces from the DAISDAIO and DAISGroupEntry IDLs. This is specified by inheritance of interfaces as seen in Figure 4-14 . A DAIS::DataAccess::Group::Manager has a state given by the DAIS::DataAccess::Group::State struct and a DAIS::DataAccess::Group::Manager object is created from the DAIS::DataAccess::Group::IHome object. In OPC the Group interface corresponds to the interfaces IOPCGroupStateMgt and IOPCPublicGroupStateMgt. DAIS::DataAccess::IO::ConnectionPoint (from DAISDAIO) <> callback() : DAIS::DataAccess::IO::Callback callback(callback : DAIS::DataAccess::IO::Callback) 11 0..10..1 DAIS::DataAccess::IO::Callback (from DAISDAIO) <> DAIS::DataAccess::IO::SyncIO (from DAISDAIO) <> sync_read() sync_write() DAIS::DataAccess::IO::AsyncIO (fromDAISDAIO) <> async_read() async_write() refresh() cancel() set_enable() get_enable() DAIS::DataAccess::GroupEntry::Manager (from DAISGrou pEntry) <> create_entries() validate_entries() remove_entries() set_active_state() set_inactive_state() set_client_handles() set_data_types() create_group_entry_iterator() DAIS::DataAccess::GroupEntry::Iterator (from DAISGroupEntry) <> 0..*0..* 11 DAIS::DataAccess::Group::Manager <> get_state() set_state() clone() clone_group_to_public() destroy() 0..n0..n 11 DAIS::DataAccess::Group::IHome <> find_public_groups() find() create_group() clone_group_from_public() remove_public_group() 11 11 DAIS::DataAccess::Group::State update_rate : unsigned long active : boolean time_bias : long percent_dead_band : double locale_id : unsigned long name : string Figure 4-14 DAIS data access group IDL in UML //File: DAISGroup.idl #ifndef _DAIS_GROUP_IDL #define _DAIS_GROUP_IDL #pragma prefix "omg.org" #include #include #include module DAIS { module DataAccess { module Group { exception DuplicateName {string reason;}; struct State { string name; unsigned long update_rate; boolean active; long time_bias; double percent_deadband; unsigned long locale_id; }; struct PublicGroupDescription { ResourceID id; State group_state; }; typedef sequencePublicGroupDescriptions; interface Manager : GroupEntry::Manager ,IO::AsyncIO ,IO::SyncIO ,IO::ConnectionPoint { State get_state (); unsigned long set_state ( in State group_state ) raises (DuplicateName); Manager clone ( in string name ) raises (DuplicateName); PublicGroupDescription clone_group_to_public ( in string name ) raises (DuplicateName); void destroy (); }; interface IHome { exception UnknownResourceID {string reason;}; PublicGroupDescriptions find_public_groups(); PublicGroupDescription find (in ResourceID public_group ) raises (UnknownResourceID); Manager create_group ( in State group_state, out unsigned long revised_update_rate ) raises (DuplicateName); Manager clone_group_from_public ( in ResourceID public_group, in string name ) raises (DuplicateName, UnknownResourceID); void remove_public_group ( in ResourceID public_group ) raises (UnknownResourceID); };};};}; #endif // _DAIS_GROUP_IDL DuplicateName An exception raised when an object is created and the name already exists. No object is created if the exception is raised. Used for session and group manager objects. State The struct contains information about the group state. Members Description name Within the session and public groups, unique name of the group. update_rate Update rate for the group in milliseconds. When used as input it specifies the fastest rate at which data changes may be sent to on_data_change() for items in this group. This also indicates the desired accuracy of cached data. This is intended only to control the behavior at the interface. How the server deals with the update rate and how often it actually polls the hardware internally is an implementation detail. Passing 0 indicates the server should use the fastest practical rate. active Indicates if the group is active and data from devices is updated in the cache. time_bias The time bias in minutes for the group. A zero value when used as input will tell the server to use the default system time bias. This bias behaves like the Bias field in the Win32 TIME_ZONE_INFORMATION structure. percent_deadband The percent change for an item value that will cause a call back for that value. This parameter only applies to items in the group that are of analog type. If a client specifies a zero deadband, the value will be reported with the update rate. locale_id The localization number for the language used when returning string values. Manager An object used to manage a group. It has a set of methods related to the group itself. It also inherits methods from interfaces for group entry management and data transfer. For group entry management refer to Section 4.2.6, “DAISGroupEntry IDL,? on page 4-32 and for data transfer refer to Section 4.2.4, “DAISItem IDL,? on page 4-15. The DAIS::DataAccess::Group::Manager interface corresponds to the IOPCGroupStateMgt interface. get_state() The method gets the group status. Parameter Description return State set_state() The method sets the group status. Parameter Description group_state The State with the updates. All members will be updated. If the name already exists, a DuplicateName exception is raised and no update is made. return The closest update rate the server is able to provide for the group. clone() Create a copy of a group. Parameter Description name The name to be given for the new group. If the name already exists, a DuplicateName exception is raised and no clone is created. return A description of the public group. clone_group_to_public () Create a public copy of a group including all items and the group state. Parameter Description name The name to be given for the new group. If the name already exists, a DuplicateName exception is raised and no public group is created. return A description of the public group. destroy() Delete the group. PublicGroupDescription A struct describing public groups. Member Description id A ResourceID identifying the public group. group_state The group state struct including the group name. IHome The factory object for groups. The corresponding OPC interface is IOPCServer. UnknownResourceID An exception telling that the ResourceID is unknown. For methods taking a sequence of resource ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find_public_groups() Find all public groups defined in the server. Member Description return A sequence of public group descriptions. find() For a given public group, return information about that group. Member Description public_group A ResourceID identifying the public group. return A public group description. create_group() Create a new initially empty group. Parameter Description group_state The State to be set for the new group. revised_update_rate The closest update rate the server is able to provide for the group. return The new group. clone_group_from_public() Create a copy from a public group having an existing set of entries and state. Parameter Description public_group The identification of the public group. name The name of the new group. return The new group. remove_public_group() Remove a public group. Parameter Description public_group The identification of the public group. return None. Group management : Client:Client : DAIS::DataAccess::Session: DAIS::DataAcce:Grup::IHome:Gss::Session : DAIS::DataAccess:o: DAIS::DataAccess:roup::IHome : DAIS::DataAccess::Group::Manager: DAIS::DataAccess::Group::Managergroup_home( ) create_group( ) create_entries( ) Do work with group manager, e.g. activate subscription destroy( ) Figure 4-15 Group management interaction Activate subscription : Client: Client : DAIS::DataAccess::Group::Manager:DAIS::DataAccess::Group::Managerss:IO::Callbacks: DAIS::DataAcce::DAIS::DataAcces::IO::Callbackcallback(DAISDACallback) refresh( ) on_data_change( ) Forced by refresh on_data_change( ) Spontaneous on_data_change( ) Spontaneous Figure 4-16 Active subscription interaction Activate a subscription silently : Client: Client : DAIS::DataAccess::Group::Manager: DAIS::DataAccess::Group::Managerss:IO::Callbacks: DAIS::DataAcce:: DAIS::DataAcces::IO::Callbackset_inactive_state( ) callback( ) set_enable( ) set_active_state( ) Disable refresh( ) on_data_change( ) set_enable( ) Enable on_data_change( ) Figure 4-17 Activate a subscription silently interaction Cancel : DAIS::DataAccess::Group::M anager:DAIS::DataAccess::Group::Manager : DAIS::DataAccess::IO::Callback: DAIS::DataAccess::IO::CallbackCancel refresh operation Cancel async_read Cancel async_write : Client: Clienton_cancel_complete( ) on_cancel_complete( ) on_cancel_complete( ) refresh( ) cancel( ) async_read( ) cancel( ) async_write( ) cancel( ) Figure 4-18 Cancellation interaction The purpose of the interface is to provide a simple read and write of data. The functionality is the same as the synchronous read and write described in Section 4.2.5, “DAISDAIO IDL,? on page 4-23 but without having to create a group. //File: DAISDASimpleIO.idl#ifndef _DAIS_DA_SIMPLE_IO_IDL#define _DAIS_DA_SIMPLE_IO_IDL#include module DAIS {module DataAccess {module SimpleIO { enum DataSource { DS_CACHE, DS_DEVICE }; struct ItemError { }; typ Error ServerItemIdentification string edef sequence err; id; reason; ItemErrors; { str uct ItemState SimpleValue DateTime Quality ServerItemIdentification value; time_stamp; dais_quality; id; }; typedef sequenceItemStates; struct ItemUpdate { ServerItemIdentification id; SimpleValue value; };typedef sequence ItemUpdates; interface IHome { ItemStates read ( in DataSource data_source, in ServerItemIdentifications ids, out ItemErrors errors ); ItemErrors write_with_qt ( in ItemStates updates ); ItemErrors write ( in ItemUpdates updates ); };};};}; #endif // _DAIS_DA_SIMPLE_IO_IDL DataSource Find all public groups defined in the server. Member Description DS_CACHE Data cached in the server is requested. DS_DEVICE Data from the device is requested. This will force a read from the device or RTU. A read from device will be made regardless of the group or item active status and no group NotActive exception will be forced. ItemError A struct for reporting of item related errors. The struct is different from the DAIS::ItemError because no handles are used to identify the item in SimpleIO. Member Description err An error code as described for DAIS::ItemError. id The identification of the item. reason An additional text explaining the error. ItemState The struct is the carrier of data conveyed over the interface. It is the “message? holding the payload. This is basically the same struct as DataAccess::IO::ItemState with the difference that instead of a handle for identification the full server identification is used. Member Description value The value itself. time_stamp The time stamp when the value was last updated. quality The quality for the value. id The identification of the value in the server. ItemUpdate The struct carries an update for an item. Member Description id The identification of the value in the server. value The value that shall be used in the update. IHome The interface for simple IO operations. read Synchronous read of items. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. Parameter Description data_source The source from where to read the data, see DataSource above. ids A sequence specifying the server identifications to read. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID return A sequence of ItemStates for the items. write_with_qt Synchronous write of item values including quality and time stamp. The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemStates specifying the updates including time stamp and quality. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE write Synchronous write of item values only. The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemUpdates specifying the update values. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE. The IDL is divided into files. Each file is modeled as a package in UML. A file that depends on declarations made in another file needs to include it. Figure 4-4 shows how the IDL files depend on each other. DAISCommon (from Common) DAISDAIO DAISGroupEntry DAISItem DAISNode (from Common) DAISProperty DAISType (from Common) (from Common) DAISGroup DAISDASimpleIO DAISDASession DAISDANode DAISSession (from Common) DAISServer (from Server) Figure 4-4 Dependencies between data access IDL files The DAIS::DataAccess::Session object implements the data access service on a per client basis. A data access session object has a number of services provided by one singleton home object each. Each home object provides methods for manipulation of the data of the specific type they provide. Rather than exposing data as objects with interfaces it is exposed as structs or sequences of structs. The reason is that a large number of data items will become a performance bottleneck if instantiated as objects over an interface. The DAIS::Group::IHome object is the only object to expose its data as objects; that is, the DAIS::Group::Manager. Each DAIS::Group::Manager is expected to connect to one callback object implemented by the client. Each client may instantiate one or more Sessions. The Session objects have one Type and Property Home object each. The client shall expect that all Type and Property Home objects expose the same types and properties. The session object corresponds to an OPCServer object. 1 0..1 10..1 DAIS::Session (from DAISSess ion) <> status() : DAIS::SessionStatus callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() DAIS::DataAccess::Session <> group_home() : DAIS::DataAccess::Group::IHome simple_io_home : DAIS::DataAccess::SimpleIO::IHome() node_home() : DAIS::DataAccess::Node::IHome item_home() : DAIS::DataAccess::Item::IHome type_home() : DAIS::Type::IHome property_home() : DAIS::Property::IHome DAIS::ShutdownCallback (from DAISSessi on) <> 0..10..1 11 Client (fro m DAISServer) 11 0..*0..* 11 DAIS::Type::IHome (f rom DAIST ype) <> DAIS::DataAccess::IO::Callback (from DAISDAIO) <> DAIS::Property::IHome (from DAISProperty) <> 0..10..1 11 11 11 DAIS::DataAccess::Node::IHome (from DAISDANode ) <> DAIS::DataAccess::IO::ConnectionPoint (from DAISDAIO) <> 11 DAIS::DataAccess::Group::IHome (from DAISGroup) <> DAIS::DataAccess::Item::IHome (from DAI SItem) <> 11 1 0.. n 10.. DAIS::DataAccess::Group::Manager (from DAISGroup) <> 11 DAIS::DataAccess::SimpleIO::IHome (from DAISDASi mp leIO) <> Figure 4-5 DAIS data access session IDL in UML //File: DAISDASession.idl #ifndef _DAIS_DA_SESSION_IDL #define _DAIS_DA_SESSION_IDL #pragma prefix "omg.org" // Common Information #include #include #include // Data Access interface #include #include #include #include #include module DAIS { module DataAccess { interface Session : DAIS::Session { readonly attribute Group::IHome group_home; readonly attribute SimpleIO::IHome simple_io_home; readonly attribute Node::IHome node_home; readonly attribute Item::IHome item_home; readonly attribute Type::IHome type_home; readonly attribute Property::IHome };};}; #endif // _DAIS_DA_SESSION_IDL property_home; Session Session is an object implementing the data access functions. It inherits common functionality as shut down callbacks and session status from DAIS::Session. group_home A read only attribute holding a reference to a singleton Group::IHome object. node_home A read only attribute holding a reference to a singleton Node::IHome object. item_home A read only attribute holding a reference to a singleton Item::IHome object. type_home A read only attribute holding a reference to a singleton Type::IHome object. property_home A read only attribute holding a reference to a singleton Property::IHome object. The DAIS::DataAccess::Node inherits most of the functionality from DAIS::Node. The only difference is that it supports to get the tree root node. 0..*0..* 11 +parent 1 01..n0..n Node id : ResourceID label : string type : Resourc eID (from DAISNode) NodeItemComponent pathname : string (from DAISNode) 11 0..n0..n DAIS::DataAccess::Node::IHome get_root() <> DAIS::Node::Iterator max_left() next_n() reset() clone() destroy() (from DAISNode) <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() (from DAISNode) <> Figure 4-6 DAIS data access node IDL in UML //File: DAISDANode.idl#ifndef _DAIS_DANODE_IDL#define _DAIS_DANODE_IDL#pragma prefix "omg.org"#include module DAIS {module DataAccess {module Node { interface IHome : DAIS::Node::IHome{ ResourceID get_root(); }; };};}; #endif // _DAIS_DANODE_IDL IHome An object used for browsing nodes. Most functionality is inherited from the DAIS::Node::IHome interface. get_root() Get the root node of the whole tree of nodes. Parameter Description return The root node identification. Hierarchical browsing : Client:Client : DAIS::DataAccess::Node::IHome:DAIS::DataAccess::Node::IHome : DAIS::Node::Iterator:DAIS::Node::Iterator: DAIS::DataAccess::Session:DAIS::DataAccess::Sessionnode_home( ) get_root( ) find_by_parent( ) next_n( ) find_by_parent( ) Get some nodes at the root Pick one of the nodes at the root and get it's children next_n( ) Get some nodes among the children to the node picked at the root Figure 4-7 Hierarchical browsing interaction Browsing by type : Client: Client : DAIS::DataAccess::Session:DAIS::DataAccess::SessioAcess::Node::IHomeAn : DAIS::Datac:DAIS::Dataccess::Node::IHome : DAIS::Node::Iterator: DAIS::Node::Iteratornode_home( ) find_by_type( ) next_n( ) Find all nodes of a certain type in sub-tree, in this case the root get_root( ) next_n( ) Figure 4-8 Browsing by type interaction An item is a property of a node. While a node generally represents a real-world object, an item represents some characteristic of that object (for example, measurement value, control variable, or parameter related to the measurement/control process). The concept of an item in DAIS corresponds to the item in OPC. More precisely, it corresponds to the “leafs? in the OPC IOPCBrowseServerAddressSpace interface. In the Resource Description Framework (RDF) data model, the item corresponds to a combination of a subject and a predicate; that is, a resource and a property. A node may have many items, each representing a different characteristic of the same real world object. An item might represent a measured variable, a calculated variable, a control variable, or a configuration parameter. An item will typically have many values where each value corresponds to a time stamped sample (a single item value corresponds to a single statement in the RDF model). Each sample will also have its own quality. An item value is then qualified by a time stamp and a quality. An item value and its qualifications are represented by six fixed attributes: • value - the value. • time_stamp - the time when the value was last updated. • quality - the quality of the value. • canonical_data_type - the data type of the value. This actually belongs to the property (see Property) but it is mirrored at the item. • access_rights - tells if the value is read only, write only, or both read/write. The access right is common for all item values and belongs to the item. • scan_rate - the fastest rate with which the value can be expected to be updated. The scan rate is common for all item values and belongs to the item. For an information model describing this refer to Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 and Section 4.1.3, “Item Values,? on page 4-4. Each item has a universal identity given by its ItemID. The ItemID is made up of the ResourceID of a node and the PropertyID of a property. The ItemID of an item is the same in all views provided by a DAIS server. Clients may construct ItemIDs given the identities of nodes and properties. DAIS servers may be coordinated with DAF servers so that valid ItemIDs can be constructed from DAF ResoureIDs. Within each view provided by the server, an item has a label that is unique among all items belonging to the same node. Within each view, an item has a unique pathname. The pathname is a string that contains the item’s label and the pathname of its node. The pathname must be a valid URI, but apart from that the syntax of pathnames is implementation dependent. Note – In OPC the pathname is the primary way to identify items and is called the ItemID. In DAIS the ResourceID, PropertyID pair is the primary identification and so it is called the ItemID. This is a potential point of confusion. The two ItemIDs play approximately the same role in OPC and DAIS respectively, but they are not the same type. The item interfaces permit the stock of items to be browsed. Once an item is located, the group interfaces are used to deliver its values, selected by source, at successive times. In addition, the item interfaces provide the most current value for the default source. In either case the item value and qualifications are represented by the six fundamental attributes listed above. The Item IDL defines a main interface Home for browsing among hierarchically structured items (leaf nodes). The information model describing the hierarchical structure is found in Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2 . DAIS::DataAccess::Item::IHome <> find() find_each() find_by_parent() find_by_type() get_pathnam es() get_ids() get_access_paths() 11 11 0..0.n.n 0..0.n.n Item cache_value : SimpleV alue cache_value_last_updated : DateTim e cache_value_quality : DAIS::Quality scan_rate : unsigned long access_rights : DAIS::AccessRights NodeItem Component (fro m DA IS Nod e) pathname : string DAIS::DataAccess::Item::Iterator <> max_left() next_n() reset() clone() destroy() Figure 4-9 DAIS data access item IDL in UML //File: DAISItem.idl #ifndef _DAIS_ITEM_IDL #define _DAIS_ITEM_IDL #pragma prefix "omg.org" #include module DAIS { module DataAccess { module Item { struct Description { ItemID id; string label; SimpleValue value; //includes the canonical_data_type Quality dais_quality; DateTime time_stamp; AccessRights access_rights; unsigned long scan_rate; }; typedef sequence< Description >Descriptions; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions items ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownResourceID {string reason;}; exception UnknownItemID {string reason;}; exception InvalidFilter {string reason;}; exception InvalidValueType {string reason;}; exception UnkownTypeID {string reason;}; exception InvalidAccessRight {string reason;}; Description find ( in ItemID item ) raises (UnknownItemID); Descriptions find_each( in ItemIDs items ) raises (UnknownItemID); Iterator find_by_parent ( in ResourceID node, in string filter_criteria, in SimpleValueType data_type_filter, in AccessRights access_rights_filter ) raises (UnknownResourceID, InvalidFilter, InvalidValueType, InvalidAccessRight); Iterator find_by_type ( in ResourceID node, in ResourceIDs type_filter, in string filter_criteria, in SimpleValueType data_type_filter, in AccessRights access_rights_filter ) raises (UnknownResourceID, InvalidFilter, InvalidValueType, UnkownTypeID, InvalidAccessRight); Strings get_pathnames ( in ItemIDs items ); ItemIDs get_ids ( in Strings pathnames ); Strings get_access_paths ( in ItemID item ) raises (UnknownItemID); };};};}; #endif // _DAIS_ITEM_IDL Description A struct describing an item. Member Description id The identification of this item. label The label (single level designation) of the item. value The current value sample for the item. The SimpleValue also contains the data type. dais_quality The current quality of the value. time_stamp The time stamp for the value sample. access_rights States if the value is read, write, or both read and write. scan_rate States the highest update rate that can be expected. Iterator Refer to Section 4.1.5, “Utility SCADA/EMS Measurement Model,? on page 4-5. This interface corresponds to the OPC interface EnumString with the difference that the Iterator return the Description struct instead of a single string. IHome An object used for browsing items and corresponds to the IOPCBrowseServerAddressSpace. UnknownResourceID An exception telling that the ResourceID is unknown. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. UnknownItemID An exception stating that the resource or property in the ItemID is unknown. For methods taking a sequence of item ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. InvalidFilter An exception stating the filter_criteria string is not correct. The likely reason behind this exception is an erroneously entered string. InvalidValueType An exception stating that the SimpleValueType does not exist. UnknownTypeID An exception stating one or more TypeIDs does not exist. InvalidAccessRight An exception stating that the access rights do not exist. find() For a given item browse position, return information about that item. Parameter Description item An item identification. return The item description. find_each () For a sequence of items, return information about each item. Parameter Description items A sequence of item identifications. return An iterator holding the item descriptions. find_by_parent () For a given node identification, return child items to that node. Hence to reach all items using this method repeated calls must be made for each node level. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_LEAF. Parameter Description node The parent node identification. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects only items with pathnames matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. data_type_filter Select items having the specified canonical data type. access_rights_filter Select items having the specified access rights. return An iterator holding item descriptions for items • that are child to the parent node. • matching the filter_criteria, data_type_filter, and access_rights_filter. find_by_type() For a sub-tree given by the node parameter, return all child items matching the filter criteria. This will return all items under the given sub-tree root node. This will make the items in the sub-tree to appear flattened out. This corresponds to the OPC method BrowseOPCItemIDs with the parameter dwBrowseFilterType set to OPC_FLAT. Parameter Description node The identification for the node defining the sub-tree. type_filter Select nodes in the sub-tree having a type matching any of the types listed in the type_filter. filter_criteria A server specific filter string. This is entirely free format and may be entered by the user via a text field. An empty string indicates no filtering. The filter selects only items with pathnames matching the filter criteria. For a description of the filter refer to Section 3.1.11, “Filter Definitions,? on page 3-25. data_type_filter Select items having the specified canonical data type. access_rights_filter Select items having the specified access rights. return An iterator holding item descriptions for items • that are child to nodes in the sub-tree and nodes having a type matching the type_filter. • matching the filter_criteria, data_type_filter, and access_rights_filter. get_pathnames() Translate a sequence of item identifications to the corresponding sequence of pathnames. If an item fails to translate to a pathname (due to an unknown identification), the corresponding pathname is an empty string. Parameter Description items The sequence of items. return The corresponding sequence of pathnames. get_ids() Translate a sequence of pathnames to the corresponding sequence of item identifications. If a pathname fails to translate to an item identification (due to an unrecognized pathname) the corresponding item identification is NULL. get_access_paths() Get the possible communication paths how data can be retrieved for the node. An access path is expected to be human readable so that a human can pick one and feed it back to the server as the preferred path (via other interfaces). Parameter Description item An item identification. return A sequence of possible access paths for the item. Browsing Items : Client: Client : DAIS::DataAccess::Item::IHome: DAIS::DataAccess::Item::IHome : DAIS::DataAccess::Item::Iterator: DAIS::DataAccess::Item::Iterator: DAIS::DataAccess::Session: DAIS::DataAccess::Sessionnode_home( ) find_by_parent( ) next_n( ) item_home( ) find_by_parent( ) Get the items for a particular node Get some item descriptions for the particular node Get the items for another node Get some node of interest, refer to browsing of Nodes Figure 4-10 Browsing items interaction Navigate across associations find_by_parent( ) : Client:Client : DAIS::DataAccess::Item::IHome: DAIS::DataAccess::Item::IHomeataccess::Node::IHomea: DAIS::DA: DAIS::DtaAccess::Node::IHomeGet information about each item at a known node find( ) Pick an item holding a ResourceID and get the node information for that ResourceID find_by_parent( ) Get the item information for the new node Figure 4-11 Navigating across associations interaction These are definitions for transmitting item values to clients. Interfaces are defined for server side read and write operations and client side callback operations. Clients shall implement the Callback object for the server to use at transfer of data. A client may have any number of callback objects. The client shall connect each callback object to a server object implementing ConnectionPoint. The IO interfaces support three different ways to read data and two different ways to write data. Read data • Synchronous read where the data is received at return from the sync_read() method. • Asynchronous read where the data is returned at the Callback object. • Subscription where data is sent spontaneously by the server at the callback object. Write data • Synchronous write returning to the client once all the written data has reached the devices. • Asynchronous write returning when the data is received by the DAIS server. A callback on Callback is sent by the server once the written data has reached the devices. Each item value is transmitted in a struct with a timestamp and quality indication. A sequence of this struct is either sent via the callback object or directly in read or write calls. In OPC the IO interface corresponds to the OPC interfaces IOPCSyncIO, IOPCAsyncIO, and IOPCDataCallback. DAIS::DataAccess::IO::SyncIO <> sync_read() sync_write() DAIS::DataAccess::IO::ConnectionPoint <> callback() : DAIS::DataAccess::IO::Callback callback(callback : DAIS::DataAccess::IO::Callback) 11 0..0.1.1 DAIS::DataAccess::IO::Callback <> on_data_change() on_read_complete() on_write_complete() on_cancel_complete() 0..*0..* 11 Client (from DAIS Server) DAIS::DataAccess::IO::AsyncIO <> async_read() async_write() refresh() cancel() set_enable() get_enable() DAIS::DataAccess::IO::ItemState <> client_handle : ClientItemHandle time_stamp : DateTime dais_quality : DAIS::Quality value : SimpleValue Figure 4-12 DAIS data access IO IDL in UML The DAISConnectionPoint callback() methods correspond to a get or set method for the callback attribute. //File: DAISDAIO.idl#ifndef _DAIS_DAIO_IDL#define _DAIS_DAIO_IDL#pragma prefix "omg.org"#include module DAIS { module DataAccess {module IO { enum DataSource { DS_CACHE, DS_DEVICE }; struct ItemState { SimpleValue value; DateTime time_stamp; Quality dais_quality; ClientItemHandle client_handle; };typedef sequence ItemStates; struct ItemUpdate { ServerItemHandle server_handle; SimpleValue value; };typedef sequence ItemUpdates; interface SyncIO{ ItemStates sync_read ( in DataSource data_source, in ServerItemHandles server_handles, out ItemErrors errors ); ItemErrors sync_write ( in ItemUpdates updates ); }; typede f unsi gned long CancelID; int erface AsyncIO { exception NotConnected{string reason;}; exception InvalidCancelID{string reason;}; exception NotActive{string reason;}; CancelID async_read ( in ServerItemHandles server_handles, in DataSource data_source, in unsigned long transaction_id ) raises (NotConnected, NotActive); CancelID async_write ( in ItemUpdates updates, in unsigned long transaction_id ) raises (NotConnected); CancelID refresh ( in DataSource data_source, ) raises (NotConnected,NotActive); void cancel ( in CancelID cancel_id in unsigned long transaction_id ) raises (InvalidCancelID); attribute boolean enabled; }; interface Callback { void on_data_change ( in unsigned long transaction_id, in boolean all_quality_good, in ItemStates states ); void on_read_complete ( in unsigned long transaction_id, in boolean all_quality_good, in ItemStates states, in ItemErrors errors ); void on_write_complete ( in unsigned long transaction_id, in ItemErrors errors ); void on_cancel_complete ( in unsigned long transaction_id ); }; interface ConnectionPoint { attribute Callback cllbck; };};};}; #endif // _DAIS_DAIO_IDL DataSource Member Description DS_CACHE Data cached in the server is requested. DS_DEVICE Data from the device is requested. This will force a read from the device or RTU. A read from device will be made regardless of the group or item active status and no group NotActive exception will be forced. ItemState The struct is the major carrier of data conveyed over the interface. It is the “message? holding the payload. Member Description value The value itself. time_stamp The time stamp when the value was last updated. quality The quality for the value. client_handle A client side handle enabling the client to make a quick look up of the item in its internal data structures. ItemUpdate The struct carry an update for an item. Member Description server_handle A server side handle enabling the server to make a quick look up of the item in its internal data structures. value The value that shall be used in the update. SyncIO An interface for the synchronous operations. sync_read() Synchronous read of items. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. Parameter Description data_source The source from where to read the data. server_handles A sequence specifying the whole or a subset of the server side handles as defined via the DAIS::GroupEntry::Manager interface. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • INVALID_DAIS_HANDLE return A sequence of ItemStates for the items. sync_write() Synchronous write of item values to devices (not the internal server cache). The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemUpdates specifying all or a subset of the items defined for a GroupEntry::Manager. The ItemUpdate::value member is used to update the items in devices. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_INVALID_DAIS_HANDLE • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE AsyncIO An interface for asynchronous read or write operations. NotConnected An exception telling that there is no callback object connected by the client. InvalidCancelID An exception telling that the supplied cancel id number is not recognized. NotActive An exception telling that the group or all items in the group is inactive. Only issued when read from cache. async_read() Asynchronous read of items from devices. OPC may report read errors both at return from async_read() and at on_read_complete(). DAIS will report all errors at on_read_complete().. Parameter Description server_handles A sequence specifying the whole or a subset of the server side handles, as defined via the DAIS::GroupEntry::Manager interface. data_source The source from where to read the data. When reading from cache, inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous read operation. async_write() Asynchronous write of item values to devices (not the internal server cache). OPC may report write errors both at return from async_write() and at on_write_complete(). DAIS will report all errors at on_write_complete(). Parameter Description updates A sequence of ItemUpdates specifying all or a subset of the items defined for a DAIS::GroupEntry::Manager. The ItemUpdate::value member is used to update the items in devices. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous write operation. refresh() Initiate a complete asynchronous read transfer for all item entries defined via the DAIS::DataAccess::GroupEntry::Manager interface. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. The cyclic on_data_change reporting continues unaffected by a refresh call. However, items still unchanged after a refresh will not be reported in a succeeding on_data_change call. Parameter Description data_source The source from where to read the data. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_data_change call. return A cancellation number unique for the client. The number is used by a client to cancel an ongoing asynchronous refresh operation. cancel() Cancel on ongoing refresh, async read, or async write operations. The server is expected to acknowledge a successfully initiated cancel operation with an on_cancel_complete() callback. Parameter Description cancel_id The server generated cancellation number for the operation to cancel. enable An attribute used to enable or disable the spontaneous on_data_change() callbacks. The enable state does not affect on data change response to refresh calls. When a group is created it is enabled by default. Callback An interface implemented by the client and used by the server to send data to the client. on_data_change() The method is called by the server when spontaneous changes occur or when the client has requested an explicit refresh. Only active items are reported in spontaneous calls. Parameter Description transaction_id If the call is in response to a refresh, the transaction number for that refresh call. If the call is autonomous due to one or more spontaneous changes, the number is zero. all_quality_good All item quality values are good. item_states A sequence of requested or spontaneously changed ItemStates. on_read_complete() The method is used by the server to report data in response to an asynchronous read. Parameter Description transaction_id The transaction number for the corresponding read. all_quality_good All item quality values are good. This requires that no errors are reported in the error parameter below. item_states A sequence of ItemStates matching the read operation. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations initially succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • ERROR_INVALID_DAIS_HANDLE on_write_complete() The method is used to report the success of an asynchronous write operation. Parameter Description transaction_id The transaction number for the corresponding write. errors A sequence reporting items for which the write failed. An empty sequence indicates all write operations initially succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_INVALID_DAIS_HANDLE • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE on_cancel_complete() The method is used to acknowledge the completion of a successfully initiated cancel call. Parameter Description transaction_id The transaction number for the corresponding cancel. ConnectionPoint An interface used by the client to connect or disconnect a client callback object at the server. callback An attribute referencing the callback object. In an implementation one get and one set method will implement the callback attribute. Due to limitation in the UML tool used to draw the diagrams, the attribute is represented by the two methods connect and disconnect. A group has a collection of group entries. Each group entry associates the group with an item. An ItemID identifies a group entry within its group. The pathname of an item may be used as an alternative to the ItemID when the group entry is created (see Section 4.2.4, “DAISItem IDL,? on page 4-15). In OPC the GroupEntry interface corresponds to the interface IOPCItemMgt. . DAIS::DataAccess::GroupEntry::Manager <> create_entries() validate_entries() remove_entries() set_active_state() set_inactive_state() set_client_handles() set_data_types() create_group_entry_iterator() 11 0..0.n.n 11 0..0.*.* GroupEntry pathname : string item : DAIS::ItemID active : boolean access_path : string client_handle : ClientItemHandle requested_data_type : SimpleValueType access_rights : AccessRights canonical_data_type : SimpleValueType DAIS::DataAccess::GroupEntry::Iterator <> max_left() next_n() reset() clone() destroy() Figure 4-13 DAIS data access group entry IDL in UML //File: DAISGroupEntry.idl #ifndef _DAIS_GROUP_ENTRY_IDL #define _DAIS_GROUP_ENTRY_IDL #pragma prefix "omg.org" #include module DAIS { module DataAccess { module GroupEntry { struct Description { ServerItemIdentification server_item_id; string access_path; ClientItemHandle client_handle; SimpleValueType requested_data_type; boolean active; }; typedef sequence Descriptions; struct DetailedDescription { ItemID item; string pathname; string access_path; ServerItemHandle server_handle; ClientItemHandle client_handle;SimpleValueType requested_data_type;SimpleValueType canonical_data_type;AccessRights access_rights;boolean active; };typedef sequence DetailedDescriptions; struct Result { ServerItemHandle server_handle; ClientItemHandle client_handle; AccessRights access_rights; SimpleValueType canonical_data_type; };typedef sequence Results; struct HandleAssociation { ServerItemHandle server_handle; ClientItemHandle client_handle; }; typedef sequenceHandleAssociations; struct DataTypeDescription { ServerItemHandle server_handle; SimpleValueType requested_data_type; }; typedef sequenceDataTypeDescriptions; interface Iterator { boolean next_n (in unsigned long n,out DetailedDescriptions entries ); void reset(); Iterator clone(); void destroy(); }; interface Manager { Results create_entries (in Descriptions entries,out ItemErrors errors ); Results validate_entries ( in Descriptions entries, out ItemErrors errors ); ItemErrors remove_entries ( in ServerItemHandles server_handles ); ItemErrors set_active_state ( in ServerItemHandles server_handles ); ItemErrors set_inactive_state ( in ServerItemHandles server_handles ); ItemErrors set_client_handles ( in HandleAssociations handle_associations ); ItemErrors set_data_types ( in DataTypeDescriptions descriptions ); Iterator create_group_entry_iterator ();};};};};#endif // _DAIS_GROUP_ENTRY_IDL Description The struct describes a group entry for an item. The client to configure new entries in a group uses it. It directly corresponds to the OPCItemDef struct. Member Description server_item_id The identification of the item. access_path The access path used by the server to connect to the device and sensor. An empty string as input tells the server to select the access path. client_handle The client provided handle to the item. requested_data_type The data type requested by the client for the value. active Tells if the item is active and data from devices is updated in the cache. DetailedDescription The struct is used to deliver group entry information to the client. In OPC this is made with the struct OPCITEMATTRIBUTES. Description is used for both these OPC structs. Member Description item The item identification by an ItemID. pathname A string concatenating the labels for all nodes in the path from the item up to the root. access_path The access path used by the server to connect to the device and sensor. An empty string as input tells the server to select the access path. server_handle Server provided handle for the item. client_handle Client provided handle for the item. requested_data_type The data type requested by the client for the value. canonical_data_type The data type the server uses internally for the value. access_rights The access rights (read, write, and read-write) active Tells if the item is active and data from devices is updated in the cache. Result The struct is used to transfer the result from a create_entries() or validate_entries() call back to a client. In OPC the corresponding struct is OPCITEMRESULT. Member Description server_handle The handle given to the client for the item. client_handle The supplied client handle for the item. access_rights The access rights (read, write, and read-write) canonical_data_type The data type the server uses internally for the value. HandleAssociation The struct is used to change the association between server handles and client handles in the set_client_handle() method. Member Description server_handle The handle given to the client for the item. client_handle The new client handle wanted by the client. DataTypeDescription The struct is used to change the data type of the value delivered in the ItemState struct. Member Description server_handle The handle given to the client for the item. requested_data_type The new data type wanted by the client. Iterator Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. The interface directly corresponds to the EnumOPCItemAttributes interface. Manager An interface for creation and browsing of group entries. The interface directly corresponds to the IOPCItemMgt interface. create_entries() Adds one or more entries to a group. Parameter Description entries Group entry descriptions for entries to be created. errors A sequence of structs reporting the items that were not entered due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_UNKNOWN_PATHNAME • ERROR_BAD_TYPE • ERROR_UNKNOWN_ACCESS_PATH return A sequence of result descriptions for the entries that were entered in the group. validate_entries() Is used to determine if an item is valid (could it be added without error). Also returns information about the item such as canonical datatype. Does not affect the group in any way. Parameter Description entries Group entry descriptions for entries to be validated. errors A sequence of structs reporting the items that could not be validated due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_UNKNOWN_PATHNAME • ERROR_BAD_TYPE • ERROR_UNKNOWN_ACCESS_PATH return A sequence of result descriptions for the entries that were validated. remove_entries() Used to remove entries from a group. Parameter Description server_handles Server handles for entries that shall be removed. return A sequence of structs reporting the items that were not recognized or could not be removed due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_active_state() Used to activate individual items in a group. Activate state means that the server acquires data from devices. Inactive state means that the server does not acquire any data. The group enable state control if acquired data shall be sent further to subscribers via on_data_change. Parameter Description server_handles Server handles for items to activate. return A sequence of structs reporting the items that were not recognized or could not be activated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_inactive_state() Used to deactivate individual items in a group. Parameter Description server_handles Server handles for items to deactivate. return A sequence of structs reporting the items that were not recognized or could not be deactivated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_client_handles() Used to change the client handles for items. Parameter Description handle_associations Change descriptions for the items where to change the client handles. return A sequence of structs reporting the items that were not recognized or could not be updated due to an error. Reported error(s): • ERROR_UNKNOWN_ITEMID set_data_types() Used to change the requested data types for items. Parameter Description descriptions Change descriptions for the items where to change the data types. return A sequence of structs reporting the items that were not recognized or could not be updated due to an error. Reported errors are: • ERROR_UNKNOWN_ITEMID • ERROR_BAD_TYPE create_group_entry_iterator() Used to create a group entry iterator. Used by clients to inspect existing group entries. Parameter Description return The GroupEntry Iterator. A group is a collection of items and a connection to one or more consumers of item values. Clients create groups and their lifetime is bounded by the session to which they belong. (See Section 4.2.2, “DAISDASession IDL,? on page 4-8). The purpose of a group is to convey selected item values to a client. A callback object may be connected to a group to receive item value information (see Section 4.2.5, “DAISDAIO IDL,? on page 4-23). Items may be added and removed from a group as group entries (see Section 4.2.6, “DAISGroupEntry IDL,? on page 4-32). A group has an update rate that determines how frequently updated values for its entries are notified to its connected callback objects. A group also has other states that control its notification behavior. A group may also be initialized with a predefined set of entries. A set of entries is called a public group and is identified by a ResourceID. A client can create or remove public groups. A server may represent a public group as a node such that the ResourceID of the public group and the node are identical. This would allow clients to locate public groups by name. The DAIS:: DataAccess::Group::Manager object implements interfaces from the DAISDAIO and DAISGroupEntry IDLs. This is specified by inheritance of interfaces as seen in Figure 4-14 . A DAIS::DataAccess::Group::Manager has a state given by the DAIS::DataAccess::Group::State struct and a DAIS::DataAccess::Group::Manager object is created from the DAIS::DataAccess::Group::IHome object. In OPC the Group interface corresponds to the interfaces IOPCGroupStateMgt and IOPCPublicGroupStateMgt. DAIS::DataAccess::IO::ConnectionPoint (from DAISDAIO) <> callback() : DAIS::DataAccess::IO::Callback callback(callback : DAIS::DataAccess::IO::Callback) 11 0..10..1 DAIS::DataAccess::IO::Callback (from DAISDAIO) <> DAIS::DataAccess::IO::SyncIO (from DAISDAIO) <> sync_read() sync_write() DAIS::DataAccess::IO::AsyncIO (fromDAISDAIO) <> async_read() async_write() refresh() cancel() set_enable() get_enable() DAIS::DataAccess::GroupEntry::Manager (from DAISGrou pEntry) <> create_entries() validate_entries() remove_entries() set_active_state() set_inactive_state() set_client_handles() set_data_types() create_group_entry_iterator() DAIS::DataAccess::GroupEntry::Iterator (from DAISGroupEntry) <> 0..*0..* 11 DAIS::DataAccess::Group::Manager <> get_state() set_state() clone() clone_group_to_public() destroy() 0..n0..n 11 DAIS::DataAccess::Group::IHome <> find_public_groups() find() create_group() clone_group_from_public() remove_public_group() 11 11 DAIS::DataAccess::Group::State update_rate : unsigned long active : boolean time_bias : long percent_dead_band : double locale_id : unsigned long name : string Figure 4-14 DAIS data access group IDL in UML //File: DAISGroup.idl #ifndef _DAIS_GROUP_IDL #define _DAIS_GROUP_IDL #pragma prefix "omg.org" #include #include #include module DAIS { module DataAccess { module Group { exception DuplicateName {string reason;}; struct State { string name; unsigned long update_rate; boolean active; long time_bias; double percent_deadband; unsigned long locale_id; }; struct PublicGroupDescription { ResourceID id; State group_state; }; typedef sequencePublicGroupDescriptions; interface Manager : GroupEntry::Manager ,IO::AsyncIO ,IO::SyncIO ,IO::ConnectionPoint { State get_state (); unsigned long set_state ( in State group_state ) raises (DuplicateName); Manager clone ( in string name ) raises (DuplicateName); PublicGroupDescription clone_group_to_public ( in string name ) raises (DuplicateName); void destroy (); }; interface IHome { exception UnknownResourceID {string reason;}; PublicGroupDescriptions find_public_groups(); PublicGroupDescription find (in ResourceID public_group ) raises (UnknownResourceID); Manager create_group ( in State group_state, out unsigned long revised_update_rate ) raises (DuplicateName); Manager clone_group_from_public ( in ResourceID public_group, in string name ) raises (DuplicateName, UnknownResourceID); void remove_public_group ( in ResourceID public_group ) raises (UnknownResourceID); };};};}; #endif // _DAIS_GROUP_IDL DuplicateName An exception raised when an object is created and the name already exists. No object is created if the exception is raised. Used for session and group manager objects. State The struct contains information about the group state. Members Description name Within the session and public groups, unique name of the group. update_rate Update rate for the group in milliseconds. When used as input it specifies the fastest rate at which data changes may be sent to on_data_change() for items in this group. This also indicates the desired accuracy of cached data. This is intended only to control the behavior at the interface. How the server deals with the update rate and how often it actually polls the hardware internally is an implementation detail. Passing 0 indicates the server should use the fastest practical rate. active Indicates if the group is active and data from devices is updated in the cache. time_bias The time bias in minutes for the group. A zero value when used as input will tell the server to use the default system time bias. This bias behaves like the Bias field in the Win32 TIME_ZONE_INFORMATION structure. percent_deadband The percent change for an item value that will cause a call back for that value. This parameter only applies to items in the group that are of analog type. If a client specifies a zero deadband, the value will be reported with the update rate. locale_id The localization number for the language used when returning string values. Manager An object used to manage a group. It has a set of methods related to the group itself. It also inherits methods from interfaces for group entry management and data transfer. For group entry management refer to Section 4.2.6, “DAISGroupEntry IDL,? on page 4-32 and for data transfer refer to Section 4.2.4, “DAISItem IDL,? on page 4-15. The DAIS::DataAccess::Group::Manager interface corresponds to the IOPCGroupStateMgt interface. get_state() The method gets the group status. Parameter Description return State set_state() The method sets the group status. Parameter Description group_state The State with the updates. All members will be updated. If the name already exists, a DuplicateName exception is raised and no update is made. return The closest update rate the server is able to provide for the group. clone() Create a copy of a group. Parameter Description name The name to be given for the new group. If the name already exists, a DuplicateName exception is raised and no clone is created. return A description of the public group. clone_group_to_public () Create a public copy of a group including all items and the group state. Parameter Description name The name to be given for the new group. If the name already exists, a DuplicateName exception is raised and no public group is created. return A description of the public group. destroy() Delete the group. PublicGroupDescription A struct describing public groups. Member Description id A ResourceID identifying the public group. group_state The group state struct including the group name. IHome The factory object for groups. The corresponding OPC interface is IOPCServer. UnknownResourceID An exception telling that the ResourceID is unknown. For methods taking a sequence of resource ids the first found unknown id is reported. The likely reason behind this exception is some misunderstanding between the server and client code due to a programming error. find_public_groups() Find all public groups defined in the server. Member Description return A sequence of public group descriptions. find() For a given public group, return information about that group. Member Description public_group A ResourceID identifying the public group. return A public group description. create_group() Create a new initially empty group. Parameter Description group_state The State to be set for the new group. revised_update_rate The closest update rate the server is able to provide for the group. return The new group. clone_group_from_public() Create a copy from a public group having an existing set of entries and state. Parameter Description public_group The identification of the public group. name The name of the new group. return The new group. remove_public_group() Remove a public group. Parameter Description public_group The identification of the public group. return None. Group management : Client:Client : DAIS::DataAccess::Session: DAIS::DataAcce:Grup::IHome:Gss::Session : DAIS::DataAccess:o: DAIS::DataAccess:roup::IHome : DAIS::DataAccess::Group::Manager: DAIS::DataAccess::Group::Managergroup_home( ) create_group( ) create_entries( ) Do work with group manager, e.g. activate subscription destroy( ) Figure 4-15 Group management interaction Activate subscription : Client: Client : DAIS::DataAccess::Group::Manager:DAIS::DataAccess::Group::Managerss:IO::Callbacks: DAIS::DataAcce::DAIS::DataAcces::IO::Callbackcallback(DAISDACallback) refresh( ) on_data_change( ) Forced by refresh on_data_change( ) Spontaneous on_data_change( ) Spontaneous Figure 4-16 Active subscription interaction Activate a subscription silently : Client: Client : DAIS::DataAccess::Group::Manager: DAIS::DataAccess::Group::Managerss:IO::Callbacks: DAIS::DataAcce:: DAIS::DataAcces::IO::Callbackset_inactive_state( ) callback( ) set_enable( ) set_active_state( ) Disable refresh( ) on_data_change( ) set_enable( ) Enable on_data_change( ) Figure 4-17 Activate a subscription silently interaction Cancel : DAIS::DataAccess::Group::M anager:DAIS::DataAccess::Group::Manager : DAIS::DataAccess::IO::Callback: DAIS::DataAccess::IO::CallbackCancel refresh operation Cancel async_read Cancel async_write : Client: Clienton_cancel_complete( ) on_cancel_complete( ) on_cancel_complete( ) refresh( ) cancel( ) async_read( ) cancel( ) async_write( ) cancel( ) Figure 4-18 Cancellation interaction The purpose of the interface is to provide a simple read and write of data. The functionality is the same as the synchronous read and write described in Section 4.2.5, “DAISDAIO IDL,? on page 4-23 but without having to create a group. //File: DAISDASimpleIO.idl#ifndef _DAIS_DA_SIMPLE_IO_IDL#define _DAIS_DA_SIMPLE_IO_IDL#include module DAIS {module DataAccess {module SimpleIO { enum DataSource { DS_CACHE, DS_DEVICE }; struct ItemError { }; typ Error ServerItemIdentification string edef sequence err; id; reason; ItemErrors; { str uct ItemState SimpleValue DateTime Quality ServerItemIdentification value; time_stamp; dais_quality; id; }; typedef sequenceItemStates; struct ItemUpdate { ServerItemIdentification id; SimpleValue value; };typedef sequence ItemUpdates; interface IHome { ItemStates read ( in DataSource data_source, in ServerItemIdentifications ids, out ItemErrors errors ); ItemErrors write_with_qt ( in ItemStates updates ); ItemErrors write ( in ItemUpdates updates ); };};};}; #endif // _DAIS_DA_SIMPLE_IO_IDL DataSource Find all public groups defined in the server. Member Description DS_CACHE Data cached in the server is requested. DS_DEVICE Data from the device is requested. This will force a read from the device or RTU. A read from device will be made regardless of the group or item active status and no group NotActive exception will be forced. ItemError A struct for reporting of item related errors. The struct is different from the DAIS::ItemError because no handles are used to identify the item in SimpleIO. Member Description err An error code as described for DAIS::ItemError. id The identification of the item. reason An additional text explaining the error. ItemState The struct is the carrier of data conveyed over the interface. It is the “message? holding the payload. This is basically the same struct as DataAccess::IO::ItemState with the difference that instead of a handle for identification the full server identification is used. Member Description value The value itself. time_stamp The time stamp when the value was last updated. quality The quality for the value. id The identification of the value in the server. ItemUpdate The struct carries an update for an item. Member Description id The identification of the value in the server. value The value that shall be used in the update. IHome The interface for simple IO operations. read Synchronous read of items. Inactive items will be reported with OPCQuality set to OPC_QUALITY_OUT_OF_SERVICE. Parameter Description data_source The source from where to read the data, see DataSource above. ids A sequence specifying the server identifications to read. errors A sequence reporting items for which the read failed. An empty sequence indicates all read operations succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is write only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID return A sequence of ItemStates for the items. write_with_qt Synchronous write of item values including quality and time stamp. The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemStates specifying the updates including time stamp and quality. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE write Synchronous write of item values only. The active state of the group or the items is ignored. Parameter Description updates A sequence of ItemUpdates specifying the update values. return A sequence reporting items for which the write failed. An empty sequence indicates write operations for all items succeeded. Reported errors are: • ERROR_BAD_RIGHTS (item is read only) • ERROR_UNKNOWN_PATHNAME • ERROR_UNKNOWN_ITEMID • ERROR_CLAMPED • ERROR_OUT_OF_RANGE • ERROR_BAD_TYPE. Contents This chapter contains the following sections. Section Title Page “Information Model? 5-2 “API? 5-6 The alarms & events interface provides a client with a way to subscribe for alarms and events generated within RTUs, devices, or any software. The server supports various filter functions so that the client can compose a filter matching its current interest in alarms and events. Once the client sets up a filter specification it has to supply the server a callback object used by the server to notify the client with generated alarms and events. Events just reports state changes while alarms have an associated alarm state and fault state. Alarms are generated with the intent to gain attention to a condition that needs operator intervention. Hence alarms and events are recorded and presented to operators. Alarm presentation usually involves acoustic annunciation and some highlighting (e.g., red color and/or blink, etc.). An operator shall acknowledge the alarm state and the fault state disappear when the fault causing the alarm disappears. Equipment and functions that may generate alarms and events are: • Process instrumentation making sensor data and actuation capabilities available. • Remote terminal units (RTUs) or substation control systems, reading sensor data, and controlling actuators. • Process communication units connecting to RTUs or substation control systems. • SCADA subsystem making processed sensor data and control capabilities available to operators, applications, or other systems. • Energy Management System (EMS) - subsystem using the SCADA subsystem for extended processing and control. An example flow of alarms, events, and acknowledgments are shown in Figure 5-1. SCADA Application Server Instrumentation RTU/ Process station Server Server HMI Data traffic for use cases Alarms and Events Acknowledgments Figure 5-1 Alarms, events and acknowledgment flows in a SCADA/EMS Alarms and events are generated by a source represented by Source. A source might be a single measurement, a collection of measurements, or some other object. A collection of measurements may represent a complex real world object like a generator or some control function for the generator. A source has a name property. The source is also associated with a type that describes any additional properties. If a DAIS server implements both data access and alarms & events, a client shall expect there is a mapping between sources and nodes. A client shall however not make assumptions on how the mapping is made and use the method translate_to_item_ids() to get the mapping from the server. Sources are organized in areas represented by Area. An area typically represents area of responsibility concerning supervision and operation of sources. Areas may however also be used for other groupings of sources. Areas can be hierarchically structured to allow creation of hierarchically organized responsibilities. Multiple views of areas are supported. Alarms and events are categorized. Category represents the categories. Three main categories are defined and must be implemented by a server: • simple - describing events that do not have an explicitly modeled condition space. • tracking - describing events generated due to an operator action. • condition - describing events generated based on an explicitly modeled condition space. The categories simple and tracking are used for events, and the category condition is used for alarms. For each main category it is possible to define a number of sub-categories. A server is free to implement any sub-categories. Each type of source is expected to be associated with at least one main category and one or more sub-categories for each main category. The main categories are not expected to have an association with a source type. Subcategories however are all expected to have an associated source type. A Condition category is associated with one or more condition spaces. ConditionSpace represents a condition space. Depending on how limits are applied to the properties defined by the type associated with a condition category it is possible to create a space consisting of different discrete conditions. Condition describes each discrete condition. A condition space will have a number of conditions defined for it. A Transition describes each possible transition between a pair of conditions. The alarms & event session does not however provide any methods for direct access of transitions. When a transition is traversed a condition event is generated. A source may be associated with one or more condition spaces. Each such association has status information describing the current condition. The association and its data are called SourceCondition. The source condition is identified by its associated source and condition space. A source is of a specific type (e.g., measurement, breaker, generator, tank, etc.) and the type has one or more properties in the same way as a node (refer to Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2). A category may have any number of properties associated with it. An alarm or event may contain values for the properties associated with the corresponding category. This is used to convey additional server specific information with alarms and events. Specification of what properties are associated with categories is outside the scope of this specification. The described classes are shown in Figure 5-2. The attributes are described later with the description of the interfaces. 0..0.n.n AreaSourceComponent (from DAISAEArea) id : ResourceID name : string description : string Area Source (from DAISAEArea ) (from DAISAESourc e) +aggregated_types +parent 0..n0..n 0..0.n.n Type (from DAIST ype) 0..0.n.n 11 1..n1..n 11 0..0.n.n Property (from DAISProperty) 0..n0..n SourceCondition (from DA I S AES o urceCon di t ion) condition_op_state : DAISConditionOpState quality : DAIS::Quality last_acknowledge : DateTime condition_last_active : DateTime condition_space_last_active : DateTime condition_space_last_inactive : DateTime acknowledger_name : string comment : string 0..0.n.n 0..0.n.n 0..n0..n 11 1..n 11..n1 1..n1..n 0..0.n.n 11 +conditions ConditionSpace (from DAISAECondition Space) id : ResourceID name : string description : string Condition (from DAISAECondition Space) id_number : unsigned long name : string description : string severity : unsigned long condition_logic : string SimpleCategory (fro m DAISAECate gory) TrackingCategory (fro m DAISAECate gory) ConditionEvent (from DAISAEIO) ConditionCategory (fro m DAISAECate gory) 11Category (f ro m DAIS A ECateg ory) 11 0..n0..n +active_condition 11 Transition (from DAISAECo nditionSp ac e) 0..n0..n Figure 5-2 DAIS Alarms and Events Information Model The objects in DAIS alarms and events has the following mapping to OPC alarms and events objects. DAIS A&E object OPC A&E object Source Source Area Area Property EventAttribute Category EventCategory The categories; simple, tracking and condition EventType ConditionSpace Condition Condition SubCondition SourceCondition SourceCondition In OPC there is a recommendation of what properties are expected to be supported by an alarm & event server. The recommended properties are shown in Table 5-1. The column names correspond to the attributes in the Property class. Table 5-1 Recommended Properties Table 5-1 Recommended Properties label id canonical_ data_type description Condition Status 300 STRING_TYPE The current alarm or condition status associated with the Item (for example, “NORMAL,? “ACTIVE,? “HI ALARM?). Alarm Quick Help 301 STRING_TYPE A short text string providing a brief set of instructions for the operator to follow when this alarm occurs. Alarm Area List 302 STRING_TYPE sequence An array of strings indicating the plant or alarm areas that include this ItemID. Primary Alarm Area 303 STRING_TYPE A string indicating the primary plant or alarm area including this ItemID. Condition Logic 304 STRING_TYPE An arbitrary string describing the test being performed (for example, “High Limit Exceeded? or “TAG.PV >= TAG.HILIM?). Refer to Section 5.2.7.3, “Condition Logic,? on page 5-38. Limit Exceeded 305 STRING_TYPE For multistate alarms, the condition exceeded (for example, HIHI, HI, LO, LOLO). Deadband 306 DOUBLE_TYPE Deadband HiHi Limit 307 DOUBLE_TYPE HiHi Limit Hi Limit 308 DOUBLE_TYPE Hi Limit Lo Limit 309 DOUBLE_TYPE Lo Limit LoLo Limit 310 DOUBLE_TYPE LoLo Limit Rate of Change Limit 311 DOUBLE_TYPE Rate of Change Limit Deviation Limit 312 DOUBLE_TYPE Deviation Limit 3124999 Reserved by OPC The dependencies among the different IDL files are shown in Figure 5-3. DAISAESession DAISAESubscription DAISAEIO DAISAESource Condition DAISConditionSpace DAISAEReason DAISAESource DAISAEArea DAISServer (from Server) DAISSession (from Com m on) DAISProperty (from Common) DAISNode (from Common) DAISCommon (from Common) DAISAECommon DAISType (from Com m on) Figure 5-3 Dependencies between alarms and events IDL files // File: DAISAECommon.idl #ifndef _DAIS_AECOMMON_IDL #define _DAIS_AECOMMON_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { typedef ResourceID EventID; struct ResourceError { Error err; ResourceID id; string reason; }; typedef sequence ResourceErrors; // error codesconst Error RES_ERROR_DAISOK= 0;const Error RES_ERROR_UNKOWN_RESOURCE= 1; typedef unsigned longSourceConditionOpState;const SourceConditionOpStateCONDITION_ENABLED= 0x0001;const SourceConditionOpStateCONDITION_ACTIVE= 0x0002;const SourceConditionOpStateCONDITION_ACKED= 0x0004; typedef unsigned short EventFormat;const EventFormat OPC_SIMPLE_EVENT = 0x0001;const EventFormat OPC_TRACKING_EVENT = 0x0002;const EventFormat OPC_CONDITION_EVENT= 0x0004;const EventFormat OPC_ALL_EVENTS = 0x0007;};};#endif // _DAIS_AECOMMON_IDL EventID A ResourceID uniquely identifying an event notification. ResourceError A struct for reporting of resource related errors. Member Description err An error code as described below. id The identification of the resource. reason An additional text explaining the error. ResourceErrors ResourceErrors is a sequence containing errors. If no errors are present, no entry shall be included in the sequence rather than including a large number of no errors. An empty sequence means no errors. Error The error codes for ResourceError. Member Description RES_ERROR_DAISOK No error. RES_ERROR_UNKOWN_RESOURCE The resource was not found. SourceConditionOpState Flag word holding for the operational state of a SourceCondition. The definitions of the state variable in the flag word are listed below. Flag Description CONDITION_ENABLED The Condition is enabled and supervision is active. CONDITION_ACTIVE The Condition is active; that is, the supervision has determined that a fault has activated the condition. CONDITION_ACKED The Condition alarm has been acknowledged. The combinations of the state variables result in eight states. The valid SourceCondition operational states are listed below. State Description Disabled Not supervised by server. Enabled, Inactive, Acked Supervised by server, no fault detected and all alarms are acknowledged. Enabled, Inactive, Unacked Supervised by server, no fault detected and unacknowledged alarms exist. Enabled, Active, Unacked Supervised by server, a fault is detected and unacknowledged alarms exist. Enabled, Active, Acked Supervised by server, a fault is persistent and all alarms are acknowledged. When enabled the state {Enabled, Inactive, Acked} is entered and from there the supervision will generate the appropriate state depending on the result of the supervision. Each state change results in sending an alarm and event notification. All notifications contain the state. EventFormat This constant tells the format of an event. Member Description OPC_SIMPLE_EVENT The event is a simple event. OPC_TRACKING_EVENT The event is a tracking event. OPC_CONDITION_EVENT The event is a condition event. OPC_ALL_EVENTS This constant value is used to ask for all event formats in a subscription set up. The DAIS::AlarmsAndEvents::Session object implements the alarms & events service on a per client basis. An alarm & event session object has a number of services provided by one singleton home object each. Each home object provides methods for manipulation of the data of the specific type they provide. The session object corresponds to an OPCEventServer object. DAIS::ShutdownCallback (from DAISSessi on) <> DAIS::AlarmsAndEvents::Session <> subscription_home() : DAIS::AlarmsAndEnvents::Subscription::Home area_home() : DAIS::AlarmsAndEvents::Area::IHome source_home() : DAIS::AlarmsAndEvents::Source::IHome condition_space_home() : DAIS::AlarmsAndEnvents::ConditionSpace::Home source_condition_home() : DAIS::AlarmsAndEvents::SourceCondition::IHome reason_home() : DAIS::AlarmsAndEvents::Category::IHome type_home() : DAIS::Type::IHome property_home() : DAIS::Property::IHome DAIS::Session (from DAISSessi on) <> status() : DAIS::SessionStatus 1 01callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() ..10..1 0..10..1 11 Client (f rom DA ISServ er) 11 DAIS::AlarmsAndEvents::Area::IHome (from DAISAEArea) <> 0..0.*.* 11 DAIS::AlarmsAndEvents::IO::Callback (f ro m DAISAE I O) <> 11 DAIS::AlarmsAndEvents::Source::IHome (f rom DA ISAE Sourc e) <> 0..0.1.1 11 11 DAIS::AlarmsAndEvents::ConditionSpace::IHome (from DAISAECondi ti onSpace ) <> DAIS::AlarmsAndEvents::SourceCondition::IHome (f ro m DA ISAE Sourc eConditi on) <> DAIS::AlarmsAndEvents::Category::IHome (from DAISAECategory) <> DAIS::AlarmsAndEvents::Subscription::IHome (from DAISAESu bscriptio n) <> 11 11 11 11 0.. 0..n DAIS::AlarmsAndEvents::Subscription::Manager (fro m DAISAESubsc ri pti on) <> 11 DAIS::Property::IHome (from DAISProperty) <> Figure 5-4 DAIS alarms and events session IDL in UML //File: DAISAESession.idl #ifndef _DAIS_AESERVER_IDL #define _DAIS_AESERVER_IDL #pragma prefix "omg.org" // Common Information#include #include #include // Events and Alarms#include #include #include #include #include #include #include module DAIS {module AlarmsAndEvents { interface Session : DAIS::Session { readonly attribute Subscription::IHome subscription_home; readonly attribute Area::IHome area_home; readonly attribute Source::IHome source_home; readonly attribute ConditionSpace::IHome condition_space_home; readonly attribute SourceCondition::IHome source_condition_home; readonly attribute Category::IHome category_home; readonly attribute Type::IHome type_home; readonly attribute Property::IHome property_home; };};}; #endif // _DAIS_AESESSION_IDL; Session Session is an object implementing the alarms & events functions. It inherits common functionality as shut down callbacks and session status from DAIS::AlarmsAndEvents::Session. subscription_home A read only attribute holding a reference to a singleton Subscription::IHome object. area_home A read only attribute holding a reference to a singleton Area::IHome object. source_home A read only attribute holding a reference to a singleton Source::IHome object. condition_space_home A read only attribute holding a reference to a singleton ConditionSpace::IHome object. source_condition_home A read only attribute holding a reference to a singleton SourceCondition::IHome object. category_home A read only attribute holding a reference to a singleton Category::IHome object. type_home A read only attribute holding a reference to a singleton Type::IHome object. property_home A read only attribute holding a reference to a singleton Property::IHome object. A DAIS::AlarmsAndEvents::Subscription::Manager is an object holding a filter specification set up by a client. The filter is used to specify what notifications shall be sent to the client. A server can support various filter functions and a client can ask the DAIS::AlarmsAndEvents::Subscription::IHome object what filter functions are supported. The subscription home is also used to create any number of subscription manager objects. Each subscription manager shall be associated with a client implemented callback object so that the server can send alarm and event notifications to the client. A server may optionally support an event history. The event history shall record all alarms and events appearing in a server. The method async_read_history() gives clients access to the event history. The size of the event history is server specific and outside the control of a client. In OPC the Subscription interface corresponds to the interface IOPCEventSubscription. DAIS::AlarmsAndEvents::Subscription::IHome query_available_filters() create_subscription() <> 0..0.1.1 11 DAIS::AlarmsAndEvents::IO::Callback (from DAISAEIO) <> 0..n0..n 11 DAIS::AlarmsAndEvents::Subscription::Manager callback() : DAIS::AlarmsAndEvents::IO::Callback callback(in callback : DAIS::AlarmsAndEvents::IO::Callback) set_filter() get_filter() select_returned_properties() get_returned_properties() refresh() asynch_read_history() cancel() get_state() set_state() clone() destroy() <> 11 0..0.n.n PropertySelection category : ResourceID properties : PropertyIDs 11 11 11 DAIS::AlarmsAndEvents::Subscription::FilterSpec reason_filter : ReasonFilter low_severity : unsigned long high_severity : unsigned long source_filter : SourceFilter type_filter : TypeIDs DAIS::AlarmsAndEvents::Subscription::State active : boolean buffer_time : unsigned_long max_size : unsigned long keep_alive_time : unsigned long 11 Figure 5-5 DAIS alarms and events subscription IDL in UML //File: DAISAESubscription.idl #ifndef _DAIS_AESUBSCRIPTION_IDL #define _DAIS_AESUBSCRIPTION_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { module Subscription { struct State { boolean active; unsigned long buffer_time; unsigned long max_size; unsigned long keep_alive_time; }; struct OPCSourceFilter { ServerItemIdentifications areas; ServerItemIdentifications sources; }; typedef short SourceFilterType;const SourceFilterType OPC_SOURCE_FILTER_TYPE = 1;const SourceFilterType XPATH_SOURCE_FILTER_TYPE = 2; union SourceFilter switch(SourceFilterType) { case OPC_SOURCE_FILTER_TYPE : OPCSourceFilter opc_source_filters; case XPATH_SOURCE_FILTER_TYPE : string xpath_source_filter; }; typedef short CategoryFilterType;const CategoryFilterType OPC_REASON_FILTER_TYPE = 1;const CategoryFilterType XPATH_REASON_FILTER_TYPE= 2; union CategoryFilter switch(ReasonFilterType) { case OPC_CATEGORY_FILTER_TYPE : ServerItemIdentifications opc_category_filters; case XPATH_CATEGORY_FILTER_TYPE : string xpath_category_filter; }; struct FilterSpec { EventFormat event_format; CategoryFilter category_filter; unsigned long low_severity; unsigned long high_severity; SourceFilter source_filter; ResourceIDs type_filter; }; struct PropSelection { ResourceID category; PropertyIDs properties; };typedef sequence PropSelections; enum ReadDirection { READ_FORWARDS, READ_BAKWARDS }; typedef unsigned long CancelID; interface Manager { exception BusyDueToRefresh{string reason;}; exception HistoryNotImplemented{string reason;}; attribute IO::Callback callback; void set_filter (in FilterSpec filer_spec) raises (BusyDueToRefresh); FilterSpec get_filter (); void select_returned_properties (in PropSelections prop_selections); PropSelections get_returned_properties (in ResourceIDs categories); CancelID refresh () raises (BusyDueToRefresh); CancelID async_read_history ( in DateTime start_time, in unsigned long number_of_events, in ReadDirection direction, in unsigned long transaction_id ) raises (HistoryNotImplemented); void cancel (in CancelID cancel_id); void refresh () raises (BusyDueToRefresh); void refresh_with_history (in DateTime start_time,in DateTime end_time ) raises (HistoryNotImplemented); void cancel_refresh (); State get_state (); State set_state ( in State subscription_spec Manager clone (); void destroy (); }; typedef unsigned longFilter;const Filter FILTER_BY_EVENT_FORMAT = 0x0001;const Filter FILTER_BY_CATEGORY = 0x0002;const Filter FILTER_BY_SEVERITY = 0x0004;const Filter FILTER_BY_AREA = 0x0008;const Filter FILTER_BY_SOURCE = 0x0010;const Filter FILTER_WITH_XPATH = 0x0020;const Filter FILTER_BY_SOURCE_TYPE = 0x0040; interface IHome{ Filter query_available_filters (); Manager create_subscription ( in State subscription_spec, out State revised_subscr_spec); };};};}; #endif // _DAIS_AESUBSCRIPTION_IDL State A struct describing the state for the subscription. Member Description active Indicates if the subscription is active; that is, is sending data on the call back interface. Events that are appearing in the server will be lost for clients connected to inactive subscriptions. buffer_time The requested buffer time in milliseconds. This is a minimum time - do not send event notifications any faster that this UNLESS max_size is greater than 0, in which case the server will send an event notification sooner to obey the max_size value. A value of 0 for buffer_time means that the server should send event notifications as soon as it gets them. This parameter along with the max_size parameter is used to improve communications efficiency between client and server. This parameter is a recommendation from the client, and the server is allowed to ignore the parameter. The server will return the buffer time it is actually providing in revised_buffer_time. max_size The requested maximum number of events that will be sent in a single callback. A value of 0 means that there is no limit to the number of events that will be sent in a single callback. Note that a value of max_size greater than 0, may cause the server to make callbacks more frequently than specified by buffer_time when a large number of events are being generated in order to limit the number of events to the max_size. This parameter is a recommendation from the client and the server is allowed to ignore this parameter. The server will return the actual number of events it is actually providing in revised_max_size. keep_alive_time The time in milliseconds for the server to send a callback to client. The intention is to indicate to the client that the server is alive and avoid the need to "poll" the server to check it is alive. If no data is available an empty message is sent. If the time is less than the buffer_time the buffer_time is used. OPCSourceFilter The struct specifies source filtering by enumerating the areas and sources the way OPC does it. Member Description areas A sequence of ResourceIDs for the areas that shall be notified. All sources below an area node will be notified. sources A sequence of ResourceIDs for sources that shall be notified. An empty sequence means all sources shall be notified. SourceFilter The union specifies OPCSourceFiltering or XPath filtering. A prerequisite for XPath filtering is that the area and source hierarchy has an XML mapping. The same mapping is used as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 with the additional comments: • an Area corresponds to a Node (Area inherits Node). • a Source corresponds to a Node (Source inherits Node). Member Description opc_source_filters An OPCSourceFilter xpath_source_filter An XPath filter. CategoryFilter The union specifies OPC style filtering or XPath filtering of categories. A prerequisite for XPath filtering is that the resource hierarchy has an XML mapping. The same mapping is used as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 with the additional comments: • a Resource corresponds to a Node (Resource inherits Node). Member Description opc_category_filters An OPCSourceFilter xpath_reason_filter An XPath filter FilterSpec A struct holding the specification for how the server shall filter notifications sent to the client. The struct is used to specify the filtering a client wants a server to do for it. All specified filter criterias shall be fulfilled for a notification to be sent. Member Description event_format An EventFormat bit mask specifying the event formats to be returned. reasons A sequence of CategoryFilter for the categories for which the client wants to get notifications. Observe that specifying a main category (for example, Simple, Tracking, Condition) will result in notifications for all sub-categories specified for that main category. low_severity The client wants all events with greater or equal severity. high_severity The client wants all events with less or equal severity. sources A SourceFilter for the sources that shall be notified. types A sequence of TypeIDs for the types that shall be notified. PropSelection A struct identifying what properties shall be included in an event notification for a specific reason. Member Description reason The reason for which the property selection is made. properties A sequence of PropertyIDs for the selected properties. ReadDirection An enumeration that tells if a read of history shall be forward or backwards in time. Member Description READ_FORWARDS Read events after the given start time. READ_BAKWARDS Read events before the given start time. Manager An object managing subscription and filtering of event notifications per client. BusyDueToRefresh An exception stating that a refresh is already going on. HistoryNotImplemented An exception stating that the server does not record the event history. callback An attribute holding a reference to the callback object. The client is required to update the attribute with a by the client implemented callback object to get event notifications from the server. The attribute corresponds to the IConnectionPoint interface in OPC. set_filter() The method updates the filter specification. A try to change the filter spec during an ongoing refresh will give an exception. The method corresponds to IOPCEventSubscriptionMgt::SetFilter(). Member Description filer_spec The filter specification. return none. get_filter() The method gets the filter specification. The method corresponds to IOPCEventSubscriptionMgt::GetFilter(). Member Description return The filter specification. select_returned_properties() The method sets what properties shall be included in a notification specified per reason. The method corresponds to IOPCEventSubscriptionMgt::SelectReturnedAttributes(). Member Description prop_selections A sequence specifying what properties to include per reason. return none. get_returned_properties() The method gets what properties currently are included in a notification specified per category. The method corresponds to IOPCEventSubscriptionMgt::GetReturnedAttributes(). Member Description categories The categories for that shall be used to fetch the properties. return A sequence specifying what properties currently are included per reason. refresh() The method forces notifications for all currently active source conditions. The notifications will not include the history but only the current source condition operational state. The method corresponds to IOPCEventSubscriptionMgt::Refresh(). Member Description return A server generated handle that the client can use to cancel the operation. async_read_history() The method read historic events recorded by the server. If the server does not support recording of alarms and events an exception is raised. No corresponding method exists in OPC. Member Description start_time The time where to start the read. An unspecified time (=0) will make the read start from the oldest recorded event. number_of_events The max number of events to deliver as a response to the read operation. Member Description direction Tells if events before or after the start time shall be read. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A server generated handle that the client can use to cancel the operation. cancel() The method cancels an ongoing refresh operation or async_read_history() operations. It corresponds to IOPCEventSubscriptionMgt::CancelRefresh(). Member Description cancel_id A server generated handle that is given back to the server when a started operation shall be cancelled. return none. get_state() The method gets the current subscription state and corresponds to IOPCEventSubscriptionMgt::GetState(). Member Description return The current subscription state. set_state() The method sets the current subscription state and corresponds to IOPCEventSubscriptionMgt::SetState(). The actual parameters set are returned and an exception is raised if any input parameters are not accepted and hence changed. Member Description subscription_spec New state wanted for the subscription. return The accepted subscription state. clone() The method creates a copy of the subscription. 5-22 Data Acquisition from Industrial Systems, v1.1 June 2005 Member Description return The copied subscription. destroy() The method destroys the subscription object. Filter A flag word holding flags specifying the filters that are implemented by the server. Flag Description FILTER_BY_MAIN_CATEGORY Filtering by main category is supported. FILTER_BY_CATEGORY Filtering by sub-category is supported. FILTER_BY_SEVERITY Filtering by severity is supported. FILTER_BY_AREA Filtering by area is supported. FILTER_BY_SOURCE Filtering by source is supported. FILTER_WITH_XPATH XPath as filter description is supported. FILTER_BY_SOURCE_TYPE Filtering by source type is supported. IHome A factory object for creation of subscription management objects. query_available_filters() Gets by the server implemented filter functions. The method corresponds to IOPCEventServer::QuearyAvailableFilters(). Member Description return Filter specification flagword. create_subscription() Creates a subscription management object. An invalid state will give an exception. Member Description subscription_spec State wanted for the subscription. revised_subscr_spec State accepted by the server. return The new subscription manager. Set up Subscription query_available_filters( ) : Client:Client : DAIS::AlarmsAndEvents::Subscription::IHome:DAIS::AlarmsAndEvents::Subscription::IHome : DAIS::AlarmsAndEvents::Subscription::Manager:DAIS::AlarmsAndEvents::Subscription::ManagerCheck what filters are supported by the server create_subscription( ) callback(DAISCallback) select_returned_properties( ) Set the callback for server to use set_filter( ) Set up filter to get only wanted event notifications Select what property values to be included in event notifications Do some browsing to prepare for setting up the filter. Browse for reasons, areas and sources Do some browsing to prepare for selecting properties Figure 5-6 Set up subscription interaction Refresh : Client: Client : DAIS::AlarmsAndEvents::Subscription::Manager: DAIS::AlarmsAndEvents:backbac:Subscription::Manager : DAIS::AlarmsAndEvents::IO::Call: DAIS::AlarmsAndEvents::IO::Callkrefresh( ) Initiate transfer of the currently active source conditions on_event( ) on_event( ) on_event( ) As many notifications sent as needed to report all source conditions Figure 5-7 Refresh interaction An area is a specialization of a node and is a collection of other areas or sources. Areas are intended for arbitrary hierarchical structuring of sources for various usages (for example, areas for authority or responsibility). DAIS::AlarmsAndEvents::Area::IHome is used for browsing the area hierarchy. The find methods in the interface correspond to the IOPCEventAreaBrowser with the filter type parameter set to OPC_AREA. The interface also implements the following OPC methods: • IOPCEventServer::EnableConditionByArea() • IOPCEventServer::DisableConditionByArea(). DAIS::AlarmsAndEvents::Area::IHome <> get_root() enable_condition() disable_condition() DAIS::Node::IHome (from DAISNode) <> find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() AreaSourceComponent id : ResourceID name : string description : string Area Source (from DAISAESource) 11 0..0.n.n 0..0.n.n +parent Figure 5-8 DAIS alarms and events area IDL in UML //File: DAISAEArea.idl #ifndef _DAIS_AEAREA_IDL #define _DAIS_AEAREA_IDL #pragma prefix "omg.org" #include #include module DAIS { module AlarmsAndEvents { module Area { interface IHome : Node::IHome { ResourceID get_root(); ResourceErrors enable_condition ( in ResourceIDs areas ); ResourceErrors disable_condition ( in ResourceIDs areas ); }; };};}; #endif // _DAIS_AEAREA_IDL IHome An object for browsing areas. get_root() A method to get the root node for the area tree. Member Description return The root area node. enable_condition() A method for enabling the sources contained by the specified areas. The corresponding OPC method is IOPCEventServer::EnableConditionByArea(). Member Description areas A sequence of area identifications. return The resource identifications that failed. disable_condition() A method for disabling the sources contained by the specified areas. The corresponding OPC method is IOPCEventServer::DisableConditionByArea(). Member Description areas A sequence of area identifications. return The resource identifications that failed. Browse areas get_root( ) : Client: Client : DAIS::AlarmsAndEvents::Area::IHome: DAIS::AlarmsAndEvents::Area::IHome : DAIS::Node::Iterator:DAIS::Node::IteratorGet the root of all areas find_by_parent( ) next_n( ) Repeat find_by_parent and next_n until the areas are explored Figure 5-9 Browse areas interaction A source is a specialization of a node and is contained by areas. A source represents an object that generates alarms and events. A source may have source conditions. The find methods in the interface correspond to the IOPCEventAreaBrowser with the filter type parameter set to OPC_SOURCE. The interface also implements the following OPC methods: • IOPCEventServer::TranslateToItemIDs • IOPCEventServer::EnableConditionBySource() • IOPCEventServer::DisableConditionBySource() DAIS::Node::IHome (from DAISNode) <> find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() DAIS::AlarmsAndEvents::Source::IHome <> translate_to_item_ids() enable_conditions() disable_conditions() Source 0..n 1 0..n10..n 1 0..n1Area (from DAI SAEArea) AreaSourceComponent (from DAI SAEArea) id : ResourceID name : string description : string 0..n +parent 0..n SourceCondition (from DAISAESo urceCon di tion) condition_op_state : DAISConditionOpState quality : DAIS::Quality last_acknowledge : DateTime condition_last_active : DateTime condition_space_last_active : DateTime condition_space_last_inactive : DateTime acknowledger_name : string comment : string Figure 5-10 DAIS alarms and events source IDL in UML //File: DAISAESource.idl #ifndef __DAIS_AESOURCE_IDL #define __DAIS_AESOURCE_IDL #pragma prefix "omg.org" #include #include module DAIS { module AlarmsAndEvents { module Source { interface IHome : Node::IHome { exception PropertyDidNotTranslate{string reason;}; ItemIDs translate_to_item_ids (in ResourceID source,in ResourceID category,in PropertyIDs properties ) raises (PropertyDidNotTranslate); ResourceErrors enable_conditions (in ResourceIDs sources); ResourceErrors disable_conditions (in ResourceIDs sources ); };};};}; #endif // __DAIS_AESOURCE_IDL IHome An object for browsing sources at areas. PropertyDidNotTranslate An exception telling that one or more properties did not translate to ItemIDs. translate_to_item_ids() A method for translation of information about a source to ItemIDs for use with the data access interface. If one or more properties did not translate to ItemIDs, an exception is raised. The corresponding OPC method is IOPCEventServer::TranslateToItemIDs(). Member Description source The identification of the source. category The identification of the category. properties A sequence of properties for which ItemIDs are wanted. return A sequence of ItemIDs. Properties that did not translate to ItemIDs are returned as empty ItemIDs. enable_conditions() A method for enabling the specified sources. The corresponding OPC method is IOPCEventServer::EnableConditionBySource(). Member Description sources A sequence of area identifications. return The resource identifications that failed. disable_conditions() A method for disabling specified sources. The corresponding OPC method is IOPCEventServer::DisableConditionBySource(). Member Description sources A sequence of area identifications. return The resource identifications that failed. Browse sources : Client: Client : DAIS::AlarmsAndEvents::Source::IHome: DAIS::AlarmsAndEvents::Source::IHome : DAIS::Node::Iterator:DAIS::Node::Iteratorfind_by_parent( ) Get all sources that has a given area as parent next_n( ) Repeat getting all found sources from the iterator and continue with another area as parent to sources. Repeat this until all wanted sources are explored. For each source inspect the conditions it might have, refer to ConditionSpace Figure 5-11 Browse sources interaction A condition space describes a set of conditions; that is, it is a space of conditions. Each condition space is associated with a particular sub-reason of the main reason ConditionReason. Each condition has logic describing when the condition is active. The logic is described in a little language having the following constructs: • arithmetic operators • logic operators • references to properties The referred properties must be included in the set of properties defined by the associated reason. The little language grammar is server specific and is outside the scope of this specification. Transitions describe what transitions between conditions are allowed. The interface does not support exploration of the transitions. In OPC the ConditionSpace interface is implemented by the methods: • IOPCEventServer::QueryConditionNames() • IOPCEventServer::QuerySubConditionNames() . DAIS::AlarmsAndEvents::ConditionSpace::IHome <> find() find_each() find_by_reason() find_by_source() get_names() get_ids() 11 0..0.n.n 1..1.n.n 11 ConditionSpace id : ResourceID name : string description : string Condition id_number : unsigned long name : string description : string severity : unsigned long condition_logic : string ConditionCategory (from DAISAECategory) 1..1.n.n +conditions 0..0.n.n 0..n0..n Transition 11 11 0..0.n.n ConditionEvent (from DAISAEIO) Figure 5-12 DAIS alarms and events condition space IDL in UML //File: DAISAEConditionSpace.idl #ifndef _DAIS_AECONDITION_SPACE_IDL #define _DAIS_AECONDITION_SPACE_IDL #pragma prefix "omg.org" #include module DAIS {module AlarmsAndEvents {module ConditionSpace { struct ConditionDescription { unsigned long id_number; string name; string condition_logic; unsigned long severity; string descrip; }; typedef sequence ConditionDescriptions; struct Description { ResourceID id; string name; string descrip; ConditionDescriptionsconditions; }; typedef sequence< Description >Descriptions; interface IHome { exception UnknownResourceID {string reason;}; Description find ( in ResourceID condition_space ) raises (UnknownResourceID); Descriptions find_each ( in ResourceIDs condition_spaces ) raises (UnknownResourceID); Descriptions find_by_category ( in ResourceID category ) raises (UnknownResourceID); Descriptions find_by_source ( in ResourceID source ) raises (UnknownResourceID); Strings get_names ( in ResourceIDs condition_spaces ); ResourceIDs get_ids ( in Strings names ); };};};};#endif // _DAIS_AECONDITION_SPACE_IDL ConditionDescription A struct describing a condition. Member Description id_number A numeric identification unique within the condition space. name The name of the condition. condition_logic The logic telling when the condition is active. Refer to Section 5.2.7.3, “Condition Logic,? on page 5-38 for a description. severity Severity is a number between 1 and 1000 having the following meaning: • Low severity 1-200 • Medium low severity 201-400 • Medium severity 401-600 • Medium high severity 601-800 • High severity 801-1000 description A text that to be included in event notifications when the condition is active. Description A struct describing the condition space. Member Description id A ResourceID identifying the condition space. name The name of the condition space. description A description of the condition space. conditions A sequence of the conditions creates the condition space. In OPC the conditions are called sub-conditions and are retrieved by the method IOPCEventServer::QuerySubConditionNames(). IHome An object for browsing the condition spaces defined by a server. find() A method for getting the description of a condition space. Parameter Description condition_space A ResourceID identifying a condition space. return The condition space description. find_each() A method for getting the descriptions for a number of condition spaces. Parameter Description condition_spaces A sequence of ResourceID identifying condition spaces. return A sequence of condition space descriptions. find_by_category() A method for finding all condition spaces defined for a category. The corresponding OPC method is IOPCEventServer::QueryConditionNames(). Parameter Description category A ResourceID identifying the category for which to get the condition spaces. return A sequence of condition space descriptions. find_by_source() A method for finding all condition spaces defined for a source. The corresponding OPC method is IOPCEventServer::QuerySourceConditions(). Parameter Description source A ResourceID identifying the source for which to get the condition spaces. return A sequence of condition space descriptions. get_names() A method translating a number of condition space identifications into name strings. Parameter Description condition_spaces A sequence of ResourceID identifying condition spaces. return A sequence of condition space names. Non-translated identifications are returned as empty strings. get_ids() A method translating a number of condition space names into ResourceIDs. Parameter Description names A sequence of condition space names. return A sequence of condition space ResourceIDs. Non- translated identifications are returned as NULL IDs. Browse condition space by source : Client: Client : DAIS::AlarmsAndEvents::ConditionSpace::IHome: DAIS::AlarmsAndEvents::ConditionSpace::IHomefind_by_source( ) Get all condition space descriptions for one source. Explore each condition space from the retrieved descriptions. Figure 5-13 Browse condition space by source interaction Browse condition space by category : Client: CliAlrmsAndEvents::ConditionSpace::IHomeAent : DAIS::a: DAIS::larmsAndEvents::ConditionSpace::IHome find_by_category( ) Get all condition space description for one category. Explore each condition space from the retrieved descriptions. Figure 5-14 Browse condition space by category interaction The reduced XPath language as defined in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 is used to describe the condition_logic. This allows description of a path through a data structure picking up property values to be used in a logical expression. A common case is property values at objects associated with a source, hence the starting point for navigation is the source. An example from the CIM model where the Measurement is the source can be found in Figure 4-3 on page 4-6. Examples how to use DAIS_Expressions starting from a source are shown below: Measurement.value < 500 assuming that the tested value is an element at the source. MeasurementValue[id(MeasurementValue.MeasurementValueSource)/label='telemetry']/ MeasurementValue.value < id(Measurement.LimitSets)[LimitSet.label = 'summer']/Limit[label = 'highalarm']/Limit.value Based on the model in Figure 4-3 on page 4-6, the XML example in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 and the source as a Measurement. A source condition associates a source with a condition space. A source condition holds the current information specific to a source using a particular condition space for the supervision. A source condition has no own identification and is identified by its associated source and condition space. Information about a source condition is accessed through its home object. In OPC a source condition is sometimes called an instance of a condition. In OPC the SourceCondition interface is implemented by the methods: • IOPCEventServer::QuerySourceConditions() • IOPCEventServer::AckCondition(). . DAIS::AlarmsAndEvents::SourceCondition::IHome <> find() find_each() ack_condition() Source (from DAISAE Source) 11 0..0.n.n 11 0..0.n.n 0..0.n.n 11 11 ConditionSpace (from DAISAE Condi ti onSpace) id : ResourceID name : string description : string Condition (from DA ISAECondi ti onSpace) id_number : unsigned long name : string description : string severity : unsigned long condition_logic : string SourceCondition condition_op_state : DAISConditionOpState quality : DAIS::Quality last_acknowledge : DateTime condition_last_active : DateTime condition_space_last_active : DateTime condition_space_last_inactive : DateTime acknowledger_name : string comment : string 0..0.n +active_condition .n Figure 5-15 DAIS alarms and events source condition IDL in UML //File: DAISAESourceCondition.idl #ifndef _DAIS_AESOURCE_CONDITION_IDL #define _DAIS_AESOURCE_CONDITION_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { module SourceCondition { struct Id { ResourceID source; ResourceID condition_space; }; typedef sequenceIds; struct Description { Id source_condition;SourceConditionOpState source_condition_op_state;unsigned long active_condition;string ac_logic;unsigned long ac_severity;string ac_description;Quality dais_quality;DateTime last_acknowledge;DateTime condition_last_active;DateTime condition_space_last_active;DateTime condition_space_last_inactive;string acknowledger_name;string comment;PropertyValues property_values; };typedef sequence< Description > Descriptions; struct AcknowledgeSpec { Id source_condition; DateTime active_time; EventID cookie; }; typedef sequenceAcknowledgeSpecs; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions c_descriptions ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownId {string reason;}; exception UnknownPropertyID {string reason;}; Description find ( in Id source_condition, in PropertyIDs properties ) raises (UnknownId, UnknownPropertyID); Iterator find_each( in Ids source_conditions, in PropertyIDs properties ) raises (UnknownId, UnknownPropertyID); Descriptions ack_condition ( #endif // _DAIS_AESOURCE_CONDITION_IDL Id in string acknowledger_name, in string comment, in AcknowledgeSpecs ack_spec ); }; };};}; A struct that identifies a source condition. Member Description source The ResourceID identifying the associated source. condition_space The ResourceID identifying the associated condition space. Description A struct describing the source condition. Member Description id The Id identifying the source condition. source_condition_op_state The DAISSourceConditionOpState as described in Section 5.2.2, “Alarms and Events Common IDL Definitions,? on page 5-7. active_condition The identification number of the currently active condition. ac_logic The condition logic from the active condition. ac_severity The severity from the active condition. ac_description The description from the active condition. dais_quality The quality is evaluated from the qualities from the properties used to evaluate the condition logic. last_acknowledge The last time the condition was acknowledged. condition_last_active Time for the latest condition transition. condition_space_last_active The last time when the condition space became active. After this time more condition transitions may occur. The condition_last_active will then be later than condition_space_last_active. condition_space_last_inactive The last time when the condition space became inactive; that is, no conditions are active. acknowledger_name The name of the client making an acknowledge. comment A comment passed by the client making an acknowledge. property_values A sequence of property values as selected by the Manager::select_returned_properties call. AcknowledgeSpec A struct specifying an alarm to acknowledge. Member Description source_condition The Id identifying the source condition for which to acknowledge an alarm. active_time The time when the alarm activated. cookie A identification of the alarm. Iterator A standard iterator. Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. IHome An object for browsing and accessing source conditions. UnknownDAISSourceConditionID An exception telling that the source condition identification was not recognized. UnknownPropertyID An exception telling that a property identification was not recognized. find() A method for getting the description of a source condition. The corresponding OPC method is IOPCEventServer::GetConditionState(). Parameter Description source_condition A ResourceID identifying a source condition. return The source condition description. find_each() A method for getting the descriptions for a number of source conditions. Parameter Description condition_spaces A sequence identifying source conditions. return A sequence of source condition descriptions. ack_condition() A method to acknowledge a number of source condition alarms. The corresponding OPC method is IOPCEventServer::AckCondition(). Parameter Description acknowledger_name The name of the client making the acknowledge. comment A comment to be added to source condition and the event. ack_spec A sequence specifying the alarms to acknowledge. return A sequence containing descriptions for the acknowledged source conditions. Inspect a specific source condition : Client: Client : D A IS :: AlarmsA ndEvent s::S ourc eC ondition:: IH ome:DAIS::AlarmsAndEvents::SourceCondition::IHomefind( ) Get all det ails on a s pec ific source c ondit on Figure 5-16 Inspect a specific source condition interaction Acknowledge alarm : Client: Client : DAIS::AlarmsAndEvents::SourceCondition::IHom e:DAIS::AlarmsAndEvents::SourceCondition::IHomeack_condition( ) Acknolwedge a set of source conditions in one call Figure 5-17 Acknowledge alarm interaction These are definitions for manipulating categories. A category describes the content of an event. Categories are organized in a two level hierarchy where the first level has the three mandatory main categories; simple, condition, and tracking. Simple category does not have a condition space (refer to ConditonSpace). Generation of simple category alarms or events is coded into some software function and cannot be configured. Typical simple categories are program errors, hardware device failures, etc. Sources of different types (e.g., breaker position, breaker current, generator active power, etc.) may have different ways an alarm or event is generated (e.g., breaker trip, breaker over current, generator active power generation overload, etc.). Condition categories are used to describe source type specific alarm and event contents. The alarm and event generation for a condition category is configured using condition spaces and several condition spaces can be created for the same condition category. This corresponds to variations in the way the alarms and events are generated using different condition logics. Alarms or events due to operator actions or control functions (intended alarms or events rather than spontaneous) use tracking categories. A category has a set of properties associated with it. Some or all of the properties may be included in event notifications. The properties come from the source type and may be used by the logic generating an event notification. The get_main_ category () method is used to obtain the three main categories. The find_by_parent() is used to get the child categories. Categories at this second level correspond to the OPC EventCategories. The labels for the three main reasons are “DAIS_CONDITION_CATEGORY,? “DAIS_TRACKING_CATEGORY,? and "DAIS_SIMPLE_CATEGORY.? In OPC the Category interface is implemented by the methods IOPCEventServer::QueryEventCategories() and IOPCEventServer::QueryEventAttributes(). TrackingCategory SimpleCategory ConditionCategory DAIS::AlarmsAndEvents::Category::IHome get_main_categories() get_event_properties() <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() (from DAISNode) <> Node id : ResourceID label : string type : ResourceID (f rom DA ISNo de) 1 0..10..nCategory Figure 5-18 DAIS alarms and events categories IDL in UML //File: DAISAECategory.idl #ifndef _DAIS_AECATEGORY_IDL #define _DAIS_AECATEGORY_IDL #pragma prefix "omg.org" #include module DAIS {module AlarmsAndEvents {module Category{ interface IHome : Node::IHome { Node::Descriptions get_main_categories (); PropertyIDs get_event_properties (in ResourceID category ); }; };};}; #endif // _DAIS_AECATEGORY_IDL IHome IHome is an object for browsing categories. Most of the browsing functionality is inherited from DAIS::Node. get_main_categories() Get the three main categories; simple, condition, and tracking. The three main categories appear as three different roots. Parameter Description return The descriptions for the three main categories. The labels for them are: • “DAIS_CONDITION_CATEGORY? • “DAIS_TRACKING_CATEGORY? • “DAIS_SIMPLE_CATEGORY? get_event_properties() Get all properties that are used in the supervision of the source type for a specific category. The corresponding OPC method is IOPCEventServer::QueryEventAttributes(). Parameter Description category The identification of the categories to get the properties for. return A sequence of property identifications. Browse categories get_main_reasons( ) : DAIS::AlarmsAndEvents::Category::IHome:DAIS::AlarmsAndEvents::Category::IHome: Client: ClientGet the three main reasons find_by_parent( ) Get the sub reasons for one main reason. For each sub reason explore 1) the condition spaces that are defined, refer to ConditionSpace 2) the properties that are used in supervision of sources Continue and explore all main reasons Figure 5-19 Browse category interaction Browse properties : DAIS::Alarm sAndE vents::Category::IHom e:DAIS::AlarmsAndEvents::Category::IHome: Client: ClientGet the three m ain categories Get the sub categories for one main category. For each sub category explore 1) the condition spaces that are defined, refer to ConditionSpace 2) the properties that are used in supervision of sources Continue and explore all main categories get_main_categories( ) find_by_parent( ) Figure 5-20 Browse properties interaction The IO interface for alarms & events only supports callbacks and the client shall implement callback. The event notifications sent over the callback are of three different formats corresponding to the three main categories (simple event, condition event, and tracking event). All three event formats have the common part Event. The tracking event has additional information on the operator and the condition event has additional information on the source condition causing the notification. In OPC the IO interface is implemented by the interface IOPCEventSink Source (from DAISAESource) Event source : ResourceID source_pathname : string time_stamp : DateTime message : string event_format : EventFormat category : ResourceID category_name : string severity : unsigned long property_values : PropertyValues 11SimpleCategory (from DAISAECa tegory) SimpleEvent 11ConditionCategory (from DAISAECategory ) ConditionEvent condition_space_name : string condition_space : ResourceID condition_name : string condition_number : unsigned long ack_required : boolean active_time : DateTime event_id : EventID change_specification : ChangeSpec source_condition_op_state : SourceConditionOpState dais_quality : Quality TrackingCategory (from DAISAECategory ) TrackingEvent actor_name : string 11DAIS::AlarmsAndEvents::IO::Callback <> on_event() on_read_complete() 11 Figure 5-21 DAIS alarms and events IO IDL in UML //File: DAISAEIO.idl#ifndef _DAIS_AEIO_IDL#define _DAIS_AEIO_IDL#pragma prefix "omg.org"#include module DAIS {module AlarmsAndEvents {module IO { typedef unsigned long ChangeSpec;const ChangeSpec CHANGE_ACTIVE_STATE = 0x0001; const ChangeSpec CHANGE_ACK_STATE = 0x0002; const ChangeSpec CHANGE_ENABLE_STATE = 0x0004; const ChangeSpec CHANGE_QUALITY = 0x0008; const ChangeSpec CHANGE_SEVERITY = 0x0010; const ChangeSpec CHANGE_CONDITION = 0x0020; const ChangeSpec CHANGE_MESSAGE = 0x0040; const ChangeSpec CHANGE_ATTRIBUTE = 0x0080; struct SimpleEvent { ResourceID source; string source_pathname; DateTime time_stamp; string message; EventFormat event_format; ResourceID category; string category_name; unsigned long severity; PropertyValues property_values; }; struct TrackingEvent { string actor_name; }; struct ConditionEvent { string condition_space_name; ResourceID condition_space; string condition_name; unsigned long condition_number; boolean ack_required; DateTime active_time; EventID event_id; ChangeSpec change_specification; SourceConditionOpState source_condition_op_state; Quality dais_quality; }; struct Event { SimpleEvent simple_event; TrackingEvent tracking_event; ConditionEvent condition_event; };typedef sequence Events; interface Callback{ void on_event (in boolean refresh,in boolean last_refresh,in Events the_events ); void on_read_complete (in Events the_events,in unsigned long transaction_id ); }; };};}; #endif // _DAIS_AEIO_IDL ChangeSpec A flag word having a number of flags telling what change caused the event notification. Flag Description CHANGE_ACTIVE_STATE Alarm active has changed. CHANGE_ACK_STATE Alarm acknowledge has changed. CHANGE_ENABLE_STATE Enable has changed. CHANGE_QUALITY The quality has changed. CHANGE_SEVERITY The severity has changed. CHANGE_CONDITION A condition has become active/inactive. CHANGE_MESSAGE The message has been updated. CHANGE_ATTRIBUTE An attribute value has changed. SimpleEvent A struct holding the simple event data. Member Description source The identification of the source for which the event notification was created. source_pathname The full pathname of the source. time_stamp Time of the event occurrence - for conditions, time that the condition transitioned into the new state or condition. For example, if the event notification is for acknowledgment of a condition, this would be the time that the condition became acknowledged. message Event notification message describing the event. event_format The identification for one of the three main formats. category The identification of the sub-category why the event notification was sent. category_name The label for the sub-category. severity The severity for the event, a number between 0 and 1000. property_values A sequence of property values as selected by the select_returned_properties() method. TrackingEvent A struct holding tracking event data. Member Description actor_name The name of the actor or operator causing the event notification. ConditionEvent A struct holding the condition event data. Member Description condition_space_name The name of the condition space that caused the event notification. condition_space Identification of the condition space. condition_name The name of the condition that caused the event notification. condition_number Identification of the condition. ack_required An indication that an alarm is generated and that an acknowledgment is required. active_time The time when the condition became active. event_id An identification of the event notification. change_specification Indicates to the client which properties of the condition have changed. source_condition_op_state The new state for the source condition. quality The quality. Event A struct composed of the three above event structs. The simple event struct always contains valid information and which of the tracking or condition event structs are valid is decided from the main_reason simple event member. Member Description simple_event The simple event. tracking_event The tracking event. condition_event The condition event. Callback The callback object implemented by the client and used by the server to send event notifications. on_event() The callback method. Parameter Description refresh Indicates if this callback is due to a refresh. last_refresh Indicates if this callback is the last in a sequence initiated by a refresh. the_events A sequence of event notifications. return None. on_read_complete() A callback method for the async_read_history() method. After an async_read_history() call from a client the server will deliver the historical events using this method. There is no corresponding OPC method. Parameter Description the_events A sequence of historical events. transaction_id The transaction number matching the client call number. Event notification callbacks : DAIS::Alarm sAndEvents::IO::Callback: DAIS::AlarmsAndEvents::Ints:Subscription::M anagerntO::Callback: DAIS::AlarmsAndEve:: DAIS::AlarmsAndEves::Subscription::Manageron_event( ) on_event( ) The on_event method is called by the server at 1) expiration of the subscription buffer_time timeout 2) subscription event buffer full For alarms the client may want to call SourceCondition::ack_alarm() to acknowledge. A ll inform ation needed for doing this is found in the event notifications. Figure 5-22 Event notification callbacks interaction Refresh callbacks : DAIS::AlarmsAndEvents::IO::Callback: DAIS::AlarmsAndEvents::IO::CallbackOn_event is called as response to a refresh. All refresh calls are made with the refresh parameter set and the last call also has the last_refresh parameter set. : DAIS::AlarmsAndEvents::Subscription::Manager:DAIS::AlarmsAndEvents::Subscription::Manageron_event( ) Figure 5-23 Refresh callbacks interaction Alarms and events are generated by a source represented by Source. A source might be a single measurement, a collection of measurements, or some other object. A collection of measurements may represent a complex real world object like a generator or some control function for the generator. A source has a name property. The source is also associated with a type that describes any additional properties. If a DAIS server implements both data access and alarms & events, a client shall expect there is a mapping between sources and nodes. A client shall however not make assumptions on how the mapping is made and use the method translate_to_item_ids() to get the mapping from the server. Sources are organized in areas represented by Area. An area typically represents area of responsibility concerning supervision and operation of sources. Areas may however also be used for other groupings of sources. Areas can be hierarchically structured to allow creation of hierarchically organized responsibilities. Multiple views of areas are supported. Alarms and events are categorized. Category represents the categories. Three main categories are defined and must be implemented by a server: • simple - describing events that do not have an explicitly modeled condition space. • tracking - describing events generated due to an operator action. • condition - describing events generated based on an explicitly modeled condition space. The categories simple and tracking are used for events, and the category condition is used for alarms. For each main category it is possible to define a number of sub-categories. A server is free to implement any sub-categories. Each type of source is expected to be associated with at least one main category and one or more sub-categories for each main category. The main categories are not expected to have an association with a source type. Subcategories however are all expected to have an associated source type. A Condition category is associated with one or more condition spaces. ConditionSpace represents a condition space. Depending on how limits are applied to the properties defined by the type associated with a condition category it is possible to create a space consisting of different discrete conditions. Condition describes each discrete condition. A condition space will have a number of conditions defined for it. A Transition describes each possible transition between a pair of conditions. The alarms & event session does not however provide any methods for direct access of transitions. When a transition is traversed a condition event is generated. A source may be associated with one or more condition spaces. Each such association has status information describing the current condition. The association and its data are called SourceCondition. The source condition is identified by its associated source and condition space. A source is of a specific type (e.g., measurement, breaker, generator, tank, etc.) and the type has one or more properties in the same way as a node (refer to Section 4.1.1, “Nodes, Items, Types, and Properties,? on page 4-2). A category may have any number of properties associated with it. An alarm or event may contain values for the properties associated with the corresponding category. This is used to convey additional server specific information with alarms and events. Specification of what properties are associated with categories is outside the scope of this specification. The described classes are shown in Figure 5-2. The attributes are described later with the description of the interfaces. 0..0.n.n AreaSourceComponent (from DAISAEArea) id : ResourceID name : string description : string Area Source (from DAISAEArea ) (from DAISAESourc e) +aggregated_types +parent 0..n0..n 0..0.n.n Type (from DAIST ype) 0..0.n.n 11 1..n1..n 11 0..0.n.n Property (from DAISProperty) 0..n0..n SourceCondition (from DA I S AES o urceCon di t ion) condition_op_state : DAISConditionOpState quality : DAIS::Quality last_acknowledge : DateTime condition_last_active : DateTime condition_space_last_active : DateTime condition_space_last_inactive : DateTime acknowledger_name : string comment : string 0..0.n.n 0..0.n.n 0..n0..n 11 1..n 11..n1 1..n1..n 0..0.n.n 11 +conditions ConditionSpace (from DAISAECondition Space) id : ResourceID name : string description : string Condition (from DAISAECondition Space) id_number : unsigned long name : string description : string severity : unsigned long condition_logic : string SimpleCategory (fro m DAISAECate gory) TrackingCategory (fro m DAISAECate gory) ConditionEvent (from DAISAEIO) ConditionCategory (fro m DAISAECate gory) 11Category (f ro m DAIS A ECateg ory) 11 0..n0..n +active_condition 11 Transition (from DAISAECo nditionSp ac e) 0..n0..n Figure 5-2 DAIS Alarms and Events Information Model The objects in DAIS alarms and events has the following mapping to OPC alarms and events objects. DAIS A&E object OPC A&E object Source Source Area Area Property EventAttribute Category EventCategory The categories; simple, tracking and condition EventType ConditionSpace Condition Condition SubCondition SourceCondition SourceCondition In OPC there is a recommendation of what properties are expected to be supported by an alarm & event server. The recommended properties are shown in Table 5-1. The column names correspond to the attributes in the Property class. Table 5-1 Recommended Properties Table 5-1 Recommended Properties label id canonical_ data_type description Condition Status 300 STRING_TYPE The current alarm or condition status associated with the Item (for example, “NORMAL,? “ACTIVE,? “HI ALARM?). Alarm Quick Help 301 STRING_TYPE A short text string providing a brief set of instructions for the operator to follow when this alarm occurs. Alarm Area List 302 STRING_TYPE sequence An array of strings indicating the plant or alarm areas that include this ItemID. Primary Alarm Area 303 STRING_TYPE A string indicating the primary plant or alarm area including this ItemID. Condition Logic 304 STRING_TYPE An arbitrary string describing the test being performed (for example, “High Limit Exceeded? or “TAG.PV >= TAG.HILIM?). Refer to Section 5.2.7.3, “Condition Logic,? on page 5-38. Limit Exceeded 305 STRING_TYPE For multistate alarms, the condition exceeded (for example, HIHI, HI, LO, LOLO). Deadband 306 DOUBLE_TYPE Deadband HiHi Limit 307 DOUBLE_TYPE HiHi Limit Hi Limit 308 DOUBLE_TYPE Hi Limit Lo Limit 309 DOUBLE_TYPE Lo Limit LoLo Limit 310 DOUBLE_TYPE LoLo Limit Rate of Change Limit 311 DOUBLE_TYPE Rate of Change Limit Deviation Limit 312 DOUBLE_TYPE Deviation Limit 3124999 Reserved by OPC In OPC there is a recommendation of what properties are expected to be supported by an alarm & event server. The recommended properties are shown in Table 5-1. The column names correspond to the attributes in the Property class. Table 5-1 Recommended Properties Table 5-1 Recommended Properties label id canonical_ data_type description Condition Status 300 STRING_TYPE The current alarm or condition status associated with the Item (for example, “NORMAL,? “ACTIVE,? “HI ALARM?). Alarm Quick Help 301 STRING_TYPE A short text string providing a brief set of instructions for the operator to follow when this alarm occurs. Alarm Area List 302 STRING_TYPE sequence An array of strings indicating the plant or alarm areas that include this ItemID. Primary Alarm Area 303 STRING_TYPE A string indicating the primary plant or alarm area including this ItemID. Condition Logic 304 STRING_TYPE An arbitrary string describing the test being performed (for example, “High Limit Exceeded? or “TAG.PV >= TAG.HILIM?). Refer to Section 5.2.7.3, “Condition Logic,? on page 5-38. Limit Exceeded 305 STRING_TYPE For multistate alarms, the condition exceeded (for example, HIHI, HI, LO, LOLO). Deadband 306 DOUBLE_TYPE Deadband HiHi Limit 307 DOUBLE_TYPE HiHi Limit Hi Limit 308 DOUBLE_TYPE Hi Limit Lo Limit 309 DOUBLE_TYPE Lo Limit LoLo Limit 310 DOUBLE_TYPE LoLo Limit Rate of Change Limit 311 DOUBLE_TYPE Rate of Change Limit Deviation Limit 312 DOUBLE_TYPE Deviation Limit 3124999 Reserved by OPC The dependencies among the different IDL files are shown in Figure 5-3. DAISAESession DAISAESubscription DAISAEIO DAISAESource Condition DAISConditionSpace DAISAEReason DAISAESource DAISAEArea DAISServer (from Server) DAISSession (from Com m on) DAISProperty (from Common) DAISNode (from Common) DAISCommon (from Common) DAISAECommon DAISType (from Com m on) Figure 5-3 Dependencies between alarms and events IDL files // File: DAISAECommon.idl #ifndef _DAIS_AECOMMON_IDL #define _DAIS_AECOMMON_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { typedef ResourceID EventID; struct ResourceError { Error err; ResourceID id; string reason; }; typedef sequence ResourceErrors; // error codesconst Error RES_ERROR_DAISOK= 0;const Error RES_ERROR_UNKOWN_RESOURCE= 1; typedef unsigned longSourceConditionOpState;const SourceConditionOpStateCONDITION_ENABLED= 0x0001;const SourceConditionOpStateCONDITION_ACTIVE= 0x0002;const SourceConditionOpStateCONDITION_ACKED= 0x0004; typedef unsigned short EventFormat;const EventFormat OPC_SIMPLE_EVENT = 0x0001;const EventFormat OPC_TRACKING_EVENT = 0x0002;const EventFormat OPC_CONDITION_EVENT= 0x0004;const EventFormat OPC_ALL_EVENTS = 0x0007;};};#endif // _DAIS_AECOMMON_IDL EventID A ResourceID uniquely identifying an event notification. ResourceError A struct for reporting of resource related errors. Member Description err An error code as described below. id The identification of the resource. reason An additional text explaining the error. ResourceErrors ResourceErrors is a sequence containing errors. If no errors are present, no entry shall be included in the sequence rather than including a large number of no errors. An empty sequence means no errors. Error The error codes for ResourceError. Member Description RES_ERROR_DAISOK No error. RES_ERROR_UNKOWN_RESOURCE The resource was not found. SourceConditionOpState Flag word holding for the operational state of a SourceCondition. The definitions of the state variable in the flag word are listed below. Flag Description CONDITION_ENABLED The Condition is enabled and supervision is active. CONDITION_ACTIVE The Condition is active; that is, the supervision has determined that a fault has activated the condition. CONDITION_ACKED The Condition alarm has been acknowledged. The combinations of the state variables result in eight states. The valid SourceCondition operational states are listed below. State Description Disabled Not supervised by server. Enabled, Inactive, Acked Supervised by server, no fault detected and all alarms are acknowledged. Enabled, Inactive, Unacked Supervised by server, no fault detected and unacknowledged alarms exist. Enabled, Active, Unacked Supervised by server, a fault is detected and unacknowledged alarms exist. Enabled, Active, Acked Supervised by server, a fault is persistent and all alarms are acknowledged. When enabled the state {Enabled, Inactive, Acked} is entered and from there the supervision will generate the appropriate state depending on the result of the supervision. Each state change results in sending an alarm and event notification. All notifications contain the state. EventFormat This constant tells the format of an event. Member Description OPC_SIMPLE_EVENT The event is a simple event. OPC_TRACKING_EVENT The event is a tracking event. OPC_CONDITION_EVENT The event is a condition event. OPC_ALL_EVENTS This constant value is used to ask for all event formats in a subscription set up. The DAIS::AlarmsAndEvents::Session object implements the alarms & events service on a per client basis. An alarm & event session object has a number of services provided by one singleton home object each. Each home object provides methods for manipulation of the data of the specific type they provide. The session object corresponds to an OPCEventServer object. DAIS::ShutdownCallback (from DAISSessi on) <> DAIS::AlarmsAndEvents::Session <> subscription_home() : DAIS::AlarmsAndEnvents::Subscription::Home area_home() : DAIS::AlarmsAndEvents::Area::IHome source_home() : DAIS::AlarmsAndEvents::Source::IHome condition_space_home() : DAIS::AlarmsAndEnvents::ConditionSpace::Home source_condition_home() : DAIS::AlarmsAndEvents::SourceCondition::IHome reason_home() : DAIS::AlarmsAndEvents::Category::IHome type_home() : DAIS::Type::IHome property_home() : DAIS::Property::IHome DAIS::Session (from DAISSessi on) <> status() : DAIS::SessionStatus 1 01callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() ..10..1 0..10..1 11 Client (f rom DA ISServ er) 11 DAIS::AlarmsAndEvents::Area::IHome (from DAISAEArea) <> 0..0.*.* 11 DAIS::AlarmsAndEvents::IO::Callback (f ro m DAISAE I O) <> 11 DAIS::AlarmsAndEvents::Source::IHome (f rom DA ISAE Sourc e) <> 0..0.1.1 11 11 DAIS::AlarmsAndEvents::ConditionSpace::IHome (from DAISAECondi ti onSpace ) <> DAIS::AlarmsAndEvents::SourceCondition::IHome (f ro m DA ISAE Sourc eConditi on) <> DAIS::AlarmsAndEvents::Category::IHome (from DAISAECategory) <> DAIS::AlarmsAndEvents::Subscription::IHome (from DAISAESu bscriptio n) <> 11 11 11 11 0.. 0..n DAIS::AlarmsAndEvents::Subscription::Manager (fro m DAISAESubsc ri pti on) <> 11 DAIS::Property::IHome (from DAISProperty) <> Figure 5-4 DAIS alarms and events session IDL in UML //File: DAISAESession.idl #ifndef _DAIS_AESERVER_IDL #define _DAIS_AESERVER_IDL #pragma prefix "omg.org" // Common Information#include #include #include // Events and Alarms#include #include #include #include #include #include #include module DAIS {module AlarmsAndEvents { interface Session : DAIS::Session { readonly attribute Subscription::IHome subscription_home; readonly attribute Area::IHome area_home; readonly attribute Source::IHome source_home; readonly attribute ConditionSpace::IHome condition_space_home; readonly attribute SourceCondition::IHome source_condition_home; readonly attribute Category::IHome category_home; readonly attribute Type::IHome type_home; readonly attribute Property::IHome property_home; };};}; #endif // _DAIS_AESESSION_IDL; Session Session is an object implementing the alarms & events functions. It inherits common functionality as shut down callbacks and session status from DAIS::AlarmsAndEvents::Session. subscription_home A read only attribute holding a reference to a singleton Subscription::IHome object. area_home A read only attribute holding a reference to a singleton Area::IHome object. source_home A read only attribute holding a reference to a singleton Source::IHome object. condition_space_home A read only attribute holding a reference to a singleton ConditionSpace::IHome object. source_condition_home A read only attribute holding a reference to a singleton SourceCondition::IHome object. category_home A read only attribute holding a reference to a singleton Category::IHome object. type_home A read only attribute holding a reference to a singleton Type::IHome object. property_home A read only attribute holding a reference to a singleton Property::IHome object. A DAIS::AlarmsAndEvents::Subscription::Manager is an object holding a filter specification set up by a client. The filter is used to specify what notifications shall be sent to the client. A server can support various filter functions and a client can ask the DAIS::AlarmsAndEvents::Subscription::IHome object what filter functions are supported. The subscription home is also used to create any number of subscription manager objects. Each subscription manager shall be associated with a client implemented callback object so that the server can send alarm and event notifications to the client. A server may optionally support an event history. The event history shall record all alarms and events appearing in a server. The method async_read_history() gives clients access to the event history. The size of the event history is server specific and outside the control of a client. In OPC the Subscription interface corresponds to the interface IOPCEventSubscription. DAIS::AlarmsAndEvents::Subscription::IHome query_available_filters() create_subscription() <> 0..0.1.1 11 DAIS::AlarmsAndEvents::IO::Callback (from DAISAEIO) <> 0..n0..n 11 DAIS::AlarmsAndEvents::Subscription::Manager callback() : DAIS::AlarmsAndEvents::IO::Callback callback(in callback : DAIS::AlarmsAndEvents::IO::Callback) set_filter() get_filter() select_returned_properties() get_returned_properties() refresh() asynch_read_history() cancel() get_state() set_state() clone() destroy() <> 11 0..0.n.n PropertySelection category : ResourceID properties : PropertyIDs 11 11 11 DAIS::AlarmsAndEvents::Subscription::FilterSpec reason_filter : ReasonFilter low_severity : unsigned long high_severity : unsigned long source_filter : SourceFilter type_filter : TypeIDs DAIS::AlarmsAndEvents::Subscription::State active : boolean buffer_time : unsigned_long max_size : unsigned long keep_alive_time : unsigned long 11 Figure 5-5 DAIS alarms and events subscription IDL in UML //File: DAISAESubscription.idl #ifndef _DAIS_AESUBSCRIPTION_IDL #define _DAIS_AESUBSCRIPTION_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { module Subscription { struct State { boolean active; unsigned long buffer_time; unsigned long max_size; unsigned long keep_alive_time; }; struct OPCSourceFilter { ServerItemIdentifications areas; ServerItemIdentifications sources; }; typedef short SourceFilterType;const SourceFilterType OPC_SOURCE_FILTER_TYPE = 1;const SourceFilterType XPATH_SOURCE_FILTER_TYPE = 2; union SourceFilter switch(SourceFilterType) { case OPC_SOURCE_FILTER_TYPE : OPCSourceFilter opc_source_filters; case XPATH_SOURCE_FILTER_TYPE : string xpath_source_filter; }; typedef short CategoryFilterType;const CategoryFilterType OPC_REASON_FILTER_TYPE = 1;const CategoryFilterType XPATH_REASON_FILTER_TYPE= 2; union CategoryFilter switch(ReasonFilterType) { case OPC_CATEGORY_FILTER_TYPE : ServerItemIdentifications opc_category_filters; case XPATH_CATEGORY_FILTER_TYPE : string xpath_category_filter; }; struct FilterSpec { EventFormat event_format; CategoryFilter category_filter; unsigned long low_severity; unsigned long high_severity; SourceFilter source_filter; ResourceIDs type_filter; }; struct PropSelection { ResourceID category; PropertyIDs properties; };typedef sequence PropSelections; enum ReadDirection { READ_FORWARDS, READ_BAKWARDS }; typedef unsigned long CancelID; interface Manager { exception BusyDueToRefresh{string reason;}; exception HistoryNotImplemented{string reason;}; attribute IO::Callback callback; void set_filter (in FilterSpec filer_spec) raises (BusyDueToRefresh); FilterSpec get_filter (); void select_returned_properties (in PropSelections prop_selections); PropSelections get_returned_properties (in ResourceIDs categories); CancelID refresh () raises (BusyDueToRefresh); CancelID async_read_history ( in DateTime start_time, in unsigned long number_of_events, in ReadDirection direction, in unsigned long transaction_id ) raises (HistoryNotImplemented); void cancel (in CancelID cancel_id); void refresh () raises (BusyDueToRefresh); void refresh_with_history (in DateTime start_time,in DateTime end_time ) raises (HistoryNotImplemented); void cancel_refresh (); State get_state (); State set_state ( in State subscription_spec Manager clone (); void destroy (); }; typedef unsigned longFilter;const Filter FILTER_BY_EVENT_FORMAT = 0x0001;const Filter FILTER_BY_CATEGORY = 0x0002;const Filter FILTER_BY_SEVERITY = 0x0004;const Filter FILTER_BY_AREA = 0x0008;const Filter FILTER_BY_SOURCE = 0x0010;const Filter FILTER_WITH_XPATH = 0x0020;const Filter FILTER_BY_SOURCE_TYPE = 0x0040; interface IHome{ Filter query_available_filters (); Manager create_subscription ( in State subscription_spec, out State revised_subscr_spec); };};};}; #endif // _DAIS_AESUBSCRIPTION_IDL State A struct describing the state for the subscription. Member Description active Indicates if the subscription is active; that is, is sending data on the call back interface. Events that are appearing in the server will be lost for clients connected to inactive subscriptions. buffer_time The requested buffer time in milliseconds. This is a minimum time - do not send event notifications any faster that this UNLESS max_size is greater than 0, in which case the server will send an event notification sooner to obey the max_size value. A value of 0 for buffer_time means that the server should send event notifications as soon as it gets them. This parameter along with the max_size parameter is used to improve communications efficiency between client and server. This parameter is a recommendation from the client, and the server is allowed to ignore the parameter. The server will return the buffer time it is actually providing in revised_buffer_time. max_size The requested maximum number of events that will be sent in a single callback. A value of 0 means that there is no limit to the number of events that will be sent in a single callback. Note that a value of max_size greater than 0, may cause the server to make callbacks more frequently than specified by buffer_time when a large number of events are being generated in order to limit the number of events to the max_size. This parameter is a recommendation from the client and the server is allowed to ignore this parameter. The server will return the actual number of events it is actually providing in revised_max_size. keep_alive_time The time in milliseconds for the server to send a callback to client. The intention is to indicate to the client that the server is alive and avoid the need to "poll" the server to check it is alive. If no data is available an empty message is sent. If the time is less than the buffer_time the buffer_time is used. OPCSourceFilter The struct specifies source filtering by enumerating the areas and sources the way OPC does it. Member Description areas A sequence of ResourceIDs for the areas that shall be notified. All sources below an area node will be notified. sources A sequence of ResourceIDs for sources that shall be notified. An empty sequence means all sources shall be notified. SourceFilter The union specifies OPCSourceFiltering or XPath filtering. A prerequisite for XPath filtering is that the area and source hierarchy has an XML mapping. The same mapping is used as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 with the additional comments: • an Area corresponds to a Node (Area inherits Node). • a Source corresponds to a Node (Source inherits Node). Member Description opc_source_filters An OPCSourceFilter xpath_source_filter An XPath filter. CategoryFilter The union specifies OPC style filtering or XPath filtering of categories. A prerequisite for XPath filtering is that the resource hierarchy has an XML mapping. The same mapping is used as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 with the additional comments: • a Resource corresponds to a Node (Resource inherits Node). Member Description opc_category_filters An OPCSourceFilter xpath_reason_filter An XPath filter FilterSpec A struct holding the specification for how the server shall filter notifications sent to the client. The struct is used to specify the filtering a client wants a server to do for it. All specified filter criterias shall be fulfilled for a notification to be sent. Member Description event_format An EventFormat bit mask specifying the event formats to be returned. reasons A sequence of CategoryFilter for the categories for which the client wants to get notifications. Observe that specifying a main category (for example, Simple, Tracking, Condition) will result in notifications for all sub-categories specified for that main category. low_severity The client wants all events with greater or equal severity. high_severity The client wants all events with less or equal severity. sources A SourceFilter for the sources that shall be notified. types A sequence of TypeIDs for the types that shall be notified. PropSelection A struct identifying what properties shall be included in an event notification for a specific reason. Member Description reason The reason for which the property selection is made. properties A sequence of PropertyIDs for the selected properties. ReadDirection An enumeration that tells if a read of history shall be forward or backwards in time. Member Description READ_FORWARDS Read events after the given start time. READ_BAKWARDS Read events before the given start time. Manager An object managing subscription and filtering of event notifications per client. BusyDueToRefresh An exception stating that a refresh is already going on. HistoryNotImplemented An exception stating that the server does not record the event history. callback An attribute holding a reference to the callback object. The client is required to update the attribute with a by the client implemented callback object to get event notifications from the server. The attribute corresponds to the IConnectionPoint interface in OPC. set_filter() The method updates the filter specification. A try to change the filter spec during an ongoing refresh will give an exception. The method corresponds to IOPCEventSubscriptionMgt::SetFilter(). Member Description filer_spec The filter specification. return none. get_filter() The method gets the filter specification. The method corresponds to IOPCEventSubscriptionMgt::GetFilter(). Member Description return The filter specification. select_returned_properties() The method sets what properties shall be included in a notification specified per reason. The method corresponds to IOPCEventSubscriptionMgt::SelectReturnedAttributes(). Member Description prop_selections A sequence specifying what properties to include per reason. return none. get_returned_properties() The method gets what properties currently are included in a notification specified per category. The method corresponds to IOPCEventSubscriptionMgt::GetReturnedAttributes(). Member Description categories The categories for that shall be used to fetch the properties. return A sequence specifying what properties currently are included per reason. refresh() The method forces notifications for all currently active source conditions. The notifications will not include the history but only the current source condition operational state. The method corresponds to IOPCEventSubscriptionMgt::Refresh(). Member Description return A server generated handle that the client can use to cancel the operation. async_read_history() The method read historic events recorded by the server. If the server does not support recording of alarms and events an exception is raised. No corresponding method exists in OPC. Member Description start_time The time where to start the read. An unspecified time (=0) will make the read start from the oldest recorded event. number_of_events The max number of events to deliver as a response to the read operation. Member Description direction Tells if events before or after the start time shall be read. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A server generated handle that the client can use to cancel the operation. cancel() The method cancels an ongoing refresh operation or async_read_history() operations. It corresponds to IOPCEventSubscriptionMgt::CancelRefresh(). Member Description cancel_id A server generated handle that is given back to the server when a started operation shall be cancelled. return none. get_state() The method gets the current subscription state and corresponds to IOPCEventSubscriptionMgt::GetState(). Member Description return The current subscription state. set_state() The method sets the current subscription state and corresponds to IOPCEventSubscriptionMgt::SetState(). The actual parameters set are returned and an exception is raised if any input parameters are not accepted and hence changed. Member Description subscription_spec New state wanted for the subscription. return The accepted subscription state. clone() The method creates a copy of the subscription. 5-22 Data Acquisition from Industrial Systems, v1.1 June 2005 Member Description return The copied subscription. destroy() The method destroys the subscription object. Filter A flag word holding flags specifying the filters that are implemented by the server. Flag Description FILTER_BY_MAIN_CATEGORY Filtering by main category is supported. FILTER_BY_CATEGORY Filtering by sub-category is supported. FILTER_BY_SEVERITY Filtering by severity is supported. FILTER_BY_AREA Filtering by area is supported. FILTER_BY_SOURCE Filtering by source is supported. FILTER_WITH_XPATH XPath as filter description is supported. FILTER_BY_SOURCE_TYPE Filtering by source type is supported. IHome A factory object for creation of subscription management objects. query_available_filters() Gets by the server implemented filter functions. The method corresponds to IOPCEventServer::QuearyAvailableFilters(). Member Description return Filter specification flagword. create_subscription() Creates a subscription management object. An invalid state will give an exception. Member Description subscription_spec State wanted for the subscription. revised_subscr_spec State accepted by the server. return The new subscription manager. Set up Subscription query_available_filters( ) : Client:Client : DAIS::AlarmsAndEvents::Subscription::IHome:DAIS::AlarmsAndEvents::Subscription::IHome : DAIS::AlarmsAndEvents::Subscription::Manager:DAIS::AlarmsAndEvents::Subscription::ManagerCheck what filters are supported by the server create_subscription( ) callback(DAISCallback) select_returned_properties( ) Set the callback for server to use set_filter( ) Set up filter to get only wanted event notifications Select what property values to be included in event notifications Do some browsing to prepare for setting up the filter. Browse for reasons, areas and sources Do some browsing to prepare for selecting properties Figure 5-6 Set up subscription interaction Refresh : Client: Client : DAIS::AlarmsAndEvents::Subscription::Manager: DAIS::AlarmsAndEvents:backbac:Subscription::Manager : DAIS::AlarmsAndEvents::IO::Call: DAIS::AlarmsAndEvents::IO::Callkrefresh( ) Initiate transfer of the currently active source conditions on_event( ) on_event( ) on_event( ) As many notifications sent as needed to report all source conditions Figure 5-7 Refresh interaction An area is a specialization of a node and is a collection of other areas or sources. Areas are intended for arbitrary hierarchical structuring of sources for various usages (for example, areas for authority or responsibility). DAIS::AlarmsAndEvents::Area::IHome is used for browsing the area hierarchy. The find methods in the interface correspond to the IOPCEventAreaBrowser with the filter type parameter set to OPC_AREA. The interface also implements the following OPC methods: • IOPCEventServer::EnableConditionByArea() • IOPCEventServer::DisableConditionByArea(). DAIS::AlarmsAndEvents::Area::IHome <> get_root() enable_condition() disable_condition() DAIS::Node::IHome (from DAISNode) <> find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() AreaSourceComponent id : ResourceID name : string description : string Area Source (from DAISAESource) 11 0..0.n.n 0..0.n.n +parent Figure 5-8 DAIS alarms and events area IDL in UML //File: DAISAEArea.idl #ifndef _DAIS_AEAREA_IDL #define _DAIS_AEAREA_IDL #pragma prefix "omg.org" #include #include module DAIS { module AlarmsAndEvents { module Area { interface IHome : Node::IHome { ResourceID get_root(); ResourceErrors enable_condition ( in ResourceIDs areas ); ResourceErrors disable_condition ( in ResourceIDs areas ); }; };};}; #endif // _DAIS_AEAREA_IDL IHome An object for browsing areas. get_root() A method to get the root node for the area tree. Member Description return The root area node. enable_condition() A method for enabling the sources contained by the specified areas. The corresponding OPC method is IOPCEventServer::EnableConditionByArea(). Member Description areas A sequence of area identifications. return The resource identifications that failed. disable_condition() A method for disabling the sources contained by the specified areas. The corresponding OPC method is IOPCEventServer::DisableConditionByArea(). Member Description areas A sequence of area identifications. return The resource identifications that failed. Browse areas get_root( ) : Client: Client : DAIS::AlarmsAndEvents::Area::IHome: DAIS::AlarmsAndEvents::Area::IHome : DAIS::Node::Iterator:DAIS::Node::IteratorGet the root of all areas find_by_parent( ) next_n( ) Repeat find_by_parent and next_n until the areas are explored Figure 5-9 Browse areas interaction A source is a specialization of a node and is contained by areas. A source represents an object that generates alarms and events. A source may have source conditions. The find methods in the interface correspond to the IOPCEventAreaBrowser with the filter type parameter set to OPC_SOURCE. The interface also implements the following OPC methods: • IOPCEventServer::TranslateToItemIDs • IOPCEventServer::EnableConditionBySource() • IOPCEventServer::DisableConditionBySource() DAIS::Node::IHome (from DAISNode) <> find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() DAIS::AlarmsAndEvents::Source::IHome <> translate_to_item_ids() enable_conditions() disable_conditions() Source 0..n 1 0..n10..n 1 0..n1Area (from DAI SAEArea) AreaSourceComponent (from DAI SAEArea) id : ResourceID name : string description : string 0..n +parent 0..n SourceCondition (from DAISAESo urceCon di tion) condition_op_state : DAISConditionOpState quality : DAIS::Quality last_acknowledge : DateTime condition_last_active : DateTime condition_space_last_active : DateTime condition_space_last_inactive : DateTime acknowledger_name : string comment : string Figure 5-10 DAIS alarms and events source IDL in UML //File: DAISAESource.idl #ifndef __DAIS_AESOURCE_IDL #define __DAIS_AESOURCE_IDL #pragma prefix "omg.org" #include #include module DAIS { module AlarmsAndEvents { module Source { interface IHome : Node::IHome { exception PropertyDidNotTranslate{string reason;}; ItemIDs translate_to_item_ids (in ResourceID source,in ResourceID category,in PropertyIDs properties ) raises (PropertyDidNotTranslate); ResourceErrors enable_conditions (in ResourceIDs sources); ResourceErrors disable_conditions (in ResourceIDs sources ); };};};}; #endif // __DAIS_AESOURCE_IDL IHome An object for browsing sources at areas. PropertyDidNotTranslate An exception telling that one or more properties did not translate to ItemIDs. translate_to_item_ids() A method for translation of information about a source to ItemIDs for use with the data access interface. If one or more properties did not translate to ItemIDs, an exception is raised. The corresponding OPC method is IOPCEventServer::TranslateToItemIDs(). Member Description source The identification of the source. category The identification of the category. properties A sequence of properties for which ItemIDs are wanted. return A sequence of ItemIDs. Properties that did not translate to ItemIDs are returned as empty ItemIDs. enable_conditions() A method for enabling the specified sources. The corresponding OPC method is IOPCEventServer::EnableConditionBySource(). Member Description sources A sequence of area identifications. return The resource identifications that failed. disable_conditions() A method for disabling specified sources. The corresponding OPC method is IOPCEventServer::DisableConditionBySource(). Member Description sources A sequence of area identifications. return The resource identifications that failed. Browse sources : Client: Client : DAIS::AlarmsAndEvents::Source::IHome: DAIS::AlarmsAndEvents::Source::IHome : DAIS::Node::Iterator:DAIS::Node::Iteratorfind_by_parent( ) Get all sources that has a given area as parent next_n( ) Repeat getting all found sources from the iterator and continue with another area as parent to sources. Repeat this until all wanted sources are explored. For each source inspect the conditions it might have, refer to ConditionSpace Figure 5-11 Browse sources interaction A condition space describes a set of conditions; that is, it is a space of conditions. Each condition space is associated with a particular sub-reason of the main reason ConditionReason. Each condition has logic describing when the condition is active. The logic is described in a little language having the following constructs: • arithmetic operators • logic operators • references to properties The referred properties must be included in the set of properties defined by the associated reason. The little language grammar is server specific and is outside the scope of this specification. Transitions describe what transitions between conditions are allowed. The interface does not support exploration of the transitions. In OPC the ConditionSpace interface is implemented by the methods: • IOPCEventServer::QueryConditionNames() • IOPCEventServer::QuerySubConditionNames() . DAIS::AlarmsAndEvents::ConditionSpace::IHome <> find() find_each() find_by_reason() find_by_source() get_names() get_ids() 11 0..0.n.n 1..1.n.n 11 ConditionSpace id : ResourceID name : string description : string Condition id_number : unsigned long name : string description : string severity : unsigned long condition_logic : string ConditionCategory (from DAISAECategory) 1..1.n.n +conditions 0..0.n.n 0..n0..n Transition 11 11 0..0.n.n ConditionEvent (from DAISAEIO) Figure 5-12 DAIS alarms and events condition space IDL in UML //File: DAISAEConditionSpace.idl #ifndef _DAIS_AECONDITION_SPACE_IDL #define _DAIS_AECONDITION_SPACE_IDL #pragma prefix "omg.org" #include module DAIS {module AlarmsAndEvents {module ConditionSpace { struct ConditionDescription { unsigned long id_number; string name; string condition_logic; unsigned long severity; string descrip; }; typedef sequence ConditionDescriptions; struct Description { ResourceID id; string name; string descrip; ConditionDescriptionsconditions; }; typedef sequence< Description >Descriptions; interface IHome { exception UnknownResourceID {string reason;}; Description find ( in ResourceID condition_space ) raises (UnknownResourceID); Descriptions find_each ( in ResourceIDs condition_spaces ) raises (UnknownResourceID); Descriptions find_by_category ( in ResourceID category ) raises (UnknownResourceID); Descriptions find_by_source ( in ResourceID source ) raises (UnknownResourceID); Strings get_names ( in ResourceIDs condition_spaces ); ResourceIDs get_ids ( in Strings names ); };};};};#endif // _DAIS_AECONDITION_SPACE_IDL ConditionDescription A struct describing a condition. Member Description id_number A numeric identification unique within the condition space. name The name of the condition. condition_logic The logic telling when the condition is active. Refer to Section 5.2.7.3, “Condition Logic,? on page 5-38 for a description. severity Severity is a number between 1 and 1000 having the following meaning: • Low severity 1-200 • Medium low severity 201-400 • Medium severity 401-600 • Medium high severity 601-800 • High severity 801-1000 description A text that to be included in event notifications when the condition is active. Description A struct describing the condition space. Member Description id A ResourceID identifying the condition space. name The name of the condition space. description A description of the condition space. conditions A sequence of the conditions creates the condition space. In OPC the conditions are called sub-conditions and are retrieved by the method IOPCEventServer::QuerySubConditionNames(). IHome An object for browsing the condition spaces defined by a server. find() A method for getting the description of a condition space. Parameter Description condition_space A ResourceID identifying a condition space. return The condition space description. find_each() A method for getting the descriptions for a number of condition spaces. Parameter Description condition_spaces A sequence of ResourceID identifying condition spaces. return A sequence of condition space descriptions. find_by_category() A method for finding all condition spaces defined for a category. The corresponding OPC method is IOPCEventServer::QueryConditionNames(). Parameter Description category A ResourceID identifying the category for which to get the condition spaces. return A sequence of condition space descriptions. find_by_source() A method for finding all condition spaces defined for a source. The corresponding OPC method is IOPCEventServer::QuerySourceConditions(). Parameter Description source A ResourceID identifying the source for which to get the condition spaces. return A sequence of condition space descriptions. get_names() A method translating a number of condition space identifications into name strings. Parameter Description condition_spaces A sequence of ResourceID identifying condition spaces. return A sequence of condition space names. Non-translated identifications are returned as empty strings. get_ids() A method translating a number of condition space names into ResourceIDs. Parameter Description names A sequence of condition space names. return A sequence of condition space ResourceIDs. Non- translated identifications are returned as NULL IDs. Browse condition space by source : Client: Client : DAIS::AlarmsAndEvents::ConditionSpace::IHome: DAIS::AlarmsAndEvents::ConditionSpace::IHomefind_by_source( ) Get all condition space descriptions for one source. Explore each condition space from the retrieved descriptions. Figure 5-13 Browse condition space by source interaction Browse condition space by category : Client: CliAlrmsAndEvents::ConditionSpace::IHomeAent : DAIS::a: DAIS::larmsAndEvents::ConditionSpace::IHome find_by_category( ) Get all condition space description for one category. Explore each condition space from the retrieved descriptions. Figure 5-14 Browse condition space by category interaction The reduced XPath language as defined in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 is used to describe the condition_logic. This allows description of a path through a data structure picking up property values to be used in a logical expression. A common case is property values at objects associated with a source, hence the starting point for navigation is the source. An example from the CIM model where the Measurement is the source can be found in Figure 4-3 on page 4-6. Examples how to use DAIS_Expressions starting from a source are shown below: Measurement.value < 500 assuming that the tested value is an element at the source. MeasurementValue[id(MeasurementValue.MeasurementValueSource)/label='telemetry']/ MeasurementValue.value < id(Measurement.LimitSets)[LimitSet.label = 'summer']/Limit[label = 'highalarm']/Limit.value Based on the model in Figure 4-3 on page 4-6, the XML example in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 and the source as a Measurement. A source condition associates a source with a condition space. A source condition holds the current information specific to a source using a particular condition space for the supervision. A source condition has no own identification and is identified by its associated source and condition space. Information about a source condition is accessed through its home object. In OPC a source condition is sometimes called an instance of a condition. In OPC the SourceCondition interface is implemented by the methods: • IOPCEventServer::QuerySourceConditions() • IOPCEventServer::AckCondition(). . DAIS::AlarmsAndEvents::SourceCondition::IHome <> find() find_each() ack_condition() Source (from DAISAE Source) 11 0..0.n.n 11 0..0.n.n 0..0.n.n 11 11 ConditionSpace (from DAISAE Condi ti onSpace) id : ResourceID name : string description : string Condition (from DA ISAECondi ti onSpace) id_number : unsigned long name : string description : string severity : unsigned long condition_logic : string SourceCondition condition_op_state : DAISConditionOpState quality : DAIS::Quality last_acknowledge : DateTime condition_last_active : DateTime condition_space_last_active : DateTime condition_space_last_inactive : DateTime acknowledger_name : string comment : string 0..0.n +active_condition .n Figure 5-15 DAIS alarms and events source condition IDL in UML //File: DAISAESourceCondition.idl #ifndef _DAIS_AESOURCE_CONDITION_IDL #define _DAIS_AESOURCE_CONDITION_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { module SourceCondition { struct Id { ResourceID source; ResourceID condition_space; }; typedef sequenceIds; struct Description { Id source_condition;SourceConditionOpState source_condition_op_state;unsigned long active_condition;string ac_logic;unsigned long ac_severity;string ac_description;Quality dais_quality;DateTime last_acknowledge;DateTime condition_last_active;DateTime condition_space_last_active;DateTime condition_space_last_inactive;string acknowledger_name;string comment;PropertyValues property_values; };typedef sequence< Description > Descriptions; struct AcknowledgeSpec { Id source_condition; DateTime active_time; EventID cookie; }; typedef sequenceAcknowledgeSpecs; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions c_descriptions ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownId {string reason;}; exception UnknownPropertyID {string reason;}; Description find ( in Id source_condition, in PropertyIDs properties ) raises (UnknownId, UnknownPropertyID); Iterator find_each( in Ids source_conditions, in PropertyIDs properties ) raises (UnknownId, UnknownPropertyID); Descriptions ack_condition ( #endif // _DAIS_AESOURCE_CONDITION_IDL Id in string acknowledger_name, in string comment, in AcknowledgeSpecs ack_spec ); }; };};}; A struct that identifies a source condition. Member Description source The ResourceID identifying the associated source. condition_space The ResourceID identifying the associated condition space. Description A struct describing the source condition. Member Description id The Id identifying the source condition. source_condition_op_state The DAISSourceConditionOpState as described in Section 5.2.2, “Alarms and Events Common IDL Definitions,? on page 5-7. active_condition The identification number of the currently active condition. ac_logic The condition logic from the active condition. ac_severity The severity from the active condition. ac_description The description from the active condition. dais_quality The quality is evaluated from the qualities from the properties used to evaluate the condition logic. last_acknowledge The last time the condition was acknowledged. condition_last_active Time for the latest condition transition. condition_space_last_active The last time when the condition space became active. After this time more condition transitions may occur. The condition_last_active will then be later than condition_space_last_active. condition_space_last_inactive The last time when the condition space became inactive; that is, no conditions are active. acknowledger_name The name of the client making an acknowledge. comment A comment passed by the client making an acknowledge. property_values A sequence of property values as selected by the Manager::select_returned_properties call. AcknowledgeSpec A struct specifying an alarm to acknowledge. Member Description source_condition The Id identifying the source condition for which to acknowledge an alarm. active_time The time when the alarm activated. cookie A identification of the alarm. Iterator A standard iterator. Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. IHome An object for browsing and accessing source conditions. UnknownDAISSourceConditionID An exception telling that the source condition identification was not recognized. UnknownPropertyID An exception telling that a property identification was not recognized. find() A method for getting the description of a source condition. The corresponding OPC method is IOPCEventServer::GetConditionState(). Parameter Description source_condition A ResourceID identifying a source condition. return The source condition description. find_each() A method for getting the descriptions for a number of source conditions. Parameter Description condition_spaces A sequence identifying source conditions. return A sequence of source condition descriptions. ack_condition() A method to acknowledge a number of source condition alarms. The corresponding OPC method is IOPCEventServer::AckCondition(). Parameter Description acknowledger_name The name of the client making the acknowledge. comment A comment to be added to source condition and the event. ack_spec A sequence specifying the alarms to acknowledge. return A sequence containing descriptions for the acknowledged source conditions. Inspect a specific source condition : Client: Client : D A IS :: AlarmsA ndEvent s::S ourc eC ondition:: IH ome:DAIS::AlarmsAndEvents::SourceCondition::IHomefind( ) Get all det ails on a s pec ific source c ondit on Figure 5-16 Inspect a specific source condition interaction Acknowledge alarm : Client: Client : DAIS::AlarmsAndEvents::SourceCondition::IHom e:DAIS::AlarmsAndEvents::SourceCondition::IHomeack_condition( ) Acknolwedge a set of source conditions in one call Figure 5-17 Acknowledge alarm interaction These are definitions for manipulating categories. A category describes the content of an event. Categories are organized in a two level hierarchy where the first level has the three mandatory main categories; simple, condition, and tracking. Simple category does not have a condition space (refer to ConditonSpace). Generation of simple category alarms or events is coded into some software function and cannot be configured. Typical simple categories are program errors, hardware device failures, etc. Sources of different types (e.g., breaker position, breaker current, generator active power, etc.) may have different ways an alarm or event is generated (e.g., breaker trip, breaker over current, generator active power generation overload, etc.). Condition categories are used to describe source type specific alarm and event contents. The alarm and event generation for a condition category is configured using condition spaces and several condition spaces can be created for the same condition category. This corresponds to variations in the way the alarms and events are generated using different condition logics. Alarms or events due to operator actions or control functions (intended alarms or events rather than spontaneous) use tracking categories. A category has a set of properties associated with it. Some or all of the properties may be included in event notifications. The properties come from the source type and may be used by the logic generating an event notification. The get_main_ category () method is used to obtain the three main categories. The find_by_parent() is used to get the child categories. Categories at this second level correspond to the OPC EventCategories. The labels for the three main reasons are “DAIS_CONDITION_CATEGORY,? “DAIS_TRACKING_CATEGORY,? and "DAIS_SIMPLE_CATEGORY.? In OPC the Category interface is implemented by the methods IOPCEventServer::QueryEventCategories() and IOPCEventServer::QueryEventAttributes(). TrackingCategory SimpleCategory ConditionCategory DAIS::AlarmsAndEvents::Category::IHome get_main_categories() get_event_properties() <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() (from DAISNode) <> Node id : ResourceID label : string type : ResourceID (f rom DA ISNo de) 1 0..10..nCategory Figure 5-18 DAIS alarms and events categories IDL in UML //File: DAISAECategory.idl #ifndef _DAIS_AECATEGORY_IDL #define _DAIS_AECATEGORY_IDL #pragma prefix "omg.org" #include module DAIS {module AlarmsAndEvents {module Category{ interface IHome : Node::IHome { Node::Descriptions get_main_categories (); PropertyIDs get_event_properties (in ResourceID category ); }; };};}; #endif // _DAIS_AECATEGORY_IDL IHome IHome is an object for browsing categories. Most of the browsing functionality is inherited from DAIS::Node. get_main_categories() Get the three main categories; simple, condition, and tracking. The three main categories appear as three different roots. Parameter Description return The descriptions for the three main categories. The labels for them are: • “DAIS_CONDITION_CATEGORY? • “DAIS_TRACKING_CATEGORY? • “DAIS_SIMPLE_CATEGORY? get_event_properties() Get all properties that are used in the supervision of the source type for a specific category. The corresponding OPC method is IOPCEventServer::QueryEventAttributes(). Parameter Description category The identification of the categories to get the properties for. return A sequence of property identifications. Browse categories get_main_reasons( ) : DAIS::AlarmsAndEvents::Category::IHome:DAIS::AlarmsAndEvents::Category::IHome: Client: ClientGet the three main reasons find_by_parent( ) Get the sub reasons for one main reason. For each sub reason explore 1) the condition spaces that are defined, refer to ConditionSpace 2) the properties that are used in supervision of sources Continue and explore all main reasons Figure 5-19 Browse category interaction Browse properties : DAIS::Alarm sAndE vents::Category::IHom e:DAIS::AlarmsAndEvents::Category::IHome: Client: ClientGet the three m ain categories Get the sub categories for one main category. For each sub category explore 1) the condition spaces that are defined, refer to ConditionSpace 2) the properties that are used in supervision of sources Continue and explore all main categories get_main_categories( ) find_by_parent( ) Figure 5-20 Browse properties interaction The IO interface for alarms & events only supports callbacks and the client shall implement callback. The event notifications sent over the callback are of three different formats corresponding to the three main categories (simple event, condition event, and tracking event). All three event formats have the common part Event. The tracking event has additional information on the operator and the condition event has additional information on the source condition causing the notification. In OPC the IO interface is implemented by the interface IOPCEventSink Source (from DAISAESource) Event source : ResourceID source_pathname : string time_stamp : DateTime message : string event_format : EventFormat category : ResourceID category_name : string severity : unsigned long property_values : PropertyValues 11SimpleCategory (from DAISAECa tegory) SimpleEvent 11ConditionCategory (from DAISAECategory ) ConditionEvent condition_space_name : string condition_space : ResourceID condition_name : string condition_number : unsigned long ack_required : boolean active_time : DateTime event_id : EventID change_specification : ChangeSpec source_condition_op_state : SourceConditionOpState dais_quality : Quality TrackingCategory (from DAISAECategory ) TrackingEvent actor_name : string 11DAIS::AlarmsAndEvents::IO::Callback <> on_event() on_read_complete() 11 Figure 5-21 DAIS alarms and events IO IDL in UML //File: DAISAEIO.idl#ifndef _DAIS_AEIO_IDL#define _DAIS_AEIO_IDL#pragma prefix "omg.org"#include module DAIS {module AlarmsAndEvents {module IO { typedef unsigned long ChangeSpec;const ChangeSpec CHANGE_ACTIVE_STATE = 0x0001; const ChangeSpec CHANGE_ACK_STATE = 0x0002; const ChangeSpec CHANGE_ENABLE_STATE = 0x0004; const ChangeSpec CHANGE_QUALITY = 0x0008; const ChangeSpec CHANGE_SEVERITY = 0x0010; const ChangeSpec CHANGE_CONDITION = 0x0020; const ChangeSpec CHANGE_MESSAGE = 0x0040; const ChangeSpec CHANGE_ATTRIBUTE = 0x0080; struct SimpleEvent { ResourceID source; string source_pathname; DateTime time_stamp; string message; EventFormat event_format; ResourceID category; string category_name; unsigned long severity; PropertyValues property_values; }; struct TrackingEvent { string actor_name; }; struct ConditionEvent { string condition_space_name; ResourceID condition_space; string condition_name; unsigned long condition_number; boolean ack_required; DateTime active_time; EventID event_id; ChangeSpec change_specification; SourceConditionOpState source_condition_op_state; Quality dais_quality; }; struct Event { SimpleEvent simple_event; TrackingEvent tracking_event; ConditionEvent condition_event; };typedef sequence Events; interface Callback{ void on_event (in boolean refresh,in boolean last_refresh,in Events the_events ); void on_read_complete (in Events the_events,in unsigned long transaction_id ); }; };};}; #endif // _DAIS_AEIO_IDL ChangeSpec A flag word having a number of flags telling what change caused the event notification. Flag Description CHANGE_ACTIVE_STATE Alarm active has changed. CHANGE_ACK_STATE Alarm acknowledge has changed. CHANGE_ENABLE_STATE Enable has changed. CHANGE_QUALITY The quality has changed. CHANGE_SEVERITY The severity has changed. CHANGE_CONDITION A condition has become active/inactive. CHANGE_MESSAGE The message has been updated. CHANGE_ATTRIBUTE An attribute value has changed. SimpleEvent A struct holding the simple event data. Member Description source The identification of the source for which the event notification was created. source_pathname The full pathname of the source. time_stamp Time of the event occurrence - for conditions, time that the condition transitioned into the new state or condition. For example, if the event notification is for acknowledgment of a condition, this would be the time that the condition became acknowledged. message Event notification message describing the event. event_format The identification for one of the three main formats. category The identification of the sub-category why the event notification was sent. category_name The label for the sub-category. severity The severity for the event, a number between 0 and 1000. property_values A sequence of property values as selected by the select_returned_properties() method. TrackingEvent A struct holding tracking event data. Member Description actor_name The name of the actor or operator causing the event notification. ConditionEvent A struct holding the condition event data. Member Description condition_space_name The name of the condition space that caused the event notification. condition_space Identification of the condition space. condition_name The name of the condition that caused the event notification. condition_number Identification of the condition. ack_required An indication that an alarm is generated and that an acknowledgment is required. active_time The time when the condition became active. event_id An identification of the event notification. change_specification Indicates to the client which properties of the condition have changed. source_condition_op_state The new state for the source condition. quality The quality. Event A struct composed of the three above event structs. The simple event struct always contains valid information and which of the tracking or condition event structs are valid is decided from the main_reason simple event member. Member Description simple_event The simple event. tracking_event The tracking event. condition_event The condition event. Callback The callback object implemented by the client and used by the server to send event notifications. on_event() The callback method. Parameter Description refresh Indicates if this callback is due to a refresh. last_refresh Indicates if this callback is the last in a sequence initiated by a refresh. the_events A sequence of event notifications. return None. on_read_complete() A callback method for the async_read_history() method. After an async_read_history() call from a client the server will deliver the historical events using this method. There is no corresponding OPC method. Parameter Description the_events A sequence of historical events. transaction_id The transaction number matching the client call number. Event notification callbacks : DAIS::Alarm sAndEvents::IO::Callback: DAIS::AlarmsAndEvents::Ints:Subscription::M anagerntO::Callback: DAIS::AlarmsAndEve:: DAIS::AlarmsAndEves::Subscription::Manageron_event( ) on_event( ) The on_event method is called by the server at 1) expiration of the subscription buffer_time timeout 2) subscription event buffer full For alarms the client may want to call SourceCondition::ack_alarm() to acknowledge. A ll inform ation needed for doing this is found in the event notifications. Figure 5-22 Event notification callbacks interaction Refresh callbacks : DAIS::AlarmsAndEvents::IO::Callback: DAIS::AlarmsAndEvents::IO::CallbackOn_event is called as response to a refresh. All refresh calls are made with the refresh parameter set and the last call also has the last_refresh parameter set. : DAIS::AlarmsAndEvents::Subscription::Manager:DAIS::AlarmsAndEvents::Subscription::Manageron_event( ) Figure 5-23 Refresh callbacks interaction The dependencies among the different IDL files are shown in Figure 5-3. DAISAESession DAISAESubscription DAISAEIO DAISAESource Condition DAISConditionSpace DAISAEReason DAISAESource DAISAEArea DAISServer (from Server) DAISSession (from Com m on) DAISProperty (from Common) DAISNode (from Common) DAISCommon (from Common) DAISAECommon DAISType (from Com m on) Figure 5-3 Dependencies between alarms and events IDL files // File: DAISAECommon.idl #ifndef _DAIS_AECOMMON_IDL #define _DAIS_AECOMMON_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { typedef ResourceID EventID; struct ResourceError { Error err; ResourceID id; string reason; }; typedef sequence ResourceErrors; // error codesconst Error RES_ERROR_DAISOK= 0;const Error RES_ERROR_UNKOWN_RESOURCE= 1; typedef unsigned longSourceConditionOpState;const SourceConditionOpStateCONDITION_ENABLED= 0x0001;const SourceConditionOpStateCONDITION_ACTIVE= 0x0002;const SourceConditionOpStateCONDITION_ACKED= 0x0004; typedef unsigned short EventFormat;const EventFormat OPC_SIMPLE_EVENT = 0x0001;const EventFormat OPC_TRACKING_EVENT = 0x0002;const EventFormat OPC_CONDITION_EVENT= 0x0004;const EventFormat OPC_ALL_EVENTS = 0x0007;};};#endif // _DAIS_AECOMMON_IDL EventID A ResourceID uniquely identifying an event notification. ResourceError A struct for reporting of resource related errors. Member Description err An error code as described below. id The identification of the resource. reason An additional text explaining the error. ResourceErrors ResourceErrors is a sequence containing errors. If no errors are present, no entry shall be included in the sequence rather than including a large number of no errors. An empty sequence means no errors. Error The error codes for ResourceError. Member Description RES_ERROR_DAISOK No error. RES_ERROR_UNKOWN_RESOURCE The resource was not found. SourceConditionOpState Flag word holding for the operational state of a SourceCondition. The definitions of the state variable in the flag word are listed below. Flag Description CONDITION_ENABLED The Condition is enabled and supervision is active. CONDITION_ACTIVE The Condition is active; that is, the supervision has determined that a fault has activated the condition. CONDITION_ACKED The Condition alarm has been acknowledged. The combinations of the state variables result in eight states. The valid SourceCondition operational states are listed below. State Description Disabled Not supervised by server. Enabled, Inactive, Acked Supervised by server, no fault detected and all alarms are acknowledged. Enabled, Inactive, Unacked Supervised by server, no fault detected and unacknowledged alarms exist. Enabled, Active, Unacked Supervised by server, a fault is detected and unacknowledged alarms exist. Enabled, Active, Acked Supervised by server, a fault is persistent and all alarms are acknowledged. When enabled the state {Enabled, Inactive, Acked} is entered and from there the supervision will generate the appropriate state depending on the result of the supervision. Each state change results in sending an alarm and event notification. All notifications contain the state. EventFormat This constant tells the format of an event. Member Description OPC_SIMPLE_EVENT The event is a simple event. OPC_TRACKING_EVENT The event is a tracking event. OPC_CONDITION_EVENT The event is a condition event. OPC_ALL_EVENTS This constant value is used to ask for all event formats in a subscription set up. The DAIS::AlarmsAndEvents::Session object implements the alarms & events service on a per client basis. An alarm & event session object has a number of services provided by one singleton home object each. Each home object provides methods for manipulation of the data of the specific type they provide. The session object corresponds to an OPCEventServer object. DAIS::ShutdownCallback (from DAISSessi on) <> DAIS::AlarmsAndEvents::Session <> subscription_home() : DAIS::AlarmsAndEnvents::Subscription::Home area_home() : DAIS::AlarmsAndEvents::Area::IHome source_home() : DAIS::AlarmsAndEvents::Source::IHome condition_space_home() : DAIS::AlarmsAndEnvents::ConditionSpace::Home source_condition_home() : DAIS::AlarmsAndEvents::SourceCondition::IHome reason_home() : DAIS::AlarmsAndEvents::Category::IHome type_home() : DAIS::Type::IHome property_home() : DAIS::Property::IHome DAIS::Session (from DAISSessi on) <> status() : DAIS::SessionStatus 1 01callback() : DAIS::ShutdownCallback callback(callback : DAIS::ShutdownCallback) destroy() ..10..1 0..10..1 11 Client (f rom DA ISServ er) 11 DAIS::AlarmsAndEvents::Area::IHome (from DAISAEArea) <> 0..0.*.* 11 DAIS::AlarmsAndEvents::IO::Callback (f ro m DAISAE I O) <> 11 DAIS::AlarmsAndEvents::Source::IHome (f rom DA ISAE Sourc e) <> 0..0.1.1 11 11 DAIS::AlarmsAndEvents::ConditionSpace::IHome (from DAISAECondi ti onSpace ) <> DAIS::AlarmsAndEvents::SourceCondition::IHome (f ro m DA ISAE Sourc eConditi on) <> DAIS::AlarmsAndEvents::Category::IHome (from DAISAECategory) <> DAIS::AlarmsAndEvents::Subscription::IHome (from DAISAESu bscriptio n) <> 11 11 11 11 0.. 0..n DAIS::AlarmsAndEvents::Subscription::Manager (fro m DAISAESubsc ri pti on) <> 11 DAIS::Property::IHome (from DAISProperty) <> Figure 5-4 DAIS alarms and events session IDL in UML //File: DAISAESession.idl #ifndef _DAIS_AESERVER_IDL #define _DAIS_AESERVER_IDL #pragma prefix "omg.org" // Common Information#include #include #include // Events and Alarms#include #include #include #include #include #include #include module DAIS {module AlarmsAndEvents { interface Session : DAIS::Session { readonly attribute Subscription::IHome subscription_home; readonly attribute Area::IHome area_home; readonly attribute Source::IHome source_home; readonly attribute ConditionSpace::IHome condition_space_home; readonly attribute SourceCondition::IHome source_condition_home; readonly attribute Category::IHome category_home; readonly attribute Type::IHome type_home; readonly attribute Property::IHome property_home; };};}; #endif // _DAIS_AESESSION_IDL; Session Session is an object implementing the alarms & events functions. It inherits common functionality as shut down callbacks and session status from DAIS::AlarmsAndEvents::Session. subscription_home A read only attribute holding a reference to a singleton Subscription::IHome object. area_home A read only attribute holding a reference to a singleton Area::IHome object. source_home A read only attribute holding a reference to a singleton Source::IHome object. condition_space_home A read only attribute holding a reference to a singleton ConditionSpace::IHome object. source_condition_home A read only attribute holding a reference to a singleton SourceCondition::IHome object. category_home A read only attribute holding a reference to a singleton Category::IHome object. type_home A read only attribute holding a reference to a singleton Type::IHome object. property_home A read only attribute holding a reference to a singleton Property::IHome object. A DAIS::AlarmsAndEvents::Subscription::Manager is an object holding a filter specification set up by a client. The filter is used to specify what notifications shall be sent to the client. A server can support various filter functions and a client can ask the DAIS::AlarmsAndEvents::Subscription::IHome object what filter functions are supported. The subscription home is also used to create any number of subscription manager objects. Each subscription manager shall be associated with a client implemented callback object so that the server can send alarm and event notifications to the client. A server may optionally support an event history. The event history shall record all alarms and events appearing in a server. The method async_read_history() gives clients access to the event history. The size of the event history is server specific and outside the control of a client. In OPC the Subscription interface corresponds to the interface IOPCEventSubscription. DAIS::AlarmsAndEvents::Subscription::IHome query_available_filters() create_subscription() <> 0..0.1.1 11 DAIS::AlarmsAndEvents::IO::Callback (from DAISAEIO) <> 0..n0..n 11 DAIS::AlarmsAndEvents::Subscription::Manager callback() : DAIS::AlarmsAndEvents::IO::Callback callback(in callback : DAIS::AlarmsAndEvents::IO::Callback) set_filter() get_filter() select_returned_properties() get_returned_properties() refresh() asynch_read_history() cancel() get_state() set_state() clone() destroy() <> 11 0..0.n.n PropertySelection category : ResourceID properties : PropertyIDs 11 11 11 DAIS::AlarmsAndEvents::Subscription::FilterSpec reason_filter : ReasonFilter low_severity : unsigned long high_severity : unsigned long source_filter : SourceFilter type_filter : TypeIDs DAIS::AlarmsAndEvents::Subscription::State active : boolean buffer_time : unsigned_long max_size : unsigned long keep_alive_time : unsigned long 11 Figure 5-5 DAIS alarms and events subscription IDL in UML //File: DAISAESubscription.idl #ifndef _DAIS_AESUBSCRIPTION_IDL #define _DAIS_AESUBSCRIPTION_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { module Subscription { struct State { boolean active; unsigned long buffer_time; unsigned long max_size; unsigned long keep_alive_time; }; struct OPCSourceFilter { ServerItemIdentifications areas; ServerItemIdentifications sources; }; typedef short SourceFilterType;const SourceFilterType OPC_SOURCE_FILTER_TYPE = 1;const SourceFilterType XPATH_SOURCE_FILTER_TYPE = 2; union SourceFilter switch(SourceFilterType) { case OPC_SOURCE_FILTER_TYPE : OPCSourceFilter opc_source_filters; case XPATH_SOURCE_FILTER_TYPE : string xpath_source_filter; }; typedef short CategoryFilterType;const CategoryFilterType OPC_REASON_FILTER_TYPE = 1;const CategoryFilterType XPATH_REASON_FILTER_TYPE= 2; union CategoryFilter switch(ReasonFilterType) { case OPC_CATEGORY_FILTER_TYPE : ServerItemIdentifications opc_category_filters; case XPATH_CATEGORY_FILTER_TYPE : string xpath_category_filter; }; struct FilterSpec { EventFormat event_format; CategoryFilter category_filter; unsigned long low_severity; unsigned long high_severity; SourceFilter source_filter; ResourceIDs type_filter; }; struct PropSelection { ResourceID category; PropertyIDs properties; };typedef sequence PropSelections; enum ReadDirection { READ_FORWARDS, READ_BAKWARDS }; typedef unsigned long CancelID; interface Manager { exception BusyDueToRefresh{string reason;}; exception HistoryNotImplemented{string reason;}; attribute IO::Callback callback; void set_filter (in FilterSpec filer_spec) raises (BusyDueToRefresh); FilterSpec get_filter (); void select_returned_properties (in PropSelections prop_selections); PropSelections get_returned_properties (in ResourceIDs categories); CancelID refresh () raises (BusyDueToRefresh); CancelID async_read_history ( in DateTime start_time, in unsigned long number_of_events, in ReadDirection direction, in unsigned long transaction_id ) raises (HistoryNotImplemented); void cancel (in CancelID cancel_id); void refresh () raises (BusyDueToRefresh); void refresh_with_history (in DateTime start_time,in DateTime end_time ) raises (HistoryNotImplemented); void cancel_refresh (); State get_state (); State set_state ( in State subscription_spec Manager clone (); void destroy (); }; typedef unsigned longFilter;const Filter FILTER_BY_EVENT_FORMAT = 0x0001;const Filter FILTER_BY_CATEGORY = 0x0002;const Filter FILTER_BY_SEVERITY = 0x0004;const Filter FILTER_BY_AREA = 0x0008;const Filter FILTER_BY_SOURCE = 0x0010;const Filter FILTER_WITH_XPATH = 0x0020;const Filter FILTER_BY_SOURCE_TYPE = 0x0040; interface IHome{ Filter query_available_filters (); Manager create_subscription ( in State subscription_spec, out State revised_subscr_spec); };};};}; #endif // _DAIS_AESUBSCRIPTION_IDL State A struct describing the state for the subscription. Member Description active Indicates if the subscription is active; that is, is sending data on the call back interface. Events that are appearing in the server will be lost for clients connected to inactive subscriptions. buffer_time The requested buffer time in milliseconds. This is a minimum time - do not send event notifications any faster that this UNLESS max_size is greater than 0, in which case the server will send an event notification sooner to obey the max_size value. A value of 0 for buffer_time means that the server should send event notifications as soon as it gets them. This parameter along with the max_size parameter is used to improve communications efficiency between client and server. This parameter is a recommendation from the client, and the server is allowed to ignore the parameter. The server will return the buffer time it is actually providing in revised_buffer_time. max_size The requested maximum number of events that will be sent in a single callback. A value of 0 means that there is no limit to the number of events that will be sent in a single callback. Note that a value of max_size greater than 0, may cause the server to make callbacks more frequently than specified by buffer_time when a large number of events are being generated in order to limit the number of events to the max_size. This parameter is a recommendation from the client and the server is allowed to ignore this parameter. The server will return the actual number of events it is actually providing in revised_max_size. keep_alive_time The time in milliseconds for the server to send a callback to client. The intention is to indicate to the client that the server is alive and avoid the need to "poll" the server to check it is alive. If no data is available an empty message is sent. If the time is less than the buffer_time the buffer_time is used. OPCSourceFilter The struct specifies source filtering by enumerating the areas and sources the way OPC does it. Member Description areas A sequence of ResourceIDs for the areas that shall be notified. All sources below an area node will be notified. sources A sequence of ResourceIDs for sources that shall be notified. An empty sequence means all sources shall be notified. SourceFilter The union specifies OPCSourceFiltering or XPath filtering. A prerequisite for XPath filtering is that the area and source hierarchy has an XML mapping. The same mapping is used as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 with the additional comments: • an Area corresponds to a Node (Area inherits Node). • a Source corresponds to a Node (Source inherits Node). Member Description opc_source_filters An OPCSourceFilter xpath_source_filter An XPath filter. CategoryFilter The union specifies OPC style filtering or XPath filtering of categories. A prerequisite for XPath filtering is that the resource hierarchy has an XML mapping. The same mapping is used as described in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 with the additional comments: • a Resource corresponds to a Node (Resource inherits Node). Member Description opc_category_filters An OPCSourceFilter xpath_reason_filter An XPath filter FilterSpec A struct holding the specification for how the server shall filter notifications sent to the client. The struct is used to specify the filtering a client wants a server to do for it. All specified filter criterias shall be fulfilled for a notification to be sent. Member Description event_format An EventFormat bit mask specifying the event formats to be returned. reasons A sequence of CategoryFilter for the categories for which the client wants to get notifications. Observe that specifying a main category (for example, Simple, Tracking, Condition) will result in notifications for all sub-categories specified for that main category. low_severity The client wants all events with greater or equal severity. high_severity The client wants all events with less or equal severity. sources A SourceFilter for the sources that shall be notified. types A sequence of TypeIDs for the types that shall be notified. PropSelection A struct identifying what properties shall be included in an event notification for a specific reason. Member Description reason The reason for which the property selection is made. properties A sequence of PropertyIDs for the selected properties. ReadDirection An enumeration that tells if a read of history shall be forward or backwards in time. Member Description READ_FORWARDS Read events after the given start time. READ_BAKWARDS Read events before the given start time. Manager An object managing subscription and filtering of event notifications per client. BusyDueToRefresh An exception stating that a refresh is already going on. HistoryNotImplemented An exception stating that the server does not record the event history. callback An attribute holding a reference to the callback object. The client is required to update the attribute with a by the client implemented callback object to get event notifications from the server. The attribute corresponds to the IConnectionPoint interface in OPC. set_filter() The method updates the filter specification. A try to change the filter spec during an ongoing refresh will give an exception. The method corresponds to IOPCEventSubscriptionMgt::SetFilter(). Member Description filer_spec The filter specification. return none. get_filter() The method gets the filter specification. The method corresponds to IOPCEventSubscriptionMgt::GetFilter(). Member Description return The filter specification. select_returned_properties() The method sets what properties shall be included in a notification specified per reason. The method corresponds to IOPCEventSubscriptionMgt::SelectReturnedAttributes(). Member Description prop_selections A sequence specifying what properties to include per reason. return none. get_returned_properties() The method gets what properties currently are included in a notification specified per category. The method corresponds to IOPCEventSubscriptionMgt::GetReturnedAttributes(). Member Description categories The categories for that shall be used to fetch the properties. return A sequence specifying what properties currently are included per reason. refresh() The method forces notifications for all currently active source conditions. The notifications will not include the history but only the current source condition operational state. The method corresponds to IOPCEventSubscriptionMgt::Refresh(). Member Description return A server generated handle that the client can use to cancel the operation. async_read_history() The method read historic events recorded by the server. If the server does not support recording of alarms and events an exception is raised. No corresponding method exists in OPC. Member Description start_time The time where to start the read. An unspecified time (=0) will make the read start from the oldest recorded event. number_of_events The max number of events to deliver as a response to the read operation. Member Description direction Tells if events before or after the start time shall be read. transaction_id A transaction number unique for the client. The number is returned in the corresponding on_read_complete call. return A server generated handle that the client can use to cancel the operation. cancel() The method cancels an ongoing refresh operation or async_read_history() operations. It corresponds to IOPCEventSubscriptionMgt::CancelRefresh(). Member Description cancel_id A server generated handle that is given back to the server when a started operation shall be cancelled. return none. get_state() The method gets the current subscription state and corresponds to IOPCEventSubscriptionMgt::GetState(). Member Description return The current subscription state. set_state() The method sets the current subscription state and corresponds to IOPCEventSubscriptionMgt::SetState(). The actual parameters set are returned and an exception is raised if any input parameters are not accepted and hence changed. Member Description subscription_spec New state wanted for the subscription. return The accepted subscription state. clone() The method creates a copy of the subscription. 5-22 Data Acquisition from Industrial Systems, v1.1 June 2005 Member Description return The copied subscription. destroy() The method destroys the subscription object. Filter A flag word holding flags specifying the filters that are implemented by the server. Flag Description FILTER_BY_MAIN_CATEGORY Filtering by main category is supported. FILTER_BY_CATEGORY Filtering by sub-category is supported. FILTER_BY_SEVERITY Filtering by severity is supported. FILTER_BY_AREA Filtering by area is supported. FILTER_BY_SOURCE Filtering by source is supported. FILTER_WITH_XPATH XPath as filter description is supported. FILTER_BY_SOURCE_TYPE Filtering by source type is supported. IHome A factory object for creation of subscription management objects. query_available_filters() Gets by the server implemented filter functions. The method corresponds to IOPCEventServer::QuearyAvailableFilters(). Member Description return Filter specification flagword. create_subscription() Creates a subscription management object. An invalid state will give an exception. Member Description subscription_spec State wanted for the subscription. revised_subscr_spec State accepted by the server. return The new subscription manager. Set up Subscription query_available_filters( ) : Client:Client : DAIS::AlarmsAndEvents::Subscription::IHome:DAIS::AlarmsAndEvents::Subscription::IHome : DAIS::AlarmsAndEvents::Subscription::Manager:DAIS::AlarmsAndEvents::Subscription::ManagerCheck what filters are supported by the server create_subscription( ) callback(DAISCallback) select_returned_properties( ) Set the callback for server to use set_filter( ) Set up filter to get only wanted event notifications Select what property values to be included in event notifications Do some browsing to prepare for setting up the filter. Browse for reasons, areas and sources Do some browsing to prepare for selecting properties Figure 5-6 Set up subscription interaction Refresh : Client: Client : DAIS::AlarmsAndEvents::Subscription::Manager: DAIS::AlarmsAndEvents:backbac:Subscription::Manager : DAIS::AlarmsAndEvents::IO::Call: DAIS::AlarmsAndEvents::IO::Callkrefresh( ) Initiate transfer of the currently active source conditions on_event( ) on_event( ) on_event( ) As many notifications sent as needed to report all source conditions Figure 5-7 Refresh interaction An area is a specialization of a node and is a collection of other areas or sources. Areas are intended for arbitrary hierarchical structuring of sources for various usages (for example, areas for authority or responsibility). DAIS::AlarmsAndEvents::Area::IHome is used for browsing the area hierarchy. The find methods in the interface correspond to the IOPCEventAreaBrowser with the filter type parameter set to OPC_AREA. The interface also implements the following OPC methods: • IOPCEventServer::EnableConditionByArea() • IOPCEventServer::DisableConditionByArea(). DAIS::AlarmsAndEvents::Area::IHome <> get_root() enable_condition() disable_condition() DAIS::Node::IHome (from DAISNode) <> find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() AreaSourceComponent id : ResourceID name : string description : string Area Source (from DAISAESource) 11 0..0.n.n 0..0.n.n +parent Figure 5-8 DAIS alarms and events area IDL in UML //File: DAISAEArea.idl #ifndef _DAIS_AEAREA_IDL #define _DAIS_AEAREA_IDL #pragma prefix "omg.org" #include #include module DAIS { module AlarmsAndEvents { module Area { interface IHome : Node::IHome { ResourceID get_root(); ResourceErrors enable_condition ( in ResourceIDs areas ); ResourceErrors disable_condition ( in ResourceIDs areas ); }; };};}; #endif // _DAIS_AEAREA_IDL IHome An object for browsing areas. get_root() A method to get the root node for the area tree. Member Description return The root area node. enable_condition() A method for enabling the sources contained by the specified areas. The corresponding OPC method is IOPCEventServer::EnableConditionByArea(). Member Description areas A sequence of area identifications. return The resource identifications that failed. disable_condition() A method for disabling the sources contained by the specified areas. The corresponding OPC method is IOPCEventServer::DisableConditionByArea(). Member Description areas A sequence of area identifications. return The resource identifications that failed. Browse areas get_root( ) : Client: Client : DAIS::AlarmsAndEvents::Area::IHome: DAIS::AlarmsAndEvents::Area::IHome : DAIS::Node::Iterator:DAIS::Node::IteratorGet the root of all areas find_by_parent( ) next_n( ) Repeat find_by_parent and next_n until the areas are explored Figure 5-9 Browse areas interaction A source is a specialization of a node and is contained by areas. A source represents an object that generates alarms and events. A source may have source conditions. The find methods in the interface correspond to the IOPCEventAreaBrowser with the filter type parameter set to OPC_SOURCE. The interface also implements the following OPC methods: • IOPCEventServer::TranslateToItemIDs • IOPCEventServer::EnableConditionBySource() • IOPCEventServer::DisableConditionBySource() DAIS::Node::IHome (from DAISNode) <> find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() DAIS::AlarmsAndEvents::Source::IHome <> translate_to_item_ids() enable_conditions() disable_conditions() Source 0..n 1 0..n10..n 1 0..n1Area (from DAI SAEArea) AreaSourceComponent (from DAI SAEArea) id : ResourceID name : string description : string 0..n +parent 0..n SourceCondition (from DAISAESo urceCon di tion) condition_op_state : DAISConditionOpState quality : DAIS::Quality last_acknowledge : DateTime condition_last_active : DateTime condition_space_last_active : DateTime condition_space_last_inactive : DateTime acknowledger_name : string comment : string Figure 5-10 DAIS alarms and events source IDL in UML //File: DAISAESource.idl #ifndef __DAIS_AESOURCE_IDL #define __DAIS_AESOURCE_IDL #pragma prefix "omg.org" #include #include module DAIS { module AlarmsAndEvents { module Source { interface IHome : Node::IHome { exception PropertyDidNotTranslate{string reason;}; ItemIDs translate_to_item_ids (in ResourceID source,in ResourceID category,in PropertyIDs properties ) raises (PropertyDidNotTranslate); ResourceErrors enable_conditions (in ResourceIDs sources); ResourceErrors disable_conditions (in ResourceIDs sources ); };};};}; #endif // __DAIS_AESOURCE_IDL IHome An object for browsing sources at areas. PropertyDidNotTranslate An exception telling that one or more properties did not translate to ItemIDs. translate_to_item_ids() A method for translation of information about a source to ItemIDs for use with the data access interface. If one or more properties did not translate to ItemIDs, an exception is raised. The corresponding OPC method is IOPCEventServer::TranslateToItemIDs(). Member Description source The identification of the source. category The identification of the category. properties A sequence of properties for which ItemIDs are wanted. return A sequence of ItemIDs. Properties that did not translate to ItemIDs are returned as empty ItemIDs. enable_conditions() A method for enabling the specified sources. The corresponding OPC method is IOPCEventServer::EnableConditionBySource(). Member Description sources A sequence of area identifications. return The resource identifications that failed. disable_conditions() A method for disabling specified sources. The corresponding OPC method is IOPCEventServer::DisableConditionBySource(). Member Description sources A sequence of area identifications. return The resource identifications that failed. Browse sources : Client: Client : DAIS::AlarmsAndEvents::Source::IHome: DAIS::AlarmsAndEvents::Source::IHome : DAIS::Node::Iterator:DAIS::Node::Iteratorfind_by_parent( ) Get all sources that has a given area as parent next_n( ) Repeat getting all found sources from the iterator and continue with another area as parent to sources. Repeat this until all wanted sources are explored. For each source inspect the conditions it might have, refer to ConditionSpace Figure 5-11 Browse sources interaction A condition space describes a set of conditions; that is, it is a space of conditions. Each condition space is associated with a particular sub-reason of the main reason ConditionReason. Each condition has logic describing when the condition is active. The logic is described in a little language having the following constructs: • arithmetic operators • logic operators • references to properties The referred properties must be included in the set of properties defined by the associated reason. The little language grammar is server specific and is outside the scope of this specification. Transitions describe what transitions between conditions are allowed. The interface does not support exploration of the transitions. In OPC the ConditionSpace interface is implemented by the methods: • IOPCEventServer::QueryConditionNames() • IOPCEventServer::QuerySubConditionNames() . DAIS::AlarmsAndEvents::ConditionSpace::IHome <> find() find_each() find_by_reason() find_by_source() get_names() get_ids() 11 0..0.n.n 1..1.n.n 11 ConditionSpace id : ResourceID name : string description : string Condition id_number : unsigned long name : string description : string severity : unsigned long condition_logic : string ConditionCategory (from DAISAECategory) 1..1.n.n +conditions 0..0.n.n 0..n0..n Transition 11 11 0..0.n.n ConditionEvent (from DAISAEIO) Figure 5-12 DAIS alarms and events condition space IDL in UML //File: DAISAEConditionSpace.idl #ifndef _DAIS_AECONDITION_SPACE_IDL #define _DAIS_AECONDITION_SPACE_IDL #pragma prefix "omg.org" #include module DAIS {module AlarmsAndEvents {module ConditionSpace { struct ConditionDescription { unsigned long id_number; string name; string condition_logic; unsigned long severity; string descrip; }; typedef sequence ConditionDescriptions; struct Description { ResourceID id; string name; string descrip; ConditionDescriptionsconditions; }; typedef sequence< Description >Descriptions; interface IHome { exception UnknownResourceID {string reason;}; Description find ( in ResourceID condition_space ) raises (UnknownResourceID); Descriptions find_each ( in ResourceIDs condition_spaces ) raises (UnknownResourceID); Descriptions find_by_category ( in ResourceID category ) raises (UnknownResourceID); Descriptions find_by_source ( in ResourceID source ) raises (UnknownResourceID); Strings get_names ( in ResourceIDs condition_spaces ); ResourceIDs get_ids ( in Strings names ); };};};};#endif // _DAIS_AECONDITION_SPACE_IDL ConditionDescription A struct describing a condition. Member Description id_number A numeric identification unique within the condition space. name The name of the condition. condition_logic The logic telling when the condition is active. Refer to Section 5.2.7.3, “Condition Logic,? on page 5-38 for a description. severity Severity is a number between 1 and 1000 having the following meaning: • Low severity 1-200 • Medium low severity 201-400 • Medium severity 401-600 • Medium high severity 601-800 • High severity 801-1000 description A text that to be included in event notifications when the condition is active. Description A struct describing the condition space. Member Description id A ResourceID identifying the condition space. name The name of the condition space. description A description of the condition space. conditions A sequence of the conditions creates the condition space. In OPC the conditions are called sub-conditions and are retrieved by the method IOPCEventServer::QuerySubConditionNames(). IHome An object for browsing the condition spaces defined by a server. find() A method for getting the description of a condition space. Parameter Description condition_space A ResourceID identifying a condition space. return The condition space description. find_each() A method for getting the descriptions for a number of condition spaces. Parameter Description condition_spaces A sequence of ResourceID identifying condition spaces. return A sequence of condition space descriptions. find_by_category() A method for finding all condition spaces defined for a category. The corresponding OPC method is IOPCEventServer::QueryConditionNames(). Parameter Description category A ResourceID identifying the category for which to get the condition spaces. return A sequence of condition space descriptions. find_by_source() A method for finding all condition spaces defined for a source. The corresponding OPC method is IOPCEventServer::QuerySourceConditions(). Parameter Description source A ResourceID identifying the source for which to get the condition spaces. return A sequence of condition space descriptions. get_names() A method translating a number of condition space identifications into name strings. Parameter Description condition_spaces A sequence of ResourceID identifying condition spaces. return A sequence of condition space names. Non-translated identifications are returned as empty strings. get_ids() A method translating a number of condition space names into ResourceIDs. Parameter Description names A sequence of condition space names. return A sequence of condition space ResourceIDs. Non- translated identifications are returned as NULL IDs. Browse condition space by source : Client: Client : DAIS::AlarmsAndEvents::ConditionSpace::IHome: DAIS::AlarmsAndEvents::ConditionSpace::IHomefind_by_source( ) Get all condition space descriptions for one source. Explore each condition space from the retrieved descriptions. Figure 5-13 Browse condition space by source interaction Browse condition space by category : Client: CliAlrmsAndEvents::ConditionSpace::IHomeAent : DAIS::a: DAIS::larmsAndEvents::ConditionSpace::IHome find_by_category( ) Get all condition space description for one category. Explore each condition space from the retrieved descriptions. Figure 5-14 Browse condition space by category interaction The reduced XPath language as defined in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 is used to describe the condition_logic. This allows description of a path through a data structure picking up property values to be used in a logical expression. A common case is property values at objects associated with a source, hence the starting point for navigation is the source. An example from the CIM model where the Measurement is the source can be found in Figure 4-3 on page 4-6. Examples how to use DAIS_Expressions starting from a source are shown below: Measurement.value < 500 assuming that the tested value is an element at the source. MeasurementValue[id(MeasurementValue.MeasurementValueSource)/label='telemetry']/ MeasurementValue.value < id(Measurement.LimitSets)[LimitSet.label = 'summer']/Limit[label = 'highalarm']/Limit.value Based on the model in Figure 4-3 on page 4-6, the XML example in Section 3.1.12, “Logical Expressions and Navigation,? on page 3-25 and the source as a Measurement. A source condition associates a source with a condition space. A source condition holds the current information specific to a source using a particular condition space for the supervision. A source condition has no own identification and is identified by its associated source and condition space. Information about a source condition is accessed through its home object. In OPC a source condition is sometimes called an instance of a condition. In OPC the SourceCondition interface is implemented by the methods: • IOPCEventServer::QuerySourceConditions() • IOPCEventServer::AckCondition(). . DAIS::AlarmsAndEvents::SourceCondition::IHome <> find() find_each() ack_condition() Source (from DAISAE Source) 11 0..0.n.n 11 0..0.n.n 0..0.n.n 11 11 ConditionSpace (from DAISAE Condi ti onSpace) id : ResourceID name : string description : string Condition (from DA ISAECondi ti onSpace) id_number : unsigned long name : string description : string severity : unsigned long condition_logic : string SourceCondition condition_op_state : DAISConditionOpState quality : DAIS::Quality last_acknowledge : DateTime condition_last_active : DateTime condition_space_last_active : DateTime condition_space_last_inactive : DateTime acknowledger_name : string comment : string 0..0.n +active_condition .n Figure 5-15 DAIS alarms and events source condition IDL in UML //File: DAISAESourceCondition.idl #ifndef _DAIS_AESOURCE_CONDITION_IDL #define _DAIS_AESOURCE_CONDITION_IDL #pragma prefix "omg.org" #include module DAIS { module AlarmsAndEvents { module SourceCondition { struct Id { ResourceID source; ResourceID condition_space; }; typedef sequenceIds; struct Description { Id source_condition;SourceConditionOpState source_condition_op_state;unsigned long active_condition;string ac_logic;unsigned long ac_severity;string ac_description;Quality dais_quality;DateTime last_acknowledge;DateTime condition_last_active;DateTime condition_space_last_active;DateTime condition_space_last_inactive;string acknowledger_name;string comment;PropertyValues property_values; };typedef sequence< Description > Descriptions; struct AcknowledgeSpec { Id source_condition; DateTime active_time; EventID cookie; }; typedef sequenceAcknowledgeSpecs; interface Iterator { boolean next_n ( in unsigned long n, out Descriptions c_descriptions ); void reset(); Iterator clone(); void destroy(); }; interface IHome { exception UnknownId {string reason;}; exception UnknownPropertyID {string reason;}; Description find ( in Id source_condition, in PropertyIDs properties ) raises (UnknownId, UnknownPropertyID); Iterator find_each( in Ids source_conditions, in PropertyIDs properties ) raises (UnknownId, UnknownPropertyID); Descriptions ack_condition ( #endif // _DAIS_AESOURCE_CONDITION_IDL Id in string acknowledger_name, in string comment, in AcknowledgeSpecs ack_spec ); }; };};}; A struct that identifies a source condition. Member Description source The ResourceID identifying the associated source. condition_space The ResourceID identifying the associated condition space. Description A struct describing the source condition. Member Description id The Id identifying the source condition. source_condition_op_state The DAISSourceConditionOpState as described in Section 5.2.2, “Alarms and Events Common IDL Definitions,? on page 5-7. active_condition The identification number of the currently active condition. ac_logic The condition logic from the active condition. ac_severity The severity from the active condition. ac_description The description from the active condition. dais_quality The quality is evaluated from the qualities from the properties used to evaluate the condition logic. last_acknowledge The last time the condition was acknowledged. condition_last_active Time for the latest condition transition. condition_space_last_active The last time when the condition space became active. After this time more condition transitions may occur. The condition_last_active will then be later than condition_space_last_active. condition_space_last_inactive The last time when the condition space became inactive; that is, no conditions are active. acknowledger_name The name of the client making an acknowledge. comment A comment passed by the client making an acknowledge. property_values A sequence of property values as selected by the Manager::select_returned_properties call. AcknowledgeSpec A struct specifying an alarm to acknowledge. Member Description source_condition The Id identifying the source condition for which to acknowledge an alarm. active_time The time when the alarm activated. cookie A identification of the alarm. Iterator A standard iterator. Refer to Section 3.1.6, “Iterator Methods IDL,? on page 3-10. IHome An object for browsing and accessing source conditions. UnknownDAISSourceConditionID An exception telling that the source condition identification was not recognized. UnknownPropertyID An exception telling that a property identification was not recognized. find() A method for getting the description of a source condition. The corresponding OPC method is IOPCEventServer::GetConditionState(). Parameter Description source_condition A ResourceID identifying a source condition. return The source condition description. find_each() A method for getting the descriptions for a number of source conditions. Parameter Description condition_spaces A sequence identifying source conditions. return A sequence of source condition descriptions. ack_condition() A method to acknowledge a number of source condition alarms. The corresponding OPC method is IOPCEventServer::AckCondition(). Parameter Description acknowledger_name The name of the client making the acknowledge. comment A comment to be added to source condition and the event. ack_spec A sequence specifying the alarms to acknowledge. return A sequence containing descriptions for the acknowledged source conditions. Inspect a specific source condition : Client: Client : D A IS :: AlarmsA ndEvent s::S ourc eC ondition:: IH ome:DAIS::AlarmsAndEvents::SourceCondition::IHomefind( ) Get all det ails on a s pec ific source c ondit on Figure 5-16 Inspect a specific source condition interaction Acknowledge alarm : Client: Client : DAIS::AlarmsAndEvents::SourceCondition::IHom e:DAIS::AlarmsAndEvents::SourceCondition::IHomeack_condition( ) Acknolwedge a set of source conditions in one call Figure 5-17 Acknowledge alarm interaction These are definitions for manipulating categories. A category describes the content of an event. Categories are organized in a two level hierarchy where the first level has the three mandatory main categories; simple, condition, and tracking. Simple category does not have a condition space (refer to ConditonSpace). Generation of simple category alarms or events is coded into some software function and cannot be configured. Typical simple categories are program errors, hardware device failures, etc. Sources of different types (e.g., breaker position, breaker current, generator active power, etc.) may have different ways an alarm or event is generated (e.g., breaker trip, breaker over current, generator active power generation overload, etc.). Condition categories are used to describe source type specific alarm and event contents. The alarm and event generation for a condition category is configured using condition spaces and several condition spaces can be created for the same condition category. This corresponds to variations in the way the alarms and events are generated using different condition logics. Alarms or events due to operator actions or control functions (intended alarms or events rather than spontaneous) use tracking categories. A category has a set of properties associated with it. Some or all of the properties may be included in event notifications. The properties come from the source type and may be used by the logic generating an event notification. The get_main_ category () method is used to obtain the three main categories. The find_by_parent() is used to get the child categories. Categories at this second level correspond to the OPC EventCategories. The labels for the three main reasons are “DAIS_CONDITION_CATEGORY,? “DAIS_TRACKING_CATEGORY,? and "DAIS_SIMPLE_CATEGORY.? In OPC the Category interface is implemented by the methods IOPCEventServer::QueryEventCategories() and IOPCEventServer::QueryEventAttributes(). TrackingCategory SimpleCategory ConditionCategory DAIS::AlarmsAndEvents::Category::IHome get_main_categories() get_event_properties() <> DAIS::Node::IHome find() find_each() find_by_parent() find_by_type() get_pathnames() get_ids() (from DAISNode) <> Node id : ResourceID label : string type : ResourceID (f rom DA ISNo de) 1 0..10..nCategory Figure 5-18 DAIS alarms and events categories IDL in UML //File: DAISAECategory.idl #ifndef _DAIS_AECATEGORY_IDL #define _DAIS_AECATEGORY_IDL #pragma prefix "omg.org" #include module DAIS {module AlarmsAndEvents {module Category{ interface IHome : Node::IHome { Node::Descriptions get_main_categories (); PropertyIDs get_event_properties (in ResourceID category ); }; };};}; #endif // _DAIS_AECATEGORY_IDL IHome IHome is an object for browsing categories. Most of the browsing functionality is inherited from DAIS::Node. get_main_categories() Get the three main categories; simple, condition, and tracking. The three main categories appear as three different roots. Parameter Description return The descriptions for the three main categories. The labels for them are: • “DAIS_CONDITION_CATEGORY? • “DAIS_TRACKING_CATEGORY? • “DAIS_SIMPLE_CATEGORY? get_event_properties() Get all properties that are used in the supervision of the source type for a specific category. The corresponding OPC method is IOPCEventServer::QueryEventAttributes(). Parameter Description category The identification of the categories to get the properties for. return A sequence of property identifications. Browse categories get_main_reasons( ) : DAIS::AlarmsAndEvents::Category::IHome:DAIS::AlarmsAndEvents::Category::IHome: Client: ClientGet the three main reasons find_by_parent( ) Get the sub reasons for one main reason. For each sub reason explore 1) the condition spaces that are defined, refer to ConditionSpace 2) the properties that are used in supervision of sources Continue and explore all main reasons Figure 5-19 Browse category interaction Browse properties : DAIS::Alarm sAndE vents::Category::IHom e:DAIS::AlarmsAndEvents::Category::IHome: Client: ClientGet the three m ain categories Get the sub categories for one main category. For each sub category explore 1) the condition spaces that are defined, refer to ConditionSpace 2) the properties that are used in supervision of sources Continue and explore all main categories get_main_categories( ) find_by_parent( ) Figure 5-20 Browse properties interaction The IO interface for alarms & events only supports callbacks and the client shall implement callback. The event notifications sent over the callback are of three different formats corresponding to the three main categories (simple event, condition event, and tracking event). All three event formats have the common part Event. The tracking event has additional information on the operator and the condition event has additional information on the source condition causing the notification. In OPC the IO interface is implemented by the interface IOPCEventSink Source (from DAISAESource) Event source : ResourceID source_pathname : string time_stamp : DateTime message : string event_format : EventFormat category : ResourceID category_name : string severity : unsigned long property_values : PropertyValues 11SimpleCategory (from DAISAECa tegory) SimpleEvent 11ConditionCategory (from DAISAECategory ) ConditionEvent condition_space_name : string condition_space : ResourceID condition_name : string condition_number : unsigned long ack_required : boolean active_time : DateTime event_id : EventID change_specification : ChangeSpec source_condition_op_state : SourceConditionOpState dais_quality : Quality TrackingCategory (from DAISAECategory ) TrackingEvent actor_name : string 11DAIS::AlarmsAndEvents::IO::Callback <> on_event() on_read_complete() 11 Figure 5-21 DAIS alarms and events IO IDL in UML //File: DAISAEIO.idl#ifndef _DAIS_AEIO_IDL#define _DAIS_AEIO_IDL#pragma prefix "omg.org"#include module DAIS {module AlarmsAndEvents {module IO { typedef unsigned long ChangeSpec;const ChangeSpec CHANGE_ACTIVE_STATE = 0x0001; const ChangeSpec CHANGE_ACK_STATE = 0x0002; const ChangeSpec CHANGE_ENABLE_STATE = 0x0004; const ChangeSpec CHANGE_QUALITY = 0x0008; const ChangeSpec CHANGE_SEVERITY = 0x0010; const ChangeSpec CHANGE_CONDITION = 0x0020; const ChangeSpec CHANGE_MESSAGE = 0x0040; const ChangeSpec CHANGE_ATTRIBUTE = 0x0080; struct SimpleEvent { ResourceID source; string source_pathname; DateTime time_stamp; string message; EventFormat event_format; ResourceID category; string category_name; unsigned long severity; PropertyValues property_values; }; struct TrackingEvent { string actor_name; }; struct ConditionEvent { string condition_space_name; ResourceID condition_space; string condition_name; unsigned long condition_number; boolean ack_required; DateTime active_time; EventID event_id; ChangeSpec change_specification; SourceConditionOpState source_condition_op_state; Quality dais_quality; }; struct Event { SimpleEvent simple_event; TrackingEvent tracking_event; ConditionEvent condition_event; };typedef sequence Events; interface Callback{ void on_event (in boolean refresh,in boolean last_refresh,in Events the_events ); void on_read_complete (in Events the_events,in unsigned long transaction_id ); }; };};}; #endif // _DAIS_AEIO_IDL ChangeSpec A flag word having a number of flags telling what change caused the event notification. Flag Description CHANGE_ACTIVE_STATE Alarm active has changed. CHANGE_ACK_STATE Alarm acknowledge has changed. CHANGE_ENABLE_STATE Enable has changed. CHANGE_QUALITY The quality has changed. CHANGE_SEVERITY The severity has changed. CHANGE_CONDITION A condition has become active/inactive. CHANGE_MESSAGE The message has been updated. CHANGE_ATTRIBUTE An attribute value has changed. SimpleEvent A struct holding the simple event data. Member Description source The identification of the source for which the event notification was created. source_pathname The full pathname of the source. time_stamp Time of the event occurrence - for conditions, time that the condition transitioned into the new state or condition. For example, if the event notification is for acknowledgment of a condition, this would be the time that the condition became acknowledged. message Event notification message describing the event. event_format The identification for one of the three main formats. category The identification of the sub-category why the event notification was sent. category_name The label for the sub-category. severity The severity for the event, a number between 0 and 1000. property_values A sequence of property values as selected by the select_returned_properties() method. TrackingEvent A struct holding tracking event data. Member Description actor_name The name of the actor or operator causing the event notification. ConditionEvent A struct holding the condition event data. Member Description condition_space_name The name of the condition space that caused the event notification. condition_space Identification of the condition space. condition_name The name of the condition that caused the event notification. condition_number Identification of the condition. ack_required An indication that an alarm is generated and that an acknowledgment is required. active_time The time when the condition became active. event_id An identification of the event notification. change_specification Indicates to the client which properties of the condition have changed. source_condition_op_state The new state for the source condition. quality The quality. Event A struct composed of the three above event structs. The simple event struct always contains valid information and which of the tracking or condition event structs are valid is decided from the main_reason simple event member. Member Description simple_event The simple event. tracking_event The tracking event. condition_event The condition event. Callback The callback object implemented by the client and used by the server to send event notifications. on_event() The callback method. Parameter Description refresh Indicates if this callback is due to a refresh. last_refresh Indicates if this callback is the last in a sequence initiated by a refresh. the_events A sequence of event notifications. return None. on_read_complete() A callback method for the async_read_history() method. After an async_read_history() call from a client the server will deliver the historical events using this method. There is no corresponding OPC method. Parameter Description the_events A sequence of historical events. transaction_id The transaction number matching the client call number. Event notification callbacks : DAIS::Alarm sAndEvents::IO::Callback: DAIS::AlarmsAndEvents::Ints:Subscription::M anagerntO::Callback: DAIS::AlarmsAndEve:: DAIS::AlarmsAndEves::Subscription::Manageron_event( ) on_event( ) The on_event method is called by the server at 1) expiration of the subscription buffer_time timeout 2) subscription event buffer full For alarms the client may want to call SourceCondition::ack_alarm() to acknowledge. A ll inform ation needed for doing this is found in the event notifications. Figure 5-22 Event notification callbacks interaction Refresh callbacks : DAIS::AlarmsAndEvents::IO::Callback: DAIS::AlarmsAndEvents::IO::CallbackOn_event is called as response to a refresh. All refresh calls are made with the refresh parameter set and the last call also has the last_refresh parameter set. : DAIS::AlarmsAndEvents::Subscription::Manager:DAIS::AlarmsAndEvents::Subscription::Manageron_event( ) Figure 5-23 Refresh callbacks interaction