西门子opc服务器的说明文档

Edition: 3C79000–G7076–C225–01

OPC Server Interface

Manual

This manual is based on version 2.0 of the OPC

specification from the OPC Foundation.

This manual is available only in English.

Computing

This manual contains notices which you should observe to ensure your own personal safety, as well as to

!Danger

indicates that death, severe personal injury or substantial property damage will result if proper precau-

tions are not taken.

!Warning

indicates that death, severe personal injury or substantial property damage can result if proper precau-

tions are not taken.

!Caution

indicates that minor personal injury or property damage can result if proper precautions are not taken.

Note

draws your attention to particularly important information on the product, handling the product, or to a

particular part of the documentation.

Qualified Personnel

Only qualified personnel should be allowed to install and work on this equipment. Qualified persons are

defined as persons who are authorized to commission, to ground, and to tag circuits, equipment, and sys-

tems in accordance with established safety practices and standards.

Correct Usage

Note the following:

!Warning

This device and its components may only be used for the applications described in the catalog or the

technical descriptions, and only in connection with devices or components from other manufacturers

which have been approved or recommended by Siemens.

This product can only function correctly and safely if it is transported, stored, set up, and installed cor-

rectly, and operated and maintained as recommended.

Trademarks

SIMATIC R, SIMATIC HMI R and SIMATIC NET R are registered trademarks of SIEMENS AG.

Some of other designations used in these documents are also registered trademarks; the owner’s rights

may be violated if they are used by third parties for their own purposes.

i

OPC Server Interface C7900–G7076–C225–01Contents

1OPC Custom Interface

1-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.1

Creating and Using an OLE Object in C/C++1-2. . . . . . . . . . . . . . . . . . . . . . . . 1.2

Additional Information about the Interface Description for the OPC Custom Interface 1-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3The “OPC Server ” Object 1-6

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4Objects of the “OPC Group ” Class 1-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.5IDataObject Interface 1-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2OPC Automation Interface 2-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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

2.3The “OPCServer ” Object 2-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.4The “OPCBrowser ” Object 2-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.5The “OPCGroups ” Collection Object 2-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.6The “OPCGroup ” Object 2-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.7The “OPCItems ” Collection Object 2-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.8The “OPCItem ” Object 2-17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figures

1-1OPC Server Object 1-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2OPC Group Object 1-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3IAdviseSink (Client) and IDataObject (Server) Interfaces 1-16. . . . . . . . . . . . . . 2-1Activating the Reference for the Automation Interface 2-2. . . . . . . . . . . . . . . . 2-2Object Model for the Automation Interface 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . Tables

1-1Objects and Interfaces of the OPC Custom Interface 1-5. . . . . . . . . . . . . . . . 2-1Properties of the “OPCServer ” Object 2-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Properties of the “OPCBrowser ” Object 2-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3Properties of the “OPCGroups ” Object 2-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Properties of the “OPCGroup ” Object 2-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Properties of the “OPCItems ” Collection Object 2-15. . . . . . . . . . . . . . . . . . . . . 2-6Properties of the “OPCItem ” Object 2-17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

OPC Server Interface C7900–G7076–C225–01

1-1

OPC Server Interface C7900–G7076–C225–01OPC Custom Interface

Chapter Overview This chapter shows how to use the OPC custom interface. It also lists the

interfaces and methods of the OPC customer interface. This is not a detailed

interface description but contains supplementary information and notes relating

specifically to the Computing software.

There is now an extended version of the OPC custom interface, specification 2.0.

Version 2.0 supplements the existing OPC custom interface in several aspects

particularly those simplifying the handling of asynchronous communication.

The interfaces of Version 1.0 of the OPC interface are completely upwards

compatible with Version 2.0.

1

OPC Custom Interface

1-2

OPC Server Interface C7900–G7076–C225–01

1.1Creating and Using an OLE Object in C/C++

The following sections illustrate step-by-step how you can call the methods of an

instance of an OLE class in C++. Note the difference between the term “Class” in

OLE and in C++:

S OLE Classes: A Windows object is an instance of an OLE class. The term OLE class differs from the class in C++.

S C++ Classes: A class in C++ is a type definition. An OLE class is, however, an object description and does not contain types.

Class Identification Code

Each OLE class can be identified uniquely by a 128-bit long identification code, the

CLSID. This is used by the operating system for the unique assignment of a DLL

or EXE file that implements this class. A client that wishes to use an object of a

class requires only the CLSID.

ProgID

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 the

algorithm for compilation, it is possible that a ProgID exists more than once. Just

like the CLSID, the ProgID is specified by the vendor of an OPC server.

The ProgID for the OPC server of Computing is: OPCServer.WinAC

Creating a COM Object

A COM object is created in five steps:

1.Initialize COM.

2.Query the CLSID.

3.Create an Object.

4.Call an OPC function.

5.Release the interfaces used.

Step 1: Initialize COM

Before you can use the functions of COM, the COM library must be initialized with

the following call:

HRESULT r1;

r1 = CoInitialize(NULL);

OPC Custom Interface

1-3

OPC Server Interface C7900–G7076–C225–01Step 2: Query the CLSID

If the name of an object is known, the CLSID can be queried using the OLE

function “CLSIDFromProgID ”.

Example: The following program section illustrates how to query the CLSID for the OPC server for Computing.

CLSID clsid; // Get the CLSID from the Name

r1 = CLSIDFromProgID((L”OPCServer.WinAC”),&clsid);

Step 3: Create an Object

If a client wants to use an object, it transfers the CLSID to the operating system

and requests an object instance. Regardless of where the server is located, the

object request is always directed to COM.

The “CoCreateInstance ” function creates an object belonging to the required class.This function includes certain intermediate steps via the “IClassFactory ” interface.Creating an object using IClassFactory is more efficient when several objects of a class must be created.

Example: The following lines show how an object of the class “OPC server ” with

reference to the “IUnknown ” interface can be created.

IUnknown * pOPCUnknown;

r1 = CoCreateInstance (clsid, NULL, CLSCTX_LOCAL_SERVER,

IID_IUnknown, (void**) &pOPCUnknown );

Step 4: Call an OPC Function

In this step, a method of the “IOPCServer ” interface of the created object will be

used to learn the status of the server. First, a pointer to the “IOPCServer ” interface is made available via “IUnKnown ”. Finally, the “GetStatus ” method is called.

Example: The program shown below outputs the status of the server and the

vendor information. If the “GetStatus ” method is called successfully, the OPC

server allocates the memory areas for the return information via the “IMalloc ”

interface. The user must release these memory areas again.

IOPCServer *pOPCServer;

OPCSERVERSTATUS *pss;

r1 = pOPCUnknown–>QueryInterface(IID_IOPCServer,

(void**)&pOPCServer);

r1 = pOPCServer –>GetStatus(&pss);

printf(”Status.szVendorInfo = %ls\n”, pss–> szVendorInfo);

// Remember to release the memory returned by the method

pIMalloc–>Free(pss–>szVendorInfo);

pIMalloc–>Free(pss);

OPC Custom Interface

1-4

OPC Server Interface C7900–G7076–C225–01

Step 5: Release the Interfaces Used

Objects include reference counters to detect when the object is no longer required

and can remove itself from memory. Each time the “QueryInterface” function is

called, the reference counter is incremented. To release the object, the counter

must be reset.

Example: Using the following commands, the reference counter for the interfaces

“IUnknown” and “IOPCServer” is reset.

pOPCServer–>Release();

pOPCUnknown–>Release();

OPC Custom Interface

1-5

OPC Server Interface C7900–G7076–C225–011.2Additional Information about the Interface Description for the

OPC Custom Interface

A comprehensive description of the OPC interfaces is beyond the scope of this

manual. This is supplied as a file along with this product as an original English

document from the OPC Foundation. The documents are located in the ”DOC ”

directory in the product directory of the OPC server for Computing.

The following supplementary information about the interfaces lists the objects of

OPC, their interfaces and the methods defined in these interfaces and points out

particular characteristics of the OPC server for Computing.

Return Values

All the listed methods return a result of the type HRESULT.

Overview of the Objects and Interfaces

Table 1-1Objects and Interfaces of the OPC Custom Interface

OPC Custom Interface

1-6OPC Server Interface C7900–G7076–C225–01

1.3The “OPC Server ” Object

The OPC server class has various attributes that contain information about the status, the version etc. of an OPC server object. The OPC server class also has methods with which a client can manage the objects of the OPC group class. A client application addresses only an object of this class directly using COM mechanisms. The other objects are created by corresponding OPC methods.The methods of the IOPCServer interface are used to manage the objects in the OPC group class. Using the methods of the IOPCBrowseServerAddressSpace interface, it is possible to investigate the address area of the server.

Figure 1-1 illustrates the “OPC server ” object with its interfaces.

Figure 1-1OPC Server Object IOPCServer Interface

This interface contains methods to manage groups within a server object. It is also possible to obtain information about the current status of the server.

AddGroup ( szName, bActive, dwRequestedUpdateRate, hClientGroup,pTimeBias, pPercentDeadband, dwLCID, phServerGroup,

pRevisedUpdateRate, riid, ppUnk )

Creates a group in the server object.

Notes:

S

The ”pTimeBias ” parameter is not evaluated by the OPC server for Computing.S

“LCID ” is irrelevant for the OPC server for Computing.S

The “UpdateRate ” is specified by the configuration parameter “Minimum Update Rate ” as a multiple of the configuration value.S

The “pPercentDeadband ” parameter is only effective for variables of the real (VT_R4) type.S If the “szName ” parameter is empty, a name is generated beginning with the underscore character (for example, “_123456”). User-defined names should therefore not begin with the underscore character.

OPC Custom Interface

1-7

OPC Server Interface C7900–G7076–C225–01CreateGroupEnumerator ( dwScope, riid, ppUnk )

Creates various enumerators for the group.

Note: Since there are no public groups in the OPC server for Computing, the return values for the parameter ”dwScope ” ”...PRIVATE ” and ”...PUBLIC ” are identical.GetErrorString ( dwError, dwLocale, ppString )

Supplies the error message for a specific error code.

Note: The OPC server for Computing supports German and English error texts.Errors detected by the Windows operating system are explained in the language in which the operating system was installed.

GetGroupByName ( szName, riid, ppUnk )

Supplies an additional interface pointer for the name of a private group, in other words the reference counter is incremented.

GetStatus ( ppServerStatus )

Supplies the status information of the server.

Note: The return value of the OPC server for Computing is the name and the version of the OPC server.

RemoveGroup ( hServerGroup, bForce )

Deletes a group on the server.

Note: 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 active.

IOPCBrowseServerAddressSpace Interface

This interface contains methods with which the address area of the server can be queried. The address area contains all the OPC items known to the server.BrowseAccessPaths ( szItemID, ppIEnumString )

This provides the possibility of querying the access path of an ItemID.

Note: Not required with the OPC server for Computing.

OPC Custom Interface

1-8

OPC Server Interface

C7900–G7076–C225–01 BrowseOPCItemIDs ( dwBrowseFilterType, szFilterCriteria, vtDataTypeFilter, dwAccessRightsFilter, ppIEnumString )

Supplies a string of the type ”IEnumString” whose content is specified by the call parameters. The position from which the list is created can be set using the

”ChangeBrowsePosition” method.

Notes:

S“BRANCH” excludes the filters for Type and AccessRights.

S The 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 set

S To 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 level or to a branch.

GetItemID ( szItemDataID, szItemID )

Creates a complete ItemID in the hierarchical address area. This function is necessary since browsing itself only provides the designations below the current node.

Note: The description of GetItemID in OPC specification is inconsistent with the description of ChangeBrowsePosition. With ChangeBrowsePosition, it is not possible to specify a complete ItemID. For this reason, the OPC server for Computing only currently supports the command GetItemID for single leaves (LEAF).

QueryOrganization ( pNameSpaceType )

Supplies the structure of the address area. The address area can be organized with a flat or hierarchical structure.

Note: The structure of the address area of the OPC server for Computing is structured hierarchically.

OPC Custom Interface

1-9

OPC Server Interface C7900–G7076–C225–01IOPCCommon Interface (Version 2.0)

This interface of version 2.0 of the OPC Custom Interface contains methods

allowing the language settings and the name of the client to be made known to the server.

SetLocaleID (dwLcid)

Sets the language code of the server. The language code specifies the language in which the server outputs text.

Note: The OPC server for Computing supports English and German.

GetLocaleID (pdwLcid)

Fetches the language code of the server.

Note: The OPC server for Computing supports English and German.

QueryAvailableLocaleIDs (pdwLcid)

Provides all the available language codes of the server.

Note: The OPC server for Computing supports English and German.

GetErrorString (dwError, ppString)

Provides the error text for a specific error code in the set language.

SetClientName (szName)

Transfers a descriptive text for the client to the server. The descriptive text can be used for any purpose by the server, for example for logging in trace files.

IConnectionPointContainer Interface

This interface is a standard COM interface for reporting asynchronous events via connection points. For more detailed information about using connection points,refer to the documentation of OLE/COM.

IOPCItemProperties (V 2.0) Interface

This interface of version 2.0 contains methods allowing specific server information to be queried about an item.

QueryAvailableProperties (szItemID, pdwCount, ppPropertyIDs,

ppDescriptions, ppvtDataTypes )

Returns a list of available properties for an item.

OPC Custom Interface

1-10

OPC Server Interface

C7900–G7076–C225–01 GetItemProperties (szItemID, dwCount, pdwPropertyIDs, ppvData,

ppErrors )

Provides the values of the properties of an item transferred in a list of PropertyIDs.

LookupItemIDs (szItemID, dwCount, pdwPropertyIDs, ppszNewItemIDs, ppErrors);

Provides (whenever possible for the propertyID) a list of ItemIDs for a list of PropertyIDs. These ItemIDs can be included in a group simplifying and speeding up access to the data.

Note: The OPC server for Computing does not support this function. The call is rejected with error message 0x8004001 (not implemented).

OPC Custom Interface

1-11

OPC Server Interface C7900–G7076–C225–011.4Objects of the “OPC Group ” Class

The “OPC Group ” class manages the individual process variables, the OPC https://www.sodocs.net/doc/514887353.html,ing these group objects, a client can form semantically meaningful units of OPC items and execute operations with them.

Figure 1-2 illustrates an object of the “OPC Group ” class and its interfaces.

Figure 1-2OPC Group Object

IOPCItemMgt Interface

This interface provides methods to manage more than one item in a group.Time Stamp

With each value read, OPC supplies a time stamp. This indicates when this value was received or when it was changed. Since the SIMATIC systems do not use a time stamp, the time at which the value is received on the server is used as the time stamp.

OPC Custom Interface

1-12

OPC Server Interface

C7900–G7076–C225–01 AddItems ( dwNumItems, pItemArray, ppAddResults, ppErrors )

Adds one or more items to a group.

Notes:

S A unique name of an item for the OPC server for Computing is as follows: Examples MD0:Real

EB0

DB1.DBD0

This name can be specified completely in the ItemID. The AccessPath must then be empty.

S As an alternative, the part of the name in square brackets can be included in the AccessPath.

Example: AccessPath:“”

MD0:Real

S It is possible to add the same OPC item to the same group more than once. In this case each of these items nevertheless has its own server handle.

The server handles of the items are only unique within a group and not for all items of all groups.

S Valid data types are as follows: VT_UI1, VT_UI2, VT_UI4, VT_I1, VT_I2, VT_I4, VT_R4, VT_BOOL, VT_BSTR

CreateEnumerator ( riid, ppUnk )

Creates an enumerator for the items of a group.

RemoveItems ( dwNumItems, phServer, ppErrors )

Deletes one or more items from a group.

SetActiveState ( dwNumItems, phServer, bActive, ppErrors )

Sets the active state of one or more items in a group.

SetClientHandles ( dwNumItems, phServer, phClient, ppErrors )

Sets the client handle of one or more items in a group.

SetDatatypes ( dwNumItems, phServer, pRequestedDatatypes, ppErrors ) Sets the requested data type of one or more items in a group.

Note: See AddItem

OPC Custom Interface

1-13

OPC Server Interface C7900–G7076–C225–01ValidateItems ( dwNumItems, pItemArray, bBlobUpdate,

ppValidationResults, ppErrors )

Checks the validity of an OPC item, for example whether it was added to a group without any error occurring, and supplies information such as the canonical data type.

Note: See AddItem

IOPCGroupStateMgt Interface

The IOPCGroupStateMgt interface provides methods with which groups can be managed. It is possible to edit group-specific parameters and to copy groups.CloneGroup ( szName, riid, ppUnk )

Creates a copy of a group. All group attributes are copied except for the following:S

The active state is set to FALSE S A new server handle is assigned

Note: The “szName ” parameter can be empty. In this case a unique name is generated (see AddGroup).

GetState ( pUpdateRate, pActive, ppName, pTimeBias, pPercentDeadband,pLCID, phClientGroup, phServerGroup )

Fetches the status of the group. The client application must inform the OPC server where the results are to be stored using a pointer.

Notes:

S

The “pTimeBias ” parameter has no significance for the OPC server for Computing.S

The “pPercentDeadband ” parameter has no significance for the OPC server for Computing.S The “LCID ” parameter, in other words language-specific textual values in read/write, has no significance for SIMATIC variables.

SetName ( szName )

Allows the name of a group to be changed. The name must always be unique.

OPC Custom Interface

1-14

OPC Server Interface

C7900–G7076–C225–01 SetState ( pRequestedUpdateRate, pRevisedUpdateRate, pActive, pTimeBias, pPercentDeadband, pLCID, phClientGroup )

SetState allows various properties of the group to be changed.

Notes:

S The “pTimeBias” parameter has no significance for the OPC server for Computing.

S The “pPercentDeadband” parameter has no significance for the OPC server for Computing.

S The “LCID” parameter, in other words language-specific textual values in read/write, has no significance for SIMATIC variables.

S The “UpdateRate” is specified by the configuration parameter “Minimum Update Rate” as a multiple of this value.

IOPCSyncIO Interface

This interface provides methods for synchronous reading and writing. Synchronous

means that the client waits until the read or write operation is completed and only

then continues execution.

The use of synchronous calls is recommended when the client requires the result

for further processing. Other clients are not blocked since the OPC server for

Computing starts a separate thread for each client.

In general, it is advisable to use the IData interface for processing variable

changes (or IAdviseSink on the client side). This interface guarantees the highest

possible data throughput and also reduces the actual number of calls to the

absolute 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 a

group. The values can be read from the cache of the server or directly from the

hardware. Reading from the cache is, however, only possible when the group is

activated.

Note: The call is monitored by the timeout monitoring on the server. The

corresponding configuration parameter is “Read/Write Timeout”.

Write ( dwNumItems, phServer, pItemValues, ppErrors )

Writes values for one or more items of a group to the hardware.

Note: The call is monitored by the timeout monitoring on the server. The

corresponding configuration parameter is ”Read/Write Timeout”.

OPC Custom Interface

1-15

OPC Server Interface C7900–G7076–C225–01IOPCAsyncIO Interface

This interface of the Group class provides methods for asynchronous reading and writing of items. Asynchronous means that the client triggers a read or write operation and then continues operation. Asynchronous operations provide a transaction ID. When the server has completed the read or write operation, the client receives a message sent to its IAdviseSink interface.

Cancel ( dwTransactionID )

Cancels an outstanding job.

Read ( dwConnection, dwSource, dwNumItems, phServer, pTransactionID,ppErrors )

Sends an asynchronous read command. The result is sent to the IAdviseSink interface of the client.

Note: The call is monitored by the timeout monitoring on the server. The

corresponding configuration parameter is “Read/Write Timeout ”. If the timeout monitoring is aborted, there is a callback with hrStatus=E_ABORT.

Refresh ( dwConnection, dwSource, pTransactionID )

Requests a current value for every active OPC item.

Write ( dwConnection, dwNumItems, phServer, pItemValues,

pTransactionID, ppErrors )

Sends an asynchronous write command.

Note: The call is monitored by the timeout monitoring on the server. The

corresponding configuration parameter is “Read/Write Timeout ”. If the timeout monitoring is aborted there is a callback with hrStatus=E_ABORT.

OPC Custom Interface

1-16OPC Server Interface C7900–G7076–C225–01

1.5IDataObject Interface

The IDataObject interface is the standard interface of OLE for data transmission. It contains methods for establishing a message connection between the client and a server group.

Description of the Mechanism

If the server wants to send a message to a client, the client must provide a partner for the server. This partner is the IadviseSink interface of the client. A server sends a message to a client by calling the OnDataChange method of the IAdviseSink interface of the client.

Representation of the Mechanism

Figure 1-3 illustrates how the “IAdviseSink ” interface on the client and

“IDataObject ” on the server interact.

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

DAdvise (pFmt, adv, pSnk, pConnection);

Establishes a connection between a server and the client. If a client wants to

receive a message, it must establish a connection using this method. It transfers a pointer to its IAdviseSink interface to the server.

DUnadvise (Connection)

Terminates an existing connection between a client and server.