2023年6月26日发(作者：)

ComputingOPC Server InterfaceManualThis manual is based on version 2.0 of the OPCspecification from the OPC manual is available only in English.C79000–G7076–C225–01Edition: 3OPC Custom Interface1OPC Automation Interface2Safety GuidelinesThis manual contains notices which you should observe to ensure your own personal safety, as well as toprotect the product and connected equipment. These notices are highlighted in the manual by a warningtriangle and are marked as follows according to the level of danger:!!!Dangerindicates that death, severe personal injury or substantial property damage will result if proper precau-tions are not gindicates that death, severe personal injury or substantial property damage can result if proper precau-tions are not nindicates that minor personal injury or property damage can result if proper precautions are not aws your attention to particularly important information on the product, handling the product, or to aparticular part of the ied PersonnelOnly qualified personnel should be allowed to install and work on this equipment. Qualified persons aredefined as persons who are authorized to commission, to ground, and to tag circuits, equipment, and sys-tems in accordance with established safety practices and t UsageNote the following:!WarningThis device and its components may only be used for the applications described in the catalog or thetechnical descriptions, and only in connection with devices or components from other manufacturerswhich have been approved or recommended by product can only function correctly and safely if it is transported, stored, set up, and installed cor-rectly, and operated and maintained as arksSIMATICR, SIMATIC HMIR and SIMATIC NETR are registered trademarks of SIEMENS of other designations used in these documents are also registered trademarks; the owner’s rightsmay be violated if they are used by third parties for their own ght Siemens AG 1999 All rights reservedThe reproduction, transmission or use of this document or its contents is notpermitted without express written authority. Offenders will be liable for rights, including rights created by patent grant or registration of a utility modelor design, are imer of LiabilityWe have checked the contents of this manual for agreement with the hardware andsoftware described. Since deviations cannot be precluded entirely, we cannotguarantee full agreement. However, the data in this manual are reviewed regularlyand any necessary corrections included in subsequent editions. Suggestions forimprovement are s AGAutomation and Drives (A&D)Industrial Automation Systems (AS)Postfach 4848, D- 90327 NürnbergSiemens AktiengesellschaftE Siemens AG 1999Technical data subject to ts1OPC Custom Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.11.21.3Creating and Using an OLE Object in C/C++. . . . . . . . . . . . . . . . . . . . . . . .

Additional Information about the Interface Description for the OPC CustomInterface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The “OPC Server” Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-11-21-51-61.4Objects of the “OPC Group” Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.5IDataObject Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2OPC Automation Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.1Creating and Using an OLE Object in Visual Basic. . . . . . . . . . . . . . . . . . .

2.2Object Model for the Automation Interface. . . . . . . . . . . . . . . . . . . . . . . . . .

2.3The “OPCServer” Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.4The “OPCBrowser” Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.5The “OPCGroups” Collection Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.6The “OPCGroup” Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.7The “OPCItems” Collection Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.8The “OPCItem” Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Figures1-1OPC Server Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-2OPC Group Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-3IAdviseSink (Client) and IDataObject (Server) Interfaces. . . . . . . . . . . . . .

2-1Activating the Reference for the Automation Interface. . . . . . . . . . . . . . . .

2-2Object Model for the Automation Interface. . . . . . . . . . . . . . . . . . . . . . . . . .

Tables1-1Objects and Interfaces of the OPC Custom Interface . . . . . . . . . . . . . . . .

2-1Properties of the “OPCServer” Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-2Properties of the “OPCBrowser” Object . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-3Properties of the “OPCGroups” Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-4Properties of the “OPCGroup” Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-5Properties of the “OPCItems” Collection Object . . . . . . . . . . . . . . . . . . . . .

2-6Properties of the “OPCItem” Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

OPC Server Interface

C7900–G7076–C225–011-111-162-12-22-52-62-82-102-122-152-171-61-111-162-22-51-52-62-82-102-122-152-17iContentsiiOPC Server Interface

C7900–G7076–C225–01OPC Custom InterfaceChapter Overview1This chapter shows how to use the OPC custom interface. It also lists theinterfaces and methods of the OPC customer interface. This is not a detailedinterface description but contains supplementary information and notes relatingspecifically to the Computing is now an extended version of the OPC custom interface, specification n 2.0 supplements the existing OPC custom interface in several aspectsparticularly those simplifying the handling of asynchronous interfaces of Version 1.0 of the OPC interface are completely upwardscompatible with Version n1.11.21.31.41.5DescriptionCreating and Using an OLE Object in C/C++Additional Information about the Interface Description for the OPCCustom InterfaceThe “OPC Server” ObjectObjects of the “OPC Group” ClassIDataObject InterfacePage1-21-51-61-111-16OPC Server Interface

C7900–G7076–C225–011-1OPC Custom Interface1.1Creating and Using an OLE Object in C/C++The following sections illustrate step-by-step how you can call the methods of aninstance of an OLE class in C++. Note the difference between the term “Class” inOLE and in C++:SSOLE Classes: A Windows object is an instance of an OLE class. The term OLEclass differs from the class in C++.C++ Classes: A class in C++ is a type definition. An OLE class is, however, anobject description and does not contain Identification CodeEach OLE class can be identified uniquely by a 128-bit long identification code, theCLSID. This is used by the operating system for the unique assignment of a DLLor EXE file that implements this class. A client that wishes to use an object of aclass requires only the To simplify the identification of OPC servers, there is normally a readable name,the ProgID assigned in the CLSIDs. While a CLSID is always unique due to thealgorithm for compilation, it is possible that a ProgID exists more than once. Justlike the CLSID, the ProgID is specified by the vendor of an OPC ProgID for the OPC server of Computing is: reating a COM ObjectA COM object is created in five steps:lize the an an OPC e the interfaces 1: Initialize COMBefore you can use the functions of COM, the COM library must be initialized withthe following call:HRESULT r1;

r1 = CoInitialize(NULL);1-2OPC Server Interface

C7900–G7076–C225–01OPC Custom InterfaceStep 2: Query the CLSIDIf the name of an object is known, the CLSID can be queried using the OLEfunction “CLSIDFromProgID”.Example: The following program section illustrates how to query the CLSID for theOPC server for clsid; // Get the CLSID from the Namer1 = CLSIDFromProgID((L””),&clsid);Step 3: Create an ObjectIf a client wants to use an object, it transfers the CLSID to the operating systemand requests an object instance. Regardless of where the server is located, theobject request is always directed to “CoCreateInstance” function creates an object belonging to the required function includes certain intermediate steps via the “IClassFactory” ng an object using IClassFactory is more efficient when several objects of aclass must be e: The following lines show how an object of the class “OPC server” withreference to the “IUnknown” interface can be wn * pOPCUnknown;r1 = CoCreateInstance (clsid, NULL, CLSCTX_LOCAL_SERVER,IID_IUnknown, (void**) &pOPCUnknown );Step 4: Call an OPC FunctionIn this step, a method of the “IOPCServer” interface of the created object will beused to learn the status of the server. First, a pointer to the “IOPCServer” interfaceis made available via “IUnKnown”. Finally, the “GetStatus” method is e: The program shown below outputs the status of the server and thevendor information. If the “GetStatus” method is called successfully, the OPCserver allocates the memory areas for the return information via the “IMalloc”interface. The user must release these memory areas rver *pOPCServer;OPCSERVERSTATUS *pss;r1 = pOPCUnknown–>QueryInterface(IID_IOPCServer,(void**)&pOPCServer);r1 = pOPCServer –>GetStatus(&pss);printf(”orInfo = %lsn”, pss–> szVendorInfo);// Remember to release the memory returned by the methodpIMalloc–>Free(pss–>szVendorInfo);pIMalloc–>Free(pss);OPC Server Interface

C7900–G7076–C225–011-3OPC Custom InterfaceStep 5: Release the Interfaces UsedObjects include reference counters to detect when the object is no longer requiredand can remove itself from memory. Each time the “QueryInterface” function iscalled, the reference counter is incremented. To release the object, the countermust be e: Using the following commands, the reference counter for the interfaces“IUnknown” and “IOPCServer” is rver–>Release();pOPCUnknown–>Release();1-4C7900OPC Server Interface

–G7076–C225–01OPC Custom Interface1.2Additional Information about the Interface Description for theOPC Custom InterfaceA comprehensive description of the OPC interfaces is beyond the scope of thismanual. This is supplied as a file along with this product as an original Englishdocument from the OPC Foundation. The documents are located in the ”DOC”directory in the product directory of the OPC server for following supplementary information about the interfaces lists the objects ofOPC, their interfaces and the methods defined in these interfaces and points outparticular characteristics of the OPC server for ValuesAll the listed methods return a result of the type ew of the Objects and InterfacesTable 1-1Objects and Interfaces of the OPC Custom Interface

ObjectIOPCServerIOPCServerPublicGroups (optional)IOPCBrowseServerAddressSpace (optional)OPCServerIOPCItemProperties (new with V 2.0)IConnectionPointContainer (new with V 2.0)IOPCCommon (new with V 2.0)IPersistFile (optional)IOPCGroupStateMgtIOPCPublicGroupStateMgt (optional)IOPCASyncIO2 (new with V 2.0)IOPCAsyncIO (no longer necessary with V2.0)OPCGroupIOPCItemMgtIConnectionPointContainer (new with V 2.0)IOPCSyncIOIDataObject (no longer necessary with V2.0)EnumOPCItemAttributesIEnumOPCItemAttributesInterfaceOPC Server Interface

C7900–G7076–C225–011-5OPC Custom Interface1.3The “OPC Server” ObjectThe OPC server class has various attributes that contain information about thestatus, the version etc. of an OPC server object. The OPC server class also hasmethods with which a client can manage the objects of the OPC group class. Aclient application addresses only an object of this class directly using COMmechanisms. The other objects are created by corresponding OPC methods of the IOPCServer interface are used to manage the objects in theOPC group class. Using the methods of the IOPCBrowseServerAddressSpaceinterface, it is possible to investigate the address area of the 1-1 illustrates the “OPC server” object with its wnIOPCServerIOPCBrowseServerAddressSpaceIOPCCommon (V2.0)IConnectionPointContainer (V2.0)IOPCItemsProperties (V2.0)Figure 1-1OPC Server ObjectOPCServer ObjectIOPCServer InterfaceThis interface contains methods to manage groups within a server object. It is alsopossible to obtain information about the current status of the up ( szName, bActive, dwRequestedUpdateRate, hClientGroup,pTimeBias, pPercentDeadband, dwLCID, phServerGroup,pRevisedUpdateRate, riid, ppUnk )Creates a group in the server :SSSSSThe ”pTimeBias” parameter is not evaluated by the OPC server for Computing.“LCID” is irrelevant for the OPC server for “UpdateRate” is specified by the configuration parameter “Minimum UpdateRate” as a multiple of the configuration “pPercentDeadband” parameter is only effective for variables of the real(VT_R4) the “szName” parameter is empty, a name is generated beginning with theunderscore character (for example, “_123456”). User-defined names shouldtherefore not begin with the underscore character.1-6OPC Server Interface

C7900–G7076–C225–01OPC Custom InterfaceCreateGroupEnumerator ( dwScope, riid, ppUnk )Creates various enumerators for the : Since there are no public groups in the OPC server for Computing, the returnvalues for the parameter ”dwScope” ”...PRIVATE” and ”...PUBLIC” are orString ( dwError, dwLocale, ppString )Supplies the error message for a specific error : The OPC server for Computing supports German and English error detected by the Windows operating system are explained in the language inwhich the operating system was upByName ( szName, riid, ppUnk )Supplies an additional interface pointer for the name of a private group, in otherwords the reference counter is tus ( ppServerStatus )Supplies the status information of the : The return value of the OPC server for Computing is the name and theversion of the OPC Group ( hServerGroup, bForce )Deletes a group on the : The OPC server for Computing does not support the use of the ”bForce”parameter. It is not possible to delete groups to which references are still owseServerAddressSpace InterfaceThis interface contains methods with which the address area of the server can bequeried. The address area contains all the OPC items known to the AccessPaths ( szItemID, ppIEnumString )This provides the possibility of querying the access path of an : Not required with the OPC server for Server Interface

C7900–G7076–C225–011-7OPC Custom InterfaceBrowseOPCItemIDs ( dwBrowseFilterType, szFilterCriteria,vtDataTypeFilter, dwAccessRightsFilter, ppIEnumString )Supplies a string of the type ”IEnumString” whose content is specified by the callparameters. The position from which the list is created can be set using the”ChangeBrowsePosition” :SS“BRANCH” excludes the filters for Type and rules for creating a filter are as follows:–Asterisk (*) Any character string, including empty strings–Plus (+) Any character string, however at least one character–Question marks (?) Any single character–Square brackets ( [ ] ) One single character from the specified setSTo use one of the filter characters, this must be preceded by a back slash ().ChangeBrowsePosition ( dwBrowseDirection, szString )Allows you to browse through the address area. You can change to the higher levelor to a mID ( szItemDataID, szItemID )Creates a complete ItemID in the hierarchical address area. This function isnecessary since browsing itself only provides the designations below the : The description of GetItemID in OPC specification is inconsistent with thedescription of ChangeBrowsePosition. With ChangeBrowsePosition, it is notpossible to specify a complete ItemID. For this reason, the OPC server forComputing only currently supports the command GetItemID for single leaves(LEAF).QueryOrganization ( pNameSpaceType )Supplies the structure of the address area. The address area can be organizedwith a flat or hierarchical : The structure of the address area of the OPC server for Computing isstructured hierarchically.1-8OPC Server Interface

C7900–G7076–C225–01OPC Custom InterfaceIOPCCommon Interface (Version 2.0)This interface of version 2.0 of the OPC Custom Interface contains methodsallowing the language settings and the name of the client to be made known to aleID (dwLcid)Sets the language code of the server. The language code specifies the language inwhich the server outputs : The OPC server for Computing supports English and aleID (pdwLcid)Fetches the language code of the : The OPC server for Computing supports English and vailableLocaleIDs (pdwLcid)Provides all the available language codes of the : The OPC server for Computing supports English and orString (dwError, ppString)Provides the error text for a specific error code in the set entName (szName)Transfers a descriptive text for the client to the server. The descriptive text can beused for any purpose by the server, for example for logging in trace ctionPointContainer InterfaceThis interface is a standard COM interface for reporting asynchronous events viaconnection points. For more detailed information about using connection points,refer to the documentation of OLE/emProperties (V 2.0) InterfaceThis interface of version 2.0 contains methods allowing specific server informationto be queried about an vailableProperties (szItemID, pdwCount, ppPropertyIDs,ppDescriptions, ppvtDataTypes )Returns a list of available properties for an Server Interface

C7900–G7076–C225–011-9OPC Custom InterfaceGetItemProperties (szItemID, dwCount, pdwPropertyIDs, ppvData,ppErrors )Provides the values of the properties of an item transferred in a list of ItemIDs (szItemID, dwCount, pdwPropertyIDs, ppszNewItemIDs,ppErrors);Provides (whenever possible for the propertyID) a list of ItemIDs for a list ofPropertyIDs. These ItemIDs can be included in a group simplifying and speedingup access to the : The OPC server for Computing does not support this function. The call isrejected with error message 0x8004001 (not implemented).1-10OPC Server Interface

C7900–G7076–C225–01OPC Custom Interface1.4Objects of the “OPC Group” ClassThe “OPC Group” class manages the individual process variables, the OPC these group objects, a client can form semantically meaningful units of OPCitems and execute operations with 1-2 illustrates an object of the “OPC Group” class and its wnIOPCItemMgtIOPCGroupStateMgtIOPCSyncIOIOPCAsyncIOIDataObjectIOPCItemsAttributesOPCGroup ObjectIOPCAsyncIO2 (V 2.0)IConnectionPointContainer (V 2.0)Figure 1-2OPC Group ObjectIOPCItemMgt InterfaceThis interface provides methods to manage more than one item in a StampWith each value read, OPC supplies a time stamp. This indicates when this valuewas received or when it was changed. Since the SIMATIC systems do not use atime stamp, the time at which the value is received on the server is used as thetime Server Interface

C7900–G7076–C225–011-11OPC Custom InterfaceAddItems ( dwNumItems, pItemArray, ppAddResults, ppErrors )Adds one or more items to a :SA unique name of an item for the OPC server for Computing is as follows:Examples

MD0:0This name can be specified completely in the ItemID. The AccessPath mustthen be an alternative, the part of the name in square brackets can be included inthe e:

SAccessPath: “”MD0:RealIt is possible to add the same OPC item to the same group more than once. Inthis case each of these items nevertheless has its own server server handles of the items are only unique within a group and not for allitems of all data types are as follows: VT_UI1, VT_UI2, VT_UI4, VT_I1, VT_I2,VT_I4, VT_R4, VT_BOOL, VT_BSTRCreateEnumerator ( riid, ppUnk )Creates an enumerator for the items of a Items ( dwNumItems, phServer, ppErrors )Deletes one or more items from a iveState ( dwNumItems, phServer, bActive, ppErrors )Sets the active state of one or more items in a entHandles ( dwNumItems, phServer, phClient, ppErrors )Sets the client handle of one or more items in a atypes ( dwNumItems, phServer, pRequestedDatatypes, ppErrors )Sets the requested data type of one or more items in a : See AddItem1-12OPC Server Interface

C7900–G7076–C225–01OPC Custom InterfaceValidateItems ( dwNumItems, pItemArray, bBlobUpdate,ppValidationResults, ppErrors )Checks the validity of an OPC item, for example whether it was added to a groupwithout any error occurring, and supplies information such as the canonical : See AddItemIOPCGroupStateMgt InterfaceThe IOPCGroupStateMgt interface provides methods with which groups can bemanaged. It is possible to edit group-specific parameters and to copy roup ( szName, riid, ppUnk )Creates a copy of a group. All group attributes are copied except for the following:SSThe active state is set to FALSEA new server handle is assignedNote: The “szName” parameter can be empty. In this case a unique name isgenerated (see AddGroup).GetState ( pUpdateRate, pActive, ppName, pTimeBias, pPercentDeadband,pLCID, phClientGroup, phServerGroup )Fetches the status of the group. The client application must inform the OPC serverwhere the results are to be stored using a :SSSThe “pTimeBias” parameter has no significance for the OPC server “pPercentDeadband” parameter has no significance for the OPC server “LCID” parameter, in other words language-specific textual values inread/write, has no significance for SIMATIC e ( szName )Allows the name of a group to be changed. The name must always be Server Interface

C7900–G7076–C225–011-13OPC Custom InterfaceSetState ( pRequestedUpdateRate, pRevisedUpdateRate, pActive,pTimeBias, pPercentDeadband, pLCID, phClientGroup )SetState allows various properties of the group to be :SSSSThe “pTimeBias” parameter has no significance for the OPC server “pPercentDeadband” parameter has no significance for the OPC server “LCID” parameter, in other words language-specific textual values inread/write, has no significance for SIMATIC “UpdateRate” is specified by the configuration parameter “Minimum UpdateRate” as a multiple of this ncIO InterfaceThis interface provides methods for synchronous reading and writing. Synchronousmeans that the client waits until the read or write operation is completed and onlythen continues use of synchronous calls is recommended when the client requires the resultfor further processing. Other clients are not blocked since the OPC server forComputing starts a separate thread for each general, it is advisable to use the IData interface for processing variablechanges (or IAdviseSink on the client side). This interface guarantees the highestpossible data throughput and also reduces the actual number of calls to theabsolute minimum (only when changes occur).Read ( dwSource, dwNumItems, phServer, ppItemValues, ppErrors )Reads the values, status information or time stamp of one or more items in agroup. The values can be read from the cache of the server or directly from thehardware. Reading from the cache is, however, only possible when the group : The call is monitored by the timeout monitoring on the server. Thecorresponding configuration parameter is “Read/Write Timeout”.Write ( dwNumItems, phServer, pItemValues, ppErrors )Writes values for one or more items of a group to the : The call is monitored by the timeout monitoring on the server. Thecorresponding configuration parameter is ”Read/Write Timeout”.1-14OPC Server Interface

C7900–G7076–C225–01OPC Custom InterfaceIOPCAsyncIO InterfaceThis interface of the Group class provides methods for asynchronous reading andwriting of items. Asynchronous means that the client triggers a read or writeoperation and then continues operation. Asynchronous operations provide atransaction ID. When the server has completed the read or write operation, theclient receives a message sent to its IAdviseSink ( dwTransactionID )Cancels an outstanding ( dwConnection, dwSource, dwNumItems, phServer, pTransactionID,ppErrors )Sends an asynchronous read command. The result is sent to the IAdviseSinkinterface of the : The call is monitored by the timeout monitoring on the server. Thecorresponding configuration parameter is “Read/Write Timeout”. If the timeoutmonitoring is aborted, there is a callback with hrStatus=E_h ( dwConnection, dwSource, pTransactionID )Requests a current value for every active OPC ( dwConnection, dwNumItems, phServer, pItemValues,pTransactionID, ppErrors )Sends an asynchronous write : The call is monitored by the timeout monitoring on the server. Thecorresponding configuration parameter is “Read/Write Timeout”. If the timeoutmonitoring is aborted there is a callback with hrStatus=E_ Server Interface

C7900–G7076–C225–011-15OPC Custom Interface1.5IDataObject InterfaceThe IDataObject interface is the standard interface of OLE for data transmission. Itcontains methods for establishing a message connection between the client and aserver ption of the MechanismIf the server wants to send a message to a client, the client must provide a partnerfor the server. This partner is the IadviseSink interface of the client. A server sendsa message to a client by calling the OnDataChange method of the IAdviseSinkinterface of the entation of the MechanismFigure 1-3 illustrates how the “IAdviseSink” interface on the client and“IDataObject” on the server IDataObject::DAdviseServerIAdviseSinkIDataObjectIAdviseSink::OnDataChangeFigure 1-3IAdviseSink (Client) and IDataObject (Server) InterfacesDAdvise (pFmt, adv, pSnk, pConnection);Establishes a connection between a server and the client. If a client wants toreceive a message, it must establish a connection using this method. It transfers apointer to its IAdviseSink interface to the ise (Connection)Terminates an existing connection between a client and server.1-16OPC Server Interface

C7900–G7076–C225–01OPC Custom InterfaceIEnumOPCItemAttributes InterfaceThis interface based on the IEnum standard interface returns the items of a interface is supplied only by “IOPCItemMgr:CreateEnumerator”. It is notobtainable with (ppEnumItemAttributes);Creates an identical copy of the (celt, ppItemArray, pceltFetched);Fetches the next OPC item of the : The OPC server for Computing does not support engineering units. EUTypeand EUInfo are therefore (void);Resets the list to the first item of the (celt);Skips a number of items in the IO2 Interface (Version 2.0)This interface in version 2.0 provides methods for asynchronous reading andwriting of items. Asynchronous means that the client triggers a read or writeoperation and then continues operation. Version 2 of the interface forasynchronous communication uses connection points. This simplifies theprocessing of the transferred (dwCount, phServer, dwTransactionID, pdwCancelID, ppErrors)Sends an asynchronous read command. The result is sent to the client via aconnection : The call is monitored by the timeout monitoring on the server. If the set timeis exceeded, this is indicated by the status E_ (dwCount, phServer, pItemValues, dwTransactionID, pdwCancelID,ppErrors)Sends an asynchronous write command. The message indicating completion ofthe job comes via the specified connection : The call is monitored by the timeout monitoring on the server. If the set timeis exceeded, this is indicated by the status E_ Server Interface

C7900–G7076–C225–011-17OPC Custom InterfaceCancel2 (dwCancelID )Cancels an outstanding h (dwSource, dwTransactionID, pdwCancelID)Requests a current value for every active OPC ble (bEnable)Activates messages via connection points. Messages generated by the Refreshmethod are sent regardless of these ble (pbEnable)Returns the current value of the flag for messages via connection ctionPointContainer InterfaceThis interface is a standard COM interface for reporting asynchronous events viaconnection points. For more detailed information about using connection points,refer to the documentation of OLE or COM.1-18OPC Server Interface

C7900–G7076–C225–01OPC Automation InterfaceChapter Overview2This chapter explains how to use the OPC automation interface. It also lists theproperties and methods of the OPC automation interface. This is not a detailedinterface description but contains supplementary information and notes relatingspecifically to the OPC server of ns of the Automation InterfaceThe OPC automation interface was specified by the OPC Foundation in version1.0. The specification, however, was unclear in some aspects. Some weaknessesof version 1.0 became particularly clear with the introduction of Visual Basic mid-1998, there is a new version of the specification of the automationinterface available with version number 2.0. The extent to which this version isapproved by the OPC Foundation can be found in the product following descriptions relate to version 2.0 of the specification of the OPCautomation n2.12.22.32.42.52.62.72.8DescriptionCreating and Using an OLE Object in Visual BasicObject Model for the Automation InterfaceThe “OPCServer” ObjectThe “OPCBrowser” ObjectThe “OPCGroups” Collection ObjectThe “OPCGroup” ObjectThe “OPCItems” Collection ObjectThe “OPCItem” ObjectPage2-22-52-62-82-102-122-152-17OPC Server Interface

C7900–G7076–C225–012-1OPC Automation Interface2.1Creating and Using an OLE Object in Visual BasicVisual Basic from Microsoft is a development environment that supports theautomation interface for the simple linking of OLE objects. The following sectionsshow how the OPC server is used via the automation interface 2.0 in Visual least version 4 of Visual Basic is for Creating an OPC ObjectCreate a new Visual Basic project. Select the Project

" References menucommand to display the “References” dialog box. As shown in Figure 2-1, activatethe reference for the automation interface 2.0 of the OPC ng an OPC Object in Visual Basic uses the following five basic tasks:ing the ting to the OPC ting an OPC OPC onous ReadingComponentsAvailable References:Visual Basic For ApplicationsVisual Basic runtime objects and proceduresVisual Basic objects and proceduresOLE AutomationOPC Automation 2.0Active Setup Control LibraryActiveMovie control type libraryAPI Declaration LoaderAutomation 1.0 Type LibraryOKCancelBrowseSelect (click on) OPC Automation 2.0and click on the “OK” buttonOPC Automation 2.0Location:C:guage:StandardFigure 2-1Activating the Reference for the Automation InterfaceStep 1: Declaring a Variable of the Object TypeIn Visual Basic or Visual Basic for Applications, a variable of the type Object refersto an OLE object. The DIM statement declares an object instance. Example:Dim ObjServer As OPCServer2-2OPC Server Interface

C7900–G7076–C225–01OPC Automation InterfaceStep 2: Creating and Assigning the ObjectCreating an OPC Server Object: Visual Basic programs are also OPC clients. Tobe able to access a process variable, the client must first create a server objectand then connect to an OPC e: The following code section shows how a Visual Basic client can connectto an OPC server ObjServer = New t (””)Step 3: Generating an OPC GroupThe next step is to create a group object to accommodate process , the group object and then the collection object are declared. The declaredcollection object is then assigned OPCGroups, a property of the server object. Agroup is finally created by calling the Add method of the collection e: The following lines show how a group is created in Visual Basic.’DeclarationsDim GroupObj As OPCGroupDim GroupCollection As OPCGroupsSet GroupCollection = upsSet GroupObj = (”MyGroup”)Step 4: Adding OPC ItemsOPC items will now be inserted in the created group object. The items representthe connections to the process variables, their parameter ItemID specified whichvariable will be AddItems method allows several items to be inserted into a group in one transfer parameters and the return values are therefore one-dimensionalarrays with identical sizes. The “lNumItems” variable contains the number of itemsto be the method is called, the server initializes the values of the arrays“lServerHandles”, “lErrors” and “ItemsObj”. The “IErrors” array contains statusinformation for each item inserted that indicated whether or not the item wassuccessfully Server Interface

C7900–G7076–C225–012-3OPC Automation InterfaceExample: The following example creates two items in the previously created OPCgroup “GrpObj”. The first item represents MD0, and the second item representsMD4.’DeclarationDim ItemCollection As OPCItemsDim ItemServerHandle() As LongConst MAX_INDEX = 2Dim lNumItems As LongDim lClientHandles(MAX_INDEX) As LongDim perror() As LongDim szItemIDs(MAX_INDEX) As StringDim AccPath(MAX_INDEX) As StringDim ReqDataTypes(MAX_INDEX) As Integer’Definition of ItemIDsszItemIDs(1) = ”MD0:Real”szItemIDs(2) = ”MD4:Real”AccPath(1) = ””AccPath(2) = ””ReqDataTypes(1) = vbVLongReqDataTypes(2) = vbVStringlClientHandles(1) = 1lClientHandles(2) = 2’Add Items to GroupSet ItemCollection = MAX_INDEX, szItemIDs, lClientHandles, _ItemServerHandle, perror, ReqDataTypes, AccPathStep 5: Synchronous ReadingIn the last step, a synchronous read operation to read the process variables of agroup is executed. Synchronous means that the server only returns control to theVisual Basic program after the required results have been returned via thecommunications system. This means that the flow of communication is delayed bythe time required for this e: Just like the AddItems command, OPCRead is also a group operation, inother words several process variables within a group can be accessed with onecall. The “lNumItems” parameter specifies the number of variables to be read. Theindividual variables themselves are described in the array “lServerHandles” by thehandle assigned by the server.’Definition of the Variables for OPCRead’Out ParameterDim vValues() As VariantDim pErrors() as ad OPCDevice, 2, ItemServerHandle, vValues, pErrors2-4OPC Server Interface

C7900–G7076–C225–01OPC Automation Interface2.2Object Model for the Automation InterfaceThe object model for the OPC automation interface according specification 2.0differs from the model described in Section 5.3: Separate collection objectsmanage the objects OPC-Group and OPC-Item. The collection objects providefunctions for counting the objects assigned to them. The browsing functions arealso brought together in a separate ver1:11:nOPCGroups(Collection)1:nOPC–BrowserOPCGroup1:1OPCItems(Collection)1:nOPCItemFigure 2-2Object Model for the Automation InterfaceOPC Server Interface

C7900–G7076–C225–012-5OPC Automation Interface2.3The “OPCServer” ObjectObjects of the OPC server class are created by the client. The properties of anOPC server contain general information about the server. When an OPC serverobject is created, an OPCGroup collection is also created as a property of the OPCserver ties of “OPCServer”Table 2-1Properties of the “OPCServer” Object

TypeDateDateDateIntegerIntegerIntegerStringLongLongOPC GroupsVariantVariantBrief DescriptionTime at which the server was started (in UTC)The current time (UTC), as supplied to the server bythe systemThe time (UTC), at which the server sent the lastupdate of data to the clientThe major version number of the serverThe minor version number of the serverThe build number of the serverThe vendor informationStatus of the serverBandwidth of the serverA collection of OPCGroup objectsThe names of the public groups provided by this serverThe names (ProgID) of the registered OPC one of these names for the “Connect” names are returned as an array of tyStartTimeCurrentTimeLastUpdateTimeMajorVersionMinorVersionBuildNumberVendorInfoServerStateBandwidthOPCGroupsPublicGroupNamesOPCServersNotes:SSSThe OPC server for Computing provides the following as vendor information:“Computing OPC–Server”Public groups are not supported by the OPC server for Bandwith property is not supported by the OPC server for Computing.2-6OPC Server Interface

C7900–G7076–C225–01OPC Automation InterfaceMethods of the “OPCServer”Connect (ProgID As String, Optional NodeName As String) As LongStructure of a link to an OPC server. The ProgID for Computing is:isconnect ()Structure of the link to an OPC : The OPC server for Computing closes all communications connections afterthe Disconnect of the last OPC eAll ()Deletes all current groups and items as preparation for a Browser () As OPCBrowserCreates an object of the OPCBrowser class to investigate the address area of : Refer to the description of the object in Section orString (ErrorCode As Long , Optional LocaleID As Long) AsStringSupplies the error message for a specific error : The OPC server for Computing supports German and English error detected by the Windows operating system are explained in the language inwhich the operating system was Server Interface

C7900–G7076–C225–012-7OPC Automation Interface2.4The “OPCBrowser” ObjectThe OPCBrowser object is a collection object with which the address area of theOPC server can be investigated. An object of the OPCBrowser class must becreated by the CreateBrowser method of the OPCServer object. It is possible tocreate several OPCBrowser objects for one ties of “OPCBrowser”Table 2-2Properties of the “OPCBrowser” Object

TypeLongStringIntegerLongString(read-only)LongBrief DescriptionThe organizational structure of the addressarea:hierarchy or flatThe filter effective for the ShowBranches andShowLeafs methodsThe data type required for the ShowLeafs method. Thedefault of this property is access rights required for the ShowLeafs methodCurrent position in the tree of the address area. Thevalue is “ ” when initialized in the root or when theorganization structure is ties necessary for the collection, provides thenumber of entriesPropertyOrganizationFilterDataTypeAccessRightsCurrentPositionCountNotes:SSThe structure of the address area of the OPC server for Computing rules for creating a filter are as follows:–Asterisk (*)–Plus (+)Any character string, including empty stringsAny string of characters, however at least one characterAny single characterExactly one character from the specified set–Question marks (?)–Open/close bracket ( [ ] )STo use one of the filter characters, this must be preceded by a back slash ().2-8OPC Server Interface

C7900–G7076–C225–01OPC Automation InterfaceMethods of “OPCBrowser”Item (Key As Variant) As StringProvides the name of the entry specified by the index “Key”.ShowBranches ()Enters the names of the branches of the current browse position into the afs (Optional Flat As Boolean)Enters the names of the leaves of the current browse position into the collection. Ifthe parameter ”Flat” is true, the collection with all leaves of the current and deeperbranches are filled starting from the current browse position. The default for ”Flat”is ()Moves the current position in the address area one level wn (Branch As String)Moves the current position in the address area into the current branch (one leveldeeper).MoveToRoot ()Moves the current position in the address area to the mID (Leaf As String) As StringCreates a complete ItemID in the hierarchical address area. This function isnecessary since browsing itself only provides the designations below the essPaths (ItemID As String) As VariantThis provides the possibility of querying the access path of an : Not required with the OPC server for Server Interface

C7900–G7076–C225–012-9OPC Automation Interface2.5The “OPCGroups” Collection ObjectThe OPCGroups object is a collection object for creating and managing OPCgroups. The default properties of OPC groups specify default values for creating allOPC groups are not supported by the OPC server for ties of “OPCGroups”Table 2-3Properties of the “OPCGroups” Object

TypeOPC Server(read-only)BooleanBrief DescritpionProvides a reference to the correspondingOPC server objectSpecifies the initial value for the “ActiveState”property of newly created OPC groupsDefault: TrueDefaultGroupUpdateLongSpecifies the initial value for the “update rate”property of newly created OPC groupsDefault: 1000 millisecondsDefaultDeadbandDefaultLocaleDefaultTimeBiasCountSingleLongLongLongSpecifies the initial value for the “Deadband”property of newly created OPC groupsSpecifies the initial value for the “locale ID”property of newly created OPC groupsSpecifies the initial value for the “time bias”property of newly created OPCGroupsProperties necessary for the collection,provides the number of entriesPropertyParentDefaultGroupActiveNotes:SSSSThe DefaultTimeBias property is not evaluated by the OPC server tLocale is irrelevant for the OPC server for DefaultGroupUpdate is specified by configuration parameter “MinimumUpdate Rate” as a multiple of the configuration DefaultDeadband property has no significance for the OPC server forComputing.2-10OPC Server Interface

C7900–G7076–C225–01OPC Automation InterfaceMethods of “OPCGroups”Item (Key As Variant) As OPCGroupProvides a reference to the indexed object of the (Name As string, ByRef ServerHandle As Long) As OPCGroupCreates a group in the server : If the szName parameter is empty, a name is generated beginning with theunderscore character (for example “_123456”). User-defined names shouldtherefore not begin with the underscore Group (Key As Variant) As OPCGroupProvides the reference to an OPC group indicated by the name or the (Key As Variant)Deletes a group on the All (Key As Variant)Deletes all groups and items of the of “OPCGroups”AllGroupsDataChange (GroupHandle as Long, MasterQuality as Long,MasterError as Long, NumItems as Long, ClientHandles() as Long,ItemValues() as Variant, Qualities() as Long, TimeStamps() as Date)This event simplifies the processing of events throughout all groups of thecollection by reporting changes in the value and state of all items in all Server Interface

C7900–G7076–C225–012-11OPC Automation Interface2.6The “OPCGroup” ObjectThe “OPC Group” class manages the individual process variables, the OPC these group objects, a client can form semantically meaningful units of OPCitems and execute operations with ties of “OPCGroup”Table 2-4Properties of the “OPCGroup” Object

TypeOPC ServerStringBooleanBooleanBrief DescriptionProvides a reference to the corresponding OPC serverobjectThe name of the groupReturns “True” when this group is a public group,otherwise FalseActive state of the groupAn active group creates events for all active items ofthe HandleLongA handle assigned by the client and that can be usedin the client program to localize data (for example, aline in a table)A unique handle assigned for the group by the serverThe client must transfer this handle with one of themany methods that influence the group (for example,Remove).LocaleIDTimeBiasDeadBandUpdateRateOPCItemsLongLongSingleLongOPC ItemsSpecifies the language ID for strings supplied by theserver (for example, error texts)Provides the time offset used to change the time stampof the data to the local timeSpecifies a bandwidth within which value changes donot result in a messageThe fastest rate at which a client is informed ofchanges in values or states of itemsCollections object “OPCItems” for managing the itemsof a groupPropertyParentNameIsPublicIsActiveServerHandleLongNotes:SSSSThe TimeBias property is not evaluated by the OPC server for ID is irrelevant for the OPC server for UpdateRate is specified by the configuration parameter “Minimum UpdateRate” as a multiple of the configuration PercentDeadBand property has no significance for the OPC server forComputing.2-12OPC Server Interface

C7900–G7076–C225–01OPC Automation InterfaceMethods of “OPCGroup”SyncRead (Source As Integer, NumItems As Long, ServerHandles() AsVariant, ByRef Values() As Variant, ByRef Errors() As Variant,Optional ByRef Qualities As Variant, Optional ByRef TimeStamps AsVariant) As LongSynchronous reading of the values, status information or time stamp of one ormore items in a group. The values can be read from the cache of the server ordirectly from the hardware. Reading from the cache is, however, only possiblewhen the group is : The call is monitored by the timeout monitoring on the server. Thecorresponding configuration parameter is “Read/Write Timeout”.SyncWrite (NumItems As Long, ServerHandles() As Variant, Values() AsVariant, ByRef Errors() As Variant) As LongSynchronous writing of values for one or more items of a group to the : The call is monitored by the timeout monitoring on the server. Thecorresponding configuration parameter is “Read/Write Timeout”.AsyncRead (Source As Integer, NumItems As Long, ServerHandles() AsVariant, ByRef Errors() As Variant, ByRef TransactionID As Long) AsLongSends an asynchronous read command. The result is returned with the“AsyncReadComplete” : The call is monitored by the timeout monitoring on the server. Thecorresponding configuration parameter is “Read/Write Timeout”.AsyncWrite (NumItems As Long, ServerHandles() As Variant, Values() AsVariant, ByRef Errors() As Variant, ByRef TransactionID As Long) AsLongSends an asynchronous write command. The result is returned with the“AsyncWriteComplete” : The call is monitored by the timeout monitoring on the server. Thecorresponding configuration parameter is “Read/Write Timeout”.AsyncRefresh (Source As Integer, ByRef TransactionID As Long) As LongRequests a current value for every active OPC item. The results are returned bythe “DataChange” Server Interface

C7900–G7076–C225–012-13OPC Automation InterfaceAsyncCancel (TransactionID As Long)Cancels an outstanding asynchronous of “OPCGroup”The OPC automation interface supplies the changes to the values of active termsand the results of asynchronous operations with ange (NumItems As Long, ClientHandles() As Long, ItemValues()As Variant, Qualities() As Variant, TimeStamps() As Date)The DataChange event occurs when it is detected that an active item has achange value or a change quality. Checking value changes is triggered by theUpdateRate timer. Only active items are created within a group of eadComplete (TransactionID As Long, NumItems As Long,ClientHandles() As Long, ItemValues() As Variant, Qualities() AsVariant, TimeStamps() As Date, Errors() As Variant)The AsyncReadComplete event is triggered when a read job is riteComplete (TransactionID As Long, NumItems As Long,ClientHandles() As Long, Errors() As Variant)The AsyncWriteComplete event is triggered when a write job is ancelComplete (TransactionID As Long)The AsyncCancelComplete event is triggered when a cancel job is completed.2-14OPC Server Interface

C7900–G7076–C225–01OPC Automation Interface2.7The “OPCItems” Collection ObjectThe OPCItems object is a collection object for creating and managing OPC default properties of OPCItems specify default values for all OPC items to ties of “OPCItems”Table 2-5Properties of the “OPCItems” Collection Object

PropertyParent OPCTypeGroupBrief DescriptionSupplies a reference to the correspondingOPCGroup objectSpecifies the initial value for the“RequestedDataType” property of newly addeditemsThe default value is vbEmpty for the canonicaldata tAccessPathStringSpecifies the initial value for the “AccessPath”property of newly added itemsThe default is an empty tIsActiveBooleanSpecifies the initial value for the ”Active State”property of newly added itemsThe default value is ongProperties necessary for the collection, providesthe number of entriesDefaultRequestedDataTypeIntegerMethods of “OPCItems”Item (ItemSpecifier As Variant) As OPCItemProvides a reference to the item of the collection described by the ItemSpecifierindex. (The ”GetOPCItem” method, on the other hand, provides a reference via theserver handle.)GetOPCItem (ServerHandle As Long) As OPCItemProvides a reference to the server handle created by Server Interface

C7900–G7076–C225–012-15OPC Automation InterfaceAdd (NumItems As Long, ItemIDs() As String, ClientHandles() As Long,ByRef ServerHandles() As Long, ByRef Errors() As Long, OptionalRequestedDataTypes() As Variant, Optional AccessPaths() As Variant)Inserts one or more items in the OPCItems collection of a : It is possible to add the same OPC item to the same group more than this case each of these items nevertheless has its own server handle. Theserver handles of the items are only unique within a group and not for all items ofall (NumItems As Long, ServerHandles() As Long, ByRef Errors() AsLong)Deletes one or more items from a te (NumItems As Long, ItemIDs() As String, ByRef Errors() AsLong, Optional RequestedDataTypes () As Variant, OptionalAccessPaths() As Variant)Checks the validity of an OPC item, for example whether it was added to a groupwithout any error occurring, and supplies information such as the canonical : See ive (NumItems As Long, ServerHandles() As Long, ActiveState AsBoolean, ByRef Errors() As Long)Sets the active state of one or more items in a entHandles (NumItems As Long, ServerHandles() As Long,ClientHandles() As Long, ByRef Errors() As Longt)Changes the client handle of one or more items in a aTypes (NumItems As Long, ServerHandles() As Long,RequestedDataTypes() As Long, ByRef Errors() As Long )Sets the required data type of one or more items in a group.2-16OPC Server Interface

C7900–G7076–C225–01OPC Automation Interface2.8The “OPCItem” ObjectAn object of the class OPC item represents a link to a process variable, forexample to the input module of a programmable controller. A process variable isdata of the process I/Os that can be written and/or read, for example thetemperature of a tank. Each process variable is associated with a value (variantdata type), a quality, and a time ties of “OPCItem”Table 2-6Properties of the “OPCItem” Object

TypeGroupLongBrief DescriptionSupplies a reference to the parent OPCGroup objectA handle that can be freely defined by the user to allowsimpler assignment of the process variable in internaldata structures of the clientA handle assigned uniquely to the item by the serverThis handle is required in several operations to identifyan PathAccessRightsItemIDIsActiveRequestedDataTypeValueQualityStringLongStringBooleanIntegerVariantLongThe access path of the item as specified in the AddfunctionProvides the access rights of the variableThe unique name of the item as specified in the AddfunctionSpecifies whether message events will be created forthis itemThe data type in which the value of the item will besuppliedThe last valid value of the variable (default property ofthe OPCItem object)The quality of the value last readThe quality indicates the validity of the value of ampCanonicalDataTypeEUTypeDateIntegerIntegerThe time at which the last value was acquiredThe original data type of the itemIdentifies the unit of the valueIf no units are available, the value is always“VT_EMPTY”.EUInfoVariantInformation about the unit of the valuePropertyParent OPCClientHandleServerHandleLongNote: The OPC server for Computing does not support units (engineering units)OPC Server Interface

C7900–G7076–C225–012-17OPC Automation InterfaceMethods of “OPCItem”Read (Source As Integer, optional ByRef Value As Variant, optionalByRef Quality As Variant, optional ByRef TimeStamp As Variant )Reads the value, the quality, and/or the time stamp of this (Value As Variant)Sets the value of this variable synchronously.2-18C7900OPC Server Interface

–G7076–C225–01ToSIEMENS ENERGY & AUTOMATION INCATTN: TECHNICAL COMMUNICATIONS M/S 5193000 BILL GARLAND ROADPO BOX 1255JOHNSON CITY TN USA 37605–1255FromName:Job Title:Company Name:Street:Country:Telephone:__________________________________________________________________________________________________________________________________________________________________________________________City and State:_______________________________Please check any industry that applies to you:rrrrrrrAutomotiveChemicalElectrical MachineryFoodInstrument and ControlNon-electrical MachineryPetrochemicalrrrrrrPharmaceuticalPlasticPulp and PaperTextilesTransportationOther ___________________________$OPC Server Interface

C7900–G7076–C225–011Remarks FormYour comments and recommendations will help us to improve the quality and usefulness of ourpublications. Please take the first available opportunity to fill out this questionnaire and return itto give each of the following questions your own personal mark within a range from 1 (verygood) to 5 (very poor). the contents meet your requirements?Is the information you need easy to find?Is the text easy to understand?Does the level of technical detail meet your requirements?Please rate the quality of the graphics and onal comments:________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________OPC Server Interface

C7900–G7076–C225–012