EJEMPLOS AVG(TAGVAL

8/20/2019 EJEMPLOS AVG(TAGVAL

1/43

PI-API-NTI 32 Bit PI-API

for Microsoft Windows NT and Windows 9x Version 1.3.8 readme.txt June 2002

Table of Contents -----------------

Troubleshooting

C Programming Information

Visual Basic Programming Information

Release Notes Version 1.3.8 Version 1.3.6 Version 1.3.5 Version 1.3.4 Version 1.3.3 Version 1.3.2 Version 1.3.1.3

Version 1.3.1.2 Version 1.3.1 Version 1.3.0 Version 1.2.3.6 Version 1.2.3.5 Version 1.2.3.4 Version 1.2.3.3 Version 1.2.3.2 Version 1.2.3.1 Version 1.2.3 Version 1.2.2 Version 1.2.1 Version 1.2.0

Version 1.2.B2 Version 1.1.4 Version 1.1.3 Version 1.1.2 Version 1.1.1 Version 1.1.0 Version 1.0.6 Version 1.0.5 Version 1.0.4 Version 1.0.4a PILogin Version 1.3.6 PILogin Version 1.3.5 PILogin Version 1.3.4

PILogin Version 1.3.3 PILogin Version 1.3.2

---------- Troubleshooting --------------------------------------|

If you have problems, make sure there are no old copies ofPIAPI32.DLL and PILOG32.DLL in your system, particularly in yourWINDOWS or WINDOWS/SYSTEM directories or on your path as describedabove. If you find any old copies of PIAPI32.DLL, remove themto a floppy disk or rename them. Only a single copy should be in


2/43

your system.

When you encounter errors, always check the file pipc.log foundin your %PIHOME%\DAT directory. The PI-API writes to this filewhen it encounters errors. (Note: PIHOME is defined in pipc.inilocated in the WINDIR directory)

The error codes which are found in the pipc.log file may betranslated using the pilogsrv -e # command.

---------- C Programming Information ----------------------------|

The import libraries, piapi32.lib and pilog32.lib, may be used toimplicitly link to the PI-API and PILOGIN routines.

An example program with a Microsoft Visual C++ 6.0 makefile islocated in the \pipc\examples\c directory.

C applications should use a struct member byte alignment of 8.

---------- Visual Basic Programming Information -----------------|

The file piapi32.bas in the INCLUDE directory contains functiondeclarations for the functions provided in the piapi32 and pilog32

DLLs. These files make it possible to call PI-API functions directlyfrom Visual Basic. See the PI-API Programming Manual for moreinformation regarding calling C routines from Visual Basic.

-----------------------------------------------------------------| RELEASE NOTES-----------------------------------------------------------------|

PI-API version 1.3.8 release notesJune-2002

Bug fixes

---------1. Crash in PINetMgr caused by a data set in PI-ProcessBookIf a PI-ProcessBook display has a data set which contains a large numberof characters (~4100), e.g.,

If(TagVal('cdf144','*')


3/43

communications to PI Universal has been re-established(e) the PI-API incorrectly initializes the APIBUF.DAT file to 16 bytes

Another scenario is the following:(a) a PI-API node is sending data to PI Universal Data Server(b) this PI-API node loses communications to PI Universal Data Server(c) the PI-Buffer Server buffers data to the APIBUF.DAT file(d) a user shuts down PI-Buffer Server(e) a user re-starts PI-Buffer Server(e) the PI-API incorrectly initializes the APIBUF.DAT file to 16 bytes

PI-API v1.3.8, along with the Bufserv v1.5.0 (PI-Buffer Server) andBufutil v1.5.0 programs that it distributes, fixes these problems.However, the following programs must be used together: PI-API v1.3.8 Bufserv v1.5.0.0 (distributed with PI-API v1.3.8) Bufutil v1.5.0.0 (distributed with PI-API v1.3.8)

The following combination will still exhibit the problems describedabove: PI-API v1.3.8 Bufserv v1.4.0.0 (distributed with PI-API v1.3.6) Bufutil v1.4.0.0 (distributed with PI-API v1.3.6)

The following combination will still exhibit the problems describedabove: PI-API v1.3.6 Bufserv v1.5.0.0 (distributed with PI-API v1.3.8) Bufutil v1.5.0.0 (distributed with PI-API v1.3.8)

To determine the version of PI-API, run apisnap. For example, C:\program files\pipc\bin>apisnap PI-API version 1.3.8.0 Attempting connection to Default homenode

To determine the version of Bufserv, use the -v parameter. For example, C:\program files\pipc\bin>bufserv -v

Version: 1.5.0.0

To determine the version of Bufutil, use the -v parameter. For example, C:\program files\pipc\bin>bufutil -v Version: 1.5.0.0

The PI-SDK installation program, which installs the PI-API, willdistribute this correct combination of files: PI-API v1.3.8 Bufserv v1.5.0.0 (distributed with PI-API v1.3.8) Bufutil v1.5.0.0 (distributed with PI-API v1.3.8)

Thus, the above warning regarding incompatabities is for informational

and troublshooting purposes.

3. Crash in PI-Buffer ServerThe PI-Buffer Server program distributed with previous versions ofthe PI-API sometimes crashed under the following scenario:(a) a PI-API node is sending data to PI Universal Data Server(b) this PI-API node loses communications to PI Universal Data Server(c) PI-Buffer Server buffers data to the APIBUF.DAT file(d) a user shuts down PI-Buffer Server


4/43

(e) a user re-starts PI-Buffer Server(f) connection to PI Universal Data Server is re-established(g) PI-Buffer Server crashes

On Windows platforms, the following appears in the DrWtsn32.log file:FramePtr ReturnAd Param#1 Param#2 Param#3 Param#4 Function Name00f5fc50 0045ce9a fffff1f0 00000001 00403983 00f5fcd4 bufserv!_mkgmtime00f5fc5c 00403983 00f5fcd4 004973c4 00497010 00000000 bufserv!mktime (FPO: [1,0,0])00f5fd08 00401f0b 004973bc 00000012 004976a8 00c60000 bufserv!bufservermgr::setdstchange

PI-Buffer Server v1.5.0.0 fixes this problem.

New feature-----------New version number for APIBUF.DATPI-Buffer Server v1.5.0.0 creates an APIBUF.DAT file that is version 2.Previous versions of PI-Buffer Server create an APIBUF.DAT that is version1. The only difference between these version is the header information inthe APIBUF.DAT file. The format of the data has not changed.

PI-Buffer Server v1.5.0.0 can process a version 1 APIBUF.DAT file. However,

when PI-Buffer Server exits, it then updates this APIBUF.DAT file to beversion 2.

PI-Buffer Server v1.4.0.0 and prior cannot process a version 2 APIBUF.DAT.

-----------------------------------------------------------------|PI-API version 1.3.6 release notesMarch-2002

Bug fixes---------The pisn_evmexceptionsx() and pisn_evmexcepts() functions now return -77

when the PI Universal Data Server determines that the exception bufferhas overflowed. However, valid data are returned via the "PI_EVENT values"and the "Val" parameters. Thus, the return of -77 is a warning to indicatethat there are too many values in the exception buffer on PI Universal DataServer.

The pitm_delay() function now works properly on Windows XP.

User defined time zones-----------------------PI-API v1.3.6.0 supports user-defined time zone specifications. Inparticular, you can define daylight/standard time transition rules that are

different from the underlying operating system's.

The user-defined time zone specification file is called localhost.tz. Youcreate this localhost.tz file via the "pidiag" command found in PI UniversalData Server v3.3.

If the PI-API is running on a machine that is also running PI Universal DataServer, then PI-API looks for the localhost.tz file in the following location: $PI\dat\localhost.tz (Windows) $PI/dat/localhost.tz (Unix)


5/43

where $PI represents the top-level directory in which PI Universal DataServer is installed. $PI is typically C:\PI (Windows) /opt/PI (Unix)Therefore, if the PI-API is running on a machine that is also running PIUniversal Data Server, PI-API looks for the time zone specification filetypically in C:\PI\dat\localhost.tz (Windows) /opt/PI/dat/localhost.tz (Unix)

If the PI-API is running on a machine that is not running PI Universal DataServer, then you need to transfer the localhost.tz file from the PI UniversalData Server machine to the PI-API machine. Put this localhost.tz file inthe following location: $PIHOME\dat\localhost.tz (Windows) $PIHOME/dat/localhost.tz (Unix)where $PIHOME represents the top-level directory in which the PI-API isinstalled. $PIHOME is typically C:\Program Files\PIPC (Windows) /opt/piapi (Unix)Therefore, if the PI-API is running on a machine that is not running PIUniversal Data Server, PI-API looks for the time zone specification filetypically in C:\Program Files\PIPC\dat\localhost.tz (Windows)

/opt/piapi/dat/localhost.tz (Unix)

If after applying the above rules, PI-API does not find the localhost.tzfile, then PI-API does not use user-defined time zone specifications.

Please see the PI Univeral Data Server v3.3 documentation on the "pidiag"command or the PITimeServer documentation for more information regarding thecreation and use of custom time zones.

ANSI C++ streams library------------------------PI-API v1.3.6 uses the ANSI C++ streams library. Previous PI-API versions

used the "standard" streams. For those of you familiar with C++ programming,the former involves #include The latter involves #include

Incompatability with previous PI-API versions on HP-UX------------------------------------------------------On HP-UX, programs built with previous versions of the PI-API are notcompatible with PI-API v1.3.6. This PI-API distribution contains 1. PI-API v1.3.4 compatible with the HP-UX cfront compiler 2. PI-API v1.3.4 compatible with the ANSI C++ compiler

3. PI-API v1.3.6 compatible with the ANSI C++ compiler and ANSI streams

If your PI-API programs (for example, PI-Interfaces) do not mention ANSI C++compiler compatibility or PI-API v1.3.6 compatibility, you should installPI-API v1.3.4 via option 1.

If you want to run a program built with PI-API v1.3.6 as well as a programbuilt with PI-API v1.3.4, you will need to install two copies of the PI-API.For example, install PI-API v1.3.6 to the directory /opt/piapi_1.3.6


6/43

by $ PIHOME=/opt/piapi_1.3.6 $ export PIHOME $ SHLIB_PATH=$PIHOME/lib $ export SHLIB_PATH $ sh pi.install Also, install PI-API v1.3.4 to the directory /opt/piapi_1.3.4by $ PIHOME=/opt/piapi_1.3.4 $ export PIHOME $ SHLIB_PATH=$PIHOME/lib $ export SHLIB_PATH $ sh pi.install

Programs that need PI-API v1.3.6 would have their PIHOME and SHLIB_PATHenvironment variables set to, respectively, /opt/piapi_1.3.6 and/opt/piapi_1.3.6/lib.

Similarly, programs that need PI-API v1.3.4 would have their PIHOME andSHLIB_PATH environment variables set to, respectively, /opt/piapi_1.3.4 and/opt/piapi_1.3.4/lib.

In order for PI-API node buffering to work for each of these two instances ofthe PI-API, you will need to create the following entries in theirrespective piclient.ini files.

In /opt/piapi_1.3.6/dat/piclient.ini:[APIBUFFER]BUF1NAME=PIAPI136_BUFFER1MEMBUF2NAME=PIAPI136_BUFFER2MEMBUF1MUTEXNAME=PIAPI136_BUF1MUTEXBUF2MUTEXNAME=PIAPI136_BUF2MUTEXFILEBUFNAME=PIAPI136_FILEBUFFILEMUTEXNAME=PIAPI136_FILEMUTEX

And in /opt/piapi_1.3.4/dat/piclient.ini:[APIBUFFER]BUF1NAME=PIAPI134_BUFFER1MEMBUF2NAME=PIAPI134_BUFFER2MEMBUF1MUTEXNAME=PIAPI134_BUF1MUTEXBUF2MUTEXNAME=PIAPI134_BUF2MUTEXFILEBUFNAME=PIAPI134_FILEBUFFILEMUTEXNAME=PIAPI134_FILEMUTEX

Building programs that use PI-API v1.3.6 on HP-UX-------------------------------------------------For C program files, you should use the ANSI C compiler. For example,

$ /opt/ansic/bin/cc -Ae +ESlit +Z -D_HPUX_SOURCE -Dhppa -Dhpux \ -c -I/opt/piapi/include \ cfile.c

For C++ program files, you should use the ANSI C++ compiler, For example,$ /opt/aCC/bin/aCC +ESlit +Z -D_HPUX_SOURCE -Dhppa -Dhpux \ -c -I/opt/piapi/include \ -O \ cppfile.cpp


7/43

To link, use the C++ linker:$ /opt/aCC/bin/aCC -AA -Aa -ext +Z -Wl,+s \ -L/opt/piapi/lib \ -lpiapi -lm \ -o finalprogram cfile.o cppfile.o

Incompatability with previous PI-API versions on Solaris--------------------------------------------------------On Solaris, programs built with previous versions of the PI-API may not becompatible with PI-API v1.3.6. This PI-API distribution contains 1. PI-API v1.3.4 compatible with the Sun version 4 compiler 2. PI-API v1.3.4 compatible with the Sun SC5 compiler 3. PI-API v1.3.6 compatible with the Sun SC5 compiler and ANSI streams

If your PI-API programs (for example, PI-Interfaces) do not mention ANSI C++compiler compatibility or PI-API v1.3.6 compatibility, you should installPI-API v1.3.4 via option 1.

If you want to run a program built with PI-API v1.3.6 as well as a programbuilt with PI-API v1.3.4, you may need to install two copies of the PI-API.For example, install PI-API v1.3.6 to the directory /opt/piapi_1.3.6by

$ PIHOME=/opt/piapi_1.3.6 $ export PIHOME $ LD_LIBRARY_PATH=$PIHOME/lib $ export LD_LIBRARY_PATH $ sh pi.install

Also, install PI-API v1.3.4 to the directory /opt/piapi_1.3.4by $ PIHOME=/opt/piapi_1.3.4 $ export PIHOME $ LD_LIBRARY_PATH=$PIHOME/lib $ export LD_LIBRARY_PATH

$ sh pi.install

Programs that need PI-API v1.3.6 would have their PIHOME and LD_LIBRARY_PATHenvironment variables set to, respectively, /opt/piapi_1.3.6 and/opt/piapi_1.3.6/lib.

Similarly, programs that need PI-API v1.3.4 would have their PIHOME andLD_LIBRARY_PATH environment variables set to, respectively, /opt/piapi_1.3.4and /opt/piapi_1.3.4/lib.

In order for PI-API node buffering to work for each of these two instances ofthe PI-API, you will need to create the following entries in theirrespective piclient.ini files.

In /opt/piapi_1.3.6/dat/piclient.ini:[APIBUFFER]BUF1NAME=PIAPI136_BUFFER1MEMBUF2NAME=PIAPI136_BUFFER2MEMBUF1MUTEXNAME=PIAPI136_BUF1MUTEXBUF2MUTEXNAME=PIAPI136_BUF2MUTEXFILEBUFNAME=PIAPI136_FILEBUFFILEMUTEXNAME=PIAPI136_FILEMUTEX


8/43

And in /opt/piapi_1.3.4/dat/piclient.ini:[APIBUFFER]BUF1NAME=PIAPI134_BUFFER1MEMBUF2NAME=PIAPI134_BUFFER2MEMBUF1MUTEXNAME=PIAPI134_BUF1MUTEXBUF2MUTEXNAME=PIAPI134_BUF2MUTEXFILEBUFNAME=PIAPI134_FILEBUFFILEMUTEXNAME=PIAPI134_FILEMUTEX

PI-API node buffering program incompatibility---------------------------------------------The PI-API node buffering programs (bufserv, bufutil, and isbuf) arecompatible with this PI-API version only. That is, you cannot usePI-API v1.3.6 with the bufserv program that was delivered as part ofPI-API v1.3.4, and vice-versa.

User-specified check-time interval for Log File Utility-------------------------------------------------------By default, the pilogsrv process checks every 600 seconds (10 minutes)to determine whether to shift the PIPC.LOG file. You may now specifythis check-time interval by putting the following entry in to the[PIPC] section of the PIPC.INI file located in the Windows directory:

[PIPC]CHECKLOGINTERVAL=300

For the above example, pilogsrv will check every 300 seconds (5 minutes)to determine whether to shift the PIPC.LOG file.

Documentation clarifications----------------------------The online help file, typically located in

C:\Program Files\PIPC\HELP\PIAPI.CHM,has been updated with regards to the following functions:

pisn_evmexceptionsx() PIAPI.CHM now indicates that this function returns -77 when an exception buffer overflow occurs

pisn_evmexceptx() PIAPI.CHM now indicates that this function returns -77 when an exception buffer overflow occurs pisn_flushputsnapq() PIAPI.CHM now contains a correct example usage. Previously, the example erroneously showed: printf("Error %ld with point %ld\n",qerror[i].point, qerror[i].error);

The example now correctly indicates printf("Error %ld with point %ld\n",qerror[i].error, qerror[i].point);

piar_getarcvaluesfilterx() PIAPI.CHM now provides an explanation of the ARCflag_comp and

ARCflag_filter specifications: Filter reporting modifiers ARCflag_filter and ARCflag_mark may also be used in conjunction with ARCflag_comp, ARCflag_even, or ARCflag_time.

That is, if you want to get filtered, compressed data, use an arcmode value that is the sum of ARCflag_comp and ARCflag_filter. The


9/43

ARCflag_mark specification returns filtered values marked as "Filtered" while ARCflag_filter omits filtered values.

Usage note - pisn_evmexceptionsx()----------------------------------Some users have requested an example regarding the usage of thepisn_evmexceptionsx() function. Its function prototype is pisn_evmexceptionsx ( int32* count, int32* ptnum, PI_EVENT* values, int32 funccode );

Before calling pisn_evmexceptionsx, a program must first register a numberof "ptnum"s via

pisn_evmestablish( &numOfpts, &ptnum );

This program can then call pisn_evmexceptionsx() with the "funccode" ofGETFIRST: pisn_evmexceptionsx( &count, &ptnum, &values, GETFIRST );

When passed, "count" represents the number of exception values to retrieve.When returned, "count" indicates the number of values actually retrieved.

If this function call is successful, the retrieved exception values are storedin an internal buffer within the PI-API. For example, if "count" is 7 when thefunction returns, the exception values may look like the following:

tagname timestamp value1. pointA 4/17/2001 10:03:01 10.5552. pointA 4/17/2001 10:03:05 11.2303. pointC 4/17/2001 10:02:59 0.1234. pointD 4/17/2001 10:03:02 3.1125. pointC 4/17/2001 10:03:01 0.140

6. pointB 4/17/2001 10:03:03 CLOSED7. pointA 4/17/2001 10:03:06 12.788

These exception values are in the same order that were received by PIUniversal Data Server.

The first call to pisn_evmexceptionsx(), with GETFIRST, returns the data inrow 1 above.

A subsequent call to pisn_evmexceptionsx() with GETNEXT returns the data inrow 2 above.

Another subsequent call to pisn_evmexceptionsx() with GETNEXT returns the

data in row 3.

Another subsequent call to pisn_evmexceptionsx() with GETNEXT returns thedata in row 4.




10/43


Another subsequent call to pisn_evmexceptionsx() with GETNEXT returns theerror code PI_NOMOREVALUES.

-----------------------------------------------------------------|PI-API version 1.3.5 release notesDec-2000 cah

1. pisn_sendexceptionq and pisn_sendexceptions did not properlyincrement the returned count parameter in versions 1.3.2 to 1.3.4. Acount=2 would be returned as 1 and count=1 was returned as 0 (except forout of order times). For the queued call, this would cause the data tobe added to the internal queue, but the calling program may not flushthe data queue to the server since count=0 in many cases. When 255events (36 for PI2) were queued the data would be sent. For programsthat send only a few values, the snapshot may not be updatedimmediately.

2. The routine piut_getprofile, implemented on UNIX, previouslyconverted strings to upper case. Now it returns strings unmodified.

3. pitm_fastservertime produced repeated messages when DSTMISMATCHwas set and there was no jump in the server time due to DST changes.This has been fixed.

4. Only PI-API programs that connect to the default servercheck to see if buffering is enabled. Previouly, all PI-APIprograms would check to see if buffering was enabled whenconnecting to the server then they would check to see if theywere connecting to the default server. This allows starting ofPI-API programs that do not connect to the default server beforethe buffer server and allows the buffer server to be startedand stopped without stopping programs that do not connect to thedefault server.

-----------------------------------------------------------------|PI-API version 1.3.4 release notesAug-2000 cah

1. Disconnection of bufserv from the PI server in a timezone eastof GMT while no data was in the buffer causes an exception violationon Windows NT. This does not affect UNIX releases. This was fixed.

2. If there are severe disk errors so that the buffer server cannotuse the file buffer, an error message would be printed for everyapplication call to put data into the file buffer. This has beenthrottled so that every 1000th put attempt with the same file error

will be printed, the buffer file that is having the problem will berenamed and another APIBUF.DAT started.

3. Windows socket behavior has changed with Windows 2000 from thebehavior observed in previous Windows versions. This behavior changecauses Windows 2000 clients using the PI-API to send a RESET to PIservers when closing a connection. As a result, a message containingthe code 64 is logged in the PI server log file instead of agraceful disconnection message (-10721). The PI-API has beenmodified so that all currently released versions of Windows sockets


11/43

close properly.

-----------------------------------------------------------------|PI-API version 1.3.3 release notesMay-2000 cah

1. Arguments to PI-API routines which are unmodified 'char *' werechanged to 'const char *' in piapi.h and piapix.h. This willprevent warnings by newer ANSI C++ compilers about passing literalstring constants as arguments.

2. Added the routine pitm_getutctime to return double UTC time fora PITIMESTAMP structure.

3. A PI-API uninstall program for Windows is now included in thePIPC\bin directory. A dialog is presented with check boxes forchoosing which components to uninstall.

4. The AIX release now has both shared and archive PI-APIlibraries. The example make file for apisnap.c and the programmersmanual have been updated with information for using sharedlibraries. These are only valid for AIX 4.2 and greater.

5. The HP-UX release now has versions for the new HP ANSI C++

compiler and the HP cfront compiler (CC). The installation scriptallows installation of either version.

6. The Solaris release now supports the ANSI C++ compiler version 5and the previous version 4 compiled code. The installatio scriptallows installation of either version.

7. Added put and get of PItimestamp point types that are availablein PI 3.3 servers. For sending values to PItimestamp point typesusing pisn_putsnapshotsx, pisn_putsnapshotx, pisn_putsnapshotqx,piar_putarcvaluesx if bval is provided in the argument list a stringis sent to PI, if drval is provided a float64 or if ival an int32.For pisn_sendexceptionsx calls with

PI_EVENT.typex=PI_Type_PItimestamp, if PI_EVENT.bval exists a stringis sent. Otherwise PI_EVENT.drval is sent. For VB variants withtypex=PI_Type_PItimestamp, pisn_sendexceptx sends a double. Forpisn_evmexceptionsx retrieving data from a PItimestamp point type,the returned type is typex=PI_Type_PItimestamp and as double(drval). For the VB routine pisn_evmexceptx, it returns VT_R8. Forpisn_getsnapshotx, double, int32, bval pointer arguments are allfilled if they exist. drval and ival arguments are UTC values andthe bval is returned in localtime.

8. Added digital states ACTIVEBATCHSTAT, WRONGTYPESTAT, OVERFLOW_STand INTFSHUTDOWN = -311 to pidgstat.h.

9. Fixed a bug in HP-UX network read/write of large networkpackets. Conditions causing the problem were packet sizes greaterthan about 1700 bytes and less than optimal speed between the clientand PI server. The impact was lost data on receiving packets.

10. Fixed bug in pisn_putsnapshotsx to PI2 server. It is possible tohave putsnapshot errors for valid values in mixed point type arrays(queued calls).

11. For pisql calls, fix SQL queries so the queries are sent to the


12/43

server in 255 char chunks. PI servers would return an error for apiversion 1.3.2 only.

12. Fixed warning message about unacceptable jumps in the servertime offset which were issued by pitm_fastservertime. These timeoffsets were typically changed by about 1 second and were obviouslyacceptable changes.

13. Fixed a problem with extended sendexception routines. New valueswith an exception deviation of zero and no change from the old valuewould not be sent to the PI server. Setting exception deviation tozero now works for all points.

14. Fixed the output message of the buffer server for points whichhad an extended putsnapshot or putarcvalues error. The timestamp andstatus of the bad value were to be printed, but the status value wasincorrect.

15. Fixed a problem in which the buffer server (bufserv) may exit ifthe client generating data puts large amounts of data into thebuffers. Under such circumstances bufsev may not be able to lock thebuffer before the status changes from second buffer to file. Afterthe unexpected status change, bufserv would exit. It now skips thatiteration of buffer processing and tries again.

16. pitm_getpitime will now return -1 for incorrectly filledPITIMESTAMP structures.

17. Eliminated possible PI_OVERFLOW (-15000) messages from thebuffer server when checking the server/client time offset.

18. Reduced the number of "connect() failure" messages which occuras the API attempts periodic reconnection. Previously, every 2minutes, the API would log the failure message. Now every 600attempts generates a message (about 10 hour intervals for 1 minutetimeout setting).

19. Fixed a problem determining version of a PI 2.1 or earlierserver. The problem would cause excessive calls to the serverduring archive or snapshot retrievals of arrays. The results wouldtake several times longer to retrieve.

20. The pilogsrv service start and stop was added to the Windows NTpistart.bat and pistop.bat scripts.

21. The definition of MAXUINT32 pidefs.h is now unsigned instead of"L".

22. bufutil would sometimes not report events that were in theprimary buffer. This was usually seen when testing with a small

number of sent events. bufutil will now indicate the presence ofevents in bufserv's temporary block used for sending data to theserver. The number of events in the block is added to the number ofevents in the primary buffer.

23. bufserv previously attempted to communicate with the PI serveronly when data was sent through the buffers by a PI-API program.Thus, bufserv would only detect a server was unreachable when newdata was sent. When little or no data was sent to the PI server,other PI-API programs could attempt to contact the server before


13/43

bufserv detected that the server was unreachable. Since bufserv didnot detect and disable the connection TIMEOUT first, these otherPI-API programs would wait for the TIMEOUT period before continuingexecution. Now bufserv checks the connection with the server everyPAUSERATE seconds (this parameter is set in piclient.ini anddefaults to 2 seconds). This allows bufserv to disable connectionTIMEOUT sooner for low throughput cases. Note: bufserv still waitsfor TIMEOUT seconds when the connection is first lost.

24. Fixed output of Windows socket error numbers. The wrong numberwas previously printed. No number-to-string lookup is available forwindows socket errors. Some socket errors have been added to thePI-API installation instructions (API_install.doc).

25. Fixed pisn_sendexcepstrucq problem in which the numbpterrsargument was not updated. Also, in some circumstances, qerrs was notupdated properly.

26. pisn_sendexceptionsx and pisn_evmexceptionsx contained a memoryleak for strings and blobs if a digital state was obtainedalternating with good values.

27. If no connection to the server was performed and no defaultserver was in pilogin.ini (or pilogin.ini was not found), making a

call which required a connection caused an exception violation.This was caused by a failure at an implied connection. This has beenfixed.

28. Windows installation program now has a checkbox for enablingauto-start of bufserv. Previously, bufserv would be installed asmanually started so that testing could be done before enablingauto-start of the bufserv service. Changes to the dialog text ofthe installation has been made for clarity.

29. The UNIX installation script has been expanded. It detectsunsupported versions of the operating system, the validity of theuser entered during installation is checked and presents information

for the HP and SUN library differences.

30. The iorates.dat file header has been updated to explain thenewer features.

31. The iorates program now detects the iorates.dat filemodification time to determine if a re-read is needed. Also, the tagname lookup by pipt_findpoint would capitalize the tagname. It wascausing a repeated lookup of tagnames.

-----------------------------------------------------------------|PI-API version 1.3.2 release notesDec-99 cah

1. A bug in the PI-API pitm_localtime routine (OSI's implementationof localtime) has been fixed. The problem caused an exceptionviolation in pitm_intsec. The problem was caused during daylightsavings when a time is entered into PI-API routines that accept thelocal time. Entering a zero local time may result in a UCT timeless than zero. The localtime routines previously used had a rangeof validity to -3600 seconds for daylight representation of timezero. Now the new localtime routine also handles the range to -3600properly.


14/43

2. A bug in bufserv has been fixed such that filling a memorybuffer exactly (0 bytes left for more events) will result in acrash. The next attempt to write into the buffer after filling thebuffer would cause either the data producing client program orbufserv to crash. This would typically occur when buffering to afile or when bufserv was emptying a file after a disconnection fromthe server and extended API pisn_putsnapshotx routines were used tosend data to PI. Standard API routines have constant size eventswhich would usually not fill the buffer exactly.

3. The buffer server would only produce a shutdown message in thelog file while running interactively on Windows NT. Now stoppingbufserv when it is running as a Windows service produces a shutdownmessage in the log file.

4. The buffer server could have produced an uninitialized number ofevents already in the block used to transfer events from the fileAPIBUF.DAT to the memory buffers during startup. This could occurwhen events exist in the file APIBUF.DAT and a restart of the bufferserver is done.

5. A bug in pisn_evmexceptx was fixed in which PI2 types were notproperly translated. Also, the variant type VT_R4 is now used for

float32 and float16 values instead of VT_R8.

6. A bug in pisn_evmexceptionsx was introduced in PI-API 1.3.1.3and has been fixed. It prevented the bsize variable of string valuesfrom being updated. Thus, the caller was required to use strlen()to determine the number of bytes actually returned.

7. A bug in pisn_sendexcepstruc, pisn_sendexcepstrucq,pisn_sendexceptionq, and pisn_sendexceptions has been fixed whichcould cause data loss during the fall DST transition. If a clientprogram adds new values with a timestamp of 0, the timestamp isresolved to the current server time. However, when the falltransition occurs, the timestamp used for the putsnapshot (oldvalue)

would not be reset since it appears to be newer than the 'newtime'.This causes two problems. First, 'oldtime' is normally set to'newtime' when an exception is indicated. However, this did notoccur with the "out of order" data until pitm_fastservertime onceagain exceeded 'oldtime'. Every "out of order" value is sent withthe timestamp which was assumed to now be in 'oldtime'. This hasbeen fixed. Second, every scan would be sent since all new valueswere determined to be out of order. This second problem has not beenfixed in the standard exception routines. It is recommended thatpisn_sendexceptionqx be used to fix both problems.

8. A bug in the routine piut_strerror resulted in the same stringbeing returned multiple times for error -411. Now the function

returns the message string once.

9. A memory leak in piut_syscommand has been fixed. The receiveddata buffer is now deleted after use.

10. An enhancement of bufserv has been added which preserves thedata in the memory buffers when data which cannot be processed isencountered. If bufserv encounters an event activation error it willexit. Previously, the memory buffers would be lost since the datawas be unreadable. Now the memory buffer which caused the error


15/43

will be dumped to a file in the PIHOME\dat directory for lateranalysis and/or recovery.

11. If more than 100 consecutive -10401 or -10407 errors arereceived by bufserv, piut_disconnect is issued and bufserv waits forthe retry interval before reconnecting. The reconnection isintended to obtain any new security permissions from changes on thePI server. The user must still identify the problem and fix theserver permissions to allow the data to be sent to PI. Previously,the permission denied error would cause data to be lost since it wasnot treated as a system error, but a point error. This situationcould arise during reconnection to a PI 3 server after a networkproblem.

12. For system errors, now "putsnapshots" is logged as the source ofthe error for standard API calls and "putevents" is logged as sourceof the error for extended API calls.

13. Putsnapshot errors for bufserv now use the routine piut_strerrorto translate error codes to strings.

14. The bufutil utility has been modified to allow multipleiterations of a buffer's header information to be printed to thescreen at the interval you specify (defaults to 5 seconds). Also,

the version of bufutil is now printed when the "-v" command lineflag is used.

15. Unix message queue now only prints an error one time if themessage queues are unavailable instead of 4 times.

16. The PI-API now remembers the login name used in piut_login andwhen a reconnection occurs to the server, the same username islogged into the PI server.

17. Added piut_getloginuser to the piapi.h list of exportedfunctions. This routine returns the name used by piut_login to loginto the PI server, if any was used.

18. piut_login will now accept NULL pointers for arguments.Previously, the empty string would indicate a request for defaultlogin privilege. NULL pointers may now be used to get the defaultlogin privilege.

19. The PI-API now can read up to 100 server entries in pilogin.ini.The previous value was 50.

20. bufserv now examines piclient.ini for the LOGIN key in theAPIBUFFER section. The string is of the format"LOGIN=username,password". If password is omitted a blank passwordis assumed. This feature is designed for testing purposes only.

THIS FILE IS NOT SECURE. The recommended method of allowing writeaccess to a PI server is to use the PI proxy table for PI3 serversor an appropriate PISYSDAT:PISERVER.DAT entry for PI2 servers.Remove the LOGIN key when testing is completed.

21. The UNIX routine piut_getprofile now implements the WindowsGetPrivateProfileString mechanism to read all section names or allkey (entry) names within a section. If a NULL is passed as thesection argument, all section names without the surrounding bracketsand without leading or trailing spaces are returned in the buffer.


16/43

Each section name is separated by a null character from thefollowing section name and the list is terminated by two nullcharacters. piut_getprofile will now accept NULL arguments withoutan exception.

22. Added server name to output of piut_fastservertime messages.

-----------------------------------------------------------------|PI-API version 1.3.1.3 release notesjul-99 cah

A bug in the PI-API has been fixed which caused some duplicateevents to be sent to the server and some events to be lost duringbuffering of the data. The problem occured when adding arrays ofevents to the buffers (pisn_putsnapshots, pisn_putsnapshotq,pisn_putsnapshotsx) and the primary or secondary memory buffers haveonly enough space for a few of the events. In this case, those fewevents are added to the next buffer as well and an equal number ofevents from the end of the array are not buffered. This is observedas duplicate events and missing events especially noticeable whencompression is turned off.

A bug in the pisn_sendexceptionsx routine has been fixed. Theproblem occured for digital tags whose values switched from values

within the tag's digital set to a system state set value. In thatcase an error would occur for the later value.

A warning message about disk space which was printed out for WindowsNT PI-API nodes has been eliminated. The message would state that notenough disk space was available for the maximum sized buffer file whenthere was actually greater than 4 GB of data.

-----------------------------------------------------------------|PI-API version 1.3.1.2 release notesjun-99 cah

A bug in the pitm_settime and pitm_getpitime routines has been

fixed. The functions pitm_settime and pitm_getpitime could produceincorrect timestamps if the time structure was populated byassigning individual members and the tzinfo member (formerlyreserved) is set to zero and the client is in daylight time. Inthis case, the time would be pushed forward 1 hour.

A new function, piut_strerror, has been added to retrieve a singleerror message string for a return code if given a string indicatingthe calling program. If a null is passed for the string, theroutine will return multiple messages for a given return code untilPI_NOMOREVALUES is returned by piut_strerror.

An installation program has been created which will automatically

install the bufserv and pilogsrv services on Windows NT. Thepiapi32.dll, pilog32.dll and run time libraries are also installed.

For windows programs, piut_getprofile is now defined asGetPrivateProfileString and piut_writeprofile is defined asWriteProfileString. This is useful for writing PI-API programs forboth UNIX and Windows platforms from the same source code.

Increased maximum log file size to 4 MB for the pilg_checklogfileroutine. This is now the maximum number of bytes for the pipc.log


17/43

file.

If an alternate file name was used in pilg_checklog, the extensionwas forced to be '.log'. Now any extension may be used.

Enabled the pilg_checklog option to re-initialize the filename andsize/number of log files using an argument of action=-1.

Fixed problem with pilg_checklog which caused Windows 9x logs tobe shifted on startup if size was not yet the maximum.

The UNIX iorates program has been enhanced to cleanly disconnectwhen a kill -2 or kill -15 command is used. Also, the connection tothe server is attempted every 1 minute and after 10 minutes anexplicit disconnection is done before the next connection attempt.The iorates.dat file is now checked every 10 minutes for additions/deletions/changes to rate tags. Long tagname support isimplemented.

Added the HPUX process name to the pilg_formputlog output insteadof the process id.

pitm_delay now uses POSIX4 subsecond sleeps for OSF1, AIX andSunOS. This forces SunOS to link with '-lposix4'.

The buffer server had a memory leak which would occur in highsnapshot rates with extended putsnapshot calls. This is fixed.

The buffer server program will now throttle error messages after100 repeats of the same error for an array of points. Thus, if allpoints get the same error, they will not all be reported.

The API buffer server program would occasionally report an errorcleared for points which never had an error reported. This has beenfixed.

The buffer server will now rename a truncated APIBUF.DAT file

which it is unable to read to APIBUF.###. It will then be able tostart successfully. Previously, the buffer server would be unableto proceed if an APIBUF.DAT file with invalid header information(such as zero byte size) was encountered.

The buffer server for Windows NT will now properly detect the freedisk space available if more than 4GB is free.

The apisnap program now can retrieve archive values with the sametimestamp as the snapshot value. The option to enter the servernameand a list of tags has been added. All tags in the list will havesnapshot and most recent archive value listed. The format of thecommand is now:

> apisnap [servername [tag1] [tag2] [...]]

where "servername" must be listed to retrieve specified tag data.If any tags are listed, the apisnap program exits after the data isretrieved. Otherwise, a prompt is displayed for tagname.

The pilogsrv utility can now provide error messages for a specificfunction (for instance, the -1 return for pisn_putsnapshot) insteadof all functions which produce that error return. The format of the


18/43

command is now, for example,

> pilogsrv -e -1 pisn_putsnapshot

A bug in piut_fastservertime was fixed which gave the wrong servertype (PI 2) for PI 3 servers with long version strings.

-----------------------------------------------------------------|PI-API version 1.3.1 release notesapr-99 cah

A bug in reconnection by the API has been fixed. After atemporary disconnection the API would delete the PI server nameinternally. During after a subsequent disconnection, the servername would not match the buffered server name. This would preventbuffering of data. The application would begin managing connectionsto the server instead of the buffer server. Temporary loss ofconnection would typically not cause the connection problem,however, restart of the PI server would cause the problem.

A bug in putsnapshot routines has been addressed. No initialconnection would default to the PI2 behavior. Now, if no initialconnection is done by the calling program, but PI server informationis required (putsnapshot calls), a connection to the default PI

server is made.

An enhancement to the connection identification has been made. Ifa client program did not set the process name identifier(piut_setprocname) before connection, the PI server would log aconnection from "UNKN". Now, if the process name is not set beforea connection to the server, the executable name is used as theprocess identifier.

pipt_findpoint previously did not attempt to determine theserver type when no initial server connection existed. Thus,the default short tagname behavior was used. An attemptto connect to the default server is now done with failure still

defaulting to short tagname behavior.

A new connection (initial) to a PI server will now generatea message in the client log file indicating a new connectionto the server and whether it is the default PI server (in brackets).

12-Apr-99 11:50:17apisnap.exe>PI-API> Initial connection to [localhost:5450][1]

The bufutil utility now indicates if bufserv is running, butthe buffering flag was not turned on in piclient.ini.

-----------------------------------------------------------------|

PI-API version 1.3.0 release notesfeb-99 cah

NEW PI-API LIBRARY CALLS:The following new extended PI-API calls have been added topiapi32.lib and the prototypes are located in piapix.h:-----------------------------------------------------------

piar_getarcvaluesfilterx(): This call will retrieve archivevalues from the server for a point with the GETFIRST/GETNEXT/GETSAME


19/43

function code. The server will return all the values requested witha GETFIRST call and the values will be buffered on the client forretrieval. A filter expression may be passed if desired. A NULLvalue for the expression is identical to the piar_getarcvaluesx()call. The allowed archive retrieval modes are (see pidefs.h):ARCflag_time Retrieve values for the passed times.ARCflag_even Retrieve evenly spaced values between the passed times.ARCflag_comp Retrieve compressed values The allowed modifiers are (see pidefs.h):ARCflag_filter Remove values which do not pass the filterexpression. ARCflag_mark Mark values which do not pass the filterexpression with FILTERFAILSTAT. Note: PI 3 servers compress aseries of subsequent filter failure statii into one filter fail. For server versions less than PI 3.2 SR1, this call reverts tothe standard API calls to return filtered archive data.

piar_putarcvaluesx(), piar_putarcvaluex(): These calls willadd/delete an event or array of events to the archive. The followingmodes are valid for these calls (see piapix.h):ARCNOREPLACE add unless event(s) exist at same time (PI 2.x)ARCAPPEND add event regardless of existing eventsARCREPLACE add event, replace if event at same timeARCREPLACEX replace existing event (fail if no event at time)

ARCDELETE remove existing eventARCAPPENDX add event regardless of existing events, no compression For server versions less than PI 3.2 SR1, this call reverts tothe standard API calls to delete/replace values.

pisn_evmexceptionsx(): This routine retrieves any new datareceived in the update manager for points selected by thepipt_evmestablish() call. It will now retrieve string type pointsin addition to float, integer, and digital points. Data types ofthe PIvaluetype enumeration are provided with the data retrievedfrom PI3 servers. The data is placed into a PI_EVENT structurewhich allows for any data type. The data type is set to PI_Type_PI2for all data retrieved from PI2 servers. The only fields of the

PI_EVENT structure which are used for PI2 types are timestamp,istat, and drval (typex=PI_Type_PI2).

pisn_flushputsnapqx(): This routine causes any queued data fromthe snapshot calls pisn_putsnapshotqx() or pisn_sendexceptionqx() tobe sent to the home node.

pisn_putsnapshotqx():This routine accepts a queueing flag which,if set, will queue data until a pinet message is filled beforesending the data to the home node or a pisn_flushputsnapqx() call ismade.

pisn_sendexceptionqx(): This routine accepts PI3 point types for

exception processing and queues the data (if queueing flag is set)until a pinet message is filled or the queue is flushed beforesending the data to the home node.

pisn_sendexceptionsx(): This routine does exception processing onan array of PI3 points.

pitm_isdst(), pitm_setdst(): These routines are used tointerpret/set the PITIMESTAMP structure tzinfo field. pitm_setdstsets the appropriate bit pattern in tzinfo according to the tm_isdst


20/43

argument of true(1) or false(0).

piut_errormsg(): This routine returns a message string for theerror code entered. Some error codes may return more than onemessage (the message depends on the PI-API call used), thus thefunction may be called until PI_NOMOREVALUES is returned.

pisn_sendexceptqx(): This routine is used as a Visual Basicinterface to the pisn_sendexceptionqx() call. This routine acceptsthe VB Variant data type for exception processing. Queueing of thesnapshot data will be done if the queueing flag is set.

pisn_evmexceptx(): This routine is used as a Visual Basicinterface to the pisn_evmexceptionsx() call. This routine acceptsthe VB Variant data types.

4 new PI-API calls have been added to piapi32.lib:and the prototype is located in piapi.h.--------------------------------------------------

pilg_checklogfile(): This routine (available on WinNT only) isused to determine the size of the pipc.log file (default) or thepassed logfile name and rename it to a numbered file. For example,pipc.log becomes pipc0001.log.

The maximum size of each file is 256kb by default, but may bechanged using the MAXLOGSIZE key in the %SystemRoot%\pipc.ini file.The maximum number of log file defaults to 20, but may be changed byusing the MAXPIPCLOGS key. Both keys are in the [PIPC] section.After the maximum file number is reached, numbering restarts atzero, thus overwriting the oldest file.

pipt_signupforupdatesfil(): This routine allows point updates tobe filtered with an optional pointsource and location1 parameter.Currently, the function should return unsupported (-10008) until PI3server modifications are completed.

pipt_userattribs(): This routine allows retrieval of the point

attributes, userint1, userint2, userreal1, and userreal2.

pisn_sendexcepstrucq(): This routine allows 32 bit integer valuesto be sent with queueing of the data. The queuing flag is used toindicate no queueing (0), queuing (1), or flush the queue (-1). Theflush call is needed for Visual Basic applications since theQERRORS structure of the flush call could not be handled in VB.

piut_fastserverversion(): This routine returns the server majorversion of the connected node and the arguments of minor version andbuild number.

ENHANCED/CHANGED PI-API CALLS:

------------------------------

piar_getarcvaluesx(): Now acceptes ARCflag_time in addition toARCflag_comp and ARCflag_even.

pipt_digcodefortag(): Previously, input strings were limited to12 characters. It now accepts digital strings up to 79 characters.

pipt_compspecseng(), pisn_excdeveng() calls would return roundeddeviation values for integer points. Now they return the decimal


21/43

value as entered in the point configuration. This does not affectdata processing since they are integer points.

pisn_sendexceptions()/pisn_sendexceptstruc()/pisn_sendexceptionq()were modified to use pitm_fastservertime() instead of pitm_systime()if a time of zero is detected.

pitm_delay(): Added support for millisecond sleeps for UNIXplatforms.

pitm_fastservertime() now does not allow step changes in theoffset between the server and client time unless explicitly allowedin the pilogin.ini or piclient.ini (UNIX) files. This preventsaccidental time changes from producing bad timestamps on the clientand prevents bad timestamps if the server and client change DSTsettings at slightly different times. This should be used if theserver observes DST changes, but the client does not, or vice versa,or if the server and client use different DST rules. A pilogin.ini key, DSTMISMATCH#, located in the [DEFAULTS]section, allows the client and server offset to change by the numberof seconds specified. The '#' represents the number correspondingto the server in the PI# setting.

pitm_settime() will allow a range of 1-31 for every month. If

the month has fewer days, it will translate the excess days as thenext month. For example: April 31 becomes May 1.

API PROGRAMS:--------------

The buffer server (bufserv) now supports buffering of all PIpoint types for the put snapshot and send exception calls (pisn_),and the put archive calls (piar_). (Extended API calls are alsobuffered). The buffer server also supports the DSTMISMATCH key inthe [PISERVER] section of the piclient.ini file. This allows theserver and client to have different DST rules. Thepitm_fastservertime() function also has this feature.

The apisnap program has been enhanced to use the extended API.The snapshot and most recent archive values will be displayed forall types except blobs (only the size of blobs will be displayed).The command line may have the server and a tagname specification.If the tagname is specified, the server must be first. If thetagname is also specified, only that tag will be displayed, then theprogram will exit instead of prompting for another tagname. Also, a point number may be entered instead of the tagname byusing a leading backslash before the number. This may be usefulwhen the point number is available, but not the tagname.

The pilogsrv utility may be installed as a Windows NT service

which will periodically check the size of the pipc.log file andrename it if it exceedes 256kb or the size specified in the pipc.inifile. The number and size of each file may be specified in pipc.iniin the [PIPC] section using the keys MAXPIPCLOGS and MAXLOGSIZErespectively. After the maximum file number is reached, numberingrestarts at zero, thus overwriting the oldest file.

The pilogsrv utility program may be used to translate error codesinto a string description. Multiple descriptions may result for asingle code due to the repeated use between some API calls. The


22/43

format is pilogsrv -e #, where '#' is the error code.

The UNIX iorates program has been modified to continue connectionattempts during startup instead of exiting if the initial connectionattempt fails. The program now uses pitm_fastservertime() insteadof pitm_systime() for timestamps.

A UNIX script (apiverify) has been provided to list the processmemory and cpu usage for PI-API processes. Additional processes maybe added to the list by editing the $PIHOME/bin/apiprocs file.

BUG FIXES:----------

A pipt_nextptwsource() bug has been fixed which translated a returnof 2 (a network error) into -1 (no more points). It now correctlyreturns 2 so that the appropriate error correction can be completed.

A pitm_parsetime bug has been fixed which would incorrectly interpreta four digit year in a PI time string. For example, 7-jul-1998 aswould become year 2019 and attempt to use the following numbers in thetime calculation. Now the function returns an error if more than twodigits are used for the year. Standard PI times only use the last twodigits of the year.

A pitm_parsetime bug has been fixed which would incorrectly allow days29, 30, or 31 for months which have fewer than 31 days. An error isnow returned.

A point retieval bug has been fixed in which multiple successive callswith a bad point number would return irrelevant data. Bad pointnumbers will now return an error every time. This bug affected allmost point calls.

A pisn_evmestablish bug has been fixed in which calls made with acount of zero would return an uninitialized integer. Now a zero isreturned.

A piar_* bug has been fixed in which some calls would return 2 insteadof -1 when an invalid point number of -1 was used. Affected routineswere piar_compvalues, piar_compvaluesfil, piar_interpvalues,piar_interpvaluesfil, piar_panvalues, piar_plotvalues, piar_summary,piar_timedvalues, piar_timedvaluesfil, piar_value.

A piar_interpvalues bug has been fixed which would cause an exceptionviolation if a null pointer for one of the arrays was passed. Now anerror is returned.

A pisn_evmexceptions bug has been fixed in which the number specifyingthe size of the returned buffer from the network call would be

uninitialized during some network errors. Usually, this wouldmanifest itself on networks which had a high load and/or slow speed(for example, serial communication lines). This bug could cause amemcpy() to unallocated memory resulting in an access violation.

A bug caused during a communication errors when more than oneconnection was opened has been fixed. A communication error with onenode would cause all the sockets to be closed, but the servers wouldnot be notified (using sendserverabort). This would cause strandedsockets on the server. Now only the connection receiving the error is


23/43

closed.

A bug on Windows NT in converting an IEEE floating point value to aVAX floating point value has been fixed. The compiler would do a typecheck on the VAX floating point format as an IEEE floating pointnumber. In 1/512 cases, the result would have one bit switched. Theaccuracy of the number would be reduced from 1.19e-7 to 7.63e-6. Thevalues affected span the entire floating point range. API callspisn_putsnapshot, pisn_putsnapshotq, pisn_putsnapshots,pisn_sendexcepstruc, pisn_sendexceptionq, pisn_sendexceptions,piar_putvalue, piar_replacevalue calls were affected.

A bug on AIX which would produce inaccurate data due to IEEE to VAXfloating point conversions has been fixed. This is the same as forWindows NT, except the values at which the error occured weredifferent.

-----------------------------------------------------------------|PI-API version 1.2.3.6 release notes10-Nov-98 hs-----------------------------------------------------------------|1. The PI-API in this and previous versions is built with theC run-time library statically linked in. This means calls withinthe PI-API to C run-time functions are not executed in the

msvcrt.dll installed on the system but instead are executed withinthe PI-API. Version 4.x of the Microsoft C run-time librariescontained a bug where conversions between local and UTC time wereincorrect for systems with a time zone setting that did not honorDaylight Savings Time (e.g. Saudia Arabia, Korea, Arizona).Recent versions of the Alpha NT PI-API (1.2.3.1 - 1.2.3.4) werestatically linked with version 4.x of the C run-time library andtherefore contained this bug. This version (1.2.3.5) is builtwith the same code as version 1.2.3.4 but is statically linkedagainst version 5.x of the C run-time library where this bug hasbeen repaired. (Note: On the NT Intel platform v1.2.3.4 is linkedwith version 5.x, prior versions are linked with version 4.x andexhibit the bug)

This bug primarily affects programs which make "ExtendedAPI" calls (see Chapter 6 of the Programmer's manual). Thesecalls send UTC times to the server and do conversion betweenlocal and UTC times on the local system exposing the bug.Regular API calls send local times to the server which in the caseof PI3 translates them to UTC on the server. As no conversion ismade on the API node the bug is not exposed. OSI products thatmake use of the extended API functions include PIPC Datalink(v 1.7) and the PI Batch File interface.

If you have been running an interface or program that sends datato the PI Server using the extended API (e.g. Batch File) and

your system is set to a timezone where DST is not observed, youmay need to correct data in the archive. See the followingweb pages for more information or call OSI technical support.

http://irn.osisoft.com/osiirn/pi/timebug/bugquest.htmlhttp://irn.osisoft.com/osiirn/pi/timebug.htm#Repair

-----------------------------------------------------------------|PI-API version 1.2.3.5 release notes15-Oct-97 hks


24/43

-----------------------------------------------------------------|

1. pisql_set_timeout: this routine now checks to make sure that the PI-APItimeout is at least 5 seconds greater than the passed timeout value. If itis not, it sets the PI-API timeout to 5 seconds greater than the passedtimeout value for the current session only, and writes an informationalmessage to the PI-API message log file. This routine is used by thePI-ODBC Driver.

2. pitm_formtime previously would crash if passed a timedate of 0 forsystems set to time zones east of Greenwich, England and west of theinternational dateline. The function pitm_secint had the same problem.The function pitm_intsec would also exhibit this problem if passedinteger date components close to Jan 1 1970 0:0:0. This behavior hasbeen fixed. The problem was that the entered local time evaluated toa time before Jan 1, 1970 0:0:0 which is the basis (epoch) of PI time.These times are now treated as the base time.

3. A new routine, pilg_formputlog was added. This routine behaves similarlyto pilg_putlog but it logs the calling application name and a passed IDstring in addition to the passed message. The prototype for the function is:PIINT32 pilg_formputlog( char PIPTR *msg, char PIPTR *idstring);The user message is the first argument and a user defined idstring is thesecond argument and is appended to the message. The internal api messages

have now been changed to use this function to give more useful errormessages. Example output appears as follows:

28-Oct-97 11:55:43apisnap>PI-API> Warning: Server Minor Protocol Vers 7 < Client Vers 8:Major version OK

28-Oct-97 11:56:17apisnap>PI-API> gethostbyname: foobar sock_errmsg: Error: 0, Error 0 occurred.

In this example, taken from a DEC UNIX system, the program apisnapsuccessfully connected to a host and posted the warning concerning differentprotocol levels. The PI-API designator is the idstring argument. The

second example shows apisnap failing to connect due to the inability totranslate the hostname foobar. In previous versions these messages werelogged with no indication of the application that encountered the error.

Under HP-UX and AIX, the calling process name could not be obtained.For these platforms the function logs the PID (process ID) which can becompared to output from the ps command to determine the calling proram.For example:

28-Oct-97 17:04:257955>PI-API> gethostbyname: foobar sock_errmsg: Error: 0, Error 0

Here the process with PID 7955 called the PI-API with a bad hostname.

-----------------------------------------------------------------|PI-API version 1.2.3.4 release notes20-Jun-97 hs-----------------------------------------------------------------|

1. The function pitm_fastservertime previously did not work correctlyagainst PI on OpenVMS systems that had security enabled (RLWL), untilthe user had successfully logged in and 10 minutes had elapsed.


25/43

Times returned from that function under those conditions wereindeterminate. This behavior has been fixed. If default read orread/write permissions were specified the function worked correctly.Calls against PI on Windows NT and UNIX also worked correctly in earlierversions.

Note: This version was only released on the PI-API for Windows NT Inteland 16 bit Windows platforms. -----------------------------------------------------------------|PI-API version 1.2.3.3 release notes24-Apr-97 hs-----------------------------------------------------------------|

1. In previous versions, on Windows platforms, when certain printerdrivers were used they would disable the default floating pointexception masking. This would lead to crashes (unhandled exceptions)in later calls to functions used to retrieve archive values whichpassed uninitialized float arrays to be filled. With this version,the PI-API will temporarily set the exception masks prior to dealingwith these floating point values. It then resets the floating pointexception mask back to the state when it was called. This onlyapplies to Win32 platforms.

Note: This version was only released on the PI-API for Windows NT Inteland 16 bit Windows platforms. -----------------------------------------------------------------|PI-API version 1.2.3.2 release notes10-Mar-97 hs-----------------------------------------------------------------|

1. When connecting to a PI3 node without specifying the port number, thePI-API could fail to find the port number from the pilogin.ini file if thenode identifiers in the file (PI1=, PI2=, PI3, ...) did not start at 1 andproceed in order. This caused a bug where a user who started with a PI2system, added a PI3 system and removed the PI2 system from his connections

dialog could no longer connect to the remaining PI3 server. The code wasnot finding the entry so no port number was supplied. This resulted infailed connections as the default port (545) was used instead of 5450.

2. The function piba_search previously returned a -411 error if duringthe intial search (searchflag = 0) the string length of the passed batchidwas > 32, the string length of the passed unit was > 12, or the stringlength of the passed product was > 12. This restriction has been relaxedallowing longer keys to be used. 3. The function pisn_getsnapshotx previously did not correctly reportreturn codes which indicated errors. Calls which failed on the server,(for example an invalid point number) would incorrectly return 0

indicating success. This has been fixed.

4. The call pisn_getsnapshotsx on 16 bit Windows systems was unable toretrieve more than about 32,000 bytes of information or about 1500events. Attempts to bring back larger sets could result in GPFs.This problem was fixed, however, the function is still limited. Under16 bit Windows pisn_getsnapshotx can retrieve no more than 16,375events. The restriction is due to the need to return an array oferror codes with the call and the 16 bit Windows memory allocation andiostream limits. This problem also required a change on the PI3 server.


26/43

The server fix is included in PI3.1 build 2.81.

Note there are also limitations using pisn_putsnapshotx under 16 bitWindows. Generally, the caller must allocate arrays to pass to thisroutine. The largest array element to be allocated is the PITIMESTAMP.Under 16 bit Windows normal memory allocation is restricted to 64K.This effectively limits the number of PITIMESTAMPS you can allocate andthus the number of events you can pass. The limit in this case is 2047events. If the caller passes a NULL for the timestamp array pointer,indicating current time, an internal allocation limit is hit. In thiscase a maximum of 2339 events can be sent in one call.

-----------------------------------------------------------------|PI-API version 1.2.3.1 release notesJan-97 hs-----------------------------------------------------------------|1. A bug in the bufserv program, used with interfaces to transfer data to thehome node, was fixed. Systems sending data for points with pointnums >9972 could crash the bufserv program. Only the bufserv program is affected.The piapi library is unaffected though the version number has beenincremented. The bufserv program distributed with this release is version1.0.3. The bufserv program can now be run from the command line with a-v option to report the version number. The version number of any versionsof the bufserv program can also be determined using the properties option

from File Manager or Explorer. -----------------------------------------------------------------|PI-API version 1.2.3 release notesNov-96 hs-----------------------------------------------------------------|

1. The iorates program was modified to avoid sending rate reports to tags thatdo not exist. Previously the program would attempt to update a point usinga pointid of -5 as returned from pipt_findpoint. Start-up reporting has beenenhanced to display the number of points in the iorates.dat file that havebeen successfully registered as well as those in error.

2. Code in piut_netnodeinfo changed to use insensitive case comparison.Previously if case of the server name did not match the pilogin.ini filethe connected flag was always false.

3. Buffering code has been modified to optimize speed and cpu usage whencalling routine is using pisn_putsnapshots. This also applies to the "q"calls (pisn_putsnapshotq, pisn_sendexceptionq) as the underlying call tothese is pisn_putsnapshots.

4. Modifications were made to pisn_sendexceptions and pisn_sendexceptionqto fix a bug introducted in version 1.2.1. The bug prevented the variableoldstat from being updated in those calls. This resulted in digital tagsincorrectly evaluating exceptions as they were always compared against the

first passed in oldstat value if the program relied on sendexceptionsto update prev and old variables.

5. The precision of timestamps entered and retrieved through the extendedAPI functions has been improved and is now reliable to +/- 15 microseconds.

6. Early releases of the extended API exhibited a behavior where whensending large amounts of data, the client would report the local systembeing out of virtual memory. This has been fixed.


27/43

-----------------------------------------------------------------|PI-API version 1.2.2 release notes13-Sep-96 hs-----------------------------------------------------------------|

1. A bug was fixed where programs which attempt to stay connected for longperiods (such as interfaces), would be unable to reconnect to the home nodeonce they lost the connection. Sometimes this was manifested as being ableto reconnect once but not again. The problem was a resource leak in thecase of a connection failure. Each time the program attempted to connectand failed, a socket descriptor was allocated but not released. There areper process limits on the number of sockets that can be opened (~ 20).Once this limit was exceeded, the program would never be able to connect.

For a long running program, the effect was cumulative. If you shut down ahome node for a short time, it was possible, depending on the program design,to only try a few connections, so that when the server again became availablethere were still socket descriptors available. However the next time theserver was taken down, there were fewer descriptors left for this processso only a shorter down time could be tolerated.

The program design mentioned above refers to explicit vs. implicitreconnection techniques. Programs can either detect connection loss andsuppress further calls and do periodic connection attempts (explicit) or

just continue to make PI-API calls ignoring the disconnect status andrely on the PI-API to attempt the reconnection(implicit). Programs usingthe explicit method had a better chance of reconnecting after a short delayas typically they made fewer connection requests during that time, losingfewer descriptors. UNIINT interfaces follow this explicit reconnectionmethod. In either case, if the server was down long enough, the problemwould arise.

2. The criteria for exception reporting was modified slightly to agreewith the documentation and with the PI2 toolkit. Previously the PI-APIwould report an exception for real and integer points when the exceptionminimum time was exceeded and the difference between the new value andthe last exception was greater than or equal to the exception deviation

for the point. The test for exceptions now uses a greater than comparisoninstead of greater than or equal. The effects of this change arenoticeable when the exception deviation for a point is set to zero.Previously if a point, whose exception deviation was set to zero, wasgenerating values of 0, the PI-API would report exceptions every exceptionminimum time as the difference (0) was equal to the deviation (0). Withthis change, in this case, an exception will only be generated when thevalue changes or the exception maximum time is reached.

3. Increased frequency of calculation of difference between pisystem's time and devices time from every 30 minutes to every 5 minutesto improve detection of daylight savings time transitions.

4. Changed flags in semaphore calls used in buffering to include SEM_UNDO.This causes semaphores from processes that die or are killed to be releasedby the system preventing other processes from hanging waiting for theseresources.

5. Previously pisn_putsnapshots did not update the iorates countercorrectly. For each call it incremented the counter by 1. This has beenchanged to increment the counter by the number of values actually sentby pisn_putsnapshots.


28/43

-----------------------------------------------------------------|PI-API version 1.2.1 release notesAug-96 hs-----------------------------------------------------------------|

1. A bug introducted in 1.2.0 in pisn_sendexceptions andpisn_sendexceptionq was fixed.

2. The extended API functions that read data from PI(pisn_getsnapshotx, pisn_getsnapshotsx, piar_getarcvaluex,piar_getarcvaluesx) will fail if the data returned is in error(i.e. non-zero istat) when communicating with PI 3.1. These bugswill be fixed in PI-API 1.2.2.

3. pisn_getsnapshotsx: system error information returned for anindividual point by this routine is lost; all returned argumentswill be zero. This will be fixed in the PI-API 1.2.2 with theaddition of a new argument. This means that you will need tochange your code if you use this routine when PI-API 1.2.2 isreleased.

The manual reflects the new calling sequence. Check thecurrent function prototype in the include file piapix.h.-----------------------------------------------------------------|

PI-API version 1.2.0 release notesJul-96 hs-----------------------------------------------------------------|

1. pipt_updates previously returned the tag name field without nulltermination. It now copies as much of the 12 characters of tag namereturned from the server as possible given the user supplied bufferand null terminates the string. When communicating with PI3 systems(3.1 and greater) it is able to determine if the string has beentruncated and returns a -411 in this case.

2. Previously dummy functions were defined for functions provided byPathworks 4 and 5 on platforms where they did not exist. These are now

wrapped within functions named pixxxx to avoid name conflictsparticularly on UNIX platforms. The functions are getnodebyname,dnet_ntoa, getnodeadd, and getnodename.

3. Previously on the Solaris platform, when the PI-API log files wereshifted, the resulting file was named incorrectly. The month and dayin the file name were months away from what should have beenyesterday. Log files when shifted now get the correct month-dayextension.

4. Previously piut_netinfo failed if no connection was made prior tocalling the function. Now it initialized the socket layer and is able todeliver the local host information prior to any connection to a PI

server

5. When connecting to multiple servers, if disconnect was calledtwice (either by application, or internally due to network failures)the second call could crash or produce strange results. The linkedlist of connections was not being cleaned up properly when removingentries. This has been fixed. This change allows versions of piverifierthat previously crashed on piut_disconnect to complete successfully.

6. The batch functions, piba_getaliaswunit, piba_getunit, and


29/43

piba_getunitswalias previously did not detect when the user hadchanged servers (piut_setservernode) and would continue to sendresults from an earlier network retrieval unless function specificcriteria, described below, changed. With this version, if you switchservers or trigger the function specific refresh criteria, the API willfetch new information from the server. The function specific refreshcriteria is: piba_getaliaswunit - Refreshed if unit parameter changes between

calls piba_getunit - Refreshed if not called within last hour piba_getunitswalias - Refreshed when alias parameter changes between

calls

The function piba_search previously would refresh its result set fromthe server whenever the passed searchflag was 0. It did not detectwhen the user had switched servers and would continue to send resultsfrom an earlier search as long as the searchflag was non 0. Thisversion remembers the server where the search was performed. Whenpiba_search is called with a non 0 searchflag and the current serverdoes not match the server on which the search was initiated, itreturns a -3 error. piba_search should always be called first with asearchflag of 0 after switching to a different server. Note if you callpiba_search on a server, switch to a different server and switch backwithout an intervening call to piba_search you can pass a non 0 search

flag and continue your search as the last server where a search wasinitiated matches the current server.

7. The function piba_search previously would return some of the stringparameters with trailing blanks. This has been changed so all returnedstrings have trailing blanks trimmed. Other piba_xxx calls also trimtheir returned string parameters.

8. The functions pisn_putsnapshot, pisn_putsnapshots, pisn_putsnapshotq,and pisn_sendexcepstruc use int32 parameters for the istat variables andexcmin and excmax. When communicating with PI2 systems, only 16 bits ofthe passed data is actually sent. Previously the upper 16 bits of passeddata was truncated during exception testing and when the data was loaded

into the packets for transmittal. In some cases, bad input data, whentruncated, became good and was erroneously accepted by the server. Thesefunctions now check the passed in data before truncation to verify thatall istats passed to PI2 systems are valid. The absolute value of istatspassed to PI2 must be < 32768.

9. A signal handler was added to catch SIG_PIPE signals on UNIXplatforms. Under some conditions and platforms (e.g. Process SoftwareTCPWare on Vax talking to SUN), when the TCP connection was terminatedon the server a SIG_PIPE signal was being sent to the client APIprocesses causing them to exit. They will now hang around trying toreconnect.

10. A separate timeout for selects done prior to a write was added witha default of 3 seconds. When sockets are opened they call connect andthen did a write select to see if the connection was ready. As thisalways happens fast, waiting for the earlier default of 1 minute for itto fail was unnecessary. An entry in pilogin.ini - section NETWORKitem WRITETIMEOUT can be used to override the 3 second default ifnecessary.

11. When network messages are sent by the client to the server, theAPI now checks to see if buffering is enabled and if the message is


30/43

going to the default server. If this is true it checks a flag inshared memory maintained by the buffer server process indicatingwhether or not the server is currently accessible. If this flag indicatesthe server is inaccessible the API immediately returns a 2 (networkerror) to the caller. When the buffer server again connects, theshared memory flag is cleared and client calls proceed normally. Thischange allows interfaces to avoid blocking with each network call whenthe server is down. Instead they continue to send snapshots to thebuffering process. This avoids gaps in the interface data.

12. piba_search formerly returned 2 when the passed timeout wasexceeded. Version 2.1.1 of the server now returns -78 for this condition.piba_search previously returned -1 when called with a non-zero searchflag after a previous call with a search flag of 0 had failed. It nowreturns -2 indicating no valid search has yet been made. piba_searchformerly returned -1 when no records were found. It now returns 1 asdocumented.

13. A bug in pitm_formtime was fixed where if the passed string bufferwas less than 19 characters, the null terminating character was insertedone bytes past the end of the passed buffer.

14. The function pisn_putsnapshots, and pisn_sendexceptions,pisn_putsnapshotq, and pisn_sendexceptionq now send up to 255 values in

each network message when sending to a PI3 server. These functionscontinue to send a maximum of 36 values per message to PI2 servers.When using the "q" functions it is important to note that until 255values are received the queue will not be flushed to the server unlesspisn_flushputsnapq is called. This results in more efficientcommunication with PI3 servers.

15. The client pinet protocol version, has been raised to 00010008(major version 0001, minor version 0008) This is to indicate supportfor extended API functions. No new protocol messages have actuallybeen added for this support but this provides a way to programaticallydetermine the level of client support. Note 00010007 indicates supportfor batch and SQL. 00010005 indicates support for long tag names.

The PI-API will work with servers supporting the same major protocoleven if the server minor protocol is lower. Unsupported serverfunctions will return an error (-991).

16. The function piut_netnodeinfo previously did not return the correctconnected status. This has been fixed.

-----------------------------------------------------------------|v1.2.b2Jun 96 hs-----------------------------------------------------------------|

1. Version 1.2b2 represents the beta release of code to supportdata buffering on API nodes. For a complete description ofthe features, files, and programs involved in buffering referto chapter 7 of the PI-API manual, distributed with this beta.This chapter will be incorporated into the version 1.2 releasemanual.

2. Version 1.2b2 also contains beta code supporting the extendedPI-API for sending and retrieving subsecond time stamps and stringvalues on PI 3.1 servers. At the time of this release, the PI3.1


31/43

system had not yet been released to beta testing. For a detaileddescription of the extended API functions, refer to chapter 6 ofthe PI-API manual. This chapter is available on request for reviewand will be incorporated into the version 1.2 release manual.PI-API Modifications between Version 1.1.0 and 1.2.0

-----------------------------------------------------------------|v1.1.4-----------------------------------------------------------------|1. The function pitm_servertime will now return -999 if security is turnedon and the caller does not have READ privilege. Previously it returned1 which for this function was success but did not update the time.-----------------------------------------------------------------|v1.1.3Jan 96 hs-----------------------------------------------------------------|1. In pipt_findpoint, if the passed tagname is a long tagname (>12chars)and contains some lower case characters, when passed to a PI3 serverit is no longer truncated on return. Instead the full long name isreturned converted to all upper case. 28-dec-95 v1.1.3

2. pipt_digpointers now returns an appropriate digcode value for PI3 systems.On PI2 systems the number was the starting digital code for the point,typically less than 512. On PI3 systems, the code is the digital state

set identifier and is >65535 or 0 for the system set.

3. pisn_evmexceptions - previously would request network messages until acount of zero was returned. Now stops requesting network messages whenless than a full buffer is returned.

4. pisn_evmexceptions - previously returned exceptions in reverse order foreach buffer returned from server. Server returns oldest data first. Withineach network buffer, function would return newest first. Now returns inserver order - oldest first.

5. pisn_evmexceptions now remembers the server used when events are retrievedfrom the server and compares it to the current server each time the function

is called. If there is still data in the buffer but the server haschanged an error (-80) is returned and the data still in the buffer islost. Previously one could get unretrieved events from the previousserver when calling pisn_evmexceptions for the new server if you hadregistered for events on both. Note programs should empty theexception buffer by calling pisn_evmexceptions until it returns a count ofzero, before switching servers to avoid losing events.

-----------------------------------------------------------------|v1.1.2Dec 95 hs-----------------------------------------------------------------|1. The message system on UNIX would fail if too many messages were sent

in to short a time to the message log using pilg_putlog, and pilg_putoutput.The result was a stream of messages reading msgq_send error: no more processesThe actual error message was lost. The system now will report to stdoutthe first such error but also will send the original message to stdout. Themessage logging system will not be retried until 100 messages have beenreceieved and sent to stdout. This allows applications to realize thatthe logging system is being overburdened but still provides a way to capturethe error messages generated during that time.

2. The api in Windows and NT now looks in pipc.ini for the entry PIPCSHARE


32/43

in the section [PIPC] for a network directory override when looking forthe pilogin.ini file. It searches for the file in the DAT subdirectory ofthe PIPCSHARE directory.

The order of directories searched when finding pilogin.ini by the PI-API DLLis maintained and enhanced for backward compatibility. It is now a. The dat subdirectory under the PIPCSHARE entry in the pipc.ini file

b. The dat subdirectory under the directory above the module's directory (../dat) where the module's directory is:

16 bit - Directory where the PI-API DLL is loaded from 32 bit - Calling application's directory c. The current directory

d. The dat subdirectory under the PIHOME entry in the pipc.ini file

e. C:\PIPC\DAT-----------------------------------------------------------------|v1.1.1Nov 96 hs-----------------------------------------------------------------|1. The function piut_disconnect formerly sent a disconnection message to the

default server, regardless of its connection status and just closed the socketfor all other outstanding connections. This meant only the default server wasgiven a chance to gracefully end its process. It also meant if you were notconnected to the default server and called piut_disconnect, the API wouldattempt to connect to that server in order to send the message it was quitting.The API now sends the disconnection message to each currently connected server.

-----------------------------------------------------------------|PI-API version 1.1.0 release notesAUG-1995 - HKS-----------------------------------------------------------------|

----------Bug fixes:----------

Fixed a bug which allowed pitm_parsetime to accept erroneous monthnames on PI3 servers.

Added a check to piut_getapiversion that the passed buffer lengthis at least 9 characters long. Previously a shorter buffer couldresult in memory overwrites.

pipt_instrumenttag previously returned only 31 characters. Thefull 32 character tag can now be returned.

pipt_recordtype incorrectly returned 1 for points with resCode of4 and 0 for all others. This behavior was in conflict with thedocumentation and the Vax toolkit. The results have now beenreversed. Existing code calling this function should be examined.

pipt_scan would not update the lscan parameter when the status bitwas off. This has been fixed. Calling functions that set thelscan parameter to 0 before calling pipt_scan are unaffected.Those that did not, in previous versions would have been returned


33/43

whatever they passed if scan was off for the point.

-------------Enhancements:-------------

The toolkit function ArcTimeFilter has been addded to the API aspiar_timefilter. This function calculates the amount of timewithin the passed in range that an expression evaluates to true.A complete description is provided in the API manual.

Several API functions previously undocumented are now describedin full in the API manual. They are:

pipt_digcodefortag Retrieve the digital state associated with a passed string within the range of the

passed pointpipt_displaydigits Retrieve the display digits attribute for

the passed point.pipt_sourcept Retrieve a passed tag's source tag.pisn_sendexcepstruc Similar to pisn_sendexceptions but takes a structure of the old, new and previous

values rather than separate arguments.pitm_delay Wait for the specified number of

milliseconds.piut_getapiversion Retrieve the version number of the PIAPI being used.piut_netnodeinfo Return network information for the passed node name.

Three new functional

EJEMPLOS AVG(TAGVAL

Documents

Transcript of EJEMPLOS AVG(TAGVAL