OPC HDA Auto 1.00 Specification

1、 subject * MERGEFORMAT Historical Data Access Automation Interface StandardJanuary 26, 2001Synopsis:This specification is an interface for developers of OPC clients and OPC Historical Data Access Servers. The specification is a result of an analysis and design process to develop a standard interface

2、 to facilitate the development of servers and clients by multiple vendors that shall inter-operate seamlessly together. This document defines the OPC Historical Data Access OLE Automation interface for developers of OPC clients and OPC Historical Data Access Servers. The purpose of this specificatio

3、n is to provide an OLE Automation interface for the OPC Historical Data Access Server Custom Interface FunctionalityDocumentation TypeIndustry Standard SpecificationTitle: TITLE * MERGEFORMAT OPC Historical Data Access Automation SpecificationDate:January 26, 2001Version:SoftMS-WordSource:Author: AU

4、THOR * MERGEFORMAT OPC FoundationStatus:ReleasedTrademarks:Most computer and software brand names have trademarks or registered trademarks. The individual trademarks have not been listed here.Required Runtime Environment:This specification requires Windows 95/98 (with DCOM installed), Windows NT 4.0

5、 or later. It is recommended that Windows NT 4.0 machines be run with SP3, or later.NON-EXCLUSIVE LICENSE AGREEMENTThe OPC Foundation, a non-profit corporation (the “OPC Foundation”), has established a set of standard OLE/COM interface protocols intended to foster greater interoperability between au

6、tomation/control applications, field systems/devices, and business/office applications in the process control industry. The current OPC specifications, prototype software examples and related documentation (collectively, the “OPC Materials”), form a set of standard OLE/COM interface protocols based

7、upon the functional requirements of Microsofts OLE/COM technology. Such technology defines standard objects, methods, and properties for servers of real-time information like distributed process systems, programmable logic controllers, smart field devices and analyzers in order to communicate the in

8、formation that such servers contain to standard OLE/COM compliant technologies enabled devices (e.g., servers, applications, etc.).The OPC Foundation will grant to you (the “User”), whether an individual or legal entity, a license to use, and provide User with a copy of, the current version of the O

9、PC Materials so long as User abides by the terms contained in this Non-Exclusive License Agreement (“Agreement”). If User does not agree to the terms and conditions contained in this Agreement, the OPC Materials may not be used, and all copies (in all formats) of such materials in Users possession m

10、ust either be destroyed or returned to the OPC Foundation. By using the OPC Materials, User (including any employees and agents of User) agrees to be bound by the terms of this Agreement.LICENSE GRANT:Subject to the terms and conditions of this Agreement, the OPC Foundation hereby grants to User a n

11、on-exclusive, royalty-free, limited license to use, copy, display and distribute the OPC Materials in order to make, use, sell or otherwise distribute any products and/or product literature that are compliant with the standards included in the OPC Materials. All copies of the OPC Materials made and/

12、or distributed by User must include all copyright and other proprietary rights notices include on or in the copy of such materials provided to User by the OPC Foundation.The OPC Foundation shall retain all right, title and interest (including, without limitation, the copyrights) in the OPC Materials

13、, subject to the limited license granted to User under this Agreement.WARRANTY AND LIABILITY DISCLAIMERS:User acknowledges that the OPC Foundation has provided the OPC Materials for informational purposes only in order to help User understand Microsofts OLE/COM technology. THE OPC MATERIALS ARE PROV

14、IDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF PERFORMANCE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. USER BEARS ALL RISK RELATING TO QUALITY, DESIGN, USE AND PERFORMANCE OF THE OPC MATERIALS. The OPC Foundatio

15、n and its members do not warrant that the OPC Materials, their design or their use will meet Users requirements, operate without interruption or be error free.IN NO EVENT SHALL THE OPC FOUNDATION, ITS MEMBERS, OR ANY THIRD PARTY BE LIABLE FOR ANY COSTS, EXPENSES, LOSSES, DAMAGES (INCLUDING, BUT NOT

16、LIMITED TO, DIRECT, INDIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR PUNITIVE DAMAGES) OR INJURIES INCURRED BY USER OR ANY THIRD PARTY AS A RESULT OF THIS AGREEMENT OR ANY USE OF THE OPC MATERIALS.GENERAL PROVISIONS:This Agreement and Users license to the OPC Materials shall be terminated (a) by User

17、 ceasing all use of the OPC Materials, (b) by User obtaining a superseding version of the OPC Materials, or (c) by the OPC Foundation, at its option, if User commits a material breach hereof. Upon any termination of this Agreement, User shall immediately cease all use of the OPC Materials, destroy a

18、ll copies thereof then in its possession and take such other actions as the OPC Foundation may reasonably request to ensure that no copies of the OPC Materials licensed under this Agreement remain in its possession.User shall not export or re-export the OPC Materials or any product produced directly

19、 by the use thereof to any person or destination that is not authorized to receive them under the export control laws and regulations of the United States.The Software and Documentation are provided with Restricted Rights. Use, duplication or disclosure by the U.S. government is subject to restricti

20、ons as set forth in (a) this Agreement pursuant to DFARs 227.7202-3(a); (b) subparagraph (c)(1)(i) of the Rights in Technical Data and Computer Software clause at DFARs 252.227-7013; or (c) the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 subdivision (c)(1) and (2), as appl

21、icable. Contractor/ manufacturer is the OPC Foundation, P.O. Box 140524, Austin, Texas 78714-0524.Should any provision of this Agreement be held to be void, invalid, unenforceable or illegal by a court, the validity and enforceability of the other provisions shall not be affected thereby. This Agree

22、ment shall be governed by and construed under the laws of the State of Minnesota, excluding its choice or law rules.This Agreement embodies the entire understanding between the parties with respect to, and supersedes any prior understanding or agreement (oral or written) relating to, the OPC Materia

23、ls. Table of Contents TOC o 1-4 1Introduction PAGEREF _Toc499438585 h 9Background PAGEREF _Toc499438586 h 9Purpose PAGEREF _Toc499438587 h 9Scope PAGEREF _Toc499438588 h 10References PAGEREF _Toc499438589 h 10Audience PAGEREF _Toc499438590 h 102Architecture PAGEREF _Toc499438591 h 11Functional Requi

24、rements PAGEREF _Toc499438592 h 11OPC HDA Automation Server Object Model PAGEREF _Toc499438593 h 12OPC HDA Automation Object Model PAGEREF _Toc499438594 h 12Introduction to Exceptions and Events PAGEREF _Toc499438595 h 13Exceptions PAGEREF _Toc499438596 h 13Events PAGEREF _Toc499438597 h 13Arrays PA

25、GEREF _Toc499438598 h 13Collections PAGEREF _Toc499438599 h 13Optional Parameters PAGEREF _Toc499438600 h 13Method Parameters PAGEREF _Toc499438601 h 14Type Library PAGEREF _Toc499438602 h 143About the OPC HDA Automation Wrapper DLL PAGEREF _Toc499438603 h 154OPC HDA Automation Objects & Interfaces

26、PAGEREF _Toc499438604 h 16OPCHDAServer Object PAGEREF _Toc499438605 h 16Summary of Properties PAGEREF _Toc499438606 h 16Summary of Methods PAGEREF _Toc499438607 h 16Summary of Events PAGEREF _Toc499438608 h 16OPCHDAServer Properties PAGEREF _Toc499438609 h 16StartTime PAGEREF _Toc499438610 h 16Curre

27、ntTime PAGEREF _Toc499438611 h 17MaxReturnValues PAGEREF _Toc499438612 h 17MajorVersion PAGEREF _Toc499438613 h 17MinorVersion PAGEREF _Toc499438614 h 18BuildNumber PAGEREF _Toc499438615 h 18VendorInfo PAGEREF _Toc499438616 h 18HistorianStatus PAGEREF _Toc499438617 h 18StatusString PAGEREF _Toc49943

28、8618 h 19ServerName PAGEREF _Toc499438619 h 19ServerNode PAGEREF _Toc499438620 h 19ClientName PAGEREF _Toc499438621 h 20LocaleID PAGEREF _Toc499438622 h 20CanSyncInsert/Replace/InsertReplace/DeleteRaw/DeleteAtTime PAGEREF _Toc499438623 h 20CanSyncRead/InsertAnnotations PAGEREF _Toc499438624 h 21CanA

29、syncInsert/Replace/InsertReplace/DeleteRaw/DeleteAtTime PAGEREF _Toc499438625 h 21CanAsyncRead/InsertAnnotations PAGEREF _Toc499438626 h 21OPCHDAItems PAGEREF _Toc499438627 h 22OPCHDAServer Methods PAGEREF _Toc499438628 h 22GetOPCHDAServers PAGEREF _Toc499438629 h 22Connect PAGEREF _Toc499438630 h 2

30、3Disconnect PAGEREF _Toc499438631 h 24GetErrorString PAGEREF _Toc499438632 h 24QueryAvailableLocaleIDs PAGEREF _Toc499438633 h 24GetItemAttributes PAGEREF _Toc499438634 h 25GetAggregates PAGEREF _Toc499438635 h 25CreateBrowser PAGEREF _Toc499438636 h 26OPCHDAServer Events PAGEREF _Toc499438637 h 27H

31、DAServerShutDown PAGEREF _Toc499438638 h 27OPCHDABrowser Object PAGEREF _Toc499438639 h 28Summary of Properties PAGEREF _Toc499438640 h 28Summary of Methods PAGEREF _Toc499438641 h 28OPCHDABrowser Properties PAGEREF _Toc499438642 h 29CurrentPosition PAGEREF _Toc499438643 h 29OPCHDABranches PAGEREF _

32、Toc499438644 h 29OPCHDALeaves PAGEREF _Toc499438645 h 29OPCHDAItems PAGEREF _Toc499438646 h 29OPCHDABrowser Methods PAGEREF _Toc499438647 h 30MoveUp PAGEREF _Toc499438648 h 30MoveToRoot PAGEREF _Toc499438649 h 30MoveDown PAGEREF _Toc499438650 h 30MoveTo PAGEREF _Toc499438651 h 30GetItemID PAGEREF _T

33、oc499438652 h 31OPCHDAItems Object PAGEREF _Toc499438653 h 32Summary of Properties PAGEREF _Toc499438654 h 32Summary of Methods PAGEREF _Toc499438655 h 32Summary of Events PAGEREF _Toc499438656 h 33OPCHDAItems Properties PAGEREF _Toc499438657 h 33Parent PAGEREF _Toc499438658 h 33Count PAGEREF _Toc49

34、9438659 h 33OPCHDAItems Methods PAGEREF _Toc499438660 h 33Item PAGEREF _Toc499438661 h 33GetOPCHDAItem PAGEREF _Toc499438662 h 34AddItem PAGEREF _Toc499438663 h 34AddItems PAGEREF _Toc499438664 h 34Remove PAGEREF _Toc499438665 h 35RemoveAll PAGEREF _Toc499438666 h 36Validate PAGEREF _Toc499438667 h

35、36SyncReadRaw PAGEREF _Toc499438668 h 36SyncReadProcessed PAGEREF _Toc499438669 h 38SyncReadAtTime PAGEREF _Toc499438670 h 39SyncReadModified PAGEREF _Toc499438671 h 40SyncReadAttribute PAGEREF _Toc499438672 h 41SyncInsert/Replace/InsertReplace PAGEREF _Toc499438673 h 43SyncDeleteRaw PAGEREF _Toc499

36、438674 h 44SyncDeleteAtTime PAGEREF _Toc499438675 h 45SyncReadAnnotations PAGEREF _Toc499438676 h 46SyncInsertAnnotations PAGEREF _Toc499438677 h 47AsyncReadRaw PAGEREF _Toc499438678 h 48AsyncAdviseRaw PAGEREF _Toc499438679 h 50AsyncReadProcessed PAGEREF _Toc499438680 h 51AsyncAdviseProcessed PAGERE

37、F _Toc499438681 h 52AsyncReadAtTime PAGEREF _Toc499438682 h 54AsyncReadModified PAGEREF _Toc499438683 h 55AsyncReadAttribute PAGEREF _Toc499438684 h 57AsyncCancelRead PAGEREF _Toc499438685 h 58AsyncInsert/Replace/InsertReplace PAGEREF _Toc499438686 h 58AsyncDeleteRaw PAGEREF _Toc499438687 h 60AsyncD

38、eleteAtTime PAGEREF _Toc499438688 h 61AsyncCancelUpdate PAGEREF _Toc499438689 h 63AsyncReadAnnotations PAGEREF _Toc499438690 h 63AsyncInsertAnnotations PAGEREF _Toc499438691 h 64AsyncCancelAnnotations PAGEREF _Toc499438692 h 66AsyncPlaybackRaw PAGEREF _Toc499438693 h 66AsyncPlaybackProcessed PAGEREF

39、 _Toc499438694 h 68AsyncCancelPlayback PAGEREF _Toc499438695 h 69OPCHDAItems Events PAGEREF _Toc499438696 h 70DataChange PAGEREF _Toc499438697 h 70AsyncReadComplete PAGEREF _Toc499438698 h 71AsyncReadModifiedComplete PAGEREF _Toc499438699 h 71AsyncReadAttributesComplete PAGEREF _Toc499438700 h 72Asy

40、ncReadAnnotationsComplete PAGEREF _Toc499438701 h 73AsyncInsertAnnotationsComplete PAGEREF _Toc499438702 h 73Playback PAGEREF _Toc499438703 h 74AsyncUpdateComplete PAGEREF _Toc499438704 h 75AsyncCancelComplete PAGEREF _Toc499438705 h 75OPCHDAItem Object PAGEREF _Toc499438706 h 77Summary of Propertie

41、s PAGEREF _Toc499438707 h 77Summary of Methods PAGEREF _Toc499438708 h 77OPCHDAItem Properties PAGEREF _Toc499438709 h 77Parent PAGEREF _Toc499438710 h 77ClientHandle PAGEREF _Toc499438711 h 77ServerHandle PAGEREF _Toc499438712 h 77ItemID PAGEREF _Toc499438713 h 78OPCHDAItem Methods PAGEREF _Toc4994

42、38714 h 78OPCHDAHistory Object PAGEREF _Toc499438715 h 79Summary of Properties PAGEREF _Toc499438716 h 79Summary of Methods PAGEREF _Toc499438717 h 79OPCHDAHistory Properties PAGEREF _Toc499438718 h 79Count PAGEREF _Toc499438719 h 79OPCHDAHistory Methods PAGEREF _Toc499438720 h 80Item PAGEREF _Toc49

43、9438721 h 80OPCHDAValue Object PAGEREF _Toc499438722 h 81Summary of Properties PAGEREF _Toc499438723 h 81OPCHDAValue Properties PAGEREF _Toc499438724 h 81TimeStamp PAGEREF _Toc499438725 h 81DataValue PAGEREF _Toc499438726 h 81Quality PAGEREF _Toc499438727 h 81OPCHDAEntry Object PAGEREF _Toc499438728

44、 h 82Summary of Properties PAGEREF _Toc499438729 h 82OPCHDAEntry Properties PAGEREF _Toc499438730 h 82TimeStamp, DataValue, Quality PAGEREF _Toc499438731 h 82EntryTime PAGEREF _Toc499438732 h 82EntryType PAGEREF _Toc499438733 h 82User PAGEREF _Toc499438734 h 825OPC HDA Automation Definitions and Sym

45、bols PAGEREF _Toc499438735 h 84OPCHDAServerState PAGEREF _Toc499438736 h 84OPCHDAOperatorCode PAGEREF _Toc499438737 h 84OPCHDAEditType PAGEREF _Toc499438738 h 84OPCHDAErrors PAGEREF _Toc499438739 h 84OPCHDAAggregate PAGEREF _Toc499438740 h 85OPCHDAQuality PAGEREF _Toc499438741 h 85OPCHDAAttribute PA

46、GEREF _Toc499438742 h 866Appendix A - OPC Automation Error Handling PAGEREF _Toc499438743 h 877Appendix B - OPC HDA Automation IDL Specification PAGEREF _Toc499438744 h 898Appendix C- Notes On Automation Data Types PAGEREF _Toc499438745 h 104IntroductionBackgroundA standard mechanism for communicati

47、ng to numerous data sources, either devices on the factory floor, or a database in a control room is the motivation for this specification. The standard mechanism would consist of a standard automation interface targeted to allow Visual Basic applications, as well as other automation enabled applica

48、tions to communicate to the above named data sources. Manufacturers need to access data from the plant floor and integrate it into their existing business systems. Manufacturers must be able to utilize off the shelf tools (SCADA Packages, Databases, spreadsheets, etc.) to assemble a system to meet t

49、heir needs. The key is open and effective communication architecture concentrating on data access, and not the types of data. We have addressed this need by architecting and specifying a standard automation interface to the OPC Historical Data Access Custom interface to facilitate the needs of appli

50、cations that utilize an automation interface to access plant floor data.PurposeWhat is needed is a common way for automation applications to access data from any data source like a device or a database.The OPC Historical Data Access Automation defines a standard by which automation applications can

51、access process data. This interface provides the same functionality as the custom interface, but in an “automation friendly” manner.Given the common use of Automation to access other software environments (e.g.: RDBMS, MS Office applications, WWW objects), this interface has been tailored to ease ap

52、plication development, without sacrificing functionality defined by the Custom interface.The figure below shows an Automation client calling into an OPC Historical Data Access Server using a wrapper DLL. This wrapper translates between the custom interface provided by the server and the automation i

53、nterface desired by the client. Note that in general the connection between the Automation Client and the Automation Server will be In Process while the connection between the Automation Server and the Custom Server may be either In Process, Local or Remote. Figure 1- SEQ Figure * ARABIC 1. Custom a

54、nd Automation Client Applications Interfacing to OPC HDA ServersScopeThis document represents the initial release of the OPC HDA Automation specification. It is assumed that the reader is familiar with the information provided on the OPC Historical Data Access Custom Interface Specification. That do

55、cument provides an Overview of the OPC functionality as well as detailed descriptions of the behavior of the various functions.We have deliberately not duplicated that information in an attempt to maintain consistency.ReferencesKraig Brockschmidt, Inside OLE, Second Edition, Microsoft Press, Redmond

56、, WA, 1995.Microsoft Systems Journal, Q&A, April 1996, pp. 89-101.OLE Automation Programming Reference, Microsoft Press, Redmond, WA, 1996.OLE 2 Programming Reference, Vol. 1, Microsoft Press, Redmond, WA, 1994.OPC Historical Data Access Custom Interface Standard, Version 2.0, OPC Foundation 1998.Au

57、dienceThis specification is intended as reference material for developers of OPC Automation Clients that require the functionality of the OPC Historical Data Access Custom Interface.The developer needs some knowledge of basic Automation concepts and terminology.Architecture The fundamental design go

58、al is that this interface is intended to work as a wrapper for existing OPC Historical Data Access Custom Interface Servers, providing an automation friendly mechanism to the functionality provided by the custom interface.Functional RequirementsThe automation interface provides nearly all of the fun

59、ctionality of the required and optional Interfaces in the OPC Historical Data Access Custom Interface. If the OPC Historical Data Access Custom server supports the interface, the functions and properties at the automation level will work. Automation interfaces generally do not support optional capab

60、ilities in the same way that the custom interface does. If the underlying custom interface omits some optional functionality then the corresponding automation functions and properties will exhibit some reasonable default behavior as described in more detail later in this document.The interfaces are