PI_XML_WITSML_Plug-in_0.9.1.0 - OSIsoft

flashypumpkincenterSoftware and s/w Development

Dec 14, 2013 (3 years and 7 months ago)

119 views


WITSML

Plug
-
i
n DLL

for
the

XML

Interface to the PI System

Version
0
.
9
.1
.0
Beta

Rev
B






ii

How to Contact Us

Phone

(510) 297
-
5800 (main number)

(510) 297
-
5828 (technical support)

Fax

(510) 357
-
8136

E
-
mail

te
chsupport@osisoft.com

World Wide Web

http://www.osisoft.com

Mail

OSIsoft

P.O. Box 727

San Leandro, CA 94577
-
0427

USA


OSI Software GmbH

Hauptstra

e 30

D
-
63674 Altenstadt 1

Deutschland

OSI Software, Ltd

P O Box 82
56

Symonds Street

Auckland 1035 New Zealand


OSI Software, Asia Pte Ltd

152 Beach Road

#09
-
06 Gateway East

Singapore, 189721

Unpublished


rights reserved under the copyright laws of the United States.

RESTRICTED RIGHTS LEGEND

Use, duplication, or discl
osure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)

of the Rights in Technical Data and Computer Software clause at DFARS 252.227
-
7013

Trademark statement

PI is a regi
stered trademark of OSIsoft
, Inc. Microsoft Windo
ws, Microsoft Windows for Workgroups, and
Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP
-
UX is
a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trad
emark of the IBM Corporation. DUX, DEC
VAX and DEC Alpha are registered trademarks of the Digital Equipme
nt Corporation.

PIXML_WITSML
_P
lug
-
in.doc



2005

OSIsoft, Inc.
All rights reserved

777 Davis Street, Suite 250, San Leandro, CA 94577



WITSML Plug
-
in DLL for the XML Interface to the PI System

iii

iii

Table of Content
s

Introduction

................................
................................
................................
...................

1

Reference Manuals

................................
................................
................................
.....

1

Plug
-
in Specific Features

................................
................................
.............................

1

Principles of Operation

................................
................................
................................

3

Installation Checklist

................................
................................
................................
....

5

Plug
-
In Installati
on and Administration

................................
................................
.......

7

Plug
-
In Directory

................................
................................
................................
..........

7

Modify PIXML.BAT

................................
.......................

Error! Bookmark not defined.

C
onfigure PI tags
................................
................................
................................
.........

7

Upgrading the Plug
-
In

................................
................................
................................
.

7

Moving the Plug
-
In to a New Directory

................................
................................
........

7

Uninstalling the Plug
-
In

................................
................................
................................

7

Startup Command File

................................
................................
................................
..

9

Configuring the Plug
-
In with PI
-
ICU

................................
................................
.............

9

Command
-
line Parameters

................................
................................
........................

11

Sample PIXML.bat File

................................
................................
..............................

13

Error and Informational Messages

................................
................................
............

19

Message Logs

................................
................................
................................
...........

19

System Errors and PI Errors

................................
................................
......................

19

Revision Histo
ry

................................
................................
................................
..........

21




WITSML Plug
-
in DLL for the XML Interface to the PI System

1

1

Introduction

The PI
-
XML interface read
s

XML data that conforms to the OPC XML
-
DA
specification using the SOAP protocol

as a transport mechanism
. In order to handle
other XML schemas and transport mechanisms, the PI
-
XML interface was designed
to allow for the development of custom plug
-
in DLLs.
The WITSML plug
-
in DLL is
a custom plug
-
in DLL that can interface with
a

WITSML
-
compliant
server
in order to
import data into PI by using

SOAP over HTTP/S
-
based protocols, dep
ending on the
security settings
,

which
are

described in detail in the

Security

section of the

PI
-
XML
I
nterface manual. The WITSML

plug
-
in is in a file called
PIXML_WITSML.DLL
.

WITSML was initially developed by an oil industry initiative as a new standar
d for
drilling information transfer.

WITSML uses XML to represent the underlying data
objects that are exchanged between systems

and is platform independent
. The
format
of the data objects is

descri
bed by the WITSML XML schemas.
Currently, the
WITSML
st
andard defines two core interfaces, STORE and PUBLISH
,

which use a
Client/Server

and a
Subscribe/Publish

mechanism for exchanging data, respectively.
The WITSML plug
-
in currently only supports the
Client/Server

mechanism (STORE
interface) while future sup
port of the PUBLISH interface is

anticipated.

Additionally,
the WITSML standard defines two supplemental interfaces,
ITEM and DOCUMENT.
The ITEM interface is used for manipulating WITSML data items without regards to
their XML representation
,

while the DO
CUMENT interface can be used to provide
document location independence. These interfaces are not relevant to the WITSML
plug
-
in as it

is

familiar with the
document location and the underlying XML
representation.

Note:
Neither this manual nor the plug
-
in a
re stand
-
alone products; they are to be
used in conjunction with the PI
-
XML interface. This version of the plug
-
in requires
1.0.0.0

or above versions of the PI
-
XML Interface.

Reference Manuals

OSIsoft



PI Server manuals



PI
-
API manual



XML Interface to the PI

System

Vendor



Extensible Markup Language (XML) 1.0

(Second Edition)



OPC XML
-
DA specification

(version 1.0)

Plug
-
in Specific Features

Several features of this product a
re unique to this plug
-
in. These

features are detailed
below.

Introduction

2


2

Exception Reporting

When
using the PIXML_
WITSML
_plugin
, it is not possible to request that exception
reporting be
performed

by the XML server through the use of the
/sn

command
-
line
option. If the
/sn

command
-
line option is specified, the PI
-
XML
I
nterface will not do
an
y exception

reporting. Also,

the

/returnallitems

command
-
line option
that is
typically

used to force the XML server to return data after each scan
,

has no effect
when the PIXML_
WITSML
_plugin is being used.

Source of Timestamps

By default, timestamps will be read fro
m the WITSML server. However, local
timestamps
can be used

if the
/TS

option is specified
.

For WITSML data objects that
do
not supply a timestamp, a local, offset
-
adjusted timestamp will be used.

Synchronous Reads

When using the PIXML_WITSML_plugin, t
he
/sync_read

command
-
line option
must be specified. This option tell
s

the interface that a client/server mechanism of
polling the WITSML server will be used.

Output Points

Cur
rently, the PIXML_WITSML_plugin

does not support outputs.




WITSML Plug
-
in DLL for the XML Interface to the PI System

3

3

Principles of Oper
ation

As with all plug
-
ins, the
WITSML
plug
-
in

acts as an intermediary between the XML
interface, which
must
receive

OPC XML
-
DA compliant data
, and the XML data
server, which in this case is the WITSML server.
The WITSML server is specified
through the us
e of
the
/server

command
-
line option

which is a URL
.

On startup,
the interface will then connect to the WITSML server and use the
WMLS_GetFromStore call to retrieve the WITSML data.

The query string for the
WMLS_GetFromStore call is built up through the
various attributes of the PI tag
requesting the data.

The data returned is an XML string that

is then transformed to be
compliant with the ReadResponse extract of the OPC XML
-
DA schema and returned
to the interface which processes the data and sends it to

PI.


Tag configuration is predominantly done through the
instrumentt
ag

field of the
PI tag, which has the following format.

nameWell
, XML_Path_to_Data_Item

Each WITSML data object has a
nameWell attribute

and this needs to be specified on
the instrument
tag field. In addition
,

the
XML_Path_to_Data_Item

portion of the
instrumentt
ag

field

specifies the data item to retrieve from the WITSML server.

The format of the
XML_Path_to_Data_Item

portion of the
instrumentt
ag

field
is a location path to the XML item

in question. For example,
the following XML
corresponds to a partial listing of a well data object described in the WITSML
schemas.

<?xml version="1.0"
?>

<
wells

xmlns
="http://www.witsml.org/schemas/120
">


<well uidWell="W
-
1"
>



<
nameWell>6507/7
-
1
</
name
Well
>



<country>Scotland</country>



...


</well
>

</
wells
>

To configure a tag that would store the

country


data item in a PI tag, the
XML_Path_to_Data_Item

portion of the
instrumentt
ag

field would be defined
as
/wells/well/country
, and full configuratio
n for
instrumentt
ag

field
would be
W
-
1,
/wells/well/country
.




WITSML Plug
-
in DLL for the XML Interface to the PI System

5

5

Installation Checklist

For those users w
ho are familiar with running PI
-
XML
interface

with the
WITSML

Plug
-
In DLL
, this checklist helps you get the PI
-
XML interface running. If you are
not fami
liar with

the

WITSML
Plug
-
In DLL for the PI
-
XML

Interface
, you should return to this section after reading the rest of the manual in
detail.

1.

Install the PI
-
Interface Configuration Utility (which installs PI
-
SDK and PI
-
API)

2.

Verify that PI
-
API and PI
-
SDK hav
e been installed.

3.

Install the
PI
-
XML
interface.

4.

Configure the PI
-
XML Interface using the PI
-
Interface Configuration Utility
which is the recommended way to configure the interface.

5.

Configure PI points.

Location1

is the interface instance.

Location2

spec
ifies

whether the tag is an input
(0)
or output

(1)

tag.

Location3

is
not used.

Location4

is the scan class.

Location5

is not used.

ExDesc

is not used.

InstrumentTag

is the itemID
.

It is specified using the following format

uID, XML_Path_to_Data_Item

6.

Star
t the interface without buffering.

7.

Verify data.

8.

Stop interface, start buffering, start interface.




WITSML Plug
-
in DLL for the XML Interface to the PI System

7

7

Plug
-
i
n

Installation

and Administration

Plug
-
In Directory

The

PIXML_WITSML
.dll

is installed in the PI
-
XML interface directory in the plug
-
ins
directory. Fo
r instance if the interface is installed in

PIHOME
\
Interfaces
\
XML

then the DLL should be present in the corresponding plug
-
in directory in

PIHOME
\
Interfaces
\
XML
\
Plug
-
I
ns
\
WITSML

The other plug
-
in DLLs are installed in their own separate sub
-
directories.

Con
figure PI tags

A detailed description for configuring tags can be found the
XML Interface to the PI
System

manual. However
, when using the
WITSML

Plug
-
In DLL
, there are a few
differences that should be noted.
Firstly
, all tags should support buffering by

setting
location3

equal to 0.
Additionally, the

instrumenttag

field
is defined using the
following format:

nameWell
, XML_Path_to_Data_Item

where
nameWell

is the
name

of the
WITSML data object and
XML_Path_to_Data_Item

is the location path to the data Ite
m (as described earlier).

Upgrading the Plug
-
i
n

If the plug
-
in is upgraded independent of the PI
-
XML
I
nterface, it will be necessary to
stop the PI
-
XML
I
nterface
,

install the plug
-
in in the appropriate directory and restart the
interface according to the i
nstructions in
the

XML Interface to the PI System

manual.

Moving the Plug
-
i
n to a New Directory

Although it is not recommended, it is possible to move the plug
-
in to a new directory.
You will need to change
pixml.bat

to reflect the name of the new directo
ry and then
stop and restart the interface as described in
the

XML Interface to the PI System

manual.

Uninstalling the Plug
-
In

In order

to run the
PI
-
XML I
nterface without the
WITSML
plug
-
in,
use the PI
-
ICU
program to change the plug
-
in DLL. S
top and resta
rt the interface according to the
instruction
s

in the
XML Interface to the PI System

manual.




WITSML Plug
-
in DLL for the XML Interface to the PI System

9

9

Startup Command File

Configuring the Plug
-
i
n with PI
-
ICU

Note:

PI
-
ICU requires PI 3.3 or greater.

The PI
-
Interface Configuration Utility provides a graphical use
r interface for configuring
PI interfaces. By configuring the interface with PI
-
ICU, the user makes it possible to
recognize the interface, edit configurations, run and stop the interface. If the interface is
configured by the PI
-
ICU, the batch file of t
he interface (
pixml.bat
) will be maintained
by the PI
-
ICU and all configuration changes will be kept in that file. The procedure
describing the necessary steps for using PI
-
ICU to configure the PI
-
XML Interface is
described in
XML Interface to the PI Syst
em

manual.

When using the XML ICU control with the
WITSML

plug
-
in, it is necessary to choose
the appropriate plug in DLL. This is done by selecting the PIXML_
WITSML
.dll in the
Configuration

tab of the XML ICU control as shown below.


Once this is done, t
he
WITSML

Plug
-
In

tab should appear, and the following options will
available for selection.

WITSML Plug
-
In


Currently there are no options available for the WITSML plug
-
in, although the following
connection settings do apply.

Connection Settings

This sel
ection provides you with specific parameters for setting up connection options of
the interface. The PI
-
XML interface is designed to provide authentication options as
Startup Command File

10


10

well the ability to connect through a proxy server. Here we list available selections f
rom
the PI
-
ICU.




Use SSL Security

--

Specifies the use of SSL to encrypt communication
between the server and the interface. Note the XML server must support the use
of SSL. (
/
USESSL
).




USE Authentication
--

Enables you to choose

an

acceptable authen
tica
tion
mechanism that is supported by the XML server. (
/
AUTHSCHEME
).




Auth Scheme

-

The value of the authentication scheme bitmask is displayed in
the text field.




The various authentication schemes that are supported by the server can be
selected by the
group of check boxes. Basic Auth, ntlm Auth, Digest Auth and
Negotiate Auth.




User

--

Enables you to choose
a user for authentication. (
/
AUTHUSER
).




Password

--

Enables you to
supply a password associated with the user for
authentication. (
/
AUTHPASSWORD
)
.



WITSML Plug
-
in DLL for the XML Interface to the PI System

11

11



Connection Timeout



Limits the time (in milliseconds) it takes to make an
initial connection with the XML server. After a connection to the server has
been established the timeout property applies (
/
CONNECTTIMEOUT
).




Runtime
Timeout



The timeout in m
illiseconds after a connection to the
XML server has been established. Communication taking longer than this value
will be dropped. The default value is 30,000 milliseconds. Not all plug
-
in DLLs
support this command line parameter (
/
TIMEOUT
).




USE Proxy

Server

--

Enables you to
enable options for connecting to a proxy
server through which the interface will connect to the XML server.
(
/
PROXYSERVER
).




Proxy Server

--

Enables you to choose
a proxy server through which the
interface will connect to the XML

server. (
/
PROXYSERVER
).




Proxy User

--

Enables you to choose
a user for the proxy server.
(
/
PROXYUSER
).




Proxy Password

--

Enables you to
supply a password associated with the
user for the proxy server. (
/
PROXYPASSWORD
).




Additional Parameters



Enter
any additional parameter not currently
supported by the XML Interface ICU Control.


Command
-
line Parameters

Not all the options available to the PIXML interface are used and only the ones listed
below are relevant.

Parameter

Description

/server=
path

Requi
red

The flag tells the interface the
URL where the WITSML server
resides.

For
other

plug
-
in DLLs, this option could be used differently and
the corresponding plug
-
in manual should be consulted.

/dll=path
\
name

Required

This specifie
s the
path

for the plug
-
in D
LL and should point to the
WITSML
plug
-
in. The default for this location is:

<int
fc

directory>
\
Plug
-
ins
\
WITSML
\
PIXML_
WITSML
.dll

/
sync_read

Required

Tells the XML interface, the data acquisition will be retrieved
synchronously. This is required as th
e WITSML plug
-
in currently
only supports the STORE interface which uses a client server
mechanism for acquiring data.

/connecttimeout=x

Optional

Limits the time (in milliseconds) it takes to make an initial
connection with the XML server. After a connect
ion to the server
has been established the timeout property applies.

Startup Command File

12


12

Parameter

Description

/timeout=x

Optional

The timeout in milliseconds after a connection to the XML server
has been established. Communication taking longer than this value
will be dropped. The default valu
e is 30,000 milliseconds. Not all
plug
-
in DLLs support this command line parameter.

/authscheme=x

Optional

Enables you to choose
an acceptable
authen
tication mechanism that
is supported by the XML server. The value of
x

corresponds to the
following valu
es.

1

-

basic authentication

2
-

ntlm auth
entication

8
-

digest auth
entication

16

-

negotiate auth
entication

Note that
x

is a bitmask so y
ou can combine these values (bitwise
OR)

to enable multiple types of authentication
.

For example, to
enable both ba
sic and digest auth,
x

would be set to 9 (1+8=9).

The
defau
lt value for this property is 18

(ntlm and negotiate).

/authuser=x

Optional

The user name (
x
) used for authentication with the XML server.
This option should only be used if the XML server has be
en
configured to support authentication. Not all plug
-
in DLLs support
this command line parameter.

/authpassword=x

Optional

The password (
x
) used for authentication with the XML server.
This option should only be used if the XML server has been
configur
ed to support authentication. It works in conjunction with
the
/authuser

option. If the
/authuser
option is specified
but this option is not, then an empty string will be passed as the
password. Not all plug
-
in DLLs support this command line
parameter.

/proxyserver=x

Optional

Identifies the proxy server (
x
) through which messages are sent and
received. It should only be used if communication to the XML
server is through a proxy server. This option may have one of the
following values:

<
LOCAL_MACHINE
>

-
-

Indicates that the proxy configuration
specified using the proxycfg utility is to be used. Use this setting
when the interface is configured as a Windows NT service, and
there is no "current user" with proxy settings.

<
CURRENT_USER
>



Indicates that the

Microsoft Internet
Explorer proxy settings for the current user should be used. Use this
setting for client programs run by a user.

host[:port]



Indicates that a specific host and port should be
used. Replace "host" with the DNS name or IP address of th
e proxy
server. Replace "port" with the proxy port on that server. Omit
":port" to use the default port of "80". Use this setting if the proxy
is known when the client program is created or when a client
application provides a way for the user to specify a

proxy
configuration. Not all plug
-
in DLLs support this command line
parameter.


WITSML Plug
-
in DLL for the XML Interface to the PI System

13

13

Parameter

Description

/proxyuser=x

Optional

The user name used for proxy authentication. The default is the
value of the proxy server port shown in the Local Area Network
(LAN) Settings dialog box

in Microsoft Internet Explorer. To open
this dialog box, on the Tools menu, point to Internet Options, click
on the Connections tab, and then click LAN Settings.

Not all plug
-
in DLLs support this command line parameter.

/proxypass=x

Optional

The passwor
d used for proxy authentication. The default is an
empty string.

Not all plug
-
in DLLs support this command line
parameter.

/usessl

Optional

A Boolean value (True or False) that specifies the use of SSL to
encrypt communication between the server and the
interface. Note
the XML server must support the use of SSL.


Sample PIXML.bat File

The following is an example file that exists in the

PIHOME
\
interfaces
\
XML
\
Plug
-
ins
\
WITSML
\

directory.

REM =============================================================
===============

REM Sample startup command file for the PI
-
XML Interface to the PI System

REM ============================================================================

REM

REM pixml.bat.new

REM Use this file as a template for pixml.bat

REM

REM Require
d command
-
line parameters

REM
----------------------------------------------------------------------------

REM

REM /ps=x Point source; must match PointSource pt attribute

REM

REM /id=x Interface ID; must match Location1
pt attribute

REM

REM /server=x XML server; must match URL of XML server

REM

REM Optional command
-
line parameters

REM
----------------------------------------------------------------------------

REM

REM /dll==x Path for plug
-
in

DLL, default uses PIXML_OPC.dll

REM located in the interface Plug
-
ins OPC subdirectory

REM

REM /sync_read Forces the interface to do synchronous reads.

REM Required for the WITSML Plug
-
in.

REM

R
EM /ts Use local timestamps instead of server timestamps.

REM

REM /arcreplace Force values into archive. Replace if they already

REM exist.

REM

REM /time_offset=x An offset of x seconds is a
pplied to all timestamps

REM

Startup Command File

14


14

REM /ignore_offset Ingore time difference between PI and interface node

REM

REM /db=x Print interface
-
level debug messages

REM

REM /sn Do not perform exception reporting, and force

XML

REM server to do exception reporting

REM

REM Common optional command
-
line parameter used by the OPC and WITSML Plug
-
ins

REM
----------------------------------------------------------------------------

REM

REM /connecttimeout
=x Limits the time (in milliseconds) it takes to make

REM an initial connection with the XML server. After a

REM connection to the server has been established the

REM timeout prope
rty applies

REM

REM /timeout=x The timeout in milliseconds after a connection to

REM the XML server has been established. Communication

REM taking longer than this value will be dropped. The

REM

default value is 30,000 milliseconds.

REM

REM /authsceme=x Enables you to choose acceptable an authentication

REM mechanism that is supported by the XML server. The

REM va
lue of x corresponds to the following values.

REM 1
-

basic authentication

REM 2
-

ntlm authentication

REM 8
-

digest authentication

REM 16
-

negotiate authentication

REM Note that x is a bitmask so you can combine

REM these values (bitwise OR) to enable multiple

REM types of authentication. For example, to

REM

enable both basic and digest auth, x would be

REM set to 9 (1+8=9). The default value for this

REM property is 18 (ntlm and negotiate).

REM /authuser=x User f
or authentication

REM

REM /authpassword=x Password for authorizing user

REM

REM /proxyserver=x Identifies the proxy server (x) through which

REM messages are sent and received.

REM

REM /proxyuser=x The us
er name used for proxy authentication.

REM

REM /proxypass=x The password used for proxy authentication.

REM

REM /usessl Use ssl to encrypt communication, XML server

REM must support the use of SSL certific
ates

REM

REM OPC Plug
-
in specific optional command
-
line parameters

REM
----------------------------------------------------------------------------

REM

REM /locale=x Specifies the LocaleID to be requested by the

REM in
terface in communicating with the XML server

REM

REM /keep_alive_mult=x The keep alive multiplier tells the XML server how


WITSML Plug
-
in DLL for the XML Interface to the PI System

15

15

REM long to keep a subscription alive. Subscription are

REM kept alive at a rat
e that is equal to x times the

REM scan frequency.

REM

REM /ssr=x Specifies the Subscription rate ratio. The value of

REM x represents the number of values to obtain between

REM

each scan and can be used to increase data

REM throughput by buffering values on the XML
-
DA server.

REM The XML
-
DA server may revise this value downwards

REM automatically i
f they cannot support the data rate.

REM

REM /holdtime=x Instructs the XML server to hold off returning any

REM value until the specified absolute XML server time

REM (x) in milliseconds is reache
d.

REM

REM /waittime=x Instructs the XML server to wait for the specified

REM duration, x, after the holdtime is reached before

REM returning if there are no changes to report.

REM

Changes that occur during this time will be

REM immediately reported to the interface.

REM

REM /returnallitems XML server will return all values for each scan

REM

REM FileReader specific optional plug
-
in command
-
l
ine parameters

REM
----------------------------------------------------------------------------

REM

REM /purge=#c Time to wait before purging old *.old files

REM already scanned. The format of the time string

REM

should be a number followed by a one
-
digit letter,

REM which can be either h for hours, m for minutes,

REM s for seconds, or d for days

REM

REM /mask=file.ext Wildcard mask use to

specify a subset of

REM of files that exist in the XML directory

REM

REM /xsl=x Location of XSLT file;

REM Matches location of XSLT file used to transform raw

REM XML

into XML that conforms to the ReadResponse

REM extract of the OPC XML
-
DA schema (version 1.0)

REM

REM /xslout=path/file Location of output XSLT file;

REM Matches location of XSLT file used to transform

XML

REM that conforms to the WriteResponse extract of the

REM OPC XML
-
DA schema (v1.0) into any kind of XML

REM

REM /output=path Path;

REM Must match path where XML file
are to written to

REM for output points

REM

REM /xsd=path
\
filename Location of schema file for input XML validation

REM Matched location of schema file used to validate

REM XML
files that are read before transforming them.

REM

REM /dbll=x Print interface
-
level debug messages

Startup Command File

16


16

REM

REM Http plug
-
in command
-
line parameters

REM
----------------------------------------------------------------------------

REM

REM /xs
l=x

Location of XSLT file;

REM

Matches location of XSLT file used to transform raw

REM

XML into XML that conforms to the ReadResponse

REM

extract of the OPC XML
-
DA sch
ema (version 1.0)

REM

REM /xsd=path
\
filename

Location of schema file for input XML validation

REM

Matched location of schema file used to validate

REM

XML files that are read before transforming them.

REM

REM /user=x


Username for authentication

REM

REM /password=x Password for authentication

REM WITSML plug
-
in command
-
line parameters

REM
---------------------------------------------------------------------------
-

REM

REM NONE except the common ones between OPC and WITSML listed above.

REM

REM ****************************************************************************

REM * Uncomment the appropriate command lines for the Plug
-
in you wish to use, *

REM * by defaul
t the OPC Plug
-
in is already uncommented *

REM ****************************************************************************

REM

REM
----------------------------------------------------------------------------

REM Sample startup comma
nd line using FileReader Plug
-
in

REM
----------------------------------------------------------------------------

REM

REM .
\
pixml.exe /ps=X /id=1 /f=00:00:30 ^

REM /server="c:
\
XMLFiles
\
testfiles" ^

REM /dll=".
\
Plug
-
Ins
\
File Reader
\
PIXML_FileR
eader.dll" ^

REM /xsl="c:
\
XSLT
\
process.xsl"^

REM /xslout="c:
\
outputs
\
test.xsl" ^

REM /output="c:
\
output files" ^

REM /stopstat="Intf Shut"

REM

REM
----------------------------------------------------------------------------

REM
Sample startup command line using OPC Plug
-
in

REM
----------------------------------------------------------------------------

REM

REM .
\
pixml.exe /ps=X /id=1 /f=00:00:05 /f=00:00:10 /f=00:00:30 ^

REM /server="http://opcfoundation.org/XmlDaSampleSe
rver/Service.asmx" ^

REM /dll=".
\
Plug
-
Ins
\
OPC
\
PIXML_OPC.dll" /stopstat="Intf Shut"

REM

REM
----------------------------------------------------------------------------

REM Sample startup command line using
htt
p plu
g
-
in

REM
-------------------------
---------------------------------------------------

REM

REM .
\
pixml.exe /ps=X /id=1 /f=00:00:30 ^

REM /server="
http://www.testserver.com
" ^

R
EM /dll=".
\
Plug
-
Ins
\
http
\
PIXML_http
.dll" ^

REM /xsl="c:
\
XSLT
\
process.xsl"^


WITSML Plug
-
in DLL for the XML Interface to the PI System

17

17

REM

REM
-----------
-----------------------------------------------------------------

REM Sample startup command line using WITSML Plug
-
in

REM
----------------------------------------------------------------------------

.
\
pixml.exe /ps=x /id=1 /f=00:00:05 /f=00:00:10 /f=00:00
:30 ^


/server=
"http://sitecom.intellifield.no/SIv3/Store/Store
.asmx" ^


/dll=".
\
Plug
-
Ins
\
WITSML
\
PIXML_WITSML.dll" /stopstat="Intf Shut"

^


/sync_read


The above command line tells the Interface to



service PI points whose PointSource is X

and Location1 is 1,



define three scan classes with periods of 5, 10 and 30 seconds



connect to an XML server whose URL is
http://sitecom.intellifield.no/SIv3/Store/Store.asmx



use the post
-
processing dll for the
WITSML

specification



write
Intf Shut

to its l
ist of points upon exit, and



uses synchronous read operations which are required for this plug
-
in.

The installation program installs a sample command file named
pixml.bat.new
. If
you are not using the PI
-
ICU, you should use this file as a template for you
r own
pixml.bat
.



WITSML Plug
-
in DLL for the XML Interface to the PI System

19

19


Error and Informational Messages

A string
NameID
is pre
-
pended to error messages written to the message log.
Name
is a
non
-
configurable identifier that is no longer than 9 characters
.
ID

is a configurable
identifier that is no longer tha
n 9 characters and is specified using the
/id

flag on the
startup command line.

Message Logs

The location of the message log depends upon the platform on which the interface is
running. See the
UniInt End User Document

for more information.

Messages are
written to
PIHOME
\
dat
\
pipc.log

at the following times.



When the interface starts many informational messages are written to the log. These
include the version of the interface, the version of UniInt, the command
-
line
parameters used, and the number of poin
ts.



As the interface retrieves points, messages are sent to the log if there are any
problems with the configuration of the points.



If the
/db

is used on the command line, then various informational messages are
written to the log file.



System Errors and

PI Errors

System errors are associated with positive error numbers
.
Errors related to PI are
associated with negative error numbers
.

Error Descriptions

Descriptions of system and PI errors can be obtained with the
pidiag

utility:

\
PI
\
adm
\
pidiag

e
error
_number




WITSML Plug
-
in DLL for the XML Interface to the PI System

21

21

Revision History


Date

Author

Comments

17
-
Aug
-
04

AS
ingh

Rough Draft.

15
-
Nov
-
04

ASingh

Changed instrument tag to use nameWell instead of UID according
to user feedback. No support for output points yet. No support for
storing full XML strings
until requested as a need.

18
-
Jul
-
05

ASingh

Added connection settings info.

18
-
Aug
-
05

MPK
elly

Fixed Copyright page, removed all references to File Reader dll ,
fixed directory paths, updated ICU Control screenshots,
updated
TOC. Fixed headers and footers
.

22
-
Aug
-
05

ASingh

Addressed MPK comments.

30
-
Aug
-
05

MKelly

Made Final.

8
-
Dec
-
05

ASingh

Version 0.9.1.0 Rev A:
Updated bat file for version 1.2.0.0 release

16
-
Dec
-
05

Chrys

Version 0.9.1.0 Rev B: fixed headers & footers; clarified ICU fields