OPCtoCSV User’s Guide
OPCtoCSV User’s Guide
Version 1.0.0.x
|OSIsoft, LLC |
|777 Davis St., Suite 250 |
|San Leandro, CA 94577 USA |
|Tel: (01) 510-297-5800 |
|Fax: (01) 510-357-8136 |
|Web: |
| |
|OSIsoft Australia • Perth, Australia |
|OSIsoft Europe GmbH • Frankfurt, Germany |
|OSIsoft Asia Pte Ltd. • Singapore |
|OSIsoft Canada ULC • Montreal & Calgary, Canada |
|OSIsoft, LLC Representative Office • Shanghai, People’s Republic of China |
|OSIsoft Japan KK • Tokyo, Japan |
|OSIsoft Mexico S. De R.L. De C.V. • Mexico City, Mexico |
|OSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil |
|OPCtoCSV User’s Guide |
|Copyright: © 2011" "2012" "2011-" "" \* MERGEFORMAT 2011-2012 OSIsoft, LLC. All rights reserved. |
|No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, |
|photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC. |
| |
|OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework(PI-AF), IT Monitor, MCN |
|Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI |
|WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other |
|trademarks or trade names used herein are the property of their respective owners. |
| |
|U.S. GOVERNMENT RIGHTS |
|Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as |
|provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC. |
| |
|Published: 02/2012 |
Table of Contents
Chapter 1. Introduction 1
Reference Manuals 2
Supported Operating Systems 2
Supported Features 3
Chapter 2. Principles of Operation 5
Exploring the OPC Address Space 5
Exporting PI Point Definitions 6
Fixed Fields 6
Configurable Fields 9
Chapter 3. Installation 11
Interface and Application Directories 11
PIHOME Directory Tree 11
OPCtoCSV Installation Directory 11
Installing OPCtoCSV Separately 12
Chapter 4. CSV Output File 13
CSV File Structure 13
Header Line 13
Value Lines 13
Fields in OPCtoCSV Output Files 15
Fixed Fields 16
Configurable Fields 18
Parsing Lines into Fields 21
Fields with no value 22
Chapter 5. Running OPCtoCSV 23
Built-in Help 23
OPCtoCSV Command Syntax 24
Priority Reduction 26
Output to Command Window 26
Error Messages 26
Exit Code 27
Terminating Before Completion 27
Chapter 6. Using with PI Tag Configurator 29
Specific Considerations 29
Configurable Fields 29
Empty Cells 30
Point Creation 30
Zero and Span from MinValue and MaxValue 30
Unacceptable Columns 30
Chapter 7. Using with GenericCSV_APS Connector 31
Advantages and Disadvantages 32
HDA 33
DA 33
GenericCSV_APS Input Files 33
Configuring GenericCSV_APS to Replace an OPC APS Connector 35
Revising the CSV File Before Synchronization 38
Appendix A. Error and Informational Messages 41
Appendix B. OPC Properties 43
Property IDs in the DA Standard 43
Attribute IDs in the HDA Standard 45
APS_OPCexplorer 46
Built-in Help 46
APS_OPCexplorer Command Syntax 47
Priority Reduction 48
Output to Command Window 48
Error Messages 48
Terminating Before Completion 48
Interpreting the Log File 48
Appendix C. Technical Support and Resources 53
Before You Call or Write for Help 53
Help Desk and Telephone Support 53
Search Support 54
Email-based Technical Support 54
Online Technical Support 54
Remote Access 55
On-site Service 55
Knowledge Center 55
Upgrades 55
OSIsoft Virtual Campus (vCampus) 55
Appendix D. Revision History 57
Introduction
The OPCtoCSV tool provides access to OPC item properties and enables you to apply OPC server-specific or site-specific knowledge to revise or create PI point attributes before PI points are created or edited. OPCtoCSV is intended to be the first step in an automated or semi-automated process that maintains PI points for the OPC DA or OPC HDA interfaces.
The OPCtoCSV tool explores an OPC Data Access (DA) or Historical Data Access (HDA) server for items with data that can be collected by the OPC DA or OPC HDA interface to the PI System and creates a file of PI point definitions for the interface. The PI point attributes in the file are derived from information from the OPC server, including OPC DA properties or OPC HDA attributes for each item.
To avoid confusion with PI point attributes, the remainder of this document uses properties as a generic term for either OPC DA properties or OPC HDA attributes.
Both the Data Access Custom Interface Standard and OPC Historical Data Access Specification allow OPC servers to provide vendor-specific properties. Both OPC specifications also give OPC server vendors complete freedom to define the structure and naming convention of the OPC address space. For example, if vendor-specific names of branches or leaves indicate the type of measurement device that is the data source for an item, you can use this information to infer attributes like EngUnits, Zero, or Span for a PI point.
Additionally, the ItemIDs or names of branches or leaves in the OPC server usually are configurable either in the OPC server or in the measurement or control systems that provide data for the OPC server. Site-specific naming conventions also can convey information about items. For example, a naming convention can use suffixes like “.TC” for temperature controllers, “.FC” for flow controllers, and so forth. In this example, the EngUnit attribute for PI points can be deduced as “degrees” for items with “.TC” suffix, “liters/second” for items with “.FC” suffix, and so forth.
OPCtoCSV writes PI point definitions into a plain text file that is structured as lines of comma-separated values (CSV). The CSV file can be modified with a text editor, Excel, or a user-written program before PI points are created or edited. After the CSV file is revised, the PI Tag Configurator add-in for Excel or the GenericCSV_APS connector for PI AutoPointSync can update the PI point database from the CSV file. The “Using with PI Tag Configurator” and “Using with GenericCSV_APS Connector” chapters in this document provide more information on using these tools with OPCtoCSV.
OPCtoCSV is intended to facilitate automation of the process of exporting OPC items as PI point definitions, applying vendor-specific or site-specific knowledge to revise the PI point definitions, and updating the PI point database. OPCtoCSV is a command-line utility (OPCtoCSV does not have a graphical user interface).
Note: The value of [PIHOME] variable for a 32-bit application depends on whether the application is being installed on a 32-bit operating system (C:\Program Files\PIPC) or a 64-bit operating system (C:\Program Files (x86)\PIPC).
Reference Manuals
OSIsoft
• PI AutoPointSync Connector for Comma-separated Values (CSV) Files
• PI Tag Configurator help file
• DCOM Configuration Guide
OPC Foundation
• Data Access Custom Interface Standard, Version 2.05A
• OPC Historical Data Access Specification, Version 1.20
The OPC standards are available to OPC Foundation members at .
Supported Operating Systems
|Platforms |32-bit application |64-bit application |
|Windows XP |32-bit OS |Yes |No |
| |64-bit OS |Yes (Emulation Mode) |No |
|Windows 2003 Server |32-bit OS |Yes |No |
| |64-bit OS |Yes (Emulation Mode) |No |
|Windows Vista |32-bit OS |Yes |No |
| |64-bit OS |Yes (Emulation Mode) |No |
|Windows 2008 |32-bit OS |Yes |No |
|Windows 2008 R2 |64-bit OS |Yes (Emulation Mode) |No |
|Windows 7 |32-bit OS |Yes |No |
| |64-bit OS |Yes (Emulation Mode) |No |
OPCtoCSV is designed to run on the abovementioned Microsoft Windows operating systems and their associated service packs.
Supported Features
|Feature |Support |
|Auto Creates PI Points |No |
|PI Point Types |int32, float32, float64, string |
|Outputs from PI |No |
|Inputs to PI: |Yes |
|Vendor Software Required on PI Interface Node / |No |
|PINet Node | |
|Vendor Software Required on Foreign Device |No |
|Vendor Hardware Required |No |
|Additional PI Software Included with Interface |No |
|* Device Point Types |VARIANT types: |
| |VT_BOOL boolean |
| |VT_BSTR string |
| |VT_I1 8-bit integer |
| |VT_I2 16-bit integer |
| |VT_I4 32-bit integer |
| |VT_I8 64-bit integer |
| |VT_INT 32-bit integer |
| |VT_R4 32-bit floating point |
| |VT_R8 64-bit floating point |
| |VT_UI1 8-bit unsigned integer |
| |VT_UI2 16-bit unsigned integer |
| |VT_UI4 32-bit unsigned integer |
| |VT_UI8 64-bit unsigned integer |
| |VT_UINT 32-bit unsigned integer |
* See paragraphs below for further explanation.
Device Point Types
OPCtoCSV converts the VARIANT types in the table to a suitable PI point type. If an item has a VARIANT type that is not in the table, the PI point type is null.
Array data types are not specifically supported. If an OPC item has an array data type, only one PI point definition is written to the CSV file. The PointType attribute for this PI point is the default for the array element data type. For example, if an OPC item has type VT_ARRAY | VT_I4, the PointType attribute is int32.
The OPC DA interface supports items with array data type. An individual PI point is required for each array element with the element index in theUserInt1 attribute. OPCtoCSV does not create individual PI point definitions for array elements. If you want to create or edit PI points for elements in an OPC array item, you must duplicate the single line that OPCtoCSV writes, change the tag name, and add UserInt1.
The OPC HDA interface does not support items with array data types.
Principles of Operation
OPCtoCSV is the OPC-facing side of the OPC APS connectors packaged as a self-contained program. To search for OPC items, OPCtoCSV makes the same series of OPC calls as the OPC APS connector. For each item found, OPCtoCSV writes the properties of the item into a file of comma-separated values (CSV).
Exploring the OPC Address Space
By default, OPCtoCSV starts exploring the OPC address space at the topmost branch (the root) of the browser hierarchy. Command-line switches /path or /down direct OPCtoCSV to use a subbranch as the starting point for exploring the OPC address space.
The /path switch is followed by a subbranch path specified in the syntax of the OPC server. This program makes a single OPC ChangeBrowsePosition(direction,subbranch path) call, where direction is OPC_BROWSE_TO for DA or OPCHDA_BROWSE_DIRECT for HDA. Unless this call fails, exploration begins at this subbranch.
The /down switch is followed by a list of one or more branch names. For each branch name, left to right, this program calls OPC ChangeBrowsePosition(direction,branch name), where direction is OPC_BROWSE_DOWN for DA or OPCHDA_BROWSE_DOWN for HDA. Unless one of the calls fails, exploration begins in the final branch in the list.
After navigating to the starting branch, OPCtoCSV exports all items in the starting branch and all of its subbranches.
In each branch being explored, OPCtoCSV calls the OPC server for a list of all leaves. Understand that the name of a leaf is a short name for an item, which usually is not the unique ItemID for the item. For each leaf, the ItemID and other properties are requested from the OPC server and a PI point definition for the item is written to the CSV file, as explained in the “Exporting PI Point Definitions” section.
After processing the leaf nodes, OPCtoCSV calls the OPC server for a list of all subbranch nodes. For each subbranch, OPCtoCSV determines if the subbranch itself is also an OPC item by calling the OPC server for the ItemID and properties of the subbranch. If the OPC server returns properties for the subbranch (indicating that the subbranch is an item), a PI point definition for the item is written to the CSV file. Regardless of the outcome, the subbranch is recursively explored.
For each subbranch, OPCtoCSV recursively explores the subbranch. That is, OPCtoCSV calls the OPC server to descend into the subbranch of the browser hierarchy. In this new context, the leaf and branch nodes are processed as described above. After processing the leaf and branch nodes, OPCtoCSV calls the OPC server to ascend to the parent branch in the browser hierarchy and resumes processing in the parent branch.
After the last subbranch of the starting branch is processed, OPCtoCSV disconnects from the OPC server, closes the CSV file, and terminates.
Exporting PI Point Definitions
A comma-separated value (CSV) file is a plain text representation of a table of data. Each line in the file corresponds to one row in the table. Each line contains data fields separated by commas. The fields correspond to the columns in the table. The first line of the CSV file is a header line, which corresponds to the heading of a table and contains the names of the data fields on the remaining lines in the file. The data fields are referred to by the names in the header line.
OPCtoCSV creates a CSV file that contains:
• seven fixed fields
• configurable fields for other PI point attributes
The “CSV Output File” chapter contains details about the CSV file structure and the reasons for including the fixed fields and for the specific names. This chapter explains how OPCtoCSV calculates the value for each field. Briefly, the value of a configurable field is either a constant or an OPC property value for an item. In contrast, each fixed field requires specific processing to calculate the value.
When OPCtoCSV discovers an item while exploring the OPC address space, OPCtoCSV calculates a value for each field and writes a line into the CSV file.
Fixed Fields
The first seven fields in the CSV file are fixed fields in the following order:
• Select (x)
• Tag
• BranchPath
• Item
• CanonicalType
• PointType
• InstrumentTag
The value for each fixed field either is derived from OPC browsing functions or requires transformation, as explained in the following sections.
Select (x)
The field value is “x” for all items.
Tag
Every PI point must have a unique name, which is the PI point Tag attribute. In an OPC server, ItemIDs must be unique and are analogous to a PI point tag name. The default Tag field value for each OPC item is the ItemID.
The OPC standards do not restrict the characters that can be used in ItemIDs. The naming convention for ItemIDs is completely server-specific.
Several punctuation characters are illegal in PI point tag names (Tag attribute). If an ItemID contains illegal characters, OPCtoCSV replaces the illegal characters in the Tag field with the characters shown in the following table:
|Illegal Character |Replacement Character |
|* |@ |
|? |% |
|' " ` |^ |
|[ { |( |
|] } |) |
|| |! |
|\ |/ |
|; |: |
BranchPath
OPCtoCSV changes the OPC browse position (that is, the “working” branch) to each branch that is explored, as discussed in the “Exploring the OPC Address Space” section. Each time that OPCtoCSV changes the OPC browse position by descending into a child branch or ascending into a parent branch, OPCtoCSV requests the full branch path from the OPC server. The full branch path is the BranchPath field value for all items in the working branch. The syntax of the branch path is server-specific.
Item
As discussed in the “Exploring the OPC Address Space” section, OPCtoCSV requests the list of leaves and the list of subbranches in each branch. The names in both lists are short names that are unique only within the current branch. That is, the short names are not unique ItemsIDs. The Item field in each CSV line is the short name for the item. The set of characters allowed in a short name is server-specific.
CanonicalType
Each item in an OPC server has a value that is returned to clients as a Windows VARIANT. A Windows VARIANT is a “universal” data type that can represent values in a variety of fundamental data types, like signed and unsigned integers of different sizes, floating-point numbers, and strings. OPC servers generally use the VARIANT type that matches the native data type of the source of each item. The internal VARIANT type for each item in the OPC server is called the canonical data type.
For each item, OPCtoCSV requests item properties. The list of properties always includes the property ID for item canonical data type, which is the internal representation of the item value in the OPC server.
The canonical data type property is an integer value that contains a Windows VARIANT type code. The Windows programming environment defines symbolic names for the VARIANT type codes and the symbolic names usually are used instead of the corresponding numeric codes. The symbolic names are a mnemonic type name prefixed with “VT_”. For example, VT_I4 (4-byte signed integer) represents type code 3, VT_UI2 (2-byte unsigned integer) represents type code 18, VT_R4 (4-byte floating-point) represents type code 4, and so forth.
A VARIANT also can contain an array of elements of a basic VARIANT type. When a VARIANT contains an array, the type code is the logical OR of the VT_ARRAY bit with the type code for the basic type.
Because the symbolic names for VARIANT type codes are mnemonic (and the type codes are not), OPCtoCSV translates the type code from the OPC canonical data type property to the corresponding symbolic name. The VT_ARRAY bit is removed to determine the basic type code. The symbolic name for the basic type code is determined from a lookup table. If a symbolic name is not found for the basic type code, the symbolic name is VT_nn where nn is the type code. If the VT_ARRAY bit was set in the original canonical data type property, “VT_ARRAY | ” is concatenated with the symbolic name of the basic type code to form the final symbolic name.
The symbolic name is the value for the CanonicalType field.
PointType
A PI point data type is required to create a PI point, which is the main application for OPCtoCSV. Because the PI type codes and symbolic names are different from the VARIANT type codes and symbolic names, the OPC canonical data type cannot be used directly as the PI point type. Therefore, OPCtoCSV maps the canonical data type to a PI point data type that can store the canonical data type over the full range of values. The symbolic name for the PI point type is the value for the PointType field.
A PI point cannot store an array. The usual approach for acquiring data from an array value is to create individual PI points for each element of the array. OPCtoCSV does not specifically support an item has the VT_ARRAY bit set in the canonical data type. For the purposes of mapping canonical data type to a PI point type, OPCtoCSV ignores the VT_ARRAY bit. In effect, OPCtoCSV treats an item with an array value as if the item were not an array. Only one PI point definition is written into the CSV file.
The following table shows the PI point type for VARIANT type codes. Generally, OPCtoCSV maps the canonical data type to a PI point data type with the same number of bits. Also, the PI point type must have a range of values that covers the full range of the canonical data type. For example, the PI point type int16 is an unsigned type, which makes int16 unsuitable for VT_I2 (because int16 cannot store any negative VT_I2 value). Another example is the mapping of VT_UI4. VT_UI4 is not mapped to int32 because int32 cannot store values in the upper half of the VT_UI4 range. OPCtoCSV maps VT_UI4 to float32, which can represent the full VT_UI4 range (with some loss of low-order bits for large numbers) in the same number of bits.
|VARIANT Type |PI point Type |
|VT_BOOL |int32 |
|VT_I1 | |
|VT_UI1 | |
|VT_I2 | |
|VT_UI2 | |
|VT_I4 | |
|VT_INT | |
|VT_UI4 |float32 |
|VT_UINT | |
|VT_R4 | |
|VT_I8 |float64 |
|VT_UI8 | |
|VT_R8 | |
|VT_BSTR |string |
|All other codes |null |
InstrumentTag
OPCtoCSV sets the InstrumentTag field to the ItemID of the item.
PI points for the OPC DA interface and the OPC HDA interface are configured by storing the ItemID for the source item in the InstrumentTag attribute. This field supplies the InstrumentTag attribute for PI points for either interface.
Configurable Fields
The fixed fields can be followed by configurable fields. The configurable fields are specified by the /fields switch in the command-line parameters. The configurable fields can contain
• Constant fields
• Property fields
Constant fields have the same value for every item. For example, most interfaces use the PointSource attribute to determine the PI points that the interface manages. A constant field named PointSource can set the PointSource attribute for all of the PI point definitions in the CSV file.
Values for property fields are obtained from the properties of an item. From the /fields parameters, OPCtoCSV assembles a list of property IDs that are referenced in all property fields. The property ID for canonical data type is always the first ID in this list because the canonical data type property is required to calculate the CanonicalType and PointType fixed fields. As OPCtoCSV explores the OPC address space, OPCtoCSV uses this list of property IDs to request properties for each leaf and branch. The presence of properties indicates that the leaf or branch is an item. When the OPC server returns property values, OPCtoCSV determines the field values for a new line in the CSV file.
An OPC server is not required to support the same set of properties for every item. When OPCtoCSV requests property values for a list of property IDs, the OPC server returns either a value or an error (like “property does not exist”) for each property. The command-line parameter for each property field includes a list of one or more property IDs. The first property ID in the list that has a value for a particular item is the value of the property field. That is, for each property field, OPCtoCSV checks the error code for the property IDs from left to right. The value of the first property with a “success” error code is the value for the corresponding field.
If the property value for a field is not a string, OPCtoCSV calls the Windows VariantChangeType function to convert the property value to a string representation. If the conversion fails, the field in the CSV file is empty (as if no property value is available for the field).
Installation
The OPCtoCSV tool does not have a separate setup kit. The OPCtoCSV tool is installed by the setup kits for OPC interfaces or PI AutoPointSync (APS) connectors for OPC. The new PI OPC Tools setup kit also installs the OPCtoCSV tool.
Note: OPCtoCSV is a new tool that is added to OPC interface and APS OPC connector setup kits when they release next. Setup kits that released before the first version of OPCtoCSV do not contain it.
Interface and Application Directories
Most OSIsoft interfaces and applications install under a common folder, which is created by the first OSIsoft setup kit that runs on a computer. The first OSIsoft setup kit also creates a system environment variable named PIHOME that is set to the path of the top-level directory for 32-bit PI clients. Because the path to the common folder can vary due to operating system, hardware configuration, or choices made while running the first OSIsoft setup kit, OSIsoft documentation refers to the common folder as PIHOME.
PIHOME Directory Tree
32-bit Applications
The [PIHOME] directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory.
For 32-bit operating systems, a typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=C:\Program Files\PIPC
For 64-bit operating systems, a typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=C:\Program Files (X86)\PIPC
The above lines define the root of the PIHOME directory on the C: drive. The PIHOME directory does not need to be on the C: drive. OSIsoft recommends using the paths shown above as the root PIHOME directory name.
OPCtoCSV Installation Directory
The setup kits automatically install the OPCtoCSV tool in folder
%PIHOME%\PI-OPC Tools\PI_OPCtoCSV\.
CSV Output File
This chapter describes the structure and contents of the comma-separated value (CSV) output file that OPCtoCSV creates. Because Excel is commonly used for viewing and revising tabular data, OPCtoCSV is specifically designed to create a CSV file that is readable by Excel.
CSV File Structure
This section contains the specifications for the structure of the CSV output file that OPCtoCSV creates. If you plan to write a program to read the CSV output file, this chapter provides information that you need to consider while designing and implementing your program.
A CSV file is a plain text representation of a table of data. Each line in the file corresponds to one row in the table.
Each line contains data fields separated by commas. The fields correspond to the columns in the table. All spaces in a field are literally part of the field value. Specifically, leading and trailing spaces are part of a field value. That is, an application that reads and parses a CSV file must not trim leading and trailing spaces in fields.
To use the data in a CSV file, the content of each field must be known. Like the heading of a table in a document, the first line in a CSV file can be a header line that identifies the contents of the fields. A header line makes the CSV file self-describing to humans or programs that read the CSV file. A header line also provides flexibility for each CSV file to have its own specific fields and field order.
Header Line
The first line in the CSV file contains a comma-separated list of field names in the same order as the corresponding comma-separated field values on the second and following lines.
The header line makes the CSV file self-describing. The header line also makes the CSV file acceptable for input to the PI Tag Configurator add-in for Excel and the GenericCSV_APS connector.
OPCtoCSV writes a combination of fixed and configurable fields into the output file. The specific fields are discussed in the “Fields in OPCtoCSV Output Files” section.
Value Lines
The second and following lines in the CSV file contain a comma-separated list of field values in the same order as the corresponding comma-separated field names on the header line.
Values Containing Comma or Double Quotation Mark
Because comma is the field delimiter, a field value that contains a comma requires special treatment. Literal commas can occur in any OPC property that has a string value, for example the OPC “description” property usually is allowed to contain any printable character. Some OPC servers permit commas in item and branch names, which are included in the CSV file. In countries that use comma as the decimal point, conversion of a numeric OPC property value to string can result in a comma in a field value.
OPCtoCSV uses the Excel convention for indicating that a field value contains a literal comma: the field value is enclosed in double quotation marks.
As a result of using double quotation mark for this purpose, double quotation mark in a field value also requires special treatment. Again, the Excel convention is used. Any double quotation mark in a field value is replaced by two consecutive double quotation marks and the field value is enclosed in double quotation marks.
For example, consider the following table:
|Tag |Descriptor |EngUnits |TypicalValue |
|SampleTag |TRIG=EVENT, comment |"Hg |12½ |
In this table, the Descriptor value contains a literal comma, the EngUnits value contains a literal double quotation mark, and the TypicalValue is a fractional number.
In a country that uses period as the decimal point, the CSV file representation of this table is:
Tag,Descriptor,EngUnits,TypicalValue
SampleTag,"TRIG=EVENT, comment","""Hg",12.5
In a country that uses comma as the decimal point, the CSV file representation of this table is:
Tag,Descriptor,EngUnits,TypicalValue
SampleTag,"TRIG=EVENT, comment","""Hg","12,5"
The Descriptor field in the CSV file is enclosed in double quotation marks because the Descriptor value contains a literal comma.
The EngUnits value contains a double quotation mark. Therefore, the corresponding field in the CSV file is enclosed in double quotation marks (the leading and trailing double quotation marks in the third field of the examples). The literal double quotation mark in the value is represented by two consecutive double quotation marks (the second and third double quotation marks in the third field of the examples).
The fourth field contains a numeric value with a fraction. The string representation of the number depends on the local conventions for representing the decimal point. Observe that the fourth field in the first CSV example is not enclosed in double quotation marks. In comparison, the fourth field in the second CSV example is enclosed in double quotation marks because the local convention for decimal point is comma.
Empty Fields and Zero-length Strings
An OPC server is not required to have a value for a particular property for all items. The absence of a property might be significant to an application that reads a CSV file from OPCtoCSV. For example, an application that updates PI points can decide not to edit an attribute if the corresponding OPC property has no value.
Although most general-purpose applications do not support the concept of a field that has no value, the objective of OPCtoCSV is to make a “no value” indication available for advanced (special-purpose) applications. However, the syntax chosen for a field with “no value” must not cause a general-purpose application to fail or perform illogically.
The intuitive representation of a field that has no value is an empty field. For example, the two consecutive commas indicate that the EngUnits field is empty in the second line in this example CSV file:
Tag,Descriptor,EngUnits,TypicalValue
SampleTag,description of SampleTag,,12.5
If a general-purpose application (like Excel) parses an empty field, the field value is a zero-length string. A zero-length string is a close approximation to “no value”, which satisfies one of the objectives.
If OPCtoCSV specifically uses an empty field to indicate “no value”, a different representation is needed for a property that has an actual zero-length string value. OPCtoCSV uses a pair of double quotation marks to indicate a zero-length string. The rationale for this design is that a field with a value from the OPC server, even a zero-length string, is never empty in the CSV file. Thus, a non-empty field is clearly a property value from the OPC server and an empty field indicates no property value from the OPC server.
For example, assume that the OPC server contains item “point1” that has no Descriptor property. Also, assume that the same OPC server contains item “point2” that has a Descriptor property with a zero-length string value. OPCtoCSV creates a CSV file that contains the following lines:
Select (x),Tag,Descriptor,InstrumentTag
x,point1,,point1
x,point2,"",point2
In the second line of this example CSV file, the Descriptor field for point1 is empty (no characters between the second and third commas), which indicates that the OPC server has no Descriptor property for point1.
In the third line of this example, the Descriptor field for point2 is an explicit zero-length string (the consecutive double quotation marks between the second and third commas), which indicates that the OPC server has a Descriptor property for point2 and the value is a zero-length string.
Although OPCtoCSV makes a distinction between the meanings of an empty field and a field containing two double quotations marks, most consumers of CSV files do not. General-purpose CSV consumer applications interpret both an empty field and a field containing two consecutive quotation marks as a zero-length string. The GenericCSV_APS connector is an exception.
Note: Excel does not distinguish between an empty field and a field containing two consecutive quotation marks. Excel interprets both cases as a zero-length string.
Fields in OPCtoCSV Output Files
In many cases, the CSV file from OPCtoCSV is expected to be input to either the PI Tag Configurator add-in for Excel or the GenericCSV_APS connector.
In the CSV output file, the first seven fields are fixed fields that are not configurable. Configurable fields follow the fixed fields. Command-line parameters specify the configurable fields that are included in the CSV file.
With one exception, the PI Tag Configurator add-in for Excel requires actual PI point attribute names for all fields in the CSV file. Three of the fixed fields are unacceptable to PI Tag Configurator due to the field name (BranchPath, Item, and CanonicalType). However, these fields are useful for filtering the point definitions or constructing values for PI point attributes, which is the reason that the fields are in the CSV file. Before you invoke a PI Tag Configurator command on a worksheet that was imported from a CSV file from OPCtoCSV, the unacceptable columns must be removed from the worksheet.
Fixed Fields
The first seven fields in the CSV output file are described in this section. These fields are not configurable because the field values are needed in the majority of applications for OPCtoCSV.
Select (x)
The PI Tag Configurator add-in for Excel requires a “Select (x)” field in column A of a compatible worksheet. To satisfy this requirement, “Select (x)” is the first fixed field in the CSV output file.
The field value is “x” for all items.
Note: “Select (x)” contains a single embedded space before the left parenthesis that is significant to the spelling. For example, “Select(x)” without the embedded space is not interpreted as the special “Select (x)” field.
Tag
All PI point configuration applications require a unique name (Tag attribute) for each PI point. The PI Tag Configurator add-in for Excel has a stronger requirement for a Tag field in column B of a compatible worksheet. To satisfy PI Tag Configurator, the second fixed field in the CSV output file is Tag. The GenericCSV_APS connector also requires a Tag field but does not require the Tag field in a specific ordinal position.
ItemIDs must be unique in the OPC server and are analogous to a PI point tag name. The default Tag field value for each OPC item is the ItemID.
Several punctuation characters are illegal in PI point tag names (Tag attribute). If an ItemID contains any of the illegal characters, OPCtoCSV replaces the illegal characters in the Tag field with the characters shown in the following table:
|Illegal Character |Replacement Character |
|* |@ |
|? |% |
|' " ` |^ |
|[ { |( |
|] } |) |
|| |! |
|\ |/ |
|; |: |
BranchPath
The BranchPath field contains the path to the branch that contains the item. The syntax of a branch path is server-specific. Therefore, the value of the BranchPath field contains server-specific delimiters between individual branches in the path.
In many OPC servers, the BranchPath field for items in the root of the OPC address space is a zero-length string.
The OPC standards do not require the branch path to be included in the ItemIDs of items in the branch. In fact, the OPC standards allow an item to appear in more than one branch, which means that there can be more than one branch path to the item.
Note: This field name is unacceptable to PI Tag Configurator. Remove the column containing this field before invoking PI Tag Configurator commands.
Item
While browsing the OPC address space, the name for an item in a branch is a short name that is not the unique ItemID. The Item field contains the short name for the item in the branch at the path in the BranchPath field. A short name is unique only within a branch. The same short name might exist in other branches and the two short names can represent different items.
Note: Item is not the unique ItemID.
To make an analogy with a computer file system, an ItemID is like a full path, which uniquely identifies a file in the file system. A short item name is like the name of a file in a folder. A file name in a folder is not necessarily unique in the file system because files with the same name can exist in different folders.
Note: This field name is unacceptable to PI Tag Configurator. Remove the column containing this field before invoking PI Tag Configurator commands.
CanonicalType
OPCtoCSV sets the CanonicalType field to the symbolic name for the Windows VARIANT type code in the canonical data type property of the item.
For example, an item that contains a 32-bit floating-point value has a canonical data type property value of 4. The CanonicalType field for this item is “VT_R4”, which is the symbolic name for VARIANT type code 4.
If the array bit is set in the VARIANT type code, the CanonicalType field value is “VT_ARRAY | ” concatenated with the symbolic name for the array element type. For example, the CanonicalType field is “VT_ARRAY | VT_I4” for an array of 32-bit integers.
If an item has an array data type, only one PI point definition is written to the CSV file.
Note: This field name is unacceptable to PI Tag Configurator. Remove the column containing this field before invoking PI Tag Configurator commands.
PointType
OPCtoCSV sets the PointType field to the symbolic name for a PI point data type that is suitable for the canonical data type of the item. The array bit in the VARIANT type code for the canonical data type is ignored. That is, the choice of PI point data type is based solely on the element type. The following table shows the PI point type for VARIANT type codes:
|VARIANT Type |PI point Type |
|VT_BOOL |int32 |
|VT_I1 | |
|VT_UI1 | |
|VT_I2 | |
|VT_UI2 | |
|VT_I4 | |
|VT_INT | |
|VT_UI4 |float32 |
|VT_UINT | |
|VT_R4 | |
|VT_I8 |float64 |
|VT_UI8 | |
|VT_R8 | |
|VT_BSTR |string |
|All other types |null |
InstrumentTag
OPCtoCSV sets the InstrumentTag field to the ItemID of the item.
PI points for the OPC DA interface and the OPC HDA interface are configured by storing the ItemID for the source item in the InstrumentTag attribute. This field supplies the InstrumentTag attribute for PI points for either interface.
Configurable Fields
The fixed fields can be followed by configurable fields. The configurable fields are specified by the /fields switch in the command-line parameters. Each configurable field is either a constant field or a property field.
When a CSV file is imported into Excel, the fields become columns and the field names become column names. Except for the “Select (x)” field, the PI Tag Configurator add-in for Excel requires column names to be PI point attribute names. If a configurable field is defined such that the field value is the value for a PI point attribute, assign the PI point attribute name to the configurable field. Any configurable field with a name that is not a PI point attribute name must be removed from the worksheet before PI Tag Configurator operations can be performed.
Constant Fields
A constant field has the same value for every item. For example, most interfaces use the PointSource attribute to identify the PI points that the interface manages. A constant field named PointSource can set the PointSource attribute for every PI point definition in the CSV file.
Property Fields
The value for a property field is obtained from the properties of an item. The command-line parameter for each property field includes a list of one or more property IDs. The first property ID in the list that has a value for a particular item is the value of the property field. If the property value is not a string, OPCtoCSV calls VariantChangeType to convert the value to a string representation. If the conversion fails, the field value is empty (as if the property does not exist for the item). Integer and floating point types usually convert. Arrays do not convert.
Some OPC servers have property values that are type VT_CY. The VT_CY type is intended to represent monetary values. A VT_CY value is a fixed-point number with four digits after an implied decimal point that is scaled and stored as a 64-bit integer. When VariantChangeType converts a VT_CY value to string, the string representation is an integer. To account for the implied decimal point, divide the integer by 10000. That is, “123456” actually represents 12.3456 (using dot to indicate the decimal point), “123” represents 0.0123, and so forth.
Some OPC servers have property values that are type VT_FILETIME. A VT_FILETIME value is a 64-bit integer that contains the number of 100-nanosecond intervals since January 1, 1601 in Universal Coordinated Time (UTC). When VariantChangeType converts a VT_FILETIME value to a string, the result is a large integer (not a date and time representation).
Default Property Fields for DA
If the /fields switch is not in the command-line parameters and the OPC server is a DA server, OPCtoCSV includes property fields for the DA properties that the OPCInt_APS connector uses to calculate attributes for PI points. The default property fields include all of the properties from the Data Access Custom Interface Standard that correspond to PI point attributes (see the “Property IDs in the DA Standard” section). However, the Data Access Custom Interface Standard does not require an OPC server to implement properties. In fact, the majority of OPC DA servers do not implement the properties that are useful for PI point attributes.
The default property fields for DA properties are EngUnits, Descriptor, MinValue, and MaxValue.
EngUnits
The EngUnits field value is assigned from property ID 100.
Descriptor
The Descriptor field value is assigned from property ID 101.
MinValue
The MinValue field value is assigned from property ID 103 or 105.
The range of values of an OPC item is indicated by recommended properties for minimum and maximum value. In contrast, PI points have a Zero and Span attribute. In most cases, the minimum property is the appropriate Zero attribute value.
This field is named MinValue instead of Zero to emphasize that MaxValue and MinValue are needed to calculate the Span attribute.
Note: This field name is unacceptable to PI Tag Configurator. Remove or rename the column containing this field before invoking PI Tag Configurator commands.
MaxValue
The MaxValue field value is assigned from property ID 102 or 104.
The range of values of an OPC item is indicated by recommended properties for minimum and maximum value. In contrast, PI points have a Zero and Span attribute. In most cases, the difference between the maximum and minimum properties is the appropriate Span attribute value.
This field is named MaxValue because no PI point attribute contains maximum value.
Note: This field name is unacceptable to PI Tag Configurator. Remove the column containing this field before invoking PI Tag Configurator commands.
Default Property Fields for HDA
If the /fields switch is not in the command-line parameters and the OPC server is an HDA server, OPCtoCSV includes property fields for the HDA properties (attributes) that the OPCHDAInt_APS connector uses to calculate attributes for PI points. The default property fields include all of the properties from the OPC Historical Data Access Specification that correspond to PI point attributes (see the “Attribute IDs in the HDA Standard” section). However, the OPC Historical Data Access Specification does not require an OPC server to implement properties. In fact, many OPC HDA servers do not implement the properties that are useful for PI point attributes.
The default fields for HDA attributes are Descriptor, EngUnits, MinValue, MaxValue, Step, CompMin, CompMax, and Archiving.
Descriptor
The Descriptor field value is assigned from property ID 0x2.
EngUnits
The EngUnits field value is assigned from property ID 0x3.
MinValue
The MinValue field value is assigned from property ID 0x0c or 0x13.
The range of values of an OPC item is indicated by recommended properties for minimum and maximum value. In contrast, PI points have a Zero and Span attribute. In most cases, the minimum property is the appropriate Zero attribute value.
This field is named MinValue instead of Zero to emphasize that MaxValue and MinValue are needed to calculate the Span attribute.
Note: This field is unacceptable to PI Tag Configurator. Remove or rename the column containing this field before invoking PI Tag Configurator commands.
MaxValue
The MaxValue field value is assigned from property ID 0x0b or 0x12.
The range of values of an OPC item is indicated by recommended properties for minimum and maximum value. In contrast, PI points have a Zero and Span attribute. In most cases, the difference between the maximum and minimum properties is the appropriate Span attribute value.
This field is named MaxValue because no PI point attribute contains maximum value.
Note: This field is unacceptable to PI Tag Configurator. Remove the column containing this field before invoking PI Tag Configurator commands.
Step
The Step field value is assigned from property ID 0x4.
CompMin
The CompMin field value is assigned from property ID 0x0f.
CompMax
The CompMax field value is assigned from property ID 0x0e.
Archiving
The Archiving field value is assigned from property ID 0x5.
Parsing Lines into Fields
If you write a program to read the CSV file, this section explains how to parse lines into fields.
The first character on each line is the start of the first field.
If the first character of a field is not a double quotation mark ("), the field extends up to (but not including) the next comma or end of line.
If the first character of a field is a double quotation mark, the field value begins with the character following the double quotation mark. The initial segment of the field extends up to (but not including) the next double quotation mark that is not followed immediately by another double quotation mark.
In the text between the opening and closing quotation marks, commas are a literal part of the field value (that is, not interpreted as field separators) and each pair of double quotation marks indicates a single double quotation mark that is a literal part of the field value.
Any text following the closing double quotation mark up to the next comma or end of line is also part of the field value. That is, following the closing double quotation mark, any double quotation marks are a literal part of the field value and do not begin a new quoted segment.
Note: A double quotation mark must be the first character on a line or immediately follow an end of field comma to be treated as the beginning of a quoted segment.
All spaces are included in the field values. In particular, leading and trailing spaces are not trimmed.
In OPCtoCSV output files, a field that contains a comma or double quotation mark is enclosed in double quotation marks as described earlier. That is, a field is either unquoted (in which case the field does not contain comma or literal double quotation marks) or the entire field is quoted (no field text follows the closing double quotation mark).
Fields with no value
The general syntax for CSV files has two representations for an “empty” field. One representation is a field that immediately ends with either a comma field delimiter or end of line, which is an implicit field delimiter for the last field. The other representation is a field that contains only two consecutive double quotation marks. Most applications that accept CSV input interpret both representations as zero-length strings.
Because every item is not guaranteed to have a particular property, an application that uses the property fields from the CSV file might want to conditionally perform an operation on items that have a particular property and do nothing for items that do not have the property. Therefore, OPCtoCSV makes use of the two representations to convey additional information to an application that is designed to distinguish between the two representations.
If the value for a field is a zero-length string, OPCtoCSV writes a field containing only two consecutive double quotations marks (that is, an explicit zero-length string). If an item does not have a property to provide the value for a field, the field is immediately ended with a field delimiter (comma or end of line). The following contrived example shows how OPCtoCSV represents fields with no values:
Field1,Field2,Field3,Field4
,value2,"",
v1,,,""
In the second line, no value is available for Field1 and Field4. Field3, however, has a value that is a zero-length string.
In the third line, no value is available for Field2 or Field3 and the value for Field4 is a zero-length string.
Running OPCtoCSV
OPCtoCSV is intended to be the first step in an automated or semi-automated process that maintains PI points for the OPC DA or OPC HDA interfaces. Therefore, OPCtoCSV is a command-line program. That is, OPCtoCSV does not have a graphical user interface.
Note: You cannot run OPCtoCSV by double-clicking on the application in Windows Explorer.
Grammar for Command Syntax
This document uses the Microsoft conventions for describing command syntax:
• Items in bold must be entered exactly as shown.
• Italicized items are placeholders for specific information that you supply.
• Vertical bar | separates items in a mutually exclusive list.
• Square brackets [ ] surround optional items or an optional mutually exclusive list.
• Curly braces { } surround a mutually exclusive list where one item from the list is required.
• Ellipsis … indicates that repetition of the previous element is permitted.
Built-in Help
OPCtoCSV has a built-in quick reference guide. The command syntax for invoking OPCtoCSV to display a command syntax summary and the quick reference is:
OPCtoCSV [ /? | /help ]
If OPCtoCSV is invoked with no parameters or the first parameter is /? or /help, the tool writes a command syntax summary and the quick reference to the command window.
OPCtoCSV Command Syntax
To facilitate automation, OPCtoCSV is a non-interactive command-line program. The command syntax for invoking OPCtoCSV to export OPC items as PI point definitions is:
OPCtoCSV [ OPChostName ] OPCserverID [ /da | /hda ]
[ /file filename ]
[ /fields { name(propertyID[,propertyID ...]) |
name=constant } ... ]
[ /pausegroup numItems ] [ /pausetime milliseconds ]
[ /path subbranchPath | /down branchName ... ]
OPCserverID is a required parameter and all other switches are optional. The switches and parameters in the command syntax are:
OPChostName
If the OPC server is on the local computer, omit this optional parameter.
If the OPC server is not on the local computer, the first parameter on the command line must be the host name of the computer where the OPC server is located. Using a remote OPC server requires DCOM configuration. Follow the instructions in the DCOM Configuration Guide for configuring DCOM on this computer as if it were an OPC interface node. DCOM settings on the OPC server node also might require changes to permit this computer to connect.
OPCserverID
OPCserverID is a required parameter that is the registered COM programmatic identifier (ProgID) of the OPC server.
/da or /hda
OPCtoCSV queries the OPC server to determine whether the OPC server implements DA, HDA, or both. If the OPC server implements only one, OPCtoCSV explores the OPC address space and, for each item, writes a PI point definition to the CSV file. If the OPC server implements both DA and HDA, the DA address space is explored and exported by default. The /hda switch causes OPCtoCSV to explore and export the HDA address space. The /da switch is generally not needed but can be used to ensure that only the DA address space is explored and exported.
/file
The /file switch is followed by the name of the CSV file. The filename can be an absolute or relative path. If the /file switch is not specified, the default CSV file name is Points_for_OPCserverID.csv, which is created in the current working directory.
/fields
The values in a CSV file are referred to as fields, which are like columns in a table or spreadsheet. The first line in the CSV file is a header line that contains the names of the data fields on the remaining lines in the file. OPCtoCSV creates seven fixed fields followed by configurable fields for other point attributes. The values of the seven fixed fields for each item are explained in the “Fields in OPCtoCSV Output Files” section in Chapter 4 and in the “Exporting PI Point Definitions” section in Chapter 2.
Configurable fields are specified by the /fields switch. The /fields switch is followed by one or more parameters of the form
name(propertyID[,propertyID ...])
or
name=constant
The first form defines a property field and the second form defines a constant field.
The name is the field name for the header line. For simple integration with PI Tag Configurator or the GenericCSV_APS connector, use PI point attribute names for field names. The field name is followed by either
• a parenthesized list of OPC DA property IDs or HDA attribute IDs, or
• an equal mark and a constant value.
For a property field, the property IDs can be expressed in decimal, hexadecimal (0x123abc notation), or octal (0123 notation). The “OPC Properties” appendix lists the OPC standard property IDs and contains suggestions for determining vendor-specific property IDs.
OPCtoCSV fills the property field for each PI point definition with the first OPC DA property or HDA attribute in the list that has a value. An OPC server is not required to provide the same set of properties for every item. If a property field has more than one propertyID, the order of the propertyIDs is the order that OPCtoCSV uses to fill the field value for each item. For example, MinValue(103,105) indicates that property 103 is the first choice for the MinValue field. If property 103 does not exist for an item, property 105 is the second choice for the MinValue field. If an item does not have either property 103 or 105, the MinValue field is empty in the CSV file.
The name=constant form creates a field that has the same value for all PI points for an interface, like PointSource or Location1.
If the /fields switch is not used, OPCtoCSV provides a default set of configurable fields that is appropriate for the OPC server. The default configurable fields include property fields for the properties that the OPCInt_APS or OPCHDAInt_APS connector uses to calculate attributes for PI points.
The default configurable fields for DA are equivalent to:
/fields EngUnits(100) Descriptor(101) MinValue(103,105) MaxValue(102,104)
The default configurable fields for HDA are equivalent to:
/fields Descriptor(0x2) EngUnits(0x3) MinValue(0x0c,0x13) MaxValue(0x0b,0x12) Step(0x4) CompMin(0x0f) CompMax(0x0e) Archiving(0x5)
/pausegroup and /pausetime
OPCtoCSV runs at reduced priority but otherwise runs as fast as resources allow. Some OPC servers are not designed for browsing by an automated program like this tool. That is, program-driven browsing can overwhelm some OPC servers and adversely affect the responsiveness of the OPC server to all clients. OPCtoCSV provides two switches that slow the rate of calls to the OPC server: /pausegroup and /pausetime. If these switches are not used, OPCtoCSV does not reduce the rate of calls to the OPC server. If one or both of the /pausegroup and /pausetime switches is used, OPCtoCSV suspends for the number of milliseconds following the /pausetime switch after browsing the number of items following the /pausegroup switch. If only one of these switches is used, the default parameter for /pausegroup is 1 item and the default parameter for /pausetime is 100 milliseconds.
/path or /down
Exploration starts at the root of the OPC address space hierarchy unless one of the optional /path or /down switches specifies a subbranch as the starting point. This program recursively explores all subbranches below the starting point.
The /path switch is followed by a subbranch path specified in the syntax of the OPC server. APS_OPCexplorer makes a single ChangeBrowsePosition(direction,subbranchPath) call to the OPC server, where direction is OPC_BROWSE_TO for DA or OPCHDA_BROWSE_DIRECT for HDA. Unless this call fails, exploration begins at this subbranch.
The /down switch is followed by a list of one or more branchNames. For each branchName, left to right, APS_OPCexplorer calls ChangeBrowsePosition(direction,branchName), where direction is OPC_BROWSE_DOWN for DA or OPCHDA_BROWSE_DOWN for HDA. Unless one of the calls fails, exploration begins in the final branch in the list.
Priority Reduction
To reduce the impact that OPCtoCSV can have on other applications, OPCtoCSV reduces its priority. That is, OPCtoCSV runs only when the CPU has idle time. As mentioned in the discussion of the /pausegroup and /pausetime switches, priority reduction is not sufficient to prevent OPCtoCSV from overwhelming some OPC servers. If the OPC server cannot support an automated browsing application, use the /pausegroup and /pausetime switches to make OPCtoCSV behave more like an interactive client.
Output to Command Window
As OPCtoCSV runs, it writes the OPC branch and item hierarchy to error output as a progress indicator. The error output defaults to the command window.
Error Messages
If OPCtoCSV calls an OPC method that returns an error code, OPCtoCSV attempts to get a description for the error code. The error code and description are reported on error output. Unless error output is redirected, error output is the command window for an interactive command. If OPCtoCSV is executed by a non-interactive application (like the APS Synchronization Engine service), error output is the null device.
Some error codes are actually warnings. OPCtoCSV reports warning codes and continues exporting items. For unexpected error codes, OPCtoCSV reports the error and terminates with a non-zero exit code.
Exit Code
OPCtoCSV sets the exit code to indicate success or failure:
• 0: Success
• 1: Fatal error
• 2: Interrupted by CTRL+C
Terminating Before Completion
If the OPC server contains a large number of items, OPCtoCSV can run for a long time and create a large CSV file. Type CTRL+C in the command window where OPCtoCSV is running to cause the program to cleanly disconnect from the OPC server, close the CSV file, and terminate. If the program is terminated early, all items in the OPC server are not exported to the CSV file.
Using with PI Tag Configurator
The main consideration for using a CSV file from OPCtoCSV with PI Tag Configurator is that the names of several fixed fields and default configurable fields are unacceptable to PI Tag Configurator. Before PI Tag Configurator commands can be performed, the columns with unacceptable names must be removed or renamed.
The general steps for using OPCtoCSV and PI Tag Configurator to maintain PI points are:
1. Run OPCtoCSV to export OPC item properties (see the “Running OPCtoCSV” chapter).
2. Open Excel.
3. On the File tab, click Open.
4. Select Text Files (*.prn;*.txt;*.csv).
5. Browse to the folder containing the CSV file from OPCtoCSV.
6. Select the CSV file.
7. Click OK.
8. Revise the worksheet. For example, subtract the MinValue column from the MaxValue column to calculate Span.
9. Remove or rename any columns that are unacceptable to PI Tag Configurator.
10. Export the PI point definitions in the worksheet to the PI Server.
As the revisions to the worksheet become routine, you can record your revisions as Excel macros to reuse in subsequent PI point maintenance sessions.
Specific Considerations
Keep the following issues in mind when you revise the worksheet.
Configurable Fields
Any configurable field with a name that is not a PI point attribute name must be removed from the worksheet before PI Tag Configurator operations can be performed. If possible and sensible, assign valid PI point attribute names to configurable fields created with command parameters.
Empty Cells
When a CSV file is imported, Excel does not differentiate between a field with no value and a field with a zero-length string. Both cases result in an empty cell in the worksheet.
Note: Excel does not distinguish between an empty field and a field containing two consecutive quotation marks.
Point Creation
PI Tag Configurator does not require a worksheet to contain columns for all supported PI point attributes because data sources rarely provide values for the entire set of supported attributes. If a CSV file does not contain a field for an attribute, the worksheet will not contain a column for the attribute. If the worksheet is exported to the PI Server to create PI points, the default value from the PI Server is used for missing attributes.
Zero and Span from MinValue and MaxValue
The MinValue and MaxValue default property fields can be transformed into columns for the Zero and Span attributes as follows:
1. Create a new column for Span. Use an Excel formula in the new Span column to calculate MaxValue minus MinValue.
1. Delete the MaxValue column.
2. Rename the MinValue column to Zero.
Unacceptable Columns
The columns for fixed fields BranchPath, Item, and CanonicalType can be useful for filtering, constructing Tag name, constructing other attributes, or overriding the default PointType. Because these columns do not have PI point attribute names, these columns cannot be exported to the PI Server. After using BranchPath, Item, and CanonicalType, delete these columns from the worksheet before exporting the PI point definitions to the PI Server.
Similarly, columns for configurable fields (like the default MinValue and MaxValue fields) might not have PI point attribute names. These columns must also be deleted before exporting the worksheet.
Note: PI Tag Configurator does not recognize BranchPath, Item, CanonicalType, MinValue, or MaxValue. After opening a CSV file with Excel, the columns with these names must be deleted to make the worksheet acceptable to PI Tag Configurator.
Using with GenericCSV_APS Connector
OPCInt_APS and OPCHDAInt_APS connectors are available for the OPC DA and OPC HDA interfaces, respectively. These APS connectors are designed for “generic” OPC servers. That is, the OPCInt_APS and OPCHDAInt_APS connectors use only properties and features that are required or recommended by the OPC standards. The OPCInt_APS and OPCHDAInt_APS connectors do not contain vendor-specific features.
Many of the enhancement requests for OPCInt_APS and OPCHDAInt_APS connectors are for either vendor-specific or site-specific features. The OPCInt_APS and OPCHDAInt_APS connectors are not programmable to the extent necessary for a user to customize them to obtain the requested functionality. This chapter discusses how you can use OPCtoCSV with the GenericCSV_APS connector as an alternative to the OPCInt_APS or OPCHDAInt_APS connector. The significant difference is that the OPCtoCSV and GenericCSV_APS combination produces an intermediate CSV file that you can revise before APS synchronizes PI points. That is, you have the opportunity to apply vendor-specific or site-specific knowledge to customize the PI point definitions for your particular requirements.
OPCtoCSV is the OPC-facing side of the OPC APS connectors packaged as a self-contained program. Instead of returning PI point definitions directly to the APS Synchronization Engine, OPCtoCSV writes the PI point definitions to a CSV file, which is accessible to users for revision.
GenericCSV_APS is a general-purpose APS connector. Instead of being coded with the API for a specific data source, GenericCSV_APS reads PI point definitions from a CSV file.
Together, OPCtoCSV and GenericCSV_APS are essentially equivalent to the OPCInt_APS connector or OPCHDAInt_APS connector, as shown in the following figure for an OPC DA server.
[pic]
PI APS Alternatives for OPC DA Server
Advantages and Disadvantages
The OPCtoCSV and GenericCSV_APS combination is not as easy to implement as the native OPCInt_APS and OPCHDAInt_APS connectors. Therefore, the combination is only recommended when there is a clear advantage that justifies the extra effort.
The main advantage for using the OPCtoCSV and GenericCSV_APS combination is that you can develop a custom application to revise the CSV file. For example, a custom application can do any of the following and more:
• Implement a custom tag naming scheme
• Implement custom filtering of OPC items (remove items)
• Apply calculations to OPC properties (like scaling)
• Add fields for attributes
If the custom application is written as a non-interactive program, you can integrate the GenericCSV_APS connector, OPCtoCSV, and the custom application into the APS framework for automatic PI point synchronization.
HDA
Unless you plan to develop a custom application to revise the CSV file, there is no advantage to using OPCtoCSV and the GenericCSV_APS connector instead of the OPCHDAInt_APS connector.
DA
The GenericCSV_APS connector offers the following features that are not available in the OPCInt_APS connector:
• Tag Selection
• Tag Naming
• Attribute Formulas
If you need any of these features, use the OPCtoCSV and GenericCSV_APS combination instead of the OPCInt_APS connector.
GenericCSV_APS Input Files
A CSV file from OPCtoCSV is an acceptable input file for the GenericCSV_APS connector.
The primary requirement of the GenericCSV_APS connector is that the CSV input file must contain Tag and InstrumentTag fields. The OPCtoCSV Tag and InstrumentTag fixed fields satisfy this requirement.
The GenericCSV_APS connector supports fields with the names of almost all of the attributes in the classic point class and several other special field names. The GenericCSV_APS connector uses fields from the CSV file whose names are:
• One of the names in the “CSV File Field Name” column of the table in the “Supported PI Point Attributes” section of the PI AutoPointSync Connector for Comma-separated Values (CSV) Files user manual.
• Select (x)
• Delete (x)
• MinValue
• MaxValue
• PointSource
• Location1
The GenericCSV_APS connector silently ignores any field that has an unrecognized name. Therefore, the GenericCSV_APS connector ignores the OPCtoCSV BranchPath, Item, and CanonicalType fixed fields.
The GenericCSV_APS connector does not require a CSV file to contain fields for all supported PI point attributes because data sources rarely provide values for the entire set of supported attributes. If a CSV file does not contain a field for an attribute, the Attribute Formulas feature can be used to generate values for attributes.
If GenericCSV_APS does not return a value for an attribute to the APS Synchronization Engine, a default value is assigned for new points or the attribute is not edited for existing points. APS has configuration settings that specify default values for certain attributes; attributes without APS defaults obtain their default values from the PI Server configuration. The default values are listed in the table in the “Supported PI Point Attributes” section in the PI AutoPointSync Connector for Comma-separated Values (CSV) Files user manual.
GenericCSV_APS uses the same syntax as OPCtoCSV to distinguish a field with no value from a zero-length string. Therefore, if an item has no property, the corresponding attribute for the PI point in the GenericCSV_APS connector is handled as a missing attribute. If APS creates a PI point for the item, either APS or the PI Server assigns a default value to the missing attribute. If APS edits a PI point for the item, the PI point attribute is not changed.
The GenericCSV_APS connector does not require a “Select (x)” field or that it is the first field. If a “Select (x)” field appears anywhere in the header line, the GenericCSV_APS connector uses it. If “Select (x)” is not a named field in a CSV file, the GenericCSV_APS connector treats each data line in the CSV file as if it were selected.
The GenericCSV_APS connector recognizes that most data sources commonly provide attributes that contain the normal low and normal high values for the point but do not provide an attribute that is equivalent to the PI point Span attribute. GenericCSV_APS supports data sources that provide normal low and high attributes by accepting field names MinValue and MaxValue that contain the normal low and high values for a point. If a line in a CSV file does not contain values for Zero and Span (or the CSV file does not contain Zero and Span fields at all) and does contain values for MinValue and MaxValue, GenericCSV_APS assigns MinValue to Zero and calculates Span by subtracting MinValue from MaxValue. GenericCSV_APS will use the OPCtoCSV default property fields MinValue and MaxValue for this purpose. If you use the OPCtoCSV /fields switch to override the defaults and the OPC server has minimum and maximum properties for items, include MinValue and MaxValue property fields in your configurable fields.
The GenericCSV_APS connector supports PointSource and Location1 fields in the Tag Filtering, Tag Naming, and Attribute Formulas features. APS obtains the PointSource and instance ID values for an interface instance from its PI ICU configuration. APS uses these attributes and the values from PI ICU to identify the existing points for an interface instance. If APS creates a point for the interface instance, the values from PI ICU are assigned to the PointSource and Location1 attributes of the new points.
Configuring GenericCSV_APS to Replace an OPC APS Connector
The general steps for registering an OPC interface with APS are the same for the native OPC APS connectors and the GenericCSV_APS connector. Follow the guidelines in the “Registering an Interface Instance with PI APS” chapter in the PI AutoPointSync Connector for Comma-separated Values (CSV) Files user manual. This section focuses on the specific configuration for using OPCtoCSV to produce the CSV input file.
The GenericCSV_APS connector has a feature to run a program or script to create the input CSV file. Because the GenericCSV_APS connector is loaded into the APS Synchronization Engine process and the Synchronization Engine usually runs under the Local System account, which has administrative privileges, the GenericCSV_APS connector requires another account for running the application that creates the input CSV file. For security reasons, the recommendation is to use a less privileged account so that the application does not have administrative privileges. Choose or create an account that GenericCSV_APS can use to run OPCtoCSV.
The child process that is created to run OPCtoCSV inherits the working directory from the Synchronization Engine. Because the Synchronization Engine usually runs as a service, the working directory is %windir%\system32. Therefore, relative paths are discouraged in the GenericCSV_APS configuration boxes.
If the OPC server is on a remote node, DCOM configuration is usually necessary. DCOM configuration is discussed in the DCOM Configuration Guide. Log in to the account chosen for GenericCSV_APS to run OPCtoCSV. Confirm that OPCtoCSV runs interactively under this account. If connection problems occur, correct the DCOM configuration before proceeding.
Choose or create a folder for the CSV file. For the examples in this section, C:\ProgramData\OPCtoCSV was created. The folder can be in any parent folder that is appropriate for data files. Protected folders (like “\Program Files” on Windows Vista or later) are discouraged. The account chosen for GenericCSV_APS to run OPCtoCSV must have permission to create new files or write existing files in this folder.
The following list contains the steps to configure APS to use GenericCSV_APS and OPCtoCSV to synchronize points for an OPC interface. The first 11 steps are a checklist for tasks that are explained in the “Registering an Interface Instance with PI APS” chapter in the PI AutoPointSync Connector for Comma-separated Values (CSV) Files user manual. The remaining steps are explained in more detail.
1. If the OPC interface is not configured with PI ICU, add the interface to ICU.
2. In the APS Configuration Utility, click Register on the tool bar, which opens the Configure Interface or COM Connector for PI APS dialog box.
3. Choose GenericCSV_APS (Unspecified) in the Select APS Connector box.
4. Choose the PI Server for the interface in the Select PI server host box.
5. Choose the OPC interface in the Select an interface box.
6. Click OK to register the interface with APS.
7. Click Close to close the Configure Interface or COM Connector for PI APS dialog box.
8. Select the new OPC interface in the Interface box.
9. On the Settings menu, click Rules… . On the Rules for interface dialog box, the Store as options are recommended for testing APS operation. After you have reviewed several synchronization scans and verified that the available points and point edits are correct, then you can change the APS rules to automatic options.
10. On the Settings menu, click Sync Schedule… and configure the options on the Synchronization Schedule for interface dialog box.
11. On the Settings menu, click User-set Defaults… and configure the options on all four tabs in the User-set defaults for interface dialog box.
12. On the Settings menu, click Connector-specific… to open the PI APS Connector Control dialog box.
13. Click the More Options tab.
14. Enter the full path for OPCtoCSV.exe in the Command box.
15. Enter command-line parameters in the Parameters box (see the “OPCtoCSV Command Syntax” section for more information).
The programmatic identifier for the OPC server is required in the Parameters box. If the OPC server is on a remote node, the remote node name is also required in the Parameters box.
The /file switch with a full path is required. Use the folder that was chosen earlier for this purpose.
Note: The error output from OPCtoCSV cannot be captured with this configuration.
The GenericCSV_APS connector does not support Windows redirection operators in the Parameters box. If you want to redirect error output from OPCtoCSV into a file, create a batch script that runs OPCtoCSV with redirected error output and enter the path to the batch script in the Command box.
The following figure shows the partially-completed More Options tab.
[pic]
16. To complete the configuration of the More Options tab, enter the account that was chosen earlier in the Run as User box. Enter the password for this account in the Password and Re-enter Password boxes.
17. Select the full path following the /file switch. Type CTRL+C to copy the path to the clipboard.
18. Click the Input Files tab.
19. Click in the CSV-format input file(s) box in the Full-export Files area.
20. Type CTRL+V to paste the CSV file path. If the path is enclosed in quotation marks, remove the quotation marks in this box.
21. Clear the Delete input file after each synchronization box.
22. Confirm that the Excel option is selected in the Syntax for literal quotation marks area.
The following figure shows the completed Input Files tab.
[pic]
23. Optionally, click the Attribute Formulas tab and configure attribute formulas.
24. Click OK to save the configuration and close the dialog box.
25. Run a synchronization scan and review the APS log files.
Revising the CSV File Before Synchronization
If you write an application to revise the CSV file before synchronization, you can integrate your application into the APS framework. If you follow the guidelines in this section, your application will execute under the account specified in the GenericCSV_APS options. If the folder containing the application or the application file is writable by other accounts, users running under the other accounts can use a Trojan horse security attack to gain the privileges of the account specified in the GenericCSV_APS options. Therefore, both the folder and application file must not be writable by other accounts.
Begin by creating a batch script (a .bat file) in a protected folder. Because this batch script will execute under the account specified in the GenericCSV_APS options, the batch script is vulnerable to Trojan horse security attacks unless the folder containing the batch script and the .bat file itself are not writable by other accounts.
The .bat file can be as simple as two commands. The first command runs OPCtoCSV to create a CSV file. The second command runs your application, which reads the CSV file from OPCtoCSV and creates a second CSV file. However, the actual .bat file probably will contain more commands.
The GenericCSV_APS connector checks the exit status code from the batch script. GenericCSV_APS interprets exit status 0 as successful and any other exit status code as failure. If the batch script returns a non-zero exit status code, GenericCSV_APS reports the application failure and does not attempt to synchronize. Therefore, the batch script must return exit code 0 when the input file for GenericCSV_APS is successfully created by the batch script.
For example, assume that a program named ReviseCSV was developed to perform customized processing of the PI point definitions written by OPCtoCSV. The ReviseCSV application has command-line switches /in and /out that specify the input and output file paths. The .bat file for this example is:
REM example batch script for custom processing
REM
REM Change working directory to simplify parameters:
cd \ProgramData\OPCtoCSV
REM Export OPC items from local OPC server OSI.DA.1.
REM Add /fields parameter or other optional parameters.
REM Redirect error output to catch any messages.
"%PIHOME%\PI-OPC Tools\PI_OPCtoCSV\OPCtoCSV" OSI.DA.1 ^
/file PointsFromOPC.csv 2>OPCtoCSV.log
REM Check for successful completion before continuing.
if ERRORLEVEL 1 exit 1
REM apply custom processing
%REVISECSVPATH%\ReviseCSV /in PointsFromOPC.csv ^
/out PointsForAPS.csv
1. On the Settings menu in the APS Configuration Utility, click Connector-specific… to open the PI APS Connector Control dialog box.
26. Click the More Options tab.
27. Enter the full path for the batch script in the Command box.
28. The Parameters box is empty because the example script does not have parameters. Parameters for the OPCtoCSV tool are in the batch script.
29. Enter the account to run the batch script in the Run as User box and the password for this account in the Password and Re-enter Password boxes.
30. Click the Input Files tab.
31. In the CSV-format input file(s) box in the Full-export Files area, enter the full path to the output file that the batch script creates. In the example script, the path is \ProgramData\OPCtoCSV\PointsForAPS.csv.
32. Click OK to save the configuration and close the dialog box.
33. Click Rules… on the Settings menu. Choose the Store as options.
34. Run a synchronization scan and review the APS log files.
A. Error and Informational Messages
OPCtoCSV writes informational, warning, and error messages to error output.
If you run OPCtoCSV in a command window, the default error output is the command window.
If OPCtoCSV is executed in a non-interactive context (such as from a Windows service), the default error output is usually the null device. That is, error output is not stored or displayed.
To change the default standard error output to a file, use the Windows redirection operator 2>:
OPCtoCSV OPCserverID parameters 2>ErrorOutputFile
The ErrorOutputFile file can be a full path.
If OPCtoCSV is integrated into the APS framework with the GenericCSV_APS connector (as presented in the “Revising the CSV File Before Synchronization” section), OPCtoCSV is executed by the APS Synchronization Engine, which is a Windows service and runs in a non-interactive context. OSIsoft recommends redirection of error output in the batch file that runs OPCtoCSV.
B. OPC Properties
This appendix contains the OPC DA property IDs and OPC HDA attribute IDs that are defined in the respective standards.
Note: The OPC standards only recommend that OPC servers implement the DA property IDs or HDA attribute IDs in the standards. Because the OPC standards do not require an OPC server to implement the standard IDs, the standard IDs are not supported by every OPC server.
Unless the documentation for a specific OPC server lists the supported property IDs, a tool that queries the OPC server for properties is necessary to determine the supported property IDs. This appendix also describes APS_OPCexplorer, which is a tool that shows the property IDs in a specific OPC server. APS_OPCexplorer works with OPC DA or HDA servers.
Property IDs in the DA Standard
The following tables are derived from section 4.4.6 in the Data Access Custom Interface Standard. The OPC DA properties are categorized into three sets.
ID Set 1 contains OPC-specific properties. These properties provide an alternative method for accessing Item information that is normally obtained by other OPC methods. The property interface is simpler to program, is limited to one item per call, and is not intended for repetitively reading.
|ID |Property Description |
|1 |“Canonical” or “Native” data type of the item. This property contains the Windows VARIANT |
| |type code for the data type. |
|2 |Item value |
|3 |Item quality as an integer |
|4 |Timestamp |
|5 |Access rights as an integer (0=No access, 1=Read, 2=Write, 3=Read/Write) |
|6 |OPC server scan rate in milliseconds. |
|7-99 |Reserved by the OPC Foundation |
ID Set 2 contains recommended properties for additional information. The standard states “Servers which provide the corresponding properties must do so using the ID codes from this list.” However, some OPC servers use vendor-specific IDs instead of the IDs in the following tables.
Properties related to the item value
|ID |Property Description |
|100 |Engineering units |
|101 |Description |
|102 |Highest normal value |
|103 |Lowest normal value |
|104 |Highest possible instrument reading |
|105 |Lowest possible instrument reading |
|106 |String label when item value is zero (typically used for boolean items) |
|107 |String label when item value is non-zero (typically used for boolean items) |
|108 |Time difference in minutes between UTC timestamp and local time |
|109-199 |Reserved by the OPC Foundation |
Properties related to the operator displays
|ID |Property Description |
|200 |Name of the default operator display for this item |
|201 |Foreground color |
|202 |Background color |
|203 |Blinking |
|204 |.bmp file name |
|205 |Sound file name |
|206 |HTML file |
|207 |.avi file |
|208-299 |Reserved by the OPC Foundation |
Properties related to alarms and events
|ID |Property Description |
|300 |Current alarm or condition status |
|301 |Brief instructions for responding to current alarm or condition |
|302 |Array of plant or alarm areas that contain this item |
|303 |Primary alarm area |
|304 |Description of the condition logic |
|305 |The condition that is exceeded, for example HiHi, High, Low, LoLo |
|306 |Deadband |
|307 |HiHi limit |
|308 |High limit |
|309 |Low limit |
|310 |LoLo limit |
|311 |Rate of change limit |
|312 |Deviation limit |
|313-399 |Reserved by the OPC Foundation |
Reserved properties
|ID |Property Description |
|400-4999 |Reserved by the OPC Foundation |
ID Set 3 is designated for vendor-specific attributes. Different OPC servers can use the same ID from this set for completely dissimilar properties.
|ID |Property Description |
|5000- |Vendor-specific |
Attribute IDs in the HDA Standard
OPC HDA attribute IDs are 32-bit unsigned numbers. The OPC Historical Data Access Specification reserves IDs from 0 to 0x7fffffff (hexadecimal notation) for the OPC Foundation. Vendor-specific attributes must be assigned IDs from 0x80000000 to 0xffffffff.
The following tables are derived from section 5.2 in the OPC Historical Data Access Specification.
General attributes
|ID |Property Description |
|0x01 |“Canonical” or “Native” data type of the item. This property contains the Windows VARIANT |
| |type code for the data type. |
|0x02 |Description |
|0x03 |Engineering Units |
|0x04 |Indicates that data from history represents step changes (non-zero), as opposed to the end |
| |points for interpolation (zero). |
|0x05 |Archiving status (0=off) |
|0x06 |Equation used to calculate a derived item |
|0x07 |Host name of source for the item |
|0x08 |Name of the process (program on the source host) that is the source for the item |
|0x09 |Name of the source item |
|0x0a |Type of data source |
|0x0b |Highest normal value |
|0x0c |Lowest normal value |
|0x0d |ItemID |
Attributes related to historization
|ID |Property Description |
|0x0e |Maximum interval between history values (in seconds) |
|0x0f |Minimum interval between history values (in seconds) |
|0x10 |Minimum amount of change for the value to be recorded in history (The specific meaning of |
| |this attribute is not standardized. The attribute value can be an absolute value, percent of |
| |value, or percent of span defined by attribute ID 0x12 value minus attribute ID 0x13 value.) |
|0x11 |Deviation type (encoding of this attribute value is not standardized) |
|0x12 |Maximum valid value |
|0x13 |Minimum valid value |
APS_OPCexplorer
APS_OPCexplorer explores an OPC server for items and DA properties or HDA attributes that OPCtoCSV or the OPCInt_APS or OPCHDAInt_APS connectors can use to synchronize or create PI points for the OPC interfaces. Essentially, this program is the OPC-facing side of the OPC APS connectors packaged as a self-contained executable. This program makes the same series of OPC calls as the OPC APS connector to search for available points and writes the results into a log file for analysis.
The APS_OPCexplorer tool is included in the setup kits for the OPCInt_APS and OPCHDAInt_APS connectors that released in May 2011 or later. The setup kits install this tool in the %PIHOME%\APS\Utilities folder.
APS_OPCexplorer is a command-line application. That is, APS_OPCexplorer does not have a graphicsl user interface.
To run APS_OPCexplorer, open a command window in the %PIHOME%\APS\Utilities folder. At the command prompt, enter the program name followed by required and optional parameters, which are described below.
Note: You cannot run APS_OPCexplorer by double-clicking on the application in Windows Explorer.
The grammar used here to describe the APS_OPCexplorer command syntax is the same as in the “Grammar for Command Syntax” section for OPCtoCSV.
Built-in Help
APS_OPCexplorer has a built-in quick reference guide. The command syntax for invoking APS_OPCexplorer to display a command syntax summary and the quick reference is:
APS_OPCexplorer [ /? | /help ]
If APS_OPCexplorer is invoked with no parameters or the first parameter is /? or /help, the tool writes a command syntax summary and the quick reference to the command window.
APS_OPCexplorer Command Syntax
The command syntax for invoking APS_OPCexplorer to explore the OPC address space and log the items and properties is:
APS_OPCexplorer [ OPChostName ] OPCserverID [ /da | /hda ]
[ /log filename ]
[ /path subbranchPath | /down branchName ... ]
OPCserverID is a required parameter and all other switches are optional. The switches and parameters in the command syntax are:
OPChostName
If the OPC server is on the local computer, omit this optional parameter.
If the OPC server is not on the local computer, the first parameter on the command line must be the host name of the computer where the OPC server is located. Using a remote OPC server requires DCOM configuration. Follow the instructions in the DCOM Configuration Guide for configuring DCOM on this computer as if it were an OPC interface node. DCOM settings on the OPC server node also might require changes to permit this computer to connect.
OPCserverID
OPCserverID is a required parameter that is the registered COM programmatic identifier (ProgID) of the OPC server.
/da or /hda
APS_OPCexplorer queries the OPC server to determine whether the OPC server implements DA, HDA, or both. Unless one of the optional /da or /hda switches is on the command line, this program explores all OPC types that the OPC server supports, which is usually only one of DA or HDA. If the OPC server supports both DA and HDA, the /da or /hda switch restricts the utility to DA or HDA, respectively.
/log
The /log switch is followed by the name of the log file. The filename can be an absolute or relative path. If the /log switch is not specified, the default log file name is OPCexplorer_OPCserverID.csv, which is created in the current working directory. The “Interpreting the Log File” section discusses the contents of the log file.
/path or /down
Exploration starts at the root of the OPC address space hierarchy unless one of the optional /path or /down switches specifies a starting point at a subbranch. This program recursively explores all subbranches below the starting point.
The /path switch is followed by a subbranch path specified in the syntax of the OPC server. APS_OPCexplorer makes a single ChangeBrowsePosition(direction,subbranchPath) call to the OPC server, where direction is OPC_BROWSE_TO for DA or OPCHDA_BROWSE_DIRECT for HDA. Unless this call fails, exploration begins at this subbranch.
The /down switch is followed by a list of one or more branchNames. For each branchName, left to right, APS_OPCexplorer calls ChangeBrowsePosition(direction,branchName), where direction is OPC_BROWSE_DOWN for DA or OPCHDA_BROWSE_DOWN for HDA. Unless one of the calls fails, exploration begins in the final branch in the list.
Priority Reduction
To reduce the impact that APS_OPCexplorer can have on other applications, APS_OPCexplorer reduces its priority. That is, APS_OPCexplorer runs only when the CPU has idle time. As mentioned in the discussion of OPCtoCSV switches, priority reduction is not sufficient to prevent APS_OPCexplorer from overwhelming some OPC servers. Unlike OPCtoCSV, APS_OPCexplorer does not provide other options to make it behave more like an interactive client.
Output to Command Window
As APS_OPCexplorer runs, it writes the OPC branch and item hierarchy to error output as a progress indicator. The error output defaults to the command window. The output in the command window is a small subset of the information that is written to the log file. The “Interpreting the Log File” section discusses the contents of the log file.
Error Messages
If APS_OPCexplorer calls an OPC method that returns an error code, APS_OPCexplorer attempts to get a description for the error code. The error code and description are reported on error output. Unless error output is redirected, error output is the command window.
Some error codes are actually warnings. APS_OPCexplorer reports warning codes and continues exporting items. For unexpected error codes, APS_OPCexplorer reports the error and terminates.
Terminating Before Completion
If the OPC server contains a large number of items, APS_OPCexplorer can run for a long time and create a large log file. Type CTRL+C in the command window where APS_OPCexplorer is running to cause the program to cleanly disconnect from the OPC server, close the log file, and terminate. If the program is terminated early, all items in the OPC server are not written to the log file.
Interpreting the Log File
The Data Access Custom Interface Standard does not provide a method for requesting a list of property IDs that an OPC DA server supports. With a DA server, the only way to find all supported property IDs is to request the properties for every item in the DA server.
The OPC Historical Data Access Specification provides a method for requesting a list of attribute IDs that the OPC HDA server supports. Every item is not required to have all of the attributes, but the list of possible attribute IDs can be obtained without examining every item in the HDA server. If the OPC server is an HDA server, APS_OPCexplorer requests the list of supported attributes and writes a line in the log file for each attribute. Each line contains:
ID 'name' type (description)
For example, the following excerpt is from the log file for the OSIsoft OPC HDA Server for PI. Some lines from the log file are too long to fit in the margins of this document and have wrapped into multiple lines.
OPC HDA Server supports 38 attributes:
0x1 'OPCHDA_DATA_TYPE' VT_I2 (Specifies the data type for the item. See the definition of a VARIANT for valid values (VT_R4, etc.))
0x2 'OPCHDA_DESCRIPTION' VT_BSTR (Describes the item.)
0x3 'OPCHDA_ENG_UNITS' VT_BSTR (Specifies the label to use in displays to define the units for the item (e.g., kg/sec).)
0x4 'OPCHDA_STEPPED' VT_I2 (Whether the values are discrete or continuous.)
0x5 'OPCHDA_ARCHIVING' VT_I2 (Whether archiving is currently on for this item)
0x7 'OPCHDA_NODE_NAME' VT_BSTR (Name of PI server on which item resides)
0x8 'OPCHDA_PROCESS_NAME' VT_BSTR (Instrument tag)
0x9 'OPCHDA_SOURCE_NAME' VT_BSTR (Point source signifying source of data (interface))
0xa 'OPCHDA_SOURCE_TYPE' VT_BSTR (Extended descriptor)
0xd 'OPCHDA_ITEMID' VT_BSTR (Specifies the item id. This is used to allow filtering in the CreateBrowse method.)
0xe 'OPCHDA_MAX_TIME_INT' VT_I4 (Exception max -- max time between snapshot values)
0xf 'OPCHDA_MIN_TIME_INT' VT_I4 (Exception min -- min time between snapshot values)
0x10 'OPCHDA_EXCEPTION_DEV' VT_R4 (Exception deviation -- min deviation between snapshot values)
0x11 'OPCHDA_EXCEPTION_DEV_TYPE' VT_I2 (Exception deviation type -- absolute value, pct of span, or pct of value)
0x12 'OPCHDA_HIGH_ENTRY_LIMIT' VT_R4 (Maximum legal value)
0x13 'OPCHDA_LOW_ENTRY_LIMIT' VT_R4 (Minimum legal value)
0x80000000 'OSI_LOCATION1' VT_I4 (Location code 1)
0x80000001 'OSI_LOCATION2' VT_I4 (Location code 2)
0x80000002 'OSI_LOCATION3' VT_I4 (Location code 3)
0x80000003 'OSI_LOCATION4' VT_I4 (Location code 4)
0x80000004 'OSI_LOCATION5' VT_I4 (Location code 5)
0x80000014 'OSI_DIGITALSET' VT_BSTR (Digital state set)
0x80000005 'OSI_COMPRESSING' VT_BOOL (Compression flag)
0x80000006 'OSI_COMPMIN' VT_I2 (Compression min time (seconds))
0x80000007 'OSI_COMPMAX' VT_I2 (Compression max time (seconds))
0x80000008 'OSI_COMPDEV' VT_R4 (Compression min deviation (eu))
0x80000009 'OSI_COMPDEVPCT' VT_R4 (Compression min deviation (pct of span))
0x8000000a 'OSI_SCAN' VT_BOOL (Scan flag)
0x8000000b 'OSI_SOURCETAG' VT_BSTR (Source tag for output value)
0x8000000c 'OSI_SQUARERT' VT_I2 (Square root code)
0x8000000d 'OSI_TOTAL' VT_I2 (Totalizer code)
0x8000000e 'OSI_CONVERS' VT_R4 (Convers code)
0x8000000f 'OSI_TYPICALVALUE' VT_R4 (Typical value)
0x80000010 'OSI_USERINT1' VT_I4 (User defined integer 1)
0x80000011 'OSI_USERINT2' VT_I4 (User defined integer 2)
0x80000012 'OSI_USERREAL1' VT_R4 (User defined real 1)
0x80000013 'OSI_USERREAL2' VT_R4 (User defined real 2)
0x80000015 'OSI_ALIAS' VT_BSTR (Alias)
The OPC HDA Server for PI supports sixteen of the nineteen attributes recommended in the OPC Historical Data Access Specification. The OPC HDA Server for PI also provides twenty-two vendor-specific attributes.
The first line is for attribute ID 0x1 (hexadecimal notation). The name for this attribute is “OPCHDA_DATA_TYPE”. The values for this attribute have type VT_I2: 2-byte (16-bit) integer. The description of the attribute is “Specifies the data type for the item. See the definition of a VARIANT for valid values (VT_R4, etc.)).”
The lines for the other attributes are interpreted similarly.
Log Entries for Items
Exploration starts at the root of the OPC address space hierarchy unless one of the optional /path or /down switches specifies a starting point at a subbranch. APS_OPCexplorer recursively explores all subbranches below the starting point.
A multi-line entry is written into the log file for each item that is found. The first line contains general item information and is followed by a line for each property of the item. The format of the lines for properties is different for DA and HDA.
The pattern for DA items is:
+ 'shortName' LeafOrBranch ItemID='itemID'
Property ID: type 'name'=value (valueType) ItemID 'propItemID'
The pattern for HDA items is:
+ 'shortName' LeafOrBranch ItemID='itemID'
Property ID: type 'name'=value (valueType)
The entries are indented to indicate the depth of the item in the OPC address space. On the first line for each item, the shortName is the name in the current branch. LeafOrBranch is either “Leaf” or “Branch” to indicate whether the OPC server returned the shortName in the request for leaves or the request for branches. The itemID is the unique item ID for the item.
In the lines for properties, ID is the DA property ID in decimal notation or HDA attribute ID in hexadecimal notation. Type is the data type for values of the property. Name is the name of the property. Value is the current property value for this item. ValueType is the actual data type of the value and usually is the same as type.
In the lines for DA properties, additional information is present. If a property is also accessible as an item, propItemID is the item ID of the item that contains the same value as the property. If a property is not accessible as an item, propItemID is replaced by “”. Property IDs 1-6 access item information that is normally obtained by adding the item to an OPC group and causing the OPC server to return data for all items in the group. That is, property IDs 1-6 contain values that are inherently part of the item and separate items for these properties are redundant. Therefore, property IDs 1-6 usually show an error for propItemID. For other property IDs, the propItemID is server-specific.
The following excerpt is from the log file for an OPC DA server that supports most of the OPC-recommended properties and seven server-specific properties:
+ 'dyn_BOOL' Leaf ItemID 'PLC1.dyn_BOOL'
Property 1 VT_I2 'Item Canonical Data Type'=8203 (VT_I2) ItemID
Property 2 VT_ARRAY | VT_BOOL 'Item Value'=???? (VT_ARRAY | VT_BOOL) ItemID
Property 3 VT_I2 'Item Quality'=192 (VT_I2) ItemID
Property 4 VT_DATE 'Item Timestamp'=10/13/2005 1:53:45 PM (VT_DATE) ItemID
Property 5 VT_I4 'Item Access Rights'=3 (VT_I4) ItemID
Property 6 VT_R4 'Server Scan Rate'=2 (VT_R4) ItemID
Property 100 VT_BSTR 'EU Units'= (VT_BSTR) ItemID 'PLC1.dyn_BOOL.EUUnits'
Property 101 VT_BSTR 'Item Description'= (VT_BSTR) ItemID 'PLC1.dyn_BOOL.Description'
Property 108 VT_I4 'Item Timezone'=-60 (VT_I4) ItemID 'PLC1.dyn_BOOL.TimeZone'
Property 200 VT_BSTR 'Default Display'= (VT_BSTR) ItemID 'PLC1.dyn_BOOL.DefDisplay'
Property 201 VT_I4 'Current Foreground Color'=16777215 (VT_I4) ItemID 'PLC1.dyn_BOOL.FgColor'
Property 202 VT_I4 'Current background Color'=0 (VT_I4) ItemID 'PLC1.dyn_BOOL.BkColor'
Property 203 VT_BOOL 'Current Blink'=0 (VT_BOOL) ItemID 'PLC1.dyn_BOOL.Blink'
Property 204 VT_BSTR 'BMP File'= (VT_BSTR) ItemID 'PLC1.dyn_BOOL.BMPFile'
Property 205 VT_BSTR 'Sound File'= (VT_BSTR) ItemID 'PLC1.dyn_BOOL.SoundFile'
Property 206 VT_BSTR 'HTML File'= (VT_BSTR) ItemID 'PLC1.dyn_BOOL.HTMLFile'
Property 207 VT_BSTR 'AVI File'= (VT_BSTR) ItemID 'PLC1.dyn_BOOL.AVIFile'
Property 5000 VT_BSTR 'Item ID'=PLC1.dyn_BOOL (VT_BSTR) ItemID 'PLC1.dyn_BOOL.ItemID'
Property 5001 VT_BSTR 'Item Name'=dyn_BOOL (VT_BSTR) ItemID 'PLC1.dyn_BOOL.Name'
Property 5002 VT_I4 'Tag Usage Count'=32 (VT_I4) ItemID 'PLC1.dyn_BOOL.UsageCnt'
Property 5003 VT_BSTR 'Data Type as String'=VT_ARRAY | VT_BOOL (VT_BSTR)
temID 'PLC1.dyn_BOOL.DataTypeStr'
Property 5006 VT_BOOL 'Background Poll'=-1 (VT_BOOL) ItemID 'PLC1.dyn_BOOL.BackgroundPoll'
Property 5007 VT_I4 'Background Poll Rate'=0 (VT_I4) ItemID 'PLC1.dyn_BOOL.BackgroundPollRate'
Property 5008 VT_BOOL 'Data Expired'=0 (VT_BOOL) ItemID 'PLC1.dyn_BOOL.DataExpired'
Observe that this OPC server returns an error code for propItemID for property IDs 1-6. The exact error code number is irrelevant. The remaining properties have item IDs that allow the properties to be read as items.
If the value of a property cannot be converted to a string by the Windows VariantChangeType function, the value in the log is “????”. For example, the value for property ID 2 in the previous log file excerpt is an array, which the Windows function does not convert.
The following excerpt is from the log file for the OSIsoft OPC HDA Server for PI, which supports most of the OPC-recommended properties and many server-specific properties:
+ 'BA:CONC.1' Leaf ItemID='\\sandbox\BA:CONC.1'
Property 0x1: VT_I2 'OPCHDA_DATA_TYPE'=4 (VT_I2)
Property 0x2: VT_BSTR 'OPCHDA_DESCRIPTION'=Concentration Reactor 1 (VT_BSTR)
Property 0x3: VT_BSTR 'OPCHDA_ENG_UNITS'=DEG. C (VT_BSTR)
Property 0x4: VT_I2 'OPCHDA_STEPPED'=0 (VT_I2)
Property 0x5: VT_I2 'OPCHDA_ARCHIVING'=1 (VT_I2)
Property 0x7: VT_BSTR 'OPCHDA_NODE_NAME'=sandbox (VT_BSTR)
Property 0x8: VT_BSTR 'OPCHDA_PROCESS_NAME'= (VT_BSTR)
Property 0x9: VT_BSTR 'OPCHDA_SOURCE_NAME'=9 (VT_BSTR)
Property 0xa: VT_BSTR 'OPCHDA_SOURCE_TYPE'=(20,20) (21,23) (10,40) (20,44) (VT_BSTR)
Property 0xd: VT_BSTR 'OPCHDA_ITEMID'=BA:CONC.1 (VT_BSTR)
Property 0xe: VT_I4 'OPCHDA_MAX_TIME_INT'=600 (VT_R8)
Property 0xf: VT_I4 'OPCHDA_MIN_TIME_INT'=0 (VT_I4)
Property 0x10: VT_R4 'OPCHDA_EXCEPTION_DEV'=2 (VT_R4)
Property 0x11: VT_I2 'OPCHDA_EXCEPTION_DEV_TYPE'=0 (VT_I2)
Property 0x12: VT_R4 'OPCHDA_HIGH_ENTRY_LIMIT'=200 (VT_R4)
Property 0x13: VT_R4 'OPCHDA_LOW_ENTRY_LIMIT'=0 (VT_R4)
Property 0x80000000: VT_I4 'OSI_LOCATION1'=1 (VT_I4)
Property 0x80000001: VT_I4 'OSI_LOCATION2'=10 (VT_I4)
Property 0x80000002: VT_I4 'OSI_LOCATION3'=12 (VT_I4)
Property 0x80000003: VT_I4 'OSI_LOCATION4'=1 (VT_I4)
Property 0x80000004: VT_I4 'OSI_LOCATION5'=180 (VT_I4)
Property 0x80000014: VT_BSTR 'OSI_DIGITALSET'= (VT_BSTR)
Property 0x80000005: VT_BOOL 'OSI_COMPRESSING'=1 (VT_I2)
Property 0x80000006: VT_I2 'OSI_COMPMIN'=0 (VT_I4)
Property 0x80000007: VT_I2 'OSI_COMPMAX'=28800 (VT_R8)
Property 0x80000008: VT_R4 'OSI_COMPDEV'=4 (VT_R4)
Property 0x80000009: VT_R4 'OSI_COMPDEVPCT'=2 (VT_R4)
Property 0x8000000a: VT_BOOL 'OSI_SCAN'=1 (VT_I2)
Property 0x8000000b: VT_BSTR 'OSI_SOURCETAG'= (VT_BSTR)
Property 0x8000000c: VT_I2 'OSI_SQUARERT'=0 (VT_I2)
Property 0x8000000d: VT_I2 'OSI_TOTAL'=0 (VT_I2)
Property 0x8000000e: VT_R4 'OSI_CONVERS'=1 (VT_R4)
Property 0x8000000f: VT_R4 'OSI_TYPICALVALUE'=140 (VT_R4)
Property 0x80000010: VT_I4 'OSI_USERINT1'=0 (VT_I4)
Property 0x80000011: VT_I4 'OSI_USERINT2'=0 (VT_I4)
Property 0x80000012: VT_R4 'OSI_USERREAL1'=0 (VT_R4)
Property 0x80000013: VT_R4 'OSI_USERREAL2'=0 (VT_R4)
Property 0x80000015: VT_BSTR 'OSI_ALIAS'=BA:CONC.1 (VT_BSTR)
C. Technical Support and Resources
You can read complete information about technical support options, and access all of the following resources at the OSIsoft Technical Support Web site:
()
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The log file(s) at that time
Help Desk and Telephone Support
You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table below to find the most appropriate number for your area. Dialing any of these numbers will route your call into our global support queue to be answered by engineers stationed around the world.
|Office Location |Access Number |Local Language Options |
|San Leandro, CA, USA |1 510 297 5828 |English |
|Philadelphia, PA, USA |1 215 606 0705 |English |
|Johnson City, TN, USA |1 423 610 3800 |English |
|Montreal, QC, Canada |1 514 493 0663 |English, French |
|Sao Paulo, Brazil |55 11 3053 5040 |English, Portuguese |
|Frankfurt, Germany |49 6047 989 333 |English, German |
|Manama, Bahrain |973 1758 4429 |English, Arabic |
|Singapore |65 6391 1811 |English, Mandarin |
| |86 021 2327 8686 |Mandarin |
|Perth, WA, Australia |61 8 9282 9220 |English |
Support may be provided in languages other than English in certain centers (listed above) based on availability of attendants. If you select a local language option, we will make best efforts to connect you with an available Technical Support Engineer (TSE) with that language skill. If no local language TSE is available to assist you, you will be routed to the first available attendant.
If all available TSEs are busy assisting other customers when you call, you will be prompted to remain on the line to wait for the next available TSE or else leave a voicemail message. If you choose to leave a message, you will not lose your place in the queue. Your voicemail will be treated as a regular phone call and will be directed to the first TSE who becomes available.
If you are calling about an ongoing case, be sure to reference your case number when you call so we can connect you to the engineer currently assigned to your case. If that engineer is not available, another engineer will attempt to assist you.
Search Support
From the OSIsoft Technical Support Web site, click Search Support.
Quickly and easily search the OSIsoft Technical Support Web site’s Support Solutions, Documentation, and Support Bulletins using the advanced MS SharePoint search engine.
Email-based Technical Support
techsupport@
When contacting OSIsoft Technical Support by email, it is helpful to send the following information:
• Description of issue: Short description of issue, symptoms, informational or error messages, history of issue
• Log files: See the product documentation for information on obtaining logs pertinent to the situation.
Online Technical Support
From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.
Using OSIsoft’s Online Technical Support, you can:
• Enter a new call directly into OSIsoft’s database (monitored 24 hours a day)
• View or edit existing OSIsoft calls that you entered
• View any of the calls entered by your organization or site, if enabled
• See your licensed software and dates of your Service Reliance Program agreements
Remote Access
From the OSIsoft Technical Support Web site, click Contact Us > Remote Support Options.
OSIsoft Support Engineers may remotely access your server in order to provide hands-on troubleshooting and assistance. See the Remote Access page for details on the various methods you can use.
On-site Service
From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service Visit.
OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more information.
Knowledge Center
From the OSIsoft Technical Support Web site, click Knowledge Center.
The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center on the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including user manuals, release notes, and white papers).
• System Manager Resources include tools and instructions that help you manage: Archive sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.
Upgrades
From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.
You are eligible to download or order any available version of a product for which you have an active Service Reliance Program (SRP), formerly known as Tech Support Agreement (TSA). To verify or change your SRP status, contact your Sales Representative or Technical Support () for assistance.
OSIsoft Virtual Campus (vCampus)
The OSIsoft Virtual Campus (vCampus) Web site offers a community-oriented program that focuses on PI System development and integration. The Web site's annual online subscriptions provide customers with software downloads, resources that include a personal development PI System, online library, technical webinars, online training, and community-oriented features such as blogs and discussion forums.
OSIsoft vCampus is intended to facilitate and encourage communication around PI programming and integration between OSIsoft partners, customers and employees. See the OSIsoft vCampus Web site, () or contact the OSIsoft vCampus team at vCampus@ for more information.
D. Revision History
|Date |Author |Comments |
|28-Nov-2011 |LDaley |First draft of OPCtoCSV User’s Guide started from interface |
| | |skeleton version 3.0.33. |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- teacher s guide sri lanka
- blackrock aladdin user s guide
- chemistry teacher s guide 2019 download
- man s guide to divorce
- a man s guide to women
- microsoft office 2010 user s guide
- java a beginner s guide pdf
- change another user s password
- men s guide to understanding women
- teacher s guide first grade wonders
- users vs user s grammar
- the teacher s guide wonders 2nd grade