Download - CIMPLICITY HMI - OSIsoftcdn.osisoft.com/interfaces/1011/PI_GECimpi_1.1.0.doc · Web viewGE Fanuc Automation, CIMPLICITY HMI for Windows NT and Windows 95, Point Management API,

CIMPLICITY HMI Interface to the PI System

V 1.1.0 or Greater

OSI Software, Inc.

How to Contact UsPhone (510) 297-5800 (main number)

(510) 297-5828 (technical support)

Fax (510) 357-8136

Internet [email protected]

World Wide Web

http://www.osisoft.com

Bulletin Board

(510) 895-9423Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible)8 data bits, 1 stop bit, no parity, up to 14400 bps downloadprotocols: Xmodem, Ymodem, Zmodem, Kermit

Mail OSI Software, Inc.P.O. Box 727San Leandro, CA 94577-0427USA

OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1Deutschland

OSI Software, LTDP. O. Box 8256Level One, 6-8 Nugent StreetAuckland 3, New Zealand

Unpublished -- rights reserved under the copyright laws of the United States.RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure 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 registered trademark of OSI Software, Inc. Microsoft Windows, 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 trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.

document.doc

1997 OSI Software, Inc. All rights reserved777 Davis Street, Suite 250, San Leandro, CA 94577

Table of ContentsIntroduction........................................................................................................................1

PI Point Configuration.......................................................................................................3

Startup Parameters...........................................................................................................7

Installation, Start and Stop..............................................................................................11

Hints for the System Manager.........................................................................................17

How the Interface Operates............................................................................................20

March 22, 1999 iii

CIMPLICITY HMI Interface Documentation

IntroductionThe CIMPLICITY HMI Interface provides the transfer of data between “GE Fanuc Automations CIMPLICITY HMI for Windows NT and Windows 95” and the Plant Information (PI) System. The interface runs on a Windows NT Workstation or Server.

The interface reads data from one or multiple Cimplicity servers and sends them to the PI server. It may be located on the PI server or one of the Cimplicity servers or – most typically – a node of its own. The interface can be run in multiple copies. A convenient – and recommended – configuration will be to run one copy for each Cimplicity project used.

The node the interface runs on is called the interface node in this document. If the interface is running on a node apart from the PI server, this node is also called a pure interface node.

The interface communicates to Cimplicity via Cimplicity Point Management API calls. It makes internal use of the PI-API-NT in order to keep a standard way of interfacing from a client node to the PI Server Node.

March 22, 1999 1

1


References:

GE Fanuc Automation, CIMPLICITY HMI for Windows NT and Windows 95,Base System, User’s Manual, GFK-1180F, October 97

GE Fanuc Automation, CIMPLICITY HMI for Windows NT and Windows 95,Point Management API, Application Developer Guide, GFK-1201C,April 1997

OSI Software Inc., PI2 Data Archive, several versions

OSI Software Inc., PI3 Data Archive, several versions

OSI Software Inc., PI-API, several versions

OSI Software Inc., Uniint End User Interface Documentation, Uniint version 2.34,November 1997

OSI Software Inc., OSI bufserv, July 1997

OSI Software Inc., OSI Interface Control Program, V 2.0, March 1999

Supported Features

Interface Platforms supported Windows NT (tested for Intel)

Order Code GmbH

Vendor Software Required Yes

Sign up for Updates Yes

Exception Reporting Yes

PI API Node Support Yes

UNIINT Yes

Input scanned, on change, on PI event

Outputs No

Text Transfer Convertible to Digital

Configuration Data Automatic extraction, changes manually or by user tools

Multiple Links Yes

Failover Yes for Cimplicity servers, No for interface node, No for PI server

Number of Points Unlimited

2 March 22, 1999


PI Point ConfigurationThe following database details are necessary for configuring a PI point for use with the Cimplicity interface.

Point Name

The point name is free, according to the normal PI point naming conventions. Watch that if the PI server is a PI 2 (=VMS based) server, tag names are much shorter (10 significant characters) than Cimplicity point ids (40). You may use the point id as a long tagname with client software, but that does not prevent you from having to generate unique 10 character tagnames for your tags.

Point Source

The point source is a single character, for example I (C-I-MPLICITY). Note, however, that the character C is reserved for another purpose in PI. For PI 2 servers the point source must be defined in the point source library before point configuration. If you are running multiple copies of the interface you may also use multiple point sources.

Point Type

The interface supports the PI point types real R, integer I and digital D. It performs the following Cimplicity to PI data type conversions:

PI Point Type Cimplicity Data TypeREAL INT(a) BOOL BITS(b) STRING others

I Yes(c) Yes - - - -

R Yes Yes(d) - - - -

D - Yes Yes Yes(e) Yes(f) -

S - - - - Yes -

(a) USINT, UINT, UDINT, SINT, INT, DINT(b) BYTE, WORD, DWORD(c) rounded(d) If a conversion to real is defined for a point (engineering unit conversion), the interface makes use of it.(e) The extended desciptor is used to specify the bit number (see below).(f) If the first 12 characters of the string match one of the digital states defined for the tag, this state becomes the value of the tag else the digital start code.

If the Cimplicity point referenced is a complex type (array, structure or bitstring), the component the PI tag refers to is selected in the extended descriptor (see there). Only one level of selection is supported.

For digital tags that are converted from Cimplicity strings special restrictions must be observed: They all have to refer to the same digital start code and range (PI2) or digital set resp. (PI3) and the range should be not too big (say 200 if you assume 100 different string texts to be used). So all those tags have to share the same digital states even if each one of them will only use a subset. If you do not observe this, some tags will be rejected by the interface. If you set the range too

March 22, 1999 3

3


big, this might put an unnecessary load on the interface when many string values arrive.

If the interface reads a Cimplicity string that is defined as PI point type digital that is not in the state table/set, it uses the first value of the range instead. So set the first state of the range to something like “unknown text”. Further on after a change of the state table/set you must restart the interface in order for it to recognize it.

If the Cimplicity string is defined as a string also in PI, it copies the first 80 characters into PI.

Instrument Tag

This field contains the Cimplicity point id. Do not use fully qualified point ids (like \\project\pointid) here. The interface generates fully qualified pointids using location 2 and the instrument tag.

Location 1

This is the number of the interface process, determined to collect data for this tag. The interface can run multiple times to distribute CPU power. E.g. it is possible to give a number of tags that are to be scanned with a high frequency a separate process.

The value you enter here must be the same as the parameter /id in the startup file of the according interface process.

Location 2

Specifies the point’s Cimplicity project. This number refers to one of the /project=<project_name> startup parameters. It specifies which of these /project parameters in their order in the startup line names the points project. Counting starts by 1.

Location 3

Not used, must be 0.

Location 4

Specifies the scan class used.

The startup command procedure contains an interface start line that includes parameters like /f=00:00:30. These parameters specify the scan rate, that is the cycle time for scan classes. The first /f= in their order in the startup line relates to scan class 1 etc.

Note however that the first scan class (1) is not used for periodic scanning but for values to be received ‘on change’. The scan rate in this case determines the cycle time the interface looks for new values received ‘by change’. Every such cycle time the interface will process all new values received. The first scan rate has to be set like the others but should normally be 1 second.

Note that it is assumed that all values for a point written to PI are in ascending time order. In order to assure this the interface discards any values out of this order.

Location 5

Not used, must be 0.

4 March 22, 1999


Extended Descriptor

The Extended Descriptor is used for 2 purposes. The specifications are done using keywords. Valid keywords are: EVENT, BIT, ELEMENT, COMPONENT.

The first purpose is to trigger the update of the point by a change of value of another PI tag. Use EVENT=<other tag>. The tag requests a value from Cimplicity whenever the specified PI event tag changes value (has an event).

The second purpose is to specify – in the case of a complex Cimplicity point – the unit to make up the value for the PI point. Complex Cimplicity points are bitstrings, arrays or structures. Bitstrings correspond to the data types BYTE, WORD and DWORD. Bitstrings consist of bits, arrays of elements and structures of components. Use BIT=<bit number> or ELEMENT=<element number> or COMPONENT=<component name>. Bit and element numbers counting starts by 0. No spaces are allowed before or after the = sign.

Engineering Units

The Engineering Units have to be defined in accordance with the meaning of the measured values.

Scan Flag

This is usually ON for all points of this interface. If you edit this Point Attribute to OFF, then the tag is OFFLINE (no values are exchanged for this tag).

Exception Maximum Time

Apart from the standard usage the excmax attribute is used for a special purpose. The interface uses this time for an automatic refresh for tags that change infrequently. Whenever a tag has not got a new value for excmax time, a new value is scanned from Cimplicity and timestamped with the PI Server time at receiption of the value. An excmax value of 0 is interpreted as the default value 28800.

Note that this is a means to recover from a Cimplicity problem: When a Cimplicity project is stopped (or more generally when there is a disconnection to a Cimplicity server or project), Cimplicity sends a ‘point unreachable’ value to the interface. This is turned to an ‘I/O Timeout’ for the tag by the interface. Unfortunately Cimplicity does not send a new value with a new timestamp after restart of the project or reconnect. The only way for the interface to detect the reconnect is to use the automatic refresh feature. So users are encouraged to make extensive use of the feature and use reasonable settings for the exception and compression parameters. Otherwise an I/O Timeout is reported for tags for a much longer time than true.

Other Exception Reporting

Standard PI usage, see PI System Manuals.

Zero, Span

Standard PI usage, see PI System Manuals.

Other Attributes

The Interface does not use the other PI tag attributes.

March 22, 1999 5

5


Conversion of configuration data

Cimplicity allows to extract configuration information to .csv or text files. These can be used to PI configuration input files with not too much effort. The actual details are left to the user, no conversion tool is supplied.

The following Cimplicity point attributes are needed for PI point configuration: point id, data type, eng unit, zero, span, eventually array element, bit number, structure component.

For PI 2 systems it may be difficult to change Cimplicity point ids to – normally much shorter – PI tag names. The point id must also be used for the instrument tag name.

Another task often found difficult is to define digital states for PI and digital start code (PI 2) or digital set (PI 3) for tags from texts used in Cimplicity. It is very useful to have all these texts available in lists.

The following is a list of steps typically needed for conversion:- group Cimplicity points by server: interface number = location 1- group by project: project number = location 2- group by scan frequency or on change: scan class = location 4- or group by common event point: ext. descr. EVENT=<event point>- default data type conversion INT to R, REAL to R, BOOL to D, BYTE to D etc.- for all bit strings: ext. descr. BIT=<bit number>- for all arrays: ext. descr. ELEMENT=<element number>- for all structures: ext. descr. COMPONENT=<component name>- take over engineering units, point id (to tag name and instrument tag)- take over zero, take over or calculate span- set for groups of points: exception specs, compression specs

6 March 22, 1999


Startup ParametersThe following table (values shown are defaults) describes the meaning and use of the most important parameters. Following are descriptions for less often used ones and test and debug helps.

/ps=I (required) Point source. For Point Source see also Chapter „Installation“.

/id=1 (optional, 1..99) Interface number. The interface number corresponds to Location 1 of a tag. All tags with that Location 1 will be serviced by that interface.

/project=CIMPROJECT

(One required, more optional, no default) Cimplicity project name.

Projects are selected by Location 2 of a Tag. If for example a tag has Location 2=3, then it refers to the 3 rd occurring /project=... in the start line of the interface. Location 2 specifies the order number of the /project parameters (starting by 1).

/f=00:00:20[,00:00:03]or/f=20,[3]

(One required, more optional, no default) Scan class frequency.

Scan frequencies are selected by Location 4 of a Tag. If for example a tag has Location 4=1, then it gets values in frequencies of the first occurring parameter /f=... in the start line of the interface. Location 4 specifies the order number of the /f parameters (starting by 1).

The first scan frequency is special in that it specifies the frequency to look for all values received for ‘on change’ tags. It should normally be 1 second.

/time=FOREIGN (optional, FOREIGN, SERVER, ADJUSTED) This parameter decides what time stamp is used for values received from Cimplicity: the time stamp sent from Cimplicity (FOREIGN), the time on the PI server when the interface receives the value (SERVER) or the Cimplicity time adjusted ‘as good as the interface can find out’ to the PI server time (ADJUSTED). Note that Cimplicity returned timestamp is the last time the value changed, not the time the value was scanned by Cimplicity. If a tag does not change value for a long time and exception maximum time passes, the corresponding PI tag will start getting PI timestamps regardless of the time option specified by this switch. User needs to be aware that if the tag finally changes value and new timestamp comes in and user specified /time=FOREIGN this new timestamp has to be later than the previously recorded PI timestamp ( at every excmax intervals), otherwise it will be considered out of order and discarded. If Cimplicity server node and the API node are synchronized within the scan frequency of the tag the new value will get through and sent to PI, however.

/host=localhost:5450 (optional,server_name:portnumber, default is the default PI server) Hostname of the PI Server to connect to. If this interface runs on a PI3 server, this should be /host=localhost:5450.

/stopstat[=Shutdown] (optional) Write status on shutdown. Not specifying this March 22, 1999 7

7


parameter at all means writing no status at all. Specifying /stopstat but no value means writing I/O Timeout.

/subsec[=no] (optional) If set to yes, this switch enables subsecond scanning

Remarks to Parameters

The timestamps for certain values must be taken from the PI Server. These are the first value for each tag after interface start, a value received by the automatic refresh mechanism and statuses written on shutdown.

If the /time parameter values FOREIGN or ADJUSTED are used and the PI Server system time is considerably different from the Cimplicity Server system time strange effects can happen for values at the start, after automatic refresh and at shutdown of the interfaces: values can easily get in the wrong order. Please make sure to set the PI Server time close to the Cimplicity server time if the /time parameter is FOREIGN or ADJUSTED.

The /time parameter value ADJUSTED is not recommended to be used. It depends on a reliable source to calculate the time difference between the PI and Cimplicity servers. There is no reliable source available to the interface - only a good guess.

Uniint Parameters

/ec=1 (optional, 1..34 or 51..200, default 1) Event counter number. Selects an event counter tag with the corresponding number in iorates.dat (typically in C:\pipc\dat). This tag is to measure the rate of events received from Cimplicity (unit 1/min). See the Data Archive documentation on this topic and how to configure event counters. Use different event counters for different copies of the interface.

There are several other parameters introduced by Uniint. As Uniint is a common frame for many interfaces there are parameters that only apply to some. See an appropriate Uniint document for more parameters.

Setup Parameters

/cimwait=0 (optional, 0..600000) The wait time in ms for Cimplicity to be initialized. If the interface is started manually, Cimplicity is expected to be started before. In the case of a reboot and both being started automatically there may be some time needed for Cimplicity to be initialized. If the wait time is over and Cimplicity is not initialized, the interface exits on error./exoncerr=YES (optional, YES or NO) ‘Exit on connection error’. This flag tells the interface if it should exit on an initial connection error to a project. An initial connection error normally means that a project that the interface wants to access for a tag is stopped on interface start. The interface is not able to detect a project start after its own start (it can however come over a project stop and restart after its own start). In order for an interface to catch up the project it must be restarted by operator interaction after the project start. If exoncerr is true and a project cannot be connected, the interface waits for 1 minute to exit (in order to keep automatic restart tries low). It can be shut down during this time by the user. If exoncerr is false and a project cannot be connected, an operator must look after the start of the project and then restart the interface./maxchtim=10000 (optional,1..20000) Max time to look for on change results in one try – in ms.

/maxsctr=1 (optional,1..1200) Max scan tries. See the /sctrtim parameter below.

/sctrtim=0 (optional,100..10000) Scan try time in ms. This time is used for scans and automatic refresh scans. If this time is 0, the interface requests a scan to

8 March 22, 1999


Cimplicity, waits for a grant and reads all data supplied by Cimplicity for this scan. If this value is not 0, the interface requests a scan, does not wait for a grant and tries in /maxsctr loops to get data for all tags in the scan. It waits /sctrtim ms before each try. It exits the loop prematurely when all tags have been covered. According to GE Fanuc the wait for a grant may block the interface in some unusual situations (which has never taken place during tests). On the other hand according to GE Fanuc the ‘several tries solution’ may not to be completely reliable in all situations (but was always during tests).

/hibtim=500 (optional,100..2000) Hibernation time in ms. This is the time the interface releases the CPU after every ‘internal cycle’ during normal operation (that means after the startup phase).

/maxchlst=1 (optional,0..9) Max on change lists. For test purposes only.

Debug Help Parameters

/deb=0 (optional,0..5) Debug level for interface. The higher the level the more detailed debug information is output.

/datadeb=n (optional,0..9, default=/deb) Debug level for interface at the start of the ‘data phase’, that is after the configuration phase. Used to start with a low level to avoid configuration logs and change to a high level as soon as data acquisition begins./output=C:\CIMPI.LOG (optional, no default) Output file name, all messages will be written to that file. If this parameter is not used at all, no output is written. If it is used without a value (just /output) the common log file PIPC.LOG is used. If interface specific log files are used there must be separate ones for different copies./lineleng=200 (optional,20..200) This is the maximum line length for the log file. Lines ar e wrapped if they exceed that length./logtimfm=1 (optional,1,2 or 3) This is the format for the time stamp used in interface specific log files. 1 is abolute timestamp and recommended for product interfaces. 2 is seconds since interface start and can be a debugging help. 3 is no time stamp./interact= NO (optional, YES or NO) ‘Debug output to screen’. For test purposes only./select=filename (optional, no default) Select certain tags for debug purposes. You can list up to 10 tags each in a line PITAG=tagname. The first line however selects a mode: With SELECT=DEBUG all tags for this interface are used but for the ones listed in <filename> more information is logged. With SELECT=USE only the ones listed in <filename> are used at all by the interface. The others will be rejected and get no data.

Notes for NTFor NT, command file names have a .bat extension. The NT continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The maximum number of flags is 128, and each flag can be a maximum of 128 characters long.

Notes for UNIXFor UNIX, command file names typically have a .sh extension, but UNIX does not enforce file-naming conventions. The backslash (\) continuation character allows one to use multiple lines for the startup command. There is no limit to the command-line length and there is no limit to the number or length of the command line parameters.

Notes for VMS

March 22, 1999 9

9


For VMS, command file names have a .com extension. The VMS continuation character (-) allows one to use multiple lines in the command file. However, the maximum number of characters for a single or multi-line command is 256 characters. That is, the continuation character does not extend the 256-character limitation.

10 March 22, 1999


Installation, Start and StopPreconditions

Some of the preparations for the interface have to be done on the PI server, some on the interface node. Some of the preparations are a different for PI 2 servers to PI 3 servers.

On PI 2 systems make sure the PISERVER.DAT file is correct and the PISERVER software running.

To install the interface, you must select a point source code.

In the PI2 System Point Source Editor set up the following values:Point Source Code: e.g. IPoint Source Descriptor: CIMPLICITY

Location Minimum 1 0 0 0 0

Location Maximum 99 99 0 99 0

For PI3 Systems no Location Parameter Limits need to be specified.

If you want to monitor the working of the interface via event counters, you create a tag for each copy of the interface you monitor. You may copy most of the attributes from the PI system tag for the snapshot event count (SYSNP001) and name it SYCIM00n for interface copy n. (Note that the point source is ‘L’, not ‘I’). On the interface node you create or edit the text file C:\PIPC\dat\iorates.dat by a line

SYCIM00n,m

For each event counter. m must be a number between 1 and 34. You must use a different number for each event counter and use that number in the /ec=m startup argument for the interface copy.

The interface needs the PI-API software to be installed on the interface node. It also normally needs the PI buffer server to be installed unless the interface runs on the PI server. PI client software (like ProcessBook or DataLink) may be installed for test purposes but is normally removed afterwards. The PI-API is automatically installed with PI server or client software. See the PI-API manual and bufserv manual for details. Contact OSI if you do not hold these manuals yet.

The documents mentioned tell you how to set up the environment using the files PIPC.INI, PILOGIN.INI and PICLIENT.INI. These settings normally set the path for the interface root to C:\PIPC as assumed in this document (it may be C:\PI on PI servers). Beyond this there must be a subdirectory interfaces. Beyond this you must create a subdirectory for the interface named cimpi (resulting in C:\PIPC\interfaces\cimpi). There you put the interface startup files CIMPI1.BAT and CIMPI1.EXE. If you are running multiple copies of the interface you must copy CIMPI1.BAT to CIMPIn.BAT and CIMPI1.EXE to CIMPIn.EXE (with n = 2,3,…) on the same directory and edit the /id argument in CIMPIn.BAT to n.

In CIMPIn.BAT you decide whether to create and where to put the interface log files. A reasonable setting was to create CIMPIn.LOG on the same directory.

March 22, 1999 11

11


Before installing the Interface itself, the Cimplicity software needs to be installed and the appropriate connections to the Cimplicity servers have to be configured.

InstallationYou may receive the interface on CD or diskette, via mail or ftp. You will get a zipped file or self extracting archive or the target file itself. This will normally be cimpi.exe or cimpi1.exe. Direct the files to the target directory. There may be a .BAT file coming with it or you can easily edit one on your own. See the startup parameters part in this manual to set up the interface to your needs. You may get the control program separately or with the interface.

1. Create the following directory:

c:\PI\interfaces\CIMPI#\ if running on a PI3 home node or

c:\pipc\interfaces\CIMPI#\ if running on a PI API node

# should be replaced by a number between 1 and 99, inclusive. # should correspond to the interface number that is specified using the /id flag in the CIMPI#.bat file. The user should create one directory for each version of the interface that he or she wishes to implement.

2. Insert the installation disk, and execute the following commands from an MsDos prompt:copy b:\CIMPI.exe c:\PI\interfaces\CIMPI#\CIMPI#.execopy b:\CIMPI.bat c:\PI\interfaces\CIMPI#\CIMPI#.batAs mentioned above, # should correspond to the interface number that is specified using the /id flag in the CIMPI#.bat file.

3. Modify the command-line arguments in your CIMPI#.bat file to customize your interface. For example, ..\interfaces\CIMPI1\CIMPI1.exe /id=1 /q /ps=M /f=00:01:00 The command-line arguments are discussed earlier in this manual. See also the notes in the preceding section on the characters per line limits in the startup file.

4. Running the interface either manually or as a service is discussed below. Manual startup is recommended the first time the interface is started because manual startup is easier to troubleshoot.

To run as a serviceThe procedure for installing the GE CIMPLICITY interface as a service depends upon whether or not Bufserv is being used. Once the interface has been installed as a service, the procedure for starting, stopping and removing the interface as a service is the same whether or not Bufserv is used. The purpose of the Bufserv utility is to continue to collect data from an interface in the event that the PI Data Archive is shut down for some reason.

For example, if the GE CIMPLICITY interface is installed on the PI home node and the PI Data Archive is shut down for an upgrade, the Bufserv utility on the PI home node will buffer the data in a file until the PI Data Archive is brought back online.

Another possibility is that the GE CIMPLICITY interface is installed on an API node. If there are problems with the PI home node, then the Bufserv utility on the API node will buffer the data in a file until the PI home node is brought back online.

12 March 22, 1999


The procedure for installing the interface in conjunction with the Bufserv Utility assumes that the user has Bufserv 1.04 or higher because the procedure implicitly assumes that Bufserv will be installed as a service (bufserv could not be run as service prior to version 1.04). The actual installation of the Bufserv Utility itself is not discussed in this documentation. For these instructions, the user is referred to the PI-API Bufserv 1.x Release Notes . Also, the installation procedure below does not discuss the details related to shutdown events that the user should be aware of when the Bufserv Utility is used. For more information, refer to the PI-API Bufserv 1.x Release Notes .

To run as a service, complete the following steps:

1. One can get help for installing the interface a service at any time by typing the following:

CIMPI# -helpNote that the –query flag that is described when help is invoked is not implemented at this time.

The CIMPI# service can be installed either as a manual or an automatic service. Automatic services are started automatically when the NT operating system is rebooted. This feature is useful in the event of a power failure. To install the interface as a manual service, execute the following command from the CIMPI#\ directory.

Without Bufserv:CIMPI# -install -depend tcpipWith Bufserv:CIMPI# -install -depend "tcpip bufserv"

To install the interface as an automatic service, execute the following command from the CIMPI#\ directory.

Without Bufserv:CIMPI# -install –auto -depend tcpipWith Bufserv:CIMPI# -install –auto -depend "tcpip bufserv"Check the Microsoft Windows NT services control panel to verify that the service has been successfully added. One can use the services control panel at any time to change the CIMPI# service from an automatic service to a manual service or vice versa. Once the CIMPI# service has been installed, the rest of the procedure is the same whether or not Bufserv has been implemented. The CIMPI# service can be started from the services control panel or by executing the following command from the CIMPI#\ directory:CIMPI# -startA message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. If the service is successfully started, the interface will attempt to read the command-line arguments from the CIMPI#.bat file. For this to succeed the root name (the part of the file name before the .exe and .bat extensions) of the batch file must be the same as the root name of the executable. Also, the batch file and the executable file must be in the same directory. If the interface is unable to read the command-line arguments or if the command-line arguments that the interface reads are invalid, the service will terminate with no error messages echoed to the screen.For this reason, the user MUST check the pipc.log file to verify that the interface is running correctly. In the pipc.log file, messages pertaining to the GE CIMPLICITY

March 22, 1999 13

13


interface will be prepended by CIMPI #>. The location of the pipc.log file is determined by the PIHOME entry in the pipc.ini file. The pipc.ini file is located in the WinNT directory. Usually, the pipc.log file will reside in the c:\pipc\dat\ directory. If the service was successfully started, the user can verify that the service is still running from the services control panel. If the service has been terminated, the reason for its termination will be given in the pipc.log file. If the service is still running, the user can use c:\PI\bin\apisnap.exe or ProcessBook to verify that data is being successfully transferred to the PI Data Archive.The CIMPI# service can be stopped at any time by issuing the following command:CIMPI# -stopThe CIMPI# service can be removed byCIMPI# -remove

2. If the CIMPI# service is installed as a manual service on the PI home node, the user may wish to edit the c:\PI\adm\pisrvsitestart.bat and the c:\PI\adm\pisrvsitestop.bat command files. These command files are invoked only when the PI data archive is started and stopped as a manual service with the c:\PI\adm\pisrvstart.bat and the c:\PI\adm\pisitestop.bat command files. In the c:\PI\adm\pisrvsitestart.bat file, make sure that the second to last line ends in& wait 5000 If not, append "& wait 5000" to the end of the line. In the same file, add the following command just above ":theend"C:\PI\interfaces\CIMPI#\CIMPI# -start & wait 5000Add the following command to the c:\PI\adm\pisrvsitestop.bat file just above ":theend"C:\PI\interfaces\CIMPI#\CIMPI# -stopNote that the full path name to the CIMPI# executable must be given in both the c:\PI\adm\pisrvsitestart.bat and the c:\PI\adm\pisrvsitestop.bat command files.

Important Node: Running cimpi interface successfully as a service requires that user configures Cimplicity project’s security settings correctly. If this is not done properly, no data will be collected. If cimpi service is configured with the following Log On As account (SYSTEM account),

14 March 22, 1999


then, in Cimplicity project’s Workbench, under Security/Users, cimpi’s LogOnAs account must be in User ID column.

To run in interactive modeTo run in interactive mode, complete the following steps

1. Execute the following command from an Ms Dos prompt:cd c:\PI\interfacesstart "CIMPI#" CIMPI#\CIMPI#.bat A new Ms Dos window will appear, and the user will see several messages echoed to the screen. Then the messages will simply stop. The user will not regain a command prompt on the mdse. window until the interface has been stopped. Pressing <CNTRL-C> key combination while the Ms Dos window is selected stops the interface. The user can use c:\PI\bin\apisnap.exe or ProcessBook to verify that data is being successfully transferred to the PI Data Archive.Check whether there is any error messages to verify successful execution of the interface. Messages that are sent to the screen are also sent to the pipc.log file. Check the pipc.log file. Some messages are written to this file that are not echoed to the screen when the interface is started up. Messages in the pipc.log file that pertain to the GE CIMPLICITY interface will be pre-pended by CIMPI #>. The location of the pipc.log file is determined by the PIHOME entry in the pipc.ini file. The pipc.ini file is located in the WinNT directory. Usually, the pipc.log file will be placed in the c:\pipc\dat\ directory.

2. If you plan on starting both the PI Data Archive and the GE CIMPLICITY interface manually, you may wish to start the GE CIMPLICITY interface along with the PI data archive. To do this you must edit the c:\PI\adm\pisitestart.bat command file (there is no such thing as a c:\PI\adm\pisitestop.bat command file). Make sure that the last line of the c:\PI\adm\pisitestart.bat file ends in:

March 22, 1999 15

15


& wait 5000 If not, append "& wait 5000" to the end of the line. In the same file, add the following two commands:echo Starting CIMPI# Interfacestart "CIMPI#" /min ..\interfaces\CIMPI#\CIMPI#.bat & wait 5000The CIMPI# interface should now be started in interactive mode. The /min flag minimizes the Ms Dos window that is created when the GE CIMPLICITY interface is executed.

Stopping the interface You can shutdown the interface via the control program (see the document on the control program). You must connect to the interface copy you want to stop and use the shutdown command.If the Interface runs interactively, you can also stop it by closing the Command Window or press Ctrl-C.Shutdown by the control program is ‘synchronous’ shutdown and requires the program to pass a certain point to notify the request. The other methods are ‘asynchronous’ (they will call the exit handler of the interface) and are more powerful (they would also shutdown a ‘hanging’ program). The control program is the more proper way to stop, but there is no practical reason to not recommend abortion of the program.For all ways to shutdown the shutdown procedure may take a while in order to leave the Cimplicity software in a correct status.

To install debug symbolsTo install the debug symbols (for version which offer these), copy the file cimpi.dbg to directory

%SystemRoot%\Symbols\exe

Service Control Manager can use the symbols contained in this file to match Dr. Watson dumps with the extracted symbol information. This directory is usually created by PI 3.2 installation program. If it does not exist, however, user should create it.

Dr. Watson is installed as the default debugger by typing

drwtsn32 –I

in Command window.

16 March 22, 1999


Hints for the System ManagerSoftware Environment and Installation

The interface needs the PI-API to be installed. This may already have taken place with other PI products (PI server, interfaces or client software) or may take place in context with the installation of the interface. See the PI-API manual if necessary.

If the interface node is a pure interface node you normally want to use buffering. Buffering enables interfaces on API nodes to carry on collecting data even if the connection to the PI server is down (e.g. because the PI server is down or because of network problems). As soon as the server is back again, the buffered data are transferred to it. Buffering is done by the buffer server which comes with the PI-API. See the PI-API manual. There are special installation hints for the buffer server on WindowsNT (install it as a service). See the bufserv manual. Note that the buffer server must be started prior to the interface.

Within the Cimplicity installation you need to have the ‘Application’ option ticked. Contact GE Fanuc in case of problems obviously due to Cimplicity installation.

To avoid that an interface has to login to a Cimplicity project the interface node has to be set up in the project’s client configuration (on the Cimplicity server) accordingly. An interface running as a service that needs to login would hang.

If you want to use multiple copies of the interface you have to create appropriate .BAT files for each copy (naming is expected to be CIMPIn… for n=1, 2, etc. CIMPI stands for CIMPIn in the following). If you want to run them as a service you have also to copy the interface .EXE, name them like their .BAT and use that name within the .BAT. For each of the copies you have to install it once using ‘CIMPI –install’. You can then use the Control Panel/Services for further settings. For automatic start on boot and dependency on bufserv see the bufserv manual. You could remove it using ‘CIMPI –remove’. After it is installed you can start and stop it using ‘CIMPI –start’. Note that you must stop it using the control program. ‘CIMPI -stop’ does not work.

The Cimplicity point attributes ‘analog_deadband’ and ‘scan’ have an impact on the interface, especially on the number and worth of the values requested on change (assumed to be widely used). Set them with care considering the points overall usage. You may even consider to create different Cimplicity points with the same source for different purposes.

There are a few reasons, the interface could exit on on purpose without being stopped by the users. They are not expected when Cimplicity projects and the interface work normally. For safety reasons it may be desirable hovever to try an automatic restart of the interface after certain exits. The interface supports this by using meaningful exit codes that can be evaluated from the calling procedure. It exits with 0 on a user-initiated shutdown, 1 or 2 on abort, and 3 in case of an error that might vanish after one or several restarts. The evaluation of the exitcode is left to the user. (In interactive mode the environment variable ERRORLEVEL can be used directly after the interface call in a .BAT procedure. In service mode it is much more difficult because a .BAT procedure cannot be started as a service. A shell program using the C standard library routine ‘system’ may be used).

March 22, 1999 17

17


Control Program

The interface can be monitored and stopped by a control program. This is a separate product with a separate manual. The keyword needed in CPPI.INI for this interface is CIMPI. Note that the control program can be used easily for interactive interfaces. For interfaces running as a service you need them to be set up like bufserv for the interfaces (run from account with adminitrative rights). Execute the setup carefully as you can normally not stop a service interface if the control program cannot connect.

The control features include:

- Setting the level of debug messages to the interface log file. The higher the debug level the more detailed infos are given. This is a means for debugging in a installation and test period and a means of problem analysis in the case of unforeseen problems in normal operation.

- Setting parameters to control the behaviour of the interface. Like timeouts, delays max and min values of operation etc.

The monitoring features include:

- Getting statistical information about points.

- Getting statistical information about values.

- Watching the actual data throughput.

There are free commands that the user can use in the command window. These are used for test and debug and for remote analysis in case of a problem (in addition to the log file). Therefore they are listed here but not explained.- HELP- SET SLEEP n (n = milliseconds)- SHOW ARGUMENTS n (n=1,2,…)- SHOW SETTINGS n (n=1,2,…)- SHOW VARIABLES n (n=1,2,…)- REPEAT- LOG ON | OFF

Error and information messages

You can find messages from the interface in 3 places:

In the command window if it is run interactively.

On the PI server in the server’s message log (OpenVMS: pilogfile, NT: use pigetmsg). Start, stop and other important messages are logged there.

The interface puts its error and information messages there except for messages from fatal errors that prevented the interface from starting up.

On the interface node to PIPC.LOG or the user defined interface output file. The messages written to the output file depend on the debug level (see there). The output file can be copied and the copy read during interface operation (instead of only after interface shutdown). This feature caused the file not be readable by notepad. Use wordpad e.g. instead.

Error statuses for tags:

Errors related to tag values being not available are reported in giving the tag an I/O Timeout state. This happens, if the status of a value derived from Cimplicity is ‘unavailable’.

Input tags also get a status of I/O Timeout if the Interface detects connection problems to a Cimplicity server or project.

Input tags get a status of Bad Input when reported ‘out of range’ by Cimplicity.

18 March 22, 1999


Tags get a status of Shutdown on interface shutdown, provided it has been started with a startup parameter of /shutdown=Shutdown (recommended).

The interface consists of Uniint, which is a frame common to many interfaces, of the Cimplicity specific part (the one this manual covers), the PI-API and the Cimplicity Point Management API. Uniint writes messages to the screen, the server log file and PIPC.LOG but not to the interface specific output file. The Cimplicity API was expected not to write to the screen. It did so however in cases, that allowed the interface to continue but were obviously error messages. The interface has no control over printouts from other parts in its context.

Creating and Editing PI Tags

The interface notices PI tags created, deleted or changed during operation but can process the changes only with considerable delay and effort. Therefore it is strongly recommended if you have a lot of changes (say more than 10) to stop the interface, do the changes and then restart the interface.

Debug Messages

Debug levels:

0 Start time, interface version, exit time, exit reason.

1 User configuration errors.

2 Unexpected errors that allow to continue working but may be an indication of wrong usage or serious problems.

3 Main steps, periodic status, periodic statistics.

4 Every point configured with tag, every scan with class or event and result, every hibernation, every remove tag with tag.

5 Every point configured with details, every event with details.

The interface can normally be run with level 3 for a long time (months). The log file would grow but should not take too much space and should still be of a ‘readable’ size. Look for messages that you get with level 1 or 2. These should be meaningful for you to confirm if the PI and Cimplicity point configurations are correct. When the system is stable for a long time and no changes are made you may just run the interface with level 0. In cases of problem analysis it may be necessary to use level 4 or 5. Watch however that you can get tenthousands of lines within few seconds if you have thousands of points and there are problems or lots of values. Use the control program (and eventually the /datadeb switch) to set the level back to at most 3 soon.

Test

The interface was tested under the following test environment: Interface node

separate from Cimplicity and PI Servers MS WindowsNT 4.0 SP3 Intel generated by MS Visual C++ V5.0 SP3 enterprise edition Cimplicity Viewer 4.0 Build 743

PI server node ALPHA/VMS PI 2.1.1

2 Cimplicity servers Cimplicity 4.0 1 server with 1 project (11000 points), 1 with 2 (8000,200)

March 22, 1999 19

19


How the Interface OperatesStartup

At startup, the interface checks all command line parameters. If one of them is out of range, the interface generates an error-message and stops. If the parameters are all right, the interface runs the initialization part. The first step is to open a connection to the PI Server in order to be able to retrieve necessary tag information.

After successful connection to the PI Server, the interface runs the initialization to the Cimplicity point management API. If Cimplicity is not running or not ready, the interface will stop with an error message.

Point Configuration

After successful startup the configuration phase is started. The interface asks PI for all points belonging to the point source and id as specified in the interface’s startup parameters and generates a list of PI tags assigned to this interface. For each tag it does the following and likewise later on during normal operation if a new tag is created:

According to the definition of the tag, it belongs to one of three types of update lists: the list of tags to be updated on change (onchange list), one of the lists of tags to be updated periodically (scan list) or one of the lists of tags to be updated whenever a certain event tag updates (event list). For each of these lists needed for one or more tags the interface adds a Cimplicity shopping list. It adds each tag to its shopping list, the onchange tags are added ‘on change’ the others ‘for snapshot’.

If a tag is deleted, the interface cancels its shopping list request and removes it. If it is the last one on its shopping list, the list is removed.

After the configuration phase the interface sets all shopping lists enabled.

Data acquisition - Input

Now the interface controls whenever one of the scan periods is due. This includes the onchange ‘scan rate’ which should normally be 1 second. It also controls whenever one of the event tags updates. At any such events the input processing of the corresponding list and shopping list is triggered. The onchange list is treated different from the scan lists and event lists the two of which are treated the same.

The interface fetches the onchange shopping list points’ new values (get shopping list) until there are no new values. Then it sends the values to PI. In case there is a second new value for one tag, it sends the values received up to then to PI and afterwards resumes fetching data.

For each run for a scan or event list the interface sends the shopping list request and waits for the collection of all results (snapshots). Then it fetches the results (get shopping list) and sends them to PI.

Data acquisition – Input Refresh

At the end of each periodic or onchange scan the interface investigates for a number of points if they have got a value in their last excmax time. If not a snapshot is required for those. A snapshot list is created and all points of the number needing an update added to this. Then the list is sent and Cimplicity

20 March 22, 1999


returns the last value. Note that these values are timestamped with the PI server time on value receiption. Tenthousands of points are investigated for refresh need in few minutes.

Data acquisition - Output

The current version of the interface does not support Output. This functionality is not part of the standard OSI interface design but can be ordered separately. Please contact OSI Software if required.

Stop

If the interface is stopped, it terminates orderly to Cimplicity (cancel all requests, remove all points, remove all shopping lists, terminate) and exits. It can write a shutdown state to all tags.

Failover

Failover is partly possible and depends of the network architecture. In most case the interface may run on a node for itself. This is a client node to a Cimplicity server then and a satellite node to the (PI2 or PI3) PI server. The interface may run on a Cimplicity server node and be a satellite node to the PI server. If the PI server is a PI3-NT one the interface may also run on the PI server. The PI server and the Cimplicity server however at least are expected to be different machines.

Failover for the Cimplicity servers is part of the Cimplicity redundancy concept and is handled by Cimplicity transparent to the interface. Watch however that points can not be created, deleted or changed in PI after a redundancy switch. The interface must be stopped and restarted to achieve this.

Failover for the PI server is normally not supported. It requires special means apart from the PI system and interface.

Also the interface does not support Failover for the interface node. This functionality is not part of the standard OSI interface design but can be ordered separately. Please contact OSI Software if required.

March 22, 1999 21

21


Revision HistoryDate Author Comments

7/12/99 KL Added detailed instructions on how to install and run the interface as a service.

1/19/00 KL Added instructions for Cimplicity security setting configuration to allow cimpi service to communicate with Cimplicity. Cimpi version 1.1.0

22 March 22, 1999

Download - CIMPLICITY HMI - OSIsoftcdn.osisoft.com/interfaces/1011/PI_GECimpi_1.1.0.doc · Web viewGE Fanuc Automation, CIMPLICITY HMI for Windows NT and Windows 95, Point Management API,

Top Related