citect for windows driver specification opc client driver · pdf filecitect for windows driver...

Citect for Windows Driver Specification OPC Client Driver

Author Date Comment

Mark Bugeja 12 May 1998 Initial Version

Trevor Hudson 6 July 98 Start of Initial Testing

Mark Bugeja 20 August 1998 Addressed Testing issues

Mark Bugeja 8 March, 1999 Added Access Path Support

Darryn Capes-Davis 24 September, 1999 Added ‘INI array’ support and various parameters

Alex Bratovic 9 April, 2001 Add OPCDA2 parameters + various updates

Lin Gu 9 May 2001 Added “array” support

Lin Gu 21 July 2001 Added timestamp support

Graeme Sutton 21 Sept, 2001 Minor updates to array support and DCOM information

Graeme Sutton 18 Oct 2001 Updated driver parameters section

Carol Jia 9 Nov 2001 Using OID to address in Citect5.41 or later

Graeme Sutton 4 Dec 2001 Updated driver specific errors

Lin Gu 8 Jan 2002 Updated section 5.3.2

Acme Team 5 Dec 2002 Updated OID blocking support

Acme Team 8 Jan. 2003 Updated parameters and qualifiers

Acme Team 24 Mar. 2003 Updated parameter FailOnBadData = 2

Lin Gu 26 May 2003 Updated parameter FailOnBadData = 2

Driver Design Specification

OPC_Extract.DOC 26/05/2003 2

Contents

1. USER INTERFACE 4 1.1 Introduction 4 1.2 Driver Name 4 1.3 Boards Form 4

1.3.1 Board Type 4 1.3.2 Address 4 1.3.3 IO Port 4 1.3.4 Interrupt 4 1.3.5 Special Opt 4

1.4 Ports Form 5 1.4.1 Baud Rate 5 1.4.2 Data Bits 5 1.4.3 Stop Bits 5 1.4.4 Parity 5 1.4.5 Special Opt 5

1.5 IO Devices Form 5 1.5.1 Protocol 5 1.5.2 Address 5

1.6 Pull-down lists Help 5 1.7 IO Device Variable Types 6

1.7.1 Formats and types 6 1.7.2 Include Project Support 6 1.7.3 OPC Array Support 7 1.7.4 Timestamp and Quality Support 9 1.7.5 Tag Qualifiers 10 1.7.6 driver.dbf Entries 10

1.8 PROTDIR.DBF 11 1.9 Parameters and INI options 11

1.9.1 Standard Parameters 11 1.9.2 Driver Specific Parameters 11 1.9.3 Device Specific Parameters 15 1.9.4 AccessPath Parameters 15 1.9.5 StatusTag Parameters 16 1.9.6 StatusTag Device Specific Parameters 16 1.9.7 Array Request Parameters 17

1.10 Remapping 18



1.11 Driver Specific Errors 18 1.12 Driver Error Help 20 1.13 Debug Messages 22

1.13.1 Debug Write 22 1.13.2 Debug Error 22 1.13.3 Debug All 22

1.14 Stats Special Counters 22 1.15 Hints and Tips 2322

2. REFERENCES AND CONTACTS 2423 2.1 References 2423



1. User Interface

1.1 Introduction This section defines how the user will see the driver. This relates directly to how the Citect forms need to be filled out and any special INI options. For the kernel, the debug trace messages and the Stats.Special counters are documented.

1.2 Driver Name The name of the driver is OPC.

1.3 Boards Form

1.3.1 Board Type

The board type will be OPC

1.3.2 Address

The ScanRate in milliseconds. Enter 0 to use the default scanrate 250ms. CitectHMI/SCADA does not require an address for the OPC Client. This field is used, however, to set the device scan rate on the OPC Server in milliseconds. The value read from the OPC Server is typically taken from the OPC Server cache. The scan rate value is often used to indicate how often the OPC Server polls the device and updates its cache. Enter 0 (zero) to use the default of 250ms. Enter any other value to use that value. Valid values range from eight character decimal 0 to 99999999. Up to six character hex values can be used, however, must be preceded with 0x.

1.3.3 IO Port

Not applicable – leave blank.

1.3.4 Interrupt


1.3.5 Special Opt

The OPC Server machine name1. Enter the name of the machine on which the OPC Server is installed. The name entered here is the Windows machine name. For Windows NT and Windows 95 based OPC Servers, this may be obtained from the “Identification” tab of the OPC Server’s machine’s

1 Option has is not in the traditional dash delimited style, ie –H<Hostname>, as the maximum length a windows workstation name is 32, exactly the length of the Special Options Field.



network properties. For other OPC Server configurations, the server’s accompanying documentation should be consulted. If left blank, the following driver will attempt to locate the server in the following manner. ? ? The in-process (DLL) server on the IO Server machine. ? ? The local (EXE) server on the IO Server machine. ? ? The remote server as hard-coded in the IO Server machine’s DCOM settings.

1.4 Ports Form The ports form must be defined to provide the proper database associations, however, all parameter fields such as baud rate, data bits, etc. will be blank.

1.4.1 Baud Rate


1.4.2 Data Bits


1.4.3 Stop Bits


1.4.4 Parity


1.4.5 Special Opt


1.5 IO Devices Form

1.5.1 Protocol

The protocol name is OPC or OPC12.

1.5.2 Address

The ProgID for the desired server. These usually take the form Vendor.Application (eg. Citect.OPC), and should be found in the documents accompanying the OPC Server. See Section Error! Reference source not found. for details.

1.6 Pull-down lists Help The following entries should be included in the Citect HELP.DBF spec file.

TYPE DATA FILTER

BOARDTYPE OPC

PROTOCOL OPC

PROTOCOL OPC1

2 See 5.16.4 Special Option for more details.



1.7 IO Device Variable Types

1.7.1 Formats and types

IO Device Type Citect data format

Citect data types

Description/Special Usage/Limitations/ Valid Ranges

VT_BOOL OPC Item Id (must be

unambiguous)

DIGITAL Bool

VT_UI1 “ BYTE Byte

VT_I2 “ INT 2 byte int

VT_UI2 “ UINT 2 byte unsigned int

VT_I4 “ LONG 4 byte int

VT_CY “ STRING Currency? This is an int64, I’m not sure how the user will get at these. Possibly request as a STRING.

VT_R4 “ REAL 4 byte real

VT_R8 “ STRING 8 byte real (RDT_LONG_REAL is not available to user… configure as STRING)

VT_DATE “ STRING 8 byte real (RDT_LONG_REAL is not available to user… configure as STRING)

VT_BSTR “ STRING String.

VT_ERROR “ LONG 32 bit error code.

VT_QUALITY “ INT 2 byte int

VT_TIMESTAMP “ LONG 32 bit timestamp code.

VT_MILLISECOND “ LONG 32 bit millisecond timestamp code.

1.7.2 Include Project Support

By default the OPC driver does not support the definition of Variable Tags in projects that are included below the main project. The parameter [OPC]UseIncludeProjects can be used to enable this. In the process of compiling the project and included projects, each time it starts compiling the variable.dbf in an included project the addresses will start from the last record number in the last included project plus 1. The tags in the main project are compiled last. So, to Tag Based Driver, it will occur the problem. To Citect5.41 or later, a new field will be added to Variable.dbf. This field will contain a Identification value value. The Identification value, termed a Tag ID (TID), will be based on the combination of a Project Number (PN) ,representing the project, and a unique index which is derived from the order in which the record is added to variable.dbf. TID values will be ONLY be generated by the compiler. The PN will be bit shifted to the upper word, and then OR-ed with the Index to create a unique 32 bit TID value for each record. So the driver is changed as it uses different lookup criteria. Firstly, the new compiler option will have to be added to the driver options in the Protdir.dbf. This is done by adding 0x200000 to the current driver options.



In Driver DBF file, different types have to have any %N, or %R’s removed. Digital tags will also no longer need the *16 specifier. In their place, the %J option to allow us to use the OID instead of record number. Digitals within word tags will need a few more changes to the specifier as described below. DIGITALS ON 32 BIT BOUNDARYS Digitals can be placed on different address boundaries depending on the driver options given. All the different boundary options are supported by this feature except the 32 bit option, namely OPT_32_BIT_DIGITAL. Any driver wishing to use this option will not be able to use the %J specifier without problems occurring. DIGITALS WITHIN WORD TAGS The specifier configuration needs to be changed to: %J%!.%+u%! The %+u specifier takes the currently generated address (the OID) and adds the bit address within the word. So for example, say there was one OPC tag Test with 3 digitals “Test”.0, “Test”.3, “Test”.15. This would result in 3 separate records in Variable.dbf. Each would have OIDs generated e.g. “Test”.0 might have OID 0x10000010 (note 16 bit boundary) “Test”.3 might have OID 0x10000020 “Test”.15 might have OID 0x10000030 The compiled address (ie that stored in the rdb file) for Digital In Word types tags consists of an address plus a mask e.g.: Address Mask “Test”.0 0x10000010 0x0001 “Test”.3 0x10000020 0x0008 “Test”.15 0x10000030 0x8000 These masks can be seen in PageName.SYMB in the kernel for a particular page. The compiler will optimise these tags together in a blocked request starting at 0x10000010 with UnitCount of 48. In the same manner as for pure digitals, the driver will be able to determine which tags are being requested. Note that the compiler doesn’t know the 3 Citect tags refer to the same OPC tag. It will be up to the OPC driver to realise they refer to the same OPC and make any decisions about this. Note: Variable tags defined on a Citect client must match the tags defined on the I/O Server exactly. If a tag is added or removed on the client then it must also be added or removed on the I/O Server and the Citect database packed. Otherwise client requests may become miss-matched and show incorrect data. Array Support For arrays to be supported in a Tag Based Driver, blocking has to be disabled for all the array types except digital array. This can be achieved by adding the specifier %K. Adding this specifier for just the array types will allow all the non array types to be blocked as per normal, whilst allowing arrays to be supported. This specifier adds the UnitType and the Index part of the OID together, and puts the result in the UnitType, so that each request is unique. Note: The length of digital array can be no more than 16 for blocking write.

1.7.3 OPC Array Support

This driver has enhanced with Array Support since Version 1.07.02.000 B1. To specify a single variable tag for an array, define the first address and add the size of the array (the number of consecutive addresses) to the register address, for example:



Variable Tag Name Conveyor_Speed Address V500[5] In this example, five register addresses are referred to by the variable tag Conveyor_Speed. As this driver is a tag based driver, there are slightly different to specify a variable tag for an array. To specify a variable tag, the first address must be defined followed by a delimiter “!” (or other character, see 5.16.2) and “A”, for example, a tag defined on BACnet OPC server: Variable Tag Name Status_Flags Address device(1967).analog-output(1).status-flags!A[4] In this example, four register addresses are referred to by the variable tag Status_Flags. Each element of an array is referred to by an index. Individual variables (from the array) can be extracted by specifying the tag name and index. For example, to refer to the third variable of the array in the above example(Status_Flags), use the following syntax: Variable Tag Status_Flags[2] Any character can be used as a delimiter provide it is not ? ? part of the OPC server item string. ? ? character “%”, as this character is used by Citect compiler as a delimiter. Note: Some OPC server include “[n]” as part of an array tag name. In this case, the syntax !A[] is appended to the whole server tag name – ie. Tagname.[20]!A[10] specifies an array of 10 elements from a server. Delimiter Specifying To specify a delimiter, the character, which is used as a delimiter, must be defined in both OPC.DBF and Citect INI file. The character, which is immediately behind “%!”, is defined as a delimiter. For example, in following opc.dbf file, the character “!” is the delimiter defined. TEMPLATE UNIT_TYPE RAW_TYPE BIT_WIDT

H LOW HIGH COMMENT

%N%! 3 4 32 0 32767 VT_I4 %R%N+%!!A 0x20030000 4 32 0 32767 VT_ARRAY OF VT_I4

A driver specific parameter [OPC]Delimiter allows the user to specify which character is being defined as an array delimiter in the driver. The default value for this parameter is “!”. The size of array The maximum request length of this protocol is 255 bytes. So that this driver supports the following array sizes depending upon the data type: VT_BOOL 2032 (0 - 2031) VT_I2 127 (0 – 126) VT_UI2 127 (0 – 126) VT_I4 63 (0 – 62) VT_R4 63 (0 – 62) Special Option A new entry OPC1 has been added to protdir.txt. This option is used to support using Cicode function TagRead() and TagWrite() for tag with “ [ ” in their address. Details as following: OPC:



Using Cicode function TagRead() and TagWrite() for Citect Array where “ [ ” is only at the end of Tag address and must be used with !A together. For example: Variable Tag Name Status_Flags Address device(1967).analog-output(1).status-flags!A[4] Using this option, driver supports both INI array and Citect array provided “ [ ” is not in tag address(device address in opc server). Otherwise, an error 'Array has been overrun' will be returned. OPC1: Using Cicode function TagRead() and TagWrite() for tag with “ [ ” in their address. For example: Variable Tag Name String1 (Single tag) Address S7:[S7_PB_Verb1|VFD1|CP_L2_1:]DB32,40.0,1 Or: Variable Tag Name Status1 (INI Array tag) Address Status_Array[52] (no exclamation mark is used) In this case, driver just supports INI array. Risk of using array write Using Cicode function TagWrite to write to array tag, Citect sends a couple of requests (depending on maximum pending commands) to opc server. Each request modifies some of array elements. For instance, we've got an array Tag[10]. When we use Cicode TagWrite writing data to whole array, Citect may send two requests to driver. One is writing data to Tag[0], another is writing data to Tag[1] - Tag[9] (requests blocked). Driver reads the whole array from driver cache and modifies the Tag[0] and sends the request to server. Then driver reads the whole array again from cache and modifies the Tag[1]-Tag[9], then sends the whole array to server again. As the cache won't be changed until it get OnDataChange call back from server, this will cause data lost because when driver reads out array from cache for second request, the cache may haven't got the OnDataChange call back from server. The data changed on first request is lost! To solve this problem, the driver is forced to do a synchronised read before data has been modified. However it still have data losing risk if the data is change by other clients during the time the data is read out and written back. This functionality is implemented at your own risk.

1.7.4 Timestamp and Quality Support

This section documents timestamp support in driver version 1.07.03.008 b1 To specify a tag for timestamp and data quality reading is similar as specifying an array. A delimiter “!” (or other character may be used, see 5.16.2) followed by “Q”, “T” or “M” is used to specify the timestamp or quality tag. For example: a tag defined on BACnet OPC server:

Variable Tag Name Present_Value Address device(1967).analog-output(1). present-value

Followed tag definition will read quality value of tag Present_Value:

Variable Tag Name Present_Value_Quality Address device(1967).analog-output(1). present-value!Q



This tag definition will read Timestamp (seconds from 1/Jan/1970) of tag Present_Value:

Variable Tag Name Present_Value_Timestamp Address device(1967).analog-output(1). present-value!T

And this will read Millisecond Timestamp (UTC FileTime at beginning (midnight) of current day) of Present_Value:

Variable Tag Name Present_Value_Millisecond Address device(1967).analog-output(1). present-value!M

NOTE: The base tag must be defined in Citect project (doesn’t matter it is defined before or behind quality or timestamp tag is defined), otherwise is will cause error returned. For instance, in above example, tag Present_Value must be defined in Citect project.

1.7.5 Tag Qualifiers

These tag qualifiers may be used to override global behaviour set using INI parameters. When used in conjunction with other qualifiers (Quality, Timestamp, Milliseconds) qualifiers must occur last. <delimiter>C Override the global CacheRead parameter for the tag. Setting this parameter allows the current tag to return the last known cache value when it is read. <delimiter>D Override the global CacheRead parameter for the tag. Setting this parameter forces a refresh before returning the value. Examples: Tag1!D Tag2!C Tag3!Q!C

1.7.6 driver.dbf Entries3

TEMPLATE UNIT_TYPE RAW_TYPE BIT_WIDTH LOW HIGH COMMENT %R%N+%!!A 0X20040000 2 32 0 32767 VT_ARRAY OF VT_R4 %R%N+%!!A 0x20030000 4 32 0 32767 VT_ARRAY OF VT_I4 %R%N+%!!A 0x20020000 1 16 0 32767 VT_ARRAY OF VT_I2 %N+%!!A16%*16 0x200c0000 0 16 0 32767 VT_ARRAY OF VT_BOOL %R%N+%!!A%*16 0x200b0000 0 16 0 32767 VT_ARRAY OF VT_BOOL %R%N+%!!Q 0x40010000 1 16 0 32767 VT_QUALITY %R%N+%!!T 0x40040000 4 32 0 32767 VT_TIMESTAMP %R%N+%!!M 0x40070000 4 32 0 32767 VT_MILLISECOND %N+%! 8 7 1024 0 32767 VT_BSTR %N+%! 4 2 32 0 32767 VT_R4 %N+%! 3 4 32 0 32767 VT_I4 %N+%! 2 1 16 0 32767 VT_I2 %N+%! 17 8 8 0 32767 VT_UI1 %N+%!%!%*16 11 0 1 0 32767 VT_BOOL In Citect5.41 or later, TEMPLATE UNIT_TYPE RAW_TYPE BIT_WIDTH LOW HIGH COMMENT %J%K%!!A 0X24000000 2 32 0 32767 VT_ARRAY OF VT_R4 %J%K%!!A 0x23000000 4 32 0 32767 VT_ARRAY OF VT_I4



%J%K%!!A 0x22000000 1 16 0 32767 VT_ARRAY OF VT_I2 %J%!!A16 0x2c000000 0 16 0 32767 VT_ARRAY OF VT_BOOL %J%K%!!A 0x2b000000 0 16 0 32767 VT_ARRAY OF VT_BOOL %J%K%!!Q 0x41000000 1 16 0 32767 VT_QUALITY %J%K%!!T 0x44000000 4 32 0 32767 VT_TIMESTAMP %J%K%!!M 0x47000000 4 32 0 32767 VT_MILLISECOND %J%! 8 7 1024 0 32767 VT_BSTR %J%! 4 2 32 0 32767 VT_R4 %J%! 3 4 32 0 32767 VT_I4 %J%! 2 1 16 0 32767 VT_I2 %J%! 17 8 8 0 32767 VT_UI1 %J%!%! 11 0 1 0 32767 VT_BOOL

1.8 PROTDIR.DBF

TAG FILE BIT_BLOCK MAX_LENGTH OPTIONS

OPC OPC 512 2040 0x080cf OPC14 OPC 16 2040 0x880cf

6 Specifier %N+ is supported by Citect V5.30 or later.

1.9 Parameters and INI options

1.9.1 Standard Parameters

Block 255 Delay 0 MaxPending 10 Polltime 0 Timeout 10000 Retry 0 WatchTime 30

1.9.2 Driver Specific Parameters

[OPC] FailOnBadData = [0|1|2] 0 – If the OPC_QUALITY status for data from a tag is BAD, the driver will return the last known

value, and report no error. 1 – If the OPC_QUALITY status for data from a tag is BAD, the driver will report a severity error and

will display #COM on all tags of the read block. 2 – If the OPC_QUALITY status for data from a tag is BAD, the driver will report a severity error and will display #COM on all tags of the read block. The start UnitAddress of the read block will also be showed in kernel window. Default Value 0 [OPC]Delimiter Determines what character is used as an array delimiter. Allowable Values Any character except “%”. (See 5.16.2 for more details) Default Value ! This parameter should be used if any other character is defined as an array delimiter.

4 See 0 Special Option for more details.



[OPC]ArrayRecordBase Since arrays work together with items in the OPC driver they are handled with common code. This parameter specifies the base of the array record numbers. Citect communicates with the OPC client driver by the record number of the tag in variable.dbf. So this parameter must be greater than the total number of tags in the project. Allowable Values

Base record number. Greater then total number of Tags – less than 65000 – (number of arrays)

Default Value 30000 [OPC]UseIncludeProjects By default the OPC driver supports the definition of Variable Tags in projects that are included below the main project. Allowable Values 0 or 1 Default Value 1 Note: Variable tags defined on a Citect client must match the tags defined on the I/O Server exactly. If a tag is added or removed on the client then it must also be added or removed on the I/O Server and the Citect database packed. Otherwise client requests may become miss-matched and show incorrect data. [OPC]AddItemAsVtEmpty Determines whether the OPC driver specifies a data type when adding an item, or whether it uses the native data type when adding items. Allowable Values 0 (Specify data type) 1 (Use native data type) Default Value 0 This parameter should only be required for incorrectly designed OPC Servers. [OPC]WriteTrueAs1 Determines whether a True is written as VARIANT_TRUE (-1) or 1. Allowable Values 0 (Write True as VARIANT_TRUE (-1)) 1 (Write True as 1) Default Value 0 This parameter should only be required for incorrectly designed OPC Servers. When the Citect data type is digital then VARIANT_TRUE (-1) is used with VT_BOOL variant type to write a value of True. This will happen even if [OPC]AddItemAsVtEmpty is set as OPC Servers should be designed to convert the value when they receive it. [OPC]ResfreshAfterAdd Determines whether a refresh is requested from the OPC Server after activating the group. Allowable Values 0 (Do not request a refresh)



1 (Request a refresh) Default Value 1 This parameter should be used if slow start up times are experienced. The server may be automatically sending a refresh in which case another request may be unnecessary. [OPC]FillCacheOnStartup Determines whether at startup the driver requests a synchronous read when adding tags to the OPC server, to fill the local cache. Allowable Values 0 (Do not do fill cache on start up) 1 (Fill cache on startup) Default Value 0 This parameter should be used if slow start up times are experienced. The server may be already sending asynchronous read results in which case a synchronous read may be unnecessary. [OPC]LeaveTagsActive Determines whether OPC tags are left as active even though Citect is no longer requesting them from the driver. Normally tags are made inactive after 5 seconds from the last time they are requested. Allowable Values 0 (Do not leave tags active) 1 (Leave tags active) Default Value 1 Tags should be made inactive when they are not used to reduce client/server activity. Some OPC Servers take a long time to return from a call to activate/inactivate tags or doing so bogs them down. [OPC]UseArrays Determines whether ini array support is active in the driver. Allowable Values 0 (Ini Array support disabled) 1 (Ini Array support enabled) Default Value 1 See the section 1.9.7 for more information on INI array support. [OPC]ShutdownWait Determines the time the front end will wait for the worker thread to terminate when a shutdown is requested. After this time it will kill the thread which may cause unexpected results. Allowable Values Time in milliseconds Default Value 5000 This parameter may be needed if the worker thread is blocked on a call to the OPC Server that does not respond within the default wait time. [OPC]RefreshAfterWrite Determines whether to force a refresh of ALL active items after Citect writes to an item. Allowable Values



0 (disable) 1 (enable) Default Value 0 [OPC]ItemLifeTime Determines the time in seconds before a tag is deemed inactive (subject to [OPC]LeaveTagsActive=0) Allowable Values Time in seconds Default Value 5 [OPC]UseOPC2 Determines whether to use OPC1.0a or OPC2.0 interfaces Allowable Values 0 (Use OPC 1.0a interfaces) 1 (Use OPCDA2 interfaces) Default Value 0 [OPC]UseStatusTags=1 (default = 0) The following status tags parameters are then available – The side effect of not waiting for the OPC Server to respond is that we don’t know the value of the OPC Tag so if we started the I/O Device now, it would be determined to be offline. If a device is offline, Citect won’t display any data from any device until an I/O Server default of 30 seconds expires. So we make another compromise and after adding all Status Groups we wait for a period specified by the following parameter – [OPC]StatusWaitPeriod=value in msec (default=5000, disable = -1) Observations indicate that most OPC Servers will have responded within a few seconds so it is now OK for the driver to request all the tags/items for each I/O Device. Previous versions of this driver added all the tags for each I/O Device without ever waiting for the OPC Server to provide valid data. [OPC]GoOfflineForBadTag=1 (default=0) This ensures all tags on an OPC Device have a OPC_QUALITY status of GOOD before Citect declares the I/O Device online. It is expected that this parameter would only be set on the I/O Server where the device is defined as primary, so it can only take over from a standby device definition when all tags and the status tag are valid. This ensures that no com-breaks occur during switchover from standby to primary. It would be prudent not to set it on a standby, as it may only be one tag that is invalid. [OPC] FailOnUncertain=1 (default=0) 0 – When data is read from any the tag for which the OPC quality value is uncertain, the driver will

return the last known value and the read will succeed. 1 – When data is read from any the tag for which the OPC quality value is uncertain, the driver will

return ERROR_BAD_DATA_VALUE. [OPC] CacheRead=1 (default=1)



0 – When an inactive item is read, the last known value may be returned. Specify 0 to force the latest value to be refreshed.

1 – When an inactive item is read, the last known value may be returned. This parameter is not needed if FillCacheOnStartup and LeaveTagsActive are set to 1 since the cache always contains the latest value in this case. This parameter may be overridden on a per tag basis using the !C or !D qualifiers on the tag address (see 1.7.5 for details).

1.9.3 Device Specific Parameters

[OPC]IOServerName.IODeviceName.Active Allows user to individually overide the global default and specify whether tags should be left active or inactive for each IODevice. Allowable Values 0 (Do not leave tags active) 1 (Leave tags active) Default Value = value of [OPC]LeaveTagsActive [OPC]IOServerName.IODeviceName.Update Allows user to individually overide the global default and specify Update Rate for each IODevice. Allowable Values Time in milliseconds Default Value = value from Boards form [OPC]IOServerName.IODeviceName.UseOPC2 Allows user to individually overide the global default and specify whether to use OPC1.0a or OPC2.0 for each IODevice. Allowable Values 0 (Use OPC 1.0a interfaces) 1 (Use OPCDA2 interfaces) Default Value = value of [OPC]UseOPC2

1.9.4 AccessPath Parameters

In some instances, an OPC Server may have more than one means of accessing a particular item. For instance, a particular Server, which communicates by means of modem, may have more than one modem at its disposal. It may be desired that certain items in the OPC server always be accessed using a particular modem, say the fastest of the group. OPC provides a means of specifying this preference via the Access Path. An Access Path is an optional piece of information, provided in addition to the Item ID (the tag address) that is provided as a recommendation to the server regarding how to get to the data. The availability, format, and use of Access Paths is highly server specific. Please consult your OPC Server documentation for details regarding the use of Access Paths in your application. The Citect OPC Client Driver supports the specification of a single Access Path for each configured I/O Device, using the [OPCACCESSPATHS] section of the CITECT.INI file. To specify the Access Path of to be used for a particular device, add an entry in the format IOServerName.IODeviceName to the above section. For example, to specify that the Access Path “COM1:” should be used for the I/O Device “OPC1” on I/O Server “IOServer1” the following entry would be added to the CITECT.INI file: [OPCACCESSPATHS]IOServerName.IODeviceName=topicname



Eg. IOServer1.OPC1=COM1: By default, when no access path INI parameter is specified and/or the path is set to "", OPC sends a NULL pointer to the server. On many machines this is not a problem. However, some servers need to be sent a NULL string. To do this, set AllowNullString=1 in the citect.ini file.

[OPCACCESSPATHS] server.name="" AllowNullString=1

1.9.5 StatusTag Parameters

[OPCStatusTags]Default.Update=value

default = ScanRate from Address field in Citect Boards form [OPCStatusTags]Default.Tag=OPCTagName (default=STATUS) [OPCStatusTags]Default.Condition=value (default=ISGOOD) Each I/O Device can also specify its own update rate, tag and or condition to override the defaults – The routine that reads the Citect.ini condition parameters, returns the text after the first = sign and this becomes the condition that determines if I/O Device should be on or offline. Condition can be any of the following – IOServer.IODevice.Condition= value IOServer.IODevice.Condition= =value (same as above) IOServer.IODevice.Condition= !value IOServer.IODevice.Condition= !=value (same as above) IOServer.IODevice.Condition= >value IOServer.IODevice.Condition= >=value IOServer.IODevice.Condition= <value IOServer.IODevice.Condition= <=value IOServer.IODevice.Condition= ISGOOD IOServer.IODevice.Condition= ISBAD IOServer.IODevice.Condition= ISUNCERTAIN On adding a Status Group (with a single OPC Tag) the driver will wait for a response from the OPC Server before adding the next Group. Some OPC Servers are a bit slow to respond when starting up (usually because they’ve just started and are trying to contact the devices they need to get values from). If Citect has been configured with a lot of I/O Devices then startup will be painfully slow. To speed things up the user can specify the following parameter – [OPCStatusTags]StartWait=value in msec (default=30000, -1=infinite) Note: Some OPC Servers will experience problems if groups are added too quickly. A minmum value of 500 is suggested.

1.9.6 StatusTag Device Specific Parameters

[OPCStatusTags] IOServerName.IODeviceName.UseOPC2=value (0=disable, 1=enable, default=[OPC]UseOPC2)



[OPCStatusTags] IOServerName.IODeviceName.Update=value [OPCStatusTags] IOServerName.IODeviceName.Tag=OPCTagName [OPCStatusTags] IOServerName.IODeviceName.Condition=value

1.9.7 Array Request Parameters

This section documents the array support in the OPC client driver. This is not to be confused with Citect array support. The array support here is to be aware of array elements and block them into a single array call. In most cases this will provide an improvement in the performance between the OPC driver and OPC Servers. Ini Array support is used by defining known arrays in the OPC Server. Array elements are still defined as such in Citect. When the OPC driver starts, it checks to see if any tags are array elements of known arrays defined in the citect ini file. If so they will be grouped with the array and only the array tag will be requested from the OPC Server. Reads for the array items will be extracted from the read array. Eg. If there are tags Tag1[0] and Tag1[1] defined in Citect then defining a known array of Tag1 with length 2 will group these two tags together. Array support is set up via the Citect.ini file. A new section [OPCArrays] is available. The parameters in this section are as below. <IOServer> and <IODevice> are placeholders. They are replaced with the IOServer and IODevice for which arrays are being set up. <n> starts from zero (0). [OPCArrays] <IOServer>.<IODevice>.Count This parameter is used to specify the number of known arrays for the IODevice that follow in the section. [OPCArrays] <IOServer>.<IODevice>.Array<n> This parameter defines array <n> for the IODevice as found in the OPC Server. This is normally done by specifying the base tag and then specifying the length. Eg. An array of integers of size 10 may be Tag1[0],l10 – an array of bits of the ten integers may be Tag1[0]/0,l160. Refer to your OPC Server documentation for more information. [OPCArrays] <IOServer>.<IODevice>.Type<n> This parameter specifies the COM type of array <n> of the IODevice. It is important that this is specified correctly so that the driver knows what the format of the returned array will be. This is the type of the COM variable that each array element is. You do not need to add the array mask. This will be done by the driver. Common possible values are: VT_I2 = 2 VT_I4 = 3 VT_R4 = 4 VT_R8 = 5 VT_CY = 6 VT_DATE = 7



VT_BSTR = 8 VT_ERROR = 10

VT_BOOL = 11 VT_UI1 = 17 [OPCArrays] Delimiters Determines what array delimiters will be searched for in tags. It is made up of the string… <Array start delimiter><Array end delimiter><Bit pick delimiter><End of tag start of length delimiter><Length character specifier> … and defaults to “ [ ] / , l “ (note that spaces are included here for clarity. Do not use spaces if you are specifying your own delimiters) (Note that the last character is an ‘el’ not an ‘i’) The default delimiters are suitable for Rockwell’s RSLinx. Array support is possible for other OPC Servers using an appropriate delimiter configuration. Array support examples - We wish to define arrays – elements of Tag1, length 10, type short and bits of elements of Tag1, length160 (10 * 16) - for IODev1 on IOServer1. The configuration of the Citect.ini would be. [OPCArrays] IOServer1.IODev1.Count=2 IOServer1.IODev1.Array0=Tag1[0],L10 IOServer1.IODev1.Type0=2 IOServer1.IODev1.Array1=Tag1[0]/0,L160 IOServer1.IODev1.Type2=2 If you have an OPC Server where the array definition is done using the period delimiter only and bit picks are done using the ^ then the delimiter string would be [OPCArrays] Delimiters=. ^,l ie. <period><space><hat><comma><l> Array support and writes When using array support writes are handled individually. If a write is done to a tag which has been grouped as part of an array then that tag is temporarily added to the OPC Server, the write done synchronously, then the tag removed from the Server.

1.10 Remapping Not implemented.

1.11 Driver Specific Errors Citect OPC Driver Errors – Driver Error Code

(Hexadecimal)

Mapped to

(Generic Error label)

Meaning of Error Code

100 GENERIC_SOFTWARE_ERROR

Failed to access variable dbf

101 DRIVER_BAD_DATA Read of Data Value Was Bad



102 GENERIC_GENERAL_ERROR

Write of one or more items failed.

103 DRIVER_UNIT_OFFLINE Could not resolve the server CLASSID.

104 GENERIC_SOFTWARE_ERROR

Could not add one or more items to the Server

Standard OPC Server Errors - Driver Error Code

(Hexadecimal)

Mapped to

(Generic Error label)

Meaning of Error Code

(0xC0040001) GENERIC_SOFTWARE_ERROR

An invalid handle was passed


A duplicate parameter was passed where one is not allowed

(0xC0040004) GENERIC_INVALID_DATA_FORMAT

The server cannot convert between the passed or requested data type and the canonical type


The requested operation cannot be done on a public group.

(0xC0040006) GENERIC_ACCESS_VOILATION

The item's Access Rights do not allow the operation


The item definition does not exist within the servers address space


The item definition does not conform to the server's syntax


The filter string was not valid

(0xC004000A) GENERIC_SOFTWARE_ERROR

The item’s access path is not known to the server

(0xC004000B) GENERIC_INVALID_DATA_FORMAT

The value passed to WRITE was out of range

(0xC004000C) GENERIC_SOFTWARE_ERROR

Duplicate name not allowed

(0xC004000D) GENERIC_SOFTWARE_ERROR

The server does not support the requested data rate, but will use the closest available rate

(0xC004000E) GENERIC_SOFTWARE_ERROR

A value passed to WRITE was accepted but the value was clamped

(0xC004000F) GENERIC_SOFTWARE_ERROR

The operations cannot be completed because the object still has references that exist


The server’s configuration file has an invalid format


The server could not locate the requested object

Standard Windows Software Interface Errors – (0x80010006) GENERIC_CHANNEL_O

FFLINE The connection terminated

(0x80010007) GENERIC_CHANNEL_OFFLINE

The server is not available

(0x8001000F) GENERIC_INVALID_RESPONSE

Received data is invalid

(0x80010012) GENERIC_SOFTWARE_ERROR

The call did not execute.




System call failed


Could not allocate some required resource

(0x80010103) GENERIC_BAD_PARAMETER

The requested interface is not registered on the server object.


Could not call the server


The server threw an exception


The server has disconnected from its clients.

(0x8001011B) GENERIC_CHANNEL_OFFLINE

Access is denied

(0x8001011C) GENERIC_CHANNEL_OFFLINE

Remote calls are not allowed for this process.

(0x80020008)

GENERIC_SOFTWARE_ERROR

Bad variable type

(0x8002000A)


Out of present range

(0x80020005)


Type mismatch.


Interface not registered


General access denied error

1.12 Driver Error Help The following entries should be included in the Citect PROTERR.DBF spec file.

PROTOCOL MASK ERROR MESSAGE REFERENCE ACTION COMMENT

OPC C0040001 An invalid handle was passed

C0040002 A duplicate parameter was passed

C0040004 Type mismatch

C0040006 Item access rights do not allow the operation

C0040007 Item definition does not exist

C0040008 Item definition



syntax is incorrect

C004000B The value passed to WRITE was out of range

80020008

Bad variable type

8002000A

Out of present range

80020005

Type mismatch.

100 Failed to access variable dbf

101 Read of data value was bad

102 Write of one or more items failed.

103 Could not resolve the server CLASSID.

104 Could not add one or more items to the Server

80010006 The connection terminated

80010007 The server is not available

8001000F Received data is invalid

80010012 The call did not execute.

80010100 System call failed

80010101 Could not allocate some required resource

80010103 The requested interface is not registered



80010104 Could not call the server

80010105 The server threw an exception

80010108 The server has disconnected from its clients.

8001011B Access is denied

8001011C Remote calls are not allowed for this process.

1.13 Debug Messages The standard Citect debug modes will be supported. 1.13.1 Debug Write Thu Aug 20 12:11:46 1998 02:58:20.346 WRITE Length 2 01 00 .. 1.13.2 Debug Error Thu Aug 20 12:11:46 1998 02:58:20.348 WRITE ERROR: 0x80004005 Length 2 01 00 .. 1.13.3 Debug All Thu Aug 20 12:11:45 1998 02:58:19.772 READ Length 184 06 00 00 00 42 00 00 00 FF FF FF FF 00 00 00 00 ....B........... 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 3D 00 00 00 0F 00 00 00 35 00 00 00 2A 00 00 00 =.......5...*... 38 00 00 00 33 00 00 00 28 00 00 00 1F 00 00 00 8...3...(....... 3C 00 00 00 1C 00 00 00 5E 00 00 00 0F 00 00 00 <.......^....... 44 00 00 00 11 00 00 00 14 00 00 00 01 00 00 00 D............... 27 00 00 00 39 00 00 00 5A 00 00 00 4A 00 00 00 '...9...Z...J... 32 00 00 00 0F 00 00 00 42 00 00 00 5F 00 00 00 2.......B..._... 3B 00 00 00 4E 00 00 00 0F 00 00 00 5E 00 00 00 ;...N.......^... 11 00 00 00 1A 00 00 00 49 00 00 00 0F 00 00 00 ........I....... 38 00 00 00 28 00 00 00 27 00 00 00 2D 00 00 00 8...(...'... -... 48 00 00 00 50 00 00 00

1.14 Stats Special Counters Accessed from the ‘Driver’ page in the Citect kernel by increasing the length of the window and pressing the ‘v’ key for verbose mode. Number Label Purpose/Meaning of this counter

0 CachedReads The number of read requests that have been serviced directly from cached data.

1 CacheMisses The number of read requests that have been resulted in a method call on the remote server object.

2 ActiveItems The number of items currently set to the active state



3 TotalItems The total number of items.

4

1.15 Hints and Tips One should become familiar with the target OPC Server(s) before using this driver, this will insure proper syntax for Tag Address - ItemName mapping. One of the joys of using remote Servers is configuring DCOM security. It pays to plan a systems settings in advance, and establish a protocol to ensuring that all windows accounts to be used by operators have sufficient privilege, as failing to do so will may result in communications failures.



2. References and Contacts

2.1 References [OPC97A] OLE for Process Control Data Access Standard, Version 1.0A. September 11, 1997.

Available from the OPC Foundation, http://www.opcfoundation.org.

[OPCDA203_CUST.doc] OPC Data Access Custom Interface Specification, Version 2.03. July 27, 1999.

Available from the OPC Foundation, http://www.opcfoundation.org.

[Include Function For Tag Based Drivers Function Specification] The detail of include function to Citect5.41 or later

citect for windows driver specification opc client driver · pdf filecitect for windows driver...

Documents