Ejemplos Avg (Tagval

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
PILogin Version
PILogin Version
PILogin Version
PILogin Version
1.3.6
1.3.5
1.3.4
1.3.3
1.3.2
---------- Troubleshooting --------------------------------------|

If you have problems, make sure there are no old copies of
PIAPI32.DLL and PILOG32.DLL in your system, particularly in your
WINDOWS or WINDOWS/SYSTEM directories or on your path as described
above. If you find any old copies of PIAPI32.DLL, remove them
to a floppy disk or rename them. Only a single copy should be in
your system.
When you encounter errors, always check the file pipc.log found
in your %PIHOME%\DAT directory. The PI-API writes to this file
when it encounters errors. (Note: PIHOME is defined in pipc.ini
located in the WINDIR directory)
The error codes which are found in the pipc.log file may be
translated using the pilogsrv -e # command.
---------- C Programming Information ----------------------------|
The import libraries, piapi32.lib and pilog32.lib, may be used to
implicitly link to the PI-API and PILOGIN routines.
An example program with a Microsoft Visual C++ 6.0 makefile is
located 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 function
declarations for the functions provided in the piapi32 and pilog32
DLLs. These files make it possible to call PI-API functions directly
from Visual Basic. See the PI-API Programming Manual for more
information regarding calling C routines from Visual Basic.
-----------------------------------------------------------------|
RELEASE NOTES
-----------------------------------------------------------------|
PI-API version 1.3.8 release notes
June-2002
Bug fixes
--------1. Crash in PINetMgr caused by a data set in PI-ProcessBook
If a PI-ProcessBook display has a data set which contains a large number
of characters (~4100), e.g.,
If(TagVal('cdf144','*')<=TagVal('cdf144','*-4h')) And SStDev ...
and so on up to about 4100 characters
previous versions of the PI-API caused the PINetMgr process of PI
Universal Data Server to crash.
PI-API v1.3.8 fixes this problem.
2. Initialization of the APIBUF.DAT file
PI-API v1.3.6 has a problem whereby the APIBUF.DAT file is
re-initialized to 16 bytes whenever a new PI-API program starts up.
A typical 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 runs "apisnap" on the PI-API node to check whether
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) and
Bufutil 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 described
above:
PI-API v1.3.8
The following combination will still exhibit the problems described
above:
PI-API v1.3.6
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, will
distribute this correct combination of files:
PI-API v1.3.8
Thus, the above warning regarding incompatabities is for informational
and troublshooting purposes.
3.
The
the
(a)
(b)
(c)
(d)
Crash in PI-Buffer Server

PI-Buffer Server program distributed with previous versions of
PI-API sometimes crashed under the following scenario:
a PI-API node is sending data to PI Universal Data Server
this PI-API node loses communications to PI Universal Data Server
PI-Buffer Server buffers data to the APIBUF.DAT file
a user shuts down PI-Buffer Server
(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
FramePtr ReturnAd Param#1 Param#2
00f5fc50 0045ce9a fffff1f0 00000001
00f5fc5c 00403983 00f5fcd4 004973c4
,0])
00f5fd08 00401f0b 004973bc 00000012
stchange
appears in the DrWtsn32.log file:

Param#3 Param#4 Function Name
00403983 00f5fcd4 bufserv!_mkgmtime
00497010 00000000 bufserv!mktime (FPO: [1,0
004976a8 00c60000 bufserv!bufservermgr::setd
PI-Buffer Server v1.5.0.0 fixes this problem.

New feature
----------New version number for APIBUF.DAT
PI-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 version
1. The only difference between these version is the header information in
the 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 be
version 2.
PI-Buffer Server v1.4.0.0 and prior cannot process a version 2 APIBUF.DAT.
-----------------------------------------------------------------|
March-2002
Bug fixes
--------The pisn_evmexceptionsx() and pisn_evmexcepts() functions now return -77
when the PI Universal Data Server determines that the exception buffer
has overflowed. However, valid data are returned via the "PI_EVENT values"
and the "Val" parameters. Thus, the return of -77 is a warning to indicate
that there are too many values in the exception buffer on PI Universal Data
Server.
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. In
particular, 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. You
create this localhost.tz file via the "pidiag" command found in PI Universal
Data Server v3.3.
If the PI-API is running on a machine that is also running PI Universal Data
Server, then PI-API looks for the localhost.tz file in the following location:
$PI\dat\localhost.tz
(Windows)
$PI/dat/localhost.tz
(Unix)
where $PI represents the top-level directory in which PI Universal Data

Server 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 PI
Universal Data Server, PI-API looks for the time zone specification file
typically 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 Data
Server, then you need to transfer the localhost.tz file from the PI Universal
Data Server machine to the PI-API machine. Put this localhost.tz file in
the following location:
$PIHOME\dat\localhost.tz (Windows)
$PIHOME/dat/localhost.tz (Unix)
where $PIHOME represents the top-level directory in which the PI-API is
installed. $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 PI
Universal Data Server, PI-API looks for the time zone specification file
typically 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.tz
file, 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 the
creation 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 <iostream>
The latter involves
#include <iostream.h>
Incompatability with previous PI-API versions on HP-UX
-----------------------------------------------------On HP-UX, programs built with previous versions of the PI-API are not
compatible 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 install
PI-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 program
built 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
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.4
by
$ 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_PATH
environment 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 and
SHLIB_PATH environment variables set to, respectively, /opt/piapi_1.3.4 and
In order for PI-API node buffering to work for each of these two instances of
the PI-API, you will need to create the following entries in their
respective piclient.ini files.
In /opt/piapi_1.3.6/dat/piclient.ini:
[APIBUFFER]
BUF1NAME=PIAPI136_BUFFER1MEM
BUF1MUTEXNAME=PIAPI136_BUF1MUTEX
FILEBUFNAME=PIAPI136_FILEBUF
FILEMUTEXNAME=PIAPI136_FILEMUTEX
And in /opt/piapi_1.3.4/dat/piclient.ini:
[APIBUFFER]
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
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 be
compatible 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 install
PI-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 program
built 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.6
by
$ 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.4
by
$ 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_PATH
environment variables set to, respectively, /opt/piapi_1.3.6 and
Similarly, programs that need PI-API v1.3.4 would have their PIHOME and
LD_LIBRARY_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 of
the PI-API, you will need to create the following entries in their
respective piclient.ini files.
In /opt/piapi_1.3.6/dat/piclient.ini:
[APIBUFFER]
And in /opt/piapi_1.3.4/dat/piclient.ini:
[APIBUFFER]
PI-API node buffering program incompatibility
--------------------------------------------The PI-API node buffering programs (bufserv, bufutil, and isbuf) are
compatible with this PI-API version only. That is, you cannot use
PI-API v1.3.6 with the bufserv program that was delivered as part of
PI-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 specify
this 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
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 the
pisn_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 number
of "ptnum"s via
pisn_evmestablish( &numOfpts, &ptnum );
This program can then call pisn_evmexceptionsx() with the "funccode" of
GETFIRST:
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 stored
in an internal buffer within the PI-API. For example, if "count" is 7 when the
function returns, the exception values may look like the following:
1.
2.
3.
4.
5.
6.
7.
tagname
pointA
pointA
pointC
pointD
pointC
pointB
pointA
timestamp
4/17/2001 10:03:01
4/17/2001 10:03:05
4/17/2001 10:02:59
4/17/2001 10:03:02
4/17/2001 10:03:01
4/17/2001 10:03:03
4/17/2001 10:03:06
value
10.555
11.230
0.123
3.112
0.140
CLOSED
12.788
These exception values are in the same order that were received by PI
Universal Data Server.
The first call to pisn_evmexceptionsx(), with GETFIRST, returns the data in
row 1 above.
A subsequent call to pisn_evmexceptionsx() with GETNEXT returns the data in
row 2 above.
Another subsequent call to pisn_evmexceptionsx() with GETNEXT returns the
data in row 3.
data in row 4.
data in row 5.
data in row 6.

data in row 7.
error code PI_NOMOREVALUES.
-----------------------------------------------------------------|
Dec-2000 cah
1. pisn_sendexceptionq and pisn_sendexceptions did not properly
increment the returned count parameter in versions 1.3.2 to 1.3.4. A
count=2 would be returned as 1 and count=1 was returned as 0 (except for
out of order times). For the queued call, this would cause the data to
be added to the internal queue, but the calling program may not flush
the data queue to the server since count=0 in many cases. When 255
events (36 for PI2) were queued the data would be sent. For programs
that send only a few values, the snapshot may not be updated
immediately.
2. The routine piut_getprofile, implemented on UNIX, previously
converted strings to upper case. Now it returns strings unmodified.
3. pitm_fastservertime produced repeated messages when DSTMISMATCH
was 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 server
check to see if buffering is enabled. Previouly, all PI-API
programs would check to see if buffering was enabled when
connecting to the server then they would check to see if they
were connecting to the default server. This allows starting of
PI-API programs that do not connect to the default server before
the buffer server and allows the buffer server to be started
and stopped without stopping programs that do not connect to the
default server.
-----------------------------------------------------------------|
Aug-2000 cah
1. Disconnection of bufserv from the PI server in a timezone east
of GMT while no data was in the buffer causes an exception violation
on Windows NT. This does not affect UNIX releases. This was fixed.
2. If there are severe disk errors so that the buffer server cannot
use the file buffer, an error message would be printed for every
application call to put data into the file buffer. This has been
throttled so that every 1000th put attempt with the same file error
will be printed, the buffer file that is having the problem will be
renamed and another APIBUF.DAT started.
3. Windows socket behavior has changed with Windows 2000 from the
behavior observed in previous Windows versions. This behavior change
causes Windows 2000 clients using the PI-API to send a RESET to PI
servers when closing a connection. As a result, a message containing
the code 64 is logged in the PI server log file instead of a
graceful disconnection message (-10721). The PI-API has been
modified so that all currently released versions of Windows sockets
close properly.
-----------------------------------------------------------------|
May-2000 cah
1. Arguments to PI-API routines which are unmodified 'char *' were
changed to 'const char *' in piapi.h and piapix.h. This will
prevent warnings by newer ANSI C++ compilers about passing literal
string constants as arguments.
2. Added the routine pitm_getutctime to return double UTC time for
a PITIMESTAMP structure.
3. A PI-API uninstall program for Windows is now included in the
PIPC\bin directory. A dialog is presented with check boxes for
choosing which components to uninstall.
4. The AIX
libraries.
manual have
libraries.
release now has both shared and archive PI-API

The example make file for apisnap.c and the programmers
been updated with information for using shared
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 script
allows installation of either version.
6. The Solaris release now supports the ANSI C++ compiler version 5
and the previous version 4 compiled code. The installatio script
allows installation of either version.
7. Added put and get of PItimestamp point types that are available
in PI 3.3 servers. For sending values to PItimestamp point types
using pisn_putsnapshotsx, pisn_putsnapshotx, pisn_putsnapshotqx,
piar_putarcvaluesx if bval is provided in the argument list a string
is 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 string
is sent. Otherwise PI_EVENT.drval is sent. For VB variants with
typex=PI_Type_PItimestamp, pisn_sendexceptx sends a double. For
pisn_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. For
pisn_getsnapshotx, double, int32, bval pointer arguments are all
filled if they exist. drval and ival arguments are UTC values and
the bval is returned in localtime.
8. Added digital states ACTIVEBATCHSTAT, WRONGTYPESTAT, OVERFLOW_ST
and INTFSHUTDOWN = -311 to pidgstat.h.
9. Fixed a bug in HP-UX network read/write of large network
packets. Conditions causing the problem were packet sizes greater
than about 1700 bytes and less than optimal speed between the client
and PI server. The impact was lost data on receiving packets.
10. Fixed bug in pisn_putsnapshotsx to PI2 server. It is possible to
have 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
server in 255 char chunks. PI servers would return an error for api
version 1.3.2 only.
12. Fixed warning message about unacceptable jumps in the server
time offset which were issued by pitm_fastservertime. These time
offsets were typically changed by about 1 second and were obviously
acceptable changes.
13. Fixed a problem with extended sendexception routines. New values
with an exception deviation of zero and no change from the old value
would not be sent to the PI server. Setting exception deviation to
zero now works for all points.
14. Fixed the output message of the buffer server for points which
had an extended putsnapshot or putarcvalues error. The timestamp and
status of the bad value were to be printed, but the status value was
incorrect.
15. Fixed a problem in which the buffer server (bufserv) may exit if
the client generating data puts large amounts of data into the
buffers. Under such circumstances bufsev may not be able to lock the
buffer before the status changes from second buffer to file. After
the unexpected status change, bufserv would exit. It now skips that
iteration of buffer processing and tries again.
16. pitm_getpitime will now return -1 for incorrectly filled
PITIMESTAMP structures.
17. Eliminated possible PI_OVERFLOW (-15000) messages from the
buffer server when checking the server/client time offset.
18. Reduced the number of "connect() failure" messages which occur
as the API attempts periodic reconnection. Previously, every 2
minutes, the API would log the failure message. Now every 600
attempts generates a message (about 10 hour intervals for 1 minute
timeout setting).
19. Fixed a problem determining version of a PI 2.1 or earlier
server. The problem would cause excessive calls to the server
during archive or snapshot retrievals of arrays. The results would
take several times longer to retrieve.
20. The pilogsrv service start and stop was added to the Windows NT
pistart.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 the
primary buffer. This was usually seen when testing with a small
number of sent events. bufutil will now indicate the presence of
events in bufserv's temporary block used for sending data to the
server. The number of events in the block is added to the number of
events in the primary buffer.
23. bufserv previously attempted to communicate with the PI server
only when data was sent through the buffers by a PI-API program.
Thus, bufserv would only detect a server was unreachable when new
data was sent. When little or no data was sent to the PI server,
other PI-API programs could attempt to contact the server before
bufserv detected that the server was unreachable. Since bufserv did
not detect and disable the connection TIMEOUT first, these other
PI-API programs would wait for the TIMEOUT period before continuing
execution. Now bufserv checks the connection with the server every
PAUSERATE seconds (this parameter is set in piclient.ini and
defaults to 2 seconds). This allows bufserv to disable connection
TIMEOUT sooner for low throughput cases. Note: bufserv still waits
for TIMEOUT seconds when the connection is first lost.
24. Fixed output of Windows socket error numbers. The wrong number
was previously printed. No number-to-string lookup is available for
windows socket errors. Some socket errors have been added to the
PI-API installation instructions (API_install.doc).
25. Fixed pisn_sendexcepstrucq problem in which the numbpterrs
argument was not updated. Also, in some circumstances, qerrs was not
updated properly.
26. pisn_sendexceptionsx and pisn_evmexceptionsx contained a memory
leak for strings and blobs if a digital state was obtained
alternating with good values.
27. If no connection to the server was performed and no default
server 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 been
fixed.
28. Windows installation program now has a checkbox for enabling
auto-start of bufserv. Previously, bufserv would be installed as
manually started so that testing could be done before enabling
auto-start of the bufserv service. Changes to the dialog text of
the installation has been made for clarity.
29. The UNIX installation script has been expanded. It detects
unsupported versions of the operating system, the validity of the
user 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 the
newer features.
31. The iorates program now detects the iorates.dat file
modification time to determine if a re-read is needed. Also, the tag
name lookup by pipt_findpoint would capitalize the tagname. It was
causing a repeated lookup of tagnames.
-----------------------------------------------------------------|
Dec-99 cah
1. A bug in the PI-API pitm_localtime routine (OSI's implementation
of localtime) has been fixed. The problem caused an exception
violation in pitm_intsec. The problem was caused during daylight
savings when a time is entered into PI-API routines that accept the
local time. Entering a zero local time may result in a UCT time
less than zero. The localtime routines previously used had a range
of validity to -3600 seconds for daylight representation of time
zero. Now the new localtime routine also handles the range to -3600
properly.
2. A bug in bufserv has been fixed such that filling a memory

buffer exactly (0 bytes left for more events) will result in a
crash. The next attempt to write into the buffer after filling the
buffer would cause either the data producing client program or
bufserv to crash. This would typically occur when buffering to a
file or when bufserv was emptying a file after a disconnection from
the server and extended API pisn_putsnapshotx routines were used to
send data to PI. Standard API routines have constant size events
which would usually not fill the buffer exactly.
3. The buffer server would only produce a shutdown message in the
log file while running interactively on Windows NT. Now stopping
bufserv when it is running as a Windows service produces a shutdown
message in the log file.
4. The buffer server could have produced an uninitialized number of
events already in the block used to transfer events from the file
APIBUF.DAT to the memory buffers during startup. This could occur
when events exist in the file APIBUF.DAT and a restart of the buffer
server is done.
5. A bug in pisn_evmexceptx was fixed in which PI2 types were not
properly 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.3
and has been fixed. It prevented the bsize variable of string values
from 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 which
could cause data loss during the fall DST transition. If a client
program adds new values with a timestamp of 0, the timestamp is
resolved to the current server time. However, when the fall
transition 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 not
occur with the "out of order" data until pitm_fastservertime once
again exceeded 'oldtime'. Every "out of order" value is sent with
the timestamp which was assumed to now be in 'oldtime'. This has
been fixed. Second, every scan would be sent since all new values
were determined to be out of order. This second problem has not been
fixed in the standard exception routines. It is recommended that
pisn_sendexceptionqx be used to fix both problems.
8. A bug in the routine piut_strerror resulted in the same string
being 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 received
data buffer is now deleted after use.
10. An enhancement of bufserv has been added which preserves the
data in the memory buffers when data which cannot be processed is
encountered. If bufserv encounters an event activation error it will
exit. Previously, the memory buffers would be lost since the data
was be unreadable. Now the memory buffer which caused the error
will be dumped to a file in the PIHOME\dat directory for later

analysis and/or recovery.
11. If more than 100 consecutive -10401 or -10407 errors are
received by bufserv, piut_disconnect is issued and bufserv waits for
the retry interval before reconnecting. The reconnection is
intended to obtain any new security permissions from changes on the
PI server. The user must still identify the problem and fix the
server permissions to allow the data to be sent to PI. Previously,
the permission denied error would cause data to be lost since it was
not treated as a system error, but a point error. This situation
could arise during reconnection to a PI 3 server after a network
problem.
12. For system errors, now "putsnapshots" is logged as the source of
the error for standard API calls and "putevents" is logged as source
of the error for extended API calls.
13. Putsnapshot errors for bufserv now use the routine piut_strerror
to translate error codes to strings.
14. The bufutil utility has been modified to allow multiple
iterations of a buffer's header information to be printed to the
screen at the interval you specify (defaults to 5 seconds). Also,
the version of bufutil is now printed when the "-v" command line
flag is used.
15. Unix message queue now only prints an error one time if the
message queues are unavailable instead of 4 times.
16. The PI-API now remembers the login name used in piut_login and
when a reconnection occurs to the server, the same username is
logged into the PI server.
17. Added piut_getloginuser to the piapi.h list of exported
functions. This routine returns the name used by piut_login to log
into 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 default
login privilege. NULL pointers may now be used to get the default
login 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 the
APIBUFFER section. The string is of the format
"LOGIN=username,password". If password is omitted a blank password
is assumed. This feature is designed for testing purposes only.
THIS FILE IS NOT SECURE. The recommended method of allowing write
access to a PI server is to use the PI proxy table for PI3 servers
or 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 Windows
GetPrivateProfileString mechanism to read all section names or all
key (entry) names within a section. If a NULL is passed as the
section argument, all section names without the surrounding brackets
and without leading or trailing spaces are returned in the buffer.
Each section name is separated by a null character from the

following section name and the list is terminated by two null
characters. piut_getprofile will now accept NULL arguments without
an exception.
22. Added server name to output of piut_fastservertime messages.
-----------------------------------------------------------------|
PI-API version 1.3.1.3 release notes
jul-99 cah
A bug in the PI-API has been fixed which caused some duplicate
events to be sent to the server and some events to be lost during
buffering of the data. The problem occured when adding arrays of
events to the buffers (pisn_putsnapshots, pisn_putsnapshotq,
pisn_putsnapshotsx) and the primary or secondary memory buffers have
only enough space for a few of the events. In this case, those few
events are added to the next buffer as well and an equal number of
events from the end of the array are not buffered. This is observed
as duplicate events and missing events especially noticeable when
compression is turned off.
A bug in the pisn_sendexceptionsx routine has been fixed. The
problem occured for digital tags whose values switched from values
within the tag's digital set to a system state set value. In that
case an error would occur for the later value.
A warning message about disk space which was printed out for Windows
NT PI-API nodes has been eliminated. The message would state that not
enough disk space was available for the maximum sized buffer file when
there was actually greater than 4 GB of data.
-----------------------------------------------------------------|
jun-99 cah
A bug in the pitm_settime and pitm_getpitime routines has been
fixed. The functions pitm_settime and pitm_getpitime could produce
incorrect timestamps if the time structure was populated by
assigning individual members and the tzinfo member (formerly
reserved) is set to zero and the client is in daylight time. In
this case, the time would be pushed forward 1 hour.
A new function, piut_strerror, has been added to retrieve a single
error message string for a return code if given a string indicating
the calling program. If a null is passed for the string, the
routine will return multiple messages for a given return code until
PI_NOMOREVALUES is returned by piut_strerror.
An installation program has been created which will automatically
install the bufserv and pilogsrv services on Windows NT. The
piapi32.dll, pilog32.dll and run time libraries are also installed.
For windows programs, piut_getprofile is now defined as
GetPrivateProfileString and piut_writeprofile is defined as
WriteProfileString. This is useful for writing PI-API programs for
both UNIX and Windows platforms from the same source code.
Increased maximum log file size to 4 MB for the pilg_checklogfile
routine. This is now the maximum number of bytes for the pipc.log
file.
If an alternate file name was used in pilg_checklog, the extension
was forced to be '.log'. Now any extension may be used.
Enabled the pilg_checklog option to re-initialize the filename and
size/number of log files using an argument of action=-1.
Fixed problem with pilg_checklog which caused Windows 9x logs to
be shifted on startup if size was not yet the maximum.
The UNIX iorates program has been enhanced to cleanly disconnect
when a kill -2 or kill -15 command is used. Also, the connection to
the server is attempted every 1 minute and after 10 minutes an
explicit 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 is
implemented.
Added the HPUX process name to the pilg_formputlog output instead
of the process id.
pitm_delay now uses POSIX4 subsecond sleeps for OSF1, AIX and
SunOS. This forces SunOS to link with '-lposix4'.
The buffer server had a memory leak which would occur in high
snapshot rates with extended putsnapshot calls. This is fixed.
The buffer server program will now throttle error messages after
100 repeats of the same error for an array of points. Thus, if all
points get the same error, they will not all be reported.
The API buffer server program would occasionally report an error
cleared for points which never had an error reported. This has been
fixed.
The buffer server will now rename a truncated APIBUF.DAT file
which it is unable to read to APIBUF.###. It will then be able to
start successfully. Previously, the buffer server would be unable
to 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 free
disk space available if more than 4GB is free.
The apisnap program now can retrieve archive values with the same
timestamp as the snapshot value. The option to enter the servername
and a list of tags has been added. All tags in the list will have
snapshot and most recent archive value listed. The format of the
command 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 is
retrieved. Otherwise, a prompt is displayed for tagname.
The pilogsrv utility can now provide error messages for a specific
function (for instance, the -1 return for pisn_putsnapshot) instead
of all functions which produce that error return. The format of the
command is now, for example,

> pilogsrv -e -1 pisn_putsnapshot
A bug in piut_fastservertime was fixed which gave the wrong server
type (PI 2) for PI 3 servers with long version strings.
-----------------------------------------------------------------|
apr-99 cah
A bug in reconnection by the API has been fixed. After a
temporary disconnection the API would delete the PI server name
internally. During after a subsequent disconnection, the server
name would not match the buffered server name. This would prevent
buffering of data. The application would begin managing connections
to the server instead of the buffer server. Temporary loss of
connection 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 initial
connection would default to the PI2 behavior. Now, if no initial
connection is done by the calling program, but PI server information
is required (putsnapshot calls), a connection to the default PI
server is made.
An enhancement to the connection identification has been made. If
a client program did not set the process name identifier
(piut_setprocname) before connection, the PI server would log a
connection from "UNKN". Now, if the process name is not set before
a connection to the server, the executable name is used as the
process identifier.
pipt_findpoint previously did not attempt to determine the
server type when no initial server connection existed. Thus,
the default short tagname behavior was used. An attempt
to 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 generate
a message in the client log file indicating a new connection
to the server and whether it is the default PI server (in brackets).
12-Apr-99 11:50:17
apisnap.exe>PI-API> Initial connection to [localhost:5450][1]
The bufutil utility now indicates if bufserv is running, but
the buffering flag was not turned on in piclient.ini.
-----------------------------------------------------------------|
feb-99 cah
NEW PI-API LIBRARY CALLS:
The following new extended PI-API calls have been added to
piapi32.lib and the prototypes are located in piapix.h:
----------------------------------------------------------piar_getarcvaluesfilterx(): This call will retrieve archive
values from the server for a point with the GETFIRST/GETNEXT/GETSAME
function code. The server will return all the values requested with
a GETFIRST call and the values will be buffered on the client for
retrieval. A filter expression may be passed if desired. A NULL
value 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 filter
expression. ARCflag_mark Mark values which do not pass the filter
expression with FILTERFAILSTAT. Note: PI 3 servers compress a
series of subsequent filter failure statii into one filter fail.
For server versions less than PI 3.2 SR1, this call reverts to
the standard API calls to return filtered archive data.
piar_putarcvaluesx(), piar_putarcvaluex(): These calls will
add/delete an event or array of events to the archive. The following
modes 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 events
ARCREPLACE
add event, replace if event at same time
ARCREPLACEX replace existing event (fail if no event at time)
ARCDELETE
remove existing event
ARCAPPENDX
add event regardless of existing events, no compression
For server versions less than PI 3.2 SR1, this call reverts to
the standard API calls to delete/replace values.
pisn_evmexceptionsx(): This routine retrieves any new data
received in the update manager for points selected by the
pipt_evmestablish() call. It will now retrieve string type points
in addition to float, integer, and digital points. Data types of
the PIvaluetype enumeration are provided with the data retrieved
from PI3 servers. The data is placed into a PI_EVENT structure
which allows for any data type. The data type is set to PI_Type_PI2
for 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 from
the snapshot calls pisn_putsnapshotqx() or pisn_sendexceptionqx() to
be 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 before
sending the data to the home node or a pisn_flushputsnapqx() call is
made.
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 before
sending the data to the home node.
pisn_sendexceptionsx(): This routine does exception processing on
an array of PI3 points.
pitm_isdst(), pitm_setdst(): These routines are used to
interpret/set the PITIMESTAMP structure tzinfo field. pitm_setdst
sets the appropriate bit pattern in tzinfo according to the tm_isdst
argument of true(1) or false(0).

piut_errormsg(): This routine returns a message string for the
error code entered. Some error codes may return more than one
message (the message depends on the PI-API call used), thus the
function may be called until PI_NOMOREVALUES is returned.
pisn_sendexceptqx(): This routine is used as a Visual Basic
interface to the pisn_sendexceptionqx() call. This routine accepts
the VB Variant data type for exception processing. Queueing of the
snapshot data will be done if the queueing flag is set.
pisn_evmexceptx(): This routine is used as a Visual Basic
interface to the pisn_evmexceptionsx() call. This routine accepts
the 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) is
used to determine the size of the pipc.log file (default) or the
passed 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 be
changed using the MAXLOGSIZE key in the %SystemRoot%\pipc.ini file.
The maximum number of log file defaults to 20, but may be changed by
using the MAXPIPCLOGS key. Both keys are in the [PIPC] section.
After the maximum file number is reached, numbering restarts at
zero, thus overwriting the oldest file.
pipt_signupforupdatesfil(): This routine allows point updates to
be filtered with an optional pointsource and location1 parameter.
Currently, the function should return unsupported (-10008) until PI3
server 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 values
to be sent with queueing of the data. The queuing flag is used to
indicate no queueing (0), queuing (1), or flush the queue (-1). The
flush call is needed for Visual Basic applications since the
QERRORS structure of the flush call could not be handled in VB.
piut_fastserverversion(): This routine returns the server major
version of the connected node and the arguments of minor version and
build number.
ENHANCED/CHANGED PI-API CALLS:
-----------------------------piar_getarcvaluesx(): Now acceptes ARCflag_time in addition to
ARCflag_comp and ARCflag_even.
pipt_digcodefortag(): Previously, input strings were limited to
12 characters. It now accepts digital strings up to 79 characters.
pipt_compspecseng(), pisn_excdeveng() calls would return rounded
deviation values for integer points. Now they return the decimal
value as entered in the point configuration. This does not affect

data 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 UNIX
platforms.
pitm_fastservertime() now does not allow step changes in the
offset between the server and client time unless explicitly allowed
in the pilogin.ini or piclient.ini (UNIX) files. This prevents
accidental time changes from producing bad timestamps on the client
and prevents bad timestamps if the server and client change DST
settings at slightly different times. This should be used if the
server 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 number
of seconds specified. The '#' represents the number corresponding
to 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 the
next month. For example: April 31 becomes May 1.
API PROGRAMS:
-------------The buffer server (bufserv) now supports buffering of all PI
point types for the put snapshot and send exception calls (pisn_),
and the put archive calls (piar_). (Extended API calls are also
buffered). The buffer server also supports the DSTMISMATCH key in
the [PISERVER] section of the piclient.ini file. This allows the
server and client to have different DST rules. The
pitm_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 for
all 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 the
tagname is also specified, only that tag will be displayed, then the
program will exit instead of prompting for another tagname.
Also, a point number may be entered instead of the tagname by
using a leading backslash before the number. This may be useful
when 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 and
rename it if it exceedes 256kb or the size specified in the pipc.ini
file. The number and size of each file may be specified in pipc.ini
in the [PIPC] section using the keys MAXPIPCLOGS and MAXLOGSIZE
respectively. After the maximum file number is reached, numbering
restarts at zero, thus overwriting the oldest file.
The pilogsrv utility program may be used to translate error codes
into a string description. Multiple descriptions may result for a
single code due to the repeated use between some API calls. The
format is pilogsrv -e #, where '#' is the error code.

The UNIX iorates program has been modified to continue connection
attempts during startup instead of exiting if the initial connection
attempt fails. The program now uses pitm_fastservertime() instead
of pitm_systime() for timestamps.
A UNIX script (apiverify) has been provided to list the process
memory and cpu usage for PI-API processes. Additional processes may
be added to the list by editing the $PIHOME/bin/apiprocs file.
BUG FIXES:
---------A pipt_nextptwsource() bug has been fixed which translated a return
of 2 (a network error) into -1 (no more points). It now correctly
returns 2 so that the appropriate error correction can be completed.
A pitm_parsetime bug has been fixed which would incorrectly interpret
a four digit year in a PI time string. For example, 7-jul-1998 as
would become year 2019 and attempt to use the following numbers in the
time calculation. Now the function returns an error if more than two
digits are used for the year. Standard PI times only use the last two
digits of the year.
A pitm_parsetime bug has been fixed which would incorrectly allow days
29, 30, or 31 for months which have fewer than 31 days. An error is
now returned.
A point retieval bug has been fixed in which multiple successive calls
with a bad point number would return irrelevant data. Bad point
numbers will now return an error every time. This bug affected all
most point calls.
A pisn_evmestablish bug has been fixed in which calls made with a
count of zero would return an uninitialized integer. Now a zero is
returned.
A piar_* bug has been fixed in which some calls would return 2 instead
of -1 when an invalid point number of -1 was used. Affected routines
were 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 exception
violation if a null pointer for one of the arrays was passed. Now an
error is returned.
A pisn_evmexceptions bug has been fixed in which the number specifying
the size of the returned buffer from the network call would be
uninitialized during some network errors. Usually, this would
manifest itself on networks which had a high load and/or slow speed
(for example, serial communication lines). This bug could cause a
memcpy() to unallocated memory resulting in an access violation.
A bug caused during a communication errors when more than one
connection was opened has been fixed. A communication error with one
node would cause all the sockets to be closed, but the servers would
not be notified (using sendserverabort). This would cause stranded
sockets on the server. Now only the connection receiving the error is
closed.
A bug on Windows NT in converting an IEEE floating point value to
VAX floating point value has been fixed. The compiler would do a
check on the VAX floating point format as an IEEE floating point
number. In 1/512 cases, the result would have one bit switched.
accuracy of the number would be reduced from 1.19e-7 to 7.63e-6.
values affected span the entire floating point range. API calls
pisn_putsnapshot, pisn_putsnapshotq, pisn_putsnapshots,
pisn_sendexcepstruc, pisn_sendexceptionq, pisn_sendexceptions,
piar_putvalue, piar_replacevalue calls were affected.
a
type
The
The
A bug on AIX which would produce inaccurate data due to IEEE to VAX
floating point conversions has been fixed. This is the same as for
Windows NT, except the values at which the error occured were
different.
-----------------------------------------------------------------|
10-Nov-98 hs
-----------------------------------------------------------------|
1. The PI-API in this and previous versions is built with the
C run-time library statically linked in. This means calls within
the PI-API to C run-time functions are not executed in the
msvcrt.dll installed on the system but instead are executed within
the PI-API. Version 4.x of the Microsoft C run-time libraries
contained a bug where conversions between local and UTC time were
incorrect for systems with a time zone setting that did not honor
Daylight Savings Time (e.g. Saudia Arabia, Korea, Arizona).
Recent versions of the Alpha NT PI-API (1.2.3.1 - 1.2.3.4) were
statically linked with version 4.x of the C run-time library and
therefore contained this bug. This version (1.2.3.5) is built
with the same code as version 1.2.3.4 but is statically linked
against version 5.x of the C run-time library where this bug has
been repaired. (Note: On the NT Intel platform v1.2.3.4 is linked
with version 5.x, prior versions are linked with version 4.x and
exhibit the bug)
This bug primarily affects programs which make "Extended
API" calls (see Chapter 6 of the Programmer's manual). These
calls send UTC times to the server and do conversion between
local and UTC times on the local system exposing the bug.
Regular API calls send local times to the server which in the case
of PI3 translates them to UTC on the server. As no conversion is
made on the API node the bug is not exposed. OSI products that
make 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 data
to the PI Server using the extended API (e.g. Batch File) and
your system is set to a timezone where DST is not observed, you
may need to correct data in the archive. See the following
web pages for more information or call OSI technical support.
http://irn.osisoft.com/osiirn/pi/timebug/bugquest.html
http://irn.osisoft.com/osiirn/pi/timebug.htm#Repair
-----------------------------------------------------------------|
15-Oct-97 hks
-----------------------------------------------------------------|
1. pisql_set_timeout: this routine now checks to make sure that the PI-API
timeout is at least 5 seconds greater than the passed timeout value. If it
is not, it sets the PI-API timeout to 5 seconds greater than the passed
timeout value for the current session only, and writes an informational
message to the PI-API message log file. This routine is used by the
PI-ODBC Driver.
2. pitm_formtime previously would crash if passed a timedate of 0 for
systems set to time zones east of Greenwich, England and west of the
international dateline. The function pitm_secint had the same problem.
The function pitm_intsec would also exhibit this problem if passed
integer date components close to Jan 1 1970 0:0:0. This behavior has
been fixed. The problem was that the entered local time evaluated to
a 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 similarly
to pilg_putlog but it logs the calling application name and a passed ID
string 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 the
second argument and is appended to the message. The internal api messages
have now been changed to use this function to give more useful error
messages. Example output appears as follows:
28-Oct-97 11:55:43
apisnap>PI-API> Warning: Server Minor Protocol Vers 7 < Client Vers 8:Major vers
ion OK
28-Oct-97 11:56:17
apisnap>PI-API> gethostbyname: foobar sock_errmsg: Error: 0, Error 0 occurred.
In this example, taken from a DEC UNIX system, the program apisnap
successfully connected to a host and posted the warning concerning different
protocol levels. The PI-API designator is the idstring argument. The
second example shows apisnap failing to connect due to the inability to
translate the hostname foobar. In previous versions these messages were
logged 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 be
compared to output from the ps command to determine the calling proram.
For example:
28-Oct-97 17:04:25
7955>PI-API> gethostbyname: foobar sock_errmsg: Error: 0, Error 0
Here the process with PID 7955 called the PI-API with a bad hostname.
-----------------------------------------------------------------|
20-Jun-97 hs
-----------------------------------------------------------------|
1. The function pitm_fastservertime previously did not work correctly
against PI on OpenVMS systems that had security enabled (RLWL), until
the user had successfully logged in and 10 minutes had elapsed.
Times returned from that function under those conditions were

indeterminate. This behavior has been fixed. If default read or
read/write permissions were specified the function worked correctly.
Calls against PI on Windows NT and UNIX also worked correctly in earlier
versions.
Note: This version was only released on the PI-API for Windows NT Intel
and 16 bit Windows platforms.
-----------------------------------------------------------------|
24-Apr-97 hs
-----------------------------------------------------------------|
1. In previous versions, on Windows platforms, when certain printer
drivers were used they would disable the default floating point
exception masking. This would lead to crashes (unhandled exceptions)
in later calls to functions used to retrieve archive values which
passed uninitialized float arrays to be filled. With this version,
the PI-API will temporarily set the exception masks prior to dealing
with these floating point values. It then resets the floating point
exception mask back to the state when it was called. This only
applies to Win32 platforms.
Note: This version was only released on the PI-API for Windows NT Intel
and 16 bit Windows platforms.
-----------------------------------------------------------------|
10-Mar-97 hs
-----------------------------------------------------------------|
1. When connecting to a PI3 node without specifying the port number, the
PI-API could fail to find the port number from the pilogin.ini file if the
node identifiers in the file (PI1=, PI2=, PI3, ...) did not start at 1 and
proceed in order. This caused a bug where a user who started with a PI2
system, added a PI3 system and removed the PI2 system from his connections
dialog could no longer connect to the remaining PI3 server. The code was
not finding the entry so no port number was supplied. This resulted in
failed connections as the default port (545) was used instead of 5450.
2. The function piba_search previously returned a -411 error if during
the intial search (searchflag = 0) the string length of the passed batchid
was > 32, the string length of the passed unit was > 12, or the string
length of the passed product was > 12. This restriction has been relaxed
allowing longer keys to be used.
3. The function pisn_getsnapshotx previously did not correctly report
return 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 to
retrieve more than about 32,000 bytes of information or about 1500
events. Attempts to bring back larger sets could result in GPFs.
This problem was fixed, however, the function is still limited. Under
16 bit Windows pisn_getsnapshotx can retrieve no more than 16,375
events. The restriction is due to the need to return an array of
error codes with the call and the 16 bit Windows memory allocation and
iostream limits. This problem also required a change on the PI3 server.
The server fix is included in PI3.1 build 2.81.

Note there are also limitations using pisn_putsnapshotx under 16 bit
Windows. Generally, the caller must allocate arrays to pass to this
routine. 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 and
thus the number of events you can pass. The limit in this case is 2047
events. If the caller passes a NULL for the timestamp array pointer,
indicating current time, an internal allocation limit is hit. In this
case a maximum of 2339 events can be sent in one call.
-----------------------------------------------------------------|
Jan-97 hs
-----------------------------------------------------------------|
1. A bug in the bufserv program, used with interfaces to transfer data to the
home 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 been
incremented. The bufserv program distributed with this release is version
1.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 versions
of the bufserv program can also be determined using the properties option
from File Manager or Explorer.
-----------------------------------------------------------------|
Nov-96 hs
-----------------------------------------------------------------|
1. The iorates program was modified to avoid sending rate reports to tags that
do not exist. Previously the program would attempt to update a point using
a pointid of -5 as returned from pipt_findpoint. Start-up reporting has been
enhanced to display the number of points in the iorates.dat file that have
been 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 file
the connected flag was always false.
3. Buffering code has been modified to optimize speed and cpu usage when
calling routine is using pisn_putsnapshots. This also applies to the "q"
calls (pisn_putsnapshotq, pisn_sendexceptionq) as the underlying call to
these is pisn_putsnapshots.
4. Modifications were made to pisn_sendexceptions and pisn_sendexceptionq
to fix a bug introducted in version 1.2.1. The bug prevented the variable
oldstat from being updated in those calls. This resulted in digital tags
incorrectly evaluating exceptions as they were always compared against the
first passed in oldstat value if the program relied on sendexceptions
to update prev and old variables.
5. The precision of timestamps entered and retrieved through the extended
API functions has been improved and is now reliable to +/- 15 microseconds.
6. Early releases of the extended API exhibited a behavior where when
sending large amounts of data, the client would report the local system
being out of virtual memory. This has been fixed.
-----------------------------------------------------------------|
13-Sep-96 hs
-----------------------------------------------------------------|
1. A bug was fixed where programs which attempt to stay connected for long
periods (such as interfaces), would be unable to reconnect to the home node
once they lost the connection. Sometimes this was manifested as being able
to reconnect once but not again. The problem was a resource leak in the
case of a connection failure. Each time the program attempted to connect
and failed, a socket descriptor was allocated but not released. There are
per 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 a
home 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 available
there were still socket descriptors available. However the next time the
server was taken down, there were fewer descriptors left for this process
so only a shorter down time could be tolerated.
The program design mentioned above refers to explicit vs. implicit
reconnection techniques. Programs can either detect connection loss and
suppress further calls and do periodic connection attempts (explicit) or
just continue to make PI-API calls ignoring the disconnect status and
rely on the PI-API to attempt the reconnection(implicit). Programs using
the explicit method had a better chance of reconnecting after a short delay
as typically they made fewer connection requests during that time, losing
fewer descriptors. UNIINT interfaces follow this explicit reconnection
method. In either case, if the server was down long enough, the problem
would arise.
2. The criteria for exception reporting was modified slightly to agree
with the documentation and with the PI2 toolkit. Previously the PI-API
would report an exception for real and integer points when the exception
minimum time was exceeded and the difference between the new value and
the last exception was greater than or equal to the exception deviation
for the point. The test for exceptions now uses a greater than comparison
instead of greater than or equal. The effects of this change are
noticeable when the exception deviation for a point is set to zero.
Previously if a point, whose exception deviation was set to zero, was
generating values of 0, the PI-API would report exceptions every exception
minimum time as the difference (0) was equal to the deviation (0). With
this change, in this case, an exception will only be generated when the
value changes or the exception maximum time is reached.
3. Increased frequency of calculation of difference between pi
system's time and devices time from every 30 minutes to every 5 minutes
to 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 released
by the system preventing other processes from hanging waiting for these
resources.
5. Previously pisn_putsnapshots did not update the iorates counter
correctly. For each call it incremented the counter by 1. This has been
changed to increment the counter by the number of values actually sent
by pisn_putsnapshots.
-----------------------------------------------------------------|
Aug-96 hs
-----------------------------------------------------------------|
1. A bug introducted in 1.2.0 in pisn_sendexceptions and
pisn_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 bugs
will be fixed in PI-API 1.2.2.
3. pisn_getsnapshotsx: system error information returned for an
individual point by this routine is lost; all returned arguments
will be zero. This will be fixed in the PI-API 1.2.2 with the
addition of a new argument. This means that you will need to
change your code if you use this routine when PI-API 1.2.2 is
released.
The manual reflects the new calling sequence. Check the
current function prototype in the include file piapix.h.
-----------------------------------------------------------------|
Jul-96 hs
-----------------------------------------------------------------|
1. pipt_updates previously returned the tag name field without null
termination. It now copies as much of the 12 characters of tag name
returned from the server as possible given the user supplied buffer
and null terminates the string. When communicating with PI3 systems
(3.1 and greater) it is able to determine if the string has been
truncated and returns a -411 in this case.
2. Previously dummy functions were defined for functions provided by
Pathworks 4 and 5 on platforms where they did not exist. These are now
wrapped within functions named pixxxx to avoid name conflicts
particularly on UNIX platforms. The functions are getnodebyname,
dnet_ntoa, getnodeadd, and getnodename.
3. Previously on the Solaris platform, when the PI-API log files were
shifted, the resulting file was named incorrectly. The month and day
in the file name were months away from what should have been
yesterday. Log files when shifted now get the correct month-day
extension.
4. Previously piut_netinfo failed if no connection was made prior to
calling the function. Now it initialized the socket layer and is able to
deliver the local host information prior to any connection to a PI
server
5. When connecting to multiple servers, if disconnect was called
twice (either by application, or internally due to network failures)
the second call could crash or produce strange results. The linked
list of connections was not being cleaned up properly when removing
entries. This has been fixed. This change allows versions of piverifier
that previously crashed on piut_disconnect to complete successfully.
6. The batch functions, piba_getaliaswunit, piba_getunit, and
piba_getunitswalias previously did not detect when the user had

changed servers (piut_setservernode) and would continue to send
results from an earlier network retrieval unless function specific
criteria, described below, changed. With this version, if you switch
servers or trigger the function specific refresh criteria, the API will
fetch new information from the server. The function specific refresh
criteria 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 from
the server whenever the passed searchflag was 0. It did not detect
when the user had switched servers and would continue to send results
from an earlier search as long as the searchflag was non 0. This
version remembers the server where the search was performed. When
piba_search is called with a non 0 searchflag and the current server
does not match the server on which the search was initiated, it
returns a -3 error. piba_search should always be called first with a
searchflag of 0 after switching to a different server. Note if you call
piba_search on a server, switch to a different server and switch back
without 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 was
initiated matches the current server.
7. The function piba_search previously would return some of the string
parameters with trailing blanks. This has been changed so all returned
strings have trailing blanks trimmed. Other piba_xxx calls also trim
their returned string parameters.
8. The functions pisn_putsnapshot, pisn_putsnapshots, pisn_putsnapshotq,
and pisn_sendexcepstruc use int32 parameters for the istat variables and
excmin and excmax. When communicating with PI2 systems, only 16 bits of
the passed data is actually sent. Previously the upper 16 bits of passed
data was truncated during exception testing and when the data was loaded
into the packets for transmittal. In some cases, bad input data, when
truncated, became good and was erroneously accepted by the server. These
functions now check the passed in data before truncation to verify that
all istats passed to PI2 systems are valid. The absolute value of istats
passed to PI2 must be < 32768.
9. A signal handler was added to catch SIG_PIPE signals on UNIX
platforms. Under some conditions and platforms (e.g. Process Software
TCPWare on Vax talking to SUN), when the TCP connection was terminated
on the server a SIG_PIPE signal was being sent to the client API
processes causing them to exit. They will now hang around trying to
reconnect.
10. A separate timeout for selects done prior to a write was added with
a default of 3 seconds. When sockets are opened they call connect and
then did a write select to see if the connection was ready. As this
always happens fast, waiting for the earlier default of 1 minute for it
to fail was unnecessary. An entry in pilogin.ini - section NETWORK
item WRITETIMEOUT can be used to override the 3 second default if
necessary.
11. When network messages are sent by the client to the server, the
API now checks to see if buffering is enabled and if the message is
going to the default server. If this is true it checks a flag in

shared memory maintained by the buffer server process indicating
whether or not the server is currently accessible. If this flag indicates
the server is inaccessible the API immediately returns a 2 (network
error) to the caller. When the buffer server again connects, the
shared memory flag is cleared and client calls proceed normally. This
change allows interfaces to avoid blocking with each network call when
the server is down. Instead they continue to send snapshots to the
buffering process. This avoids gaps in the interface data.
12. piba_search formerly returned 2 when the passed timeout was
exceeded. Version 2.1.1 of the server now returns -78 for this condition.
piba_search previously returned -1 when called with a non-zero search
flag after a previous call with a search flag of 0 had failed. It now
returns -2 indicating no valid search has yet been made. piba_search
formerly returned -1 when no records were found. It now returns 1 as
documented.
13. A bug in pitm_formtime was fixed where if the passed string buffer
was less than 19 characters, the null terminating character was inserted
one 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 functions
continue to send a maximum of 36 values per message to PI2 servers.
When using the "q" functions it is important to note that until 255
values are received the queue will not be flushed to the server unless
pisn_flushputsnapq is called. This results in more efficient
communication with PI3 servers.
15. The client pinet protocol version, has been raised to 00010008
(major version 0001, minor version 0008) This is to indicate support
for extended API functions. No new protocol messages have actually
been added for this support but this provides a way to programatically
determine the level of client support. Note 00010007 indicates support
for batch and SQL. 00010005 indicates support for long tag names.
The PI-API will work with servers supporting the same major protocol
even if the server minor protocol is lower. Unsupported server
functions will return an error (-991).
16. The function piut_netnodeinfo previously did not return the correct
connected status. This has been fixed.
-----------------------------------------------------------------|
v1.2.b2
Jun 96 hs
-----------------------------------------------------------------|
1. Version 1.2b2 represents the beta release of code to support
data buffering on API nodes. For a complete description of
the features, files, and programs involved in buffering refer
to chapter 7 of the PI-API manual, distributed with this beta.
This chapter will be incorporated into the version 1.2 release
manual.
2. Version 1.2b2 also contains beta code supporting the extended
PI-API for sending and retrieving subsecond time stamps and string
values on PI 3.1 servers. At the time of this release, the PI3.1
system had not yet been released to beta testing. For a detailed
description of the extended API functions, refer to chapter 6 of
the PI-API manual. This chapter is available on request for review
and 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 turned
on and the caller does not have READ privilege. Previously it returned
1 which for this function was success but did not update the time.
-----------------------------------------------------------------|
v1.1.3
Jan 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 server
it is no longer truncated on return. Instead the full long name is
returned 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 a
count of zero was returned. Now stops requesting network messages when
less than a full buffer is returned.
4. pisn_evmexceptions - previously returned exceptions in reverse order for
each buffer returned from server. Server returns oldest data first. Within
each network buffer, function would return newest first. Now returns in
server order - oldest first.
5. pisn_evmexceptions now remembers the server used when events are retrieved
from 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 has
changed an error (-80) is returned and the data still in the buffer is
lost. Previously one could get unretrieved events from the previous
server when calling pisn_evmexceptions for the new server if you had
registered for events on both. Note programs should empty the
exception buffer by calling pisn_evmexceptions until it returns a count of
zero, before switching servers to avoid losing events.
-----------------------------------------------------------------|
v1.1.2
Dec 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 processes
The actual error message was lost. The system now will report to stdout
the first such error but also will send the original message to stdout. The
message logging system will not be retried until 100 messages have been
receieved and sent to stdout. This allows applications to realize that
the logging system is being overburdened but still provides a way to capture
the error messages generated during that time.
2. The api in Windows and NT now looks in pipc.ini for the entry PIPCSHARE
in the section [PIPC] for a network directory override when looking for
the pilogin.ini file. It searches for the file in the DAT subdirectory of
the PIPCSHARE directory.
The order of directories searched when finding pilogin.ini by the PI-API DLL
is 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.1
Nov 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 socket
for all other outstanding connections. This meant only the default server was
given a chance to gracefully end its process. It also meant if you were not
connected to the default server and called piut_disconnect, the API would
attempt 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.
-----------------------------------------------------------------|
AUG-1995 - HKS
-----------------------------------------------------------------|
---------Bug fixes:
---------Fixed a bug which allowed pitm_parsetime to accept erroneous month
names on PI3 servers.
Added a check to piut_getapiversion that the passed buffer length
is at least 9 characters long. Previously a shorter buffer could
result in memory overwrites.
pipt_instrumenttag previously returned only 31 characters. The
full 32 character tag can now be returned.
pipt_recordtype incorrectly returned 1 for points with resCode of
4 and 0 for all others. This behavior was in conflict with the
documentation and the Vax toolkit. The results have now been
reversed. Existing code calling this function should be examined.
pipt_scan would not update the lscan parameter when the status bit
was off. This has been fixed. Calling functions that set the
lscan parameter to 0 before calling pipt_scan are unaffected.
Those that did not, in previous versions would have been returned
whatever they passed if scan was off for the point.

------------Enhancements:
------------The toolkit function ArcTimeFilter has been addded to the API as
piar_timefilter. This function calculates the amount of time
within 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 described
in full in the API manual. They are:
pipt_digcodefortag
pipt_displaydigits
pipt_sourcept
pisn_sendexcepstruc
pitm_delay
piut_getapiversion
piut_netnodeinfo
Retrieve the digital state associated with

a passed string within the range of the
passed point
Retrieve the display digits attribute for
the passed point.
Retrieve a passed tag's source tag.
Similar to pisn_sendexceptions but takes a
structure of the old, new and previous
values rather than separate arguments.
Wait for the specified number of
milliseconds.
Retrieve the version number of the PIAPI
being used.
Return network information for the passed
node name.
Three new functional areas have been added to the API each with
a list of supporting functions.
PIBATCH (piba_xxxx)
Access functions to the batch configuration data and the batch
history data. These functions are described in the PI-API
Programming Manual
PISQL (pisql_xxxx)
Functions which provide access to PI data as if it were stored
in a relational database. The functions provided are conceptually similar to other RDBMS API's (ODBC, DBLib, etc.). These
functions are now supported in the API but must be separately
licensed. The functions are briefly described below.
PILOGIN (pilg_xxxx)
Functions which provide commonly used connection services and
information as well as common PI dialogs - login, tag search,
and point attributes. These functions are described in the
PI-API Programming Manual.
Client Platforms
---------------The PILOGIN functions are provided for MS Windows only. PIBatch
and PISQL are not supported on MSW clients running Pathworks 4
communications software. An upgrade to Pathworks 5 or a WinSock
compliant product is recommended. PIBATCH and PISQL are not
supported on Solaris 1. It is also unlikely these functions will
be ported to Unix platforms which do not provide a C++ compiler.
Server Requirements
------------------PIBatch and PISQL API calls are only supported by server version
2.1.1 or higher and are not available on the PI3 platform yet.
Libaries
-------The new API functions continue to be supplied by a single library
except for the new PILOGIN functions which are delivered in a
separate dynamic link library (PILOGIN.DLL) only available in
MS Windows. On some UNIX platforms libraries are available for
both static linking and as shareable object libraries.
PISQL Functions
--------------pisql_bind_list
pisql_bind_param *
pisql_clear_data
pisql_clear_stmt
pisql_del2string
pisql_describe_list
pisql_describe_params *
pisql_error
pisql_execute
pisql_execute_callback *
pisql_fetch
pisql_free_stmt
pisql_get_data
pisql_get_info
pisql_get_list_info
pisql_get_param_info *
pisql_get_tagsize
pisql_get_timeout
Bind a program variable to a query

result column.
Bind a program variable to a query
parameter (marker).
Clear result data for reexecution of a
query.
Clear the current statement to allow
processing a new statement with the
current statement handle.
Convert a passed in number of seconds
to a formatted string in the lowest
common denominator (e.g. 2h {2 hours},
3d {3 days}).
Prepare a results descriptor array for
use with the query in the passed
statement handle.
Prepare a query descriptor array with
query parameters for execution
Returns the error condition of the last
executed pisql function.
Execute the statement in the passed
statement handle
Associate a callback function with a
statement handle to provide periodic
notification during statement execution
for progress measurement.
Retrieve a row of results from a statement that has successfully executed.
Release a statement handle.
Retrieve a pointer to the the data for
a single fetched column. This function
performs some data type conversions.
Provides information about the query in
the passed statement handle.
Provides the name and type of a column
in the query in the passed statement
handle.
Provides the variable name and type of
a query parameter (marker).
Get the current number of characters
returned in queries requesting tags.
Get the current query timeout value.
pisql_get_timestep
pisql_new_sqlda
pisql_new_stmt
pisql_prepare
pisql_reset
pisql_set_options
pisql_set_tagsize
pisql_set_timeout
pisql_set_timestep
Get the current time step value used

for tables which perform interpolation.
Allocates a descriptor array to be used
for either a query or a results set.
Allocates a statement structure and
returns the statement handle.
Parses the SQL in the passed statement
handle.
Set the index into the returned results
set for subsequent fetches. Allows
cursor like result retrieval.
Reset the statement execution options
originally specified with the call
pisql_new_stmt.
Set the number of characters returned
in queries for tag names.
Set the number of seconds pisql_execute
will block before aborting a long query
and returning.
Set the interval used by tables which
perform interpolation on behalf of a
query.
* Not currently implemented.

SQL language features supported in version 1.1.0
-----------------------------------------------Version 2.1.1 of the PI Server supports a subset of ANSI SQL;
features will be added with subsequent releases of PI.
The tables and columns supported by the PI SQL interface are
described in the PI-ODBC driver manual. The SQL statement support
is not limited by the API but is dependent on the server version.
The limitations of the current server version are listed here
for convenience. The server release notes should be consulted
for the full description of SQL syntax supported.
Version 2.1.1 of the PI Server supports only the SELECT statement
(INSERT, UPDATE, DELETE, are not supported). The ORDER BY, and
GROUP BY clauses are not supported. The WHERE clause operators
LIKE, and BETWEEN are not supported. Aggregate functions (AVG,
MAX, MIN ...) are not supported. Dates and PI tags require
special consideration - see the PI-ODBC Driver manual Appendix A
for details. The UNION, INTERSECTION, and outer join syntax is
not supported. Multi-table joins, self joins, and table aliases
are supported.
PILogin Functionality
--------------------The PILOGIN DLL is used to manage connections and calls the PIAPI
DLL connection routines. Given this architecture it is necessary
to use the pilg_ routines to establish connections in order for
the connection dialog to keep track of outstanding connections.
For example, if a program calls pilg_resgisterapp followed by
piut_connect and then calls pilg_connectdlg, the dialog will not
show an existing connection even though piut_connect successfully
established one. At this point, choosing to connect through the
dialog will work very quickly because the PILOGIN DLL will call
the PIAPI DLL which will return quickly as it is already connected
to the requested server.

----------------------------Default server and .ini files
----------------------------Under Windows 3.1, two .ini files are used to perform
initialization tasks for the PIAPI DLL: pilogin.ini and
piclient.ini The piclient.ini file has been used to provide
the default server name for API programs. The pilogin.ini file
was developed along with the ProcessBook product and stores
connection information for each user as well as a default server
designator. To align these views and to capitalize on the
additional connection information stored in the pilogin.ini file,
the API search path for initialization files and retrieving the
default server has changed. The change is intended to search for
the preferred files and data while providing support for older
versions.
To find the default server the API first looks for a valid
pilogin.ini file (one containing a section DEFAULTS and an entry
PISERVER) following the paths described below. If found, the
value for the entry PISERVER under the section DEFAULTS is used.
Failing that, the API searches for a valid piclient.ini file
(one containing a section PISERVER and an entry PIHOMENODE) in the
described paths. If found, the value for the entry PIHOMENODE in
the section PISERVER is used. If the required entries are not
found in any of the files the error PSNODEFHOST (-1001) will be
returned.
pilogin.ini search path:
1. From the DLL's directory move up one level then down into
the dat directory. (..\dat\pilogin.ini)
2. The current directory. (.\pilogin.ini)
3. In the windows directory look for the pipc.ini file and in
it search for the value for the PIHOME entry under the PIPC
section. If found this value is used as the directory to
search for the pilogin.ini file.
4. If pipc.ini was not found in the user's windows directory
look for pipc.ini in c:\pipc. As in 3 look at the value for
PIHOME in the PIPC section and if found use it as the
directory to search for the pilogin.ini file.
If none of the above has turned up a pilogin.ini file that
contains a section DEFAULTS with an entry PISERVER, the search
for a pilogin.ini file has failed.
piclient.ini search path:
1. From the current directory move up one level then down into
the dat directory. (..\dat\piclient.ini)
2. In the windows directory look for the pipc.ini file and in
it search for the value for the PIHOME entry under the PIPC
section. If found this value is used as the directory to
search for the piclient.ini file.
3. If pipc.ini was not found in the user's windows directory
look for pipic.ini in c:\pipc. Look at the value for PIHOME
in the section PIPC and if found use it as the directory to
search for the piclient.ini file.
If none of the above has turned up a piclient.ini file that
contains a section PISERVER with an entry PIHOMENODE, the
search for a piclient.ini file has failed.
Besides establishing a default server, the pilogin.ini file is

used to store ports associated with particular servers. The
connections dialog (provided now in the PILOGIN DLL) allows a user
to manage a personal connection list of servers. The list
includes user names and ports for each server and is stored in the
user's pilogin.ini file. The PIAPI now consults this file when a
TCP/IP connection is requested without specifying a port number to
determine the proper port to use. With PI2 servers the port has
consistently been 545. Berkeley UNIX, however, imposes the rule
that port numbers below 1024 may only be used by the super-user.
PI3 systems are being configured to connect at port 5450. The use
of the pilogin.ini file by PIAPI allows an application to connect
to multiple servers on different ports. Previously only a single
default was available.
-----------------------------------------------------------------|
26-APR-1995
-----------------------------------------------------------------|
---------Bug fixes:
---------Correct handling of Daylight Savings and Standard time
transitions. The API supports local time based archives, PI 2.x
(clasic PI), and Universal coordinated time based archives, PI
3.0. This feature requires knowledge of archive time base before
calling pitm_parsetime. Therefore, piut_setservernode should be
called for the appropriate server before calling pitm_parsetime.
Applications that follow this practice will allow correct time
representation when displaying data from PI 2.x and PI 3.0
simultaneously. Default behavior assumes a local time based
archive (PI 2.x).
Fixed bug which could prevent multiple piserver connections.
------------Allow TCP/IP connections by address. Previously only connections
by name were allowed. This feature allows calling
piut_setservernode with an address or name. For example the
following 2 syntaxes are now supported:
char hostname[25] = "pisystem"
int32 result = piut_setservernode ( hostname );
char hostaddress[25] = "123.45.123.32"
int32 result = piut_setservernode ( hostaddress );
Allow specifying TCP/IP port in connection. The syntax is name,
or address, followed by :port. For example:
char hostname[25] = "pisystem:7777"

int32 result = piut_setservernode ( hostname );
char hostaddress[25] = "123.45.123.32:7777"
int32 result = piut_setservernode ( hostaddress );
Archive calls have been enhanced to require about 40% less network
traffic. This enhancement is available only on servers which
support it. Currently only PI 3.0 servers offer this support.
-----------------------------------------------------------------|
(09-Jan-95)
-----------------------------------------------------------------|
------------Added following functions:
PIINT32 piut_disconnectnode ( char PIPTR *nodename )
This function closes connection to passed nodename. Function
piut_disconnect closes all existing connections.
PIINT32 piut_netnodeinfo( char PIPTR *namestr, int32 namelen,
char PIPTR *addressstr,
int32 addresslen,
int32 PIPTR *connected )
This function returns network information for the host name passed
in namestr.
Simplified PI homenode security interpretation. The function
piut_login now returns one of the following values in the valid
argument:
0
1
2
All access denied.

Read only access.
Read and write access.
Added pinetinfo support for DECnet WINSOCK.

For Windows and NT only:
Added initialization file pilogin.ini. This file may be edited
to modify TCP/IP port, and network timeout values. This file
is located in the dat subdirectory of the PIHOME directory.
This file will also be used to define the default pihome node
and winsock address family. On UNIX systems PICLIENT.INI will
still be searched for these definitions for backwards
compatability.
The TCP/IP and NETWORK sections are now supported on all
platforms except Open VMS. Under Windows and NT they are located
in the pilogin.ini file, under UNIX they are in the piclient.ini
file. The syntax for modifying the default TCP/IP port is as
follows:
[TCP/IP]
port = 545
where port defines the port number. The default is 545.

The syntax to modify the network timeout value is as follows:
[NETWORK]
timeout = 60
where timeout defines the timeout period in seconds. The default
is 60 seconds.
---------Bug fixes:
---------Fixed bug in connection retry throttling. Previously, certain conditions
could lead to non-stop connection attempts rather than waiting
60 seconds between attempts.
Connections are now attempted in non-blocking mode. This prevents
the PI-API from hanging while attempting connections on mal-functioning
networks.
-----------------------------------------------------------------|
PI-API version 1.0.4 Release Notes:
-----------------------------------------------------------------|
Added long tagname support. Tag names up to 80 characters long
are now supported. To accomodate the longer lengths applications
should increase tagname buffers to 81 characters. Certain
functions have a new return code: -411. A -411 error notifies the
calling application the tagname was truncated to fit in the passed
buffer. Functions that may return -411 are:
pipt_instrumenttag
pipt_taglong
pipt_tagprefferred
pipt_wildcardsearch
Added function pipt_taglong. This function returns the long tag
name if defined. The function prototype is:
PIINT32 pipt_taglong( long pt, char PIPTR *tag, long len );
pt is the PI point number.
tag is a pointer to character buffer
len is the size of the character buffer pointed to by tag
return
>0
0
-1
-411
codes are
System error
Success
Point does not exist
Tag was truncated (passed buffer not large engough)
Added function pipt_tagpreferred. This function returns the long

name if defined, else the standard tag name. The function
prototype is:
PIINT32 pipt_tagpreferred( long pt, char PIPTR *tag, long len );
pt is the PI point number.

tag is a pointer to character buffer
len is the size of the character buffer pointed to by tag
return
>0
0
-1
-411
codes are
System error
Success
tag was truncated (passed buffer not large engough)
Added support for DEC Pathworks ver 5. The WINSOCK version is

used for Pathworks version 5. DEC Pathworks ver 4 continues to
use the DECnet version (piapidnt.dll).
Pathworks ver 5 WINSOCK implementation supports INET address format (TCP/IP)
and DECnet address format (DECnet). Therefore it is possible to access both
DECnet and TCP/IP via WINSOCK. The default behavior of WINSOCK PIAPI is to
first attempt TCP/IP startup; if this fails DECnet startup is attempted.
Clients with TCP/IP and DECnet installed which require DECnet PIHOME
connections need to override this behavior. This is accomplished by
adding the following two lines to PICLIENT.INI:
[WINSOCK]
AF=DECnet
; forces use of WINSOCK DECnet (pathworks vers 5 only)
Added message flags to prevent excess messages. Previously

certain error conditions could result in hundreds of messages in
PIPC.LOG.
Fixed bug in Standard Time to Daylight Savings Time transition.
When converting a string format of time to PITIME the 1 hour
"hole" created by the spring transition is compensated for. Local
time is used to determine current Daylight Savings state;
therefore large time differences between client and PIHome node
may result in incorrect time display.
Added function pipt_instrumenttag. The function prototype is:
PIINT32 pipt_instrumenttag ( int32 point,
char PIPTR *instrumenttag, int32 len );
point
is the PI point number.
instrummenttag is a pointer to character buffer
len
is the size of the character buffer pointed to
by instrummentag
return
>0
0
-1
-2
-411
codes are
System error
Success
Instrument tag not defined
Instrument tag is defined but truncated (passed buffer
not large engough)
Added function pipt_getapiversion. The function prototype is:

PIINT32 piut_getapiversion ( char PIPTR *version, int32 len );
version is pointer to character buffer
len
is size of buffer pointed to by character
return values are:

0 for success
-1 if buffer is not large enough for version number.
Added a new MS Visual C++ example application. The source code is
example/msw/c/apisnap.c. A MSVC makefile, apisnap.mak is also
included. This makefile will create a quickwin application.
Apisnap.mak may require modification for different installation
paths.
-----------------------------------------------------------------|
Version 1.04a release notes:
(BV 10 mar 95)
-----------------------------------------------------------------|
>> Fixed numerous bugs in PIPC/INCLUDE/PIAPI.BAS. PIAPI.BAS now
contains correct prototypes for all API routines that can be
called from Visual Basic, i.e. all but pisn_sendexceptionq,
pisn_putsnapshotq, and pisn_flushsnapshotq. These routines
return a pointer to a QERROR structure and therefore cannot be
called from Visual Basic.
>> Added a new utility file, PIUTIL.BAS, which may simplify PI-API
Visual Basic programming. You may use these routines in your
programs directly, or simply use them as programming examples.
>> Deleted the old "snapshot" Visual Basic example program, and
replaced it with two others, Monitor and ManInput. These two
programs are derived from our experience teaching the
programming class, and provide detailed examples of PI-API
Visual Basic programming. Executable versions of these
programs are also provided, but to run them you will need
VBRUN300.DLL on your machine. This DLL is automatically
installed by Microsoft Visual Basic 3.0.
====== PILOG32.DLL Release Notes ======
-----------------------------------------------------------------|
PILOGIN DLL version 1.3.7 release notes
27-Jan-00 cah
-----------------------------------------------------------------|
The resource file was changed so the default port displayed when
adding a PI server is 5450.
-----------------------------------------------------------------|
PI Login DLL Version 1.3.6 release notes
12-Nov-99 cah
-----------------------------------------------------------------|
The maximum number of servers in the connection dialog has been
increased from 50 to 100.
The Point attributes dialog now can display negative integer values.
Negative integers from PI 3 systems are returned as UnderRange by
getsnapshot, but the rval contains the true value.
The Tag Search dialog can now search for negative integer values.
-----------------------------------------------------------------|
6-Oct-99 hs
-----------------------------------------------------------------|
The tag search dialog has been changed to reset to the selected
server during the retrieval of tags. In previous versions, it
was possible for the current active server used by the PI-API
to be changed after the first tag was retrieved but before all
tags meeting the selection criteria had been successfully
returned. The observable effects of this problem were an
inconsistent number of tags being returned, percentage completion
jumping from a few percent to 100% and tags from incorrect servers
being returned but shown with the proper server name in the tag
search list box.
This problem was only exhibited in OSI software by ProcessBook 2.1
beta versions when working with displays showing multiple servers or
a server other than the server being searched for tags. During the
retrieval process the tag search allows buffered window messages to be
processed in order to allow the user to hit the abort button on the
dialog. ProcessBook 2.1 would receive timer messages at this time
and update its displays, switching the server context to accomplish
the update.
-----------------------------------------------------------------|
Aug-99 cah
-----------------------------------------------------------------|
The pilog32.dll now replicates server changes made with the pilogin
functions in the PI-SDK server registry.
The connection information dialog now specifies the user actually
used to log in for the "Connection Status" field. The "User Name"
field has been changed to "Default User Name".
-----------------------------------------------------------------|
27-Jan-99 hs
-----------------------------------------------------------------|
BUG FIXES:
---------The point attributes dialog formerly would incorrectly display a short
tagname of "N/A" for points found by long name on PI2 systems. This
has been corrected so that against PI2 systems the point name found
is displayed as well as the associated long or short name(whichever
is not displayed as the found name). Against PI3 systems the dialog
continues to show N/A for the short name as PI3 systems only have a
single point name.
--------------------------------------------------------------------PI Login DLL Version 1.3.2
24-Oct-96 hs
--------------------------------------------------------------------1. A bug in the tag search dialog was fixed where searching for tags
by other than the tagname (e.g. point source) would bring up tagnames
truncated to 12 characters when communicating with a PI3 server.
2. A bug in the point attributes dialog was fixed where tags with longer
than 12 character tag names on PI3 systems would show their short tag
name as the tag name truncated to 12 characters. A similar bug was
fixed where if you selected a tag in a display and hit the properties icon
the tag would not be found if it was from a PI3 system and the tagname
was greater than 12 characters.

3. The connection dialog was modified to allow users to double
click on a server in the connections list box to connect. Double clicking
on a server that is already connected has no effect. The default
pushbutton has been changed in the dialog from Close, to Connect
or Disconnect depending on whether the server in the connections
list is disconnected or connected. Hitting return in this dialog will
now connect or disconnect the selected server in the list.

Ejemplos Avg (Tagval

Uploaded by

Copyright:

Available Formats

Ejemplos Avg (Tagval

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Ejemplos Avg (Tagval

Uploaded by

Copyright:

Available Formats

PI-API-NTI

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

communications to PI Universal has been re-established

Crash in PI-Buffer Server

(e) a user re-starts PI-Buffer Server

appears in the DrWtsn32.log file:

PI-Buffer Server v1.5.0.0 fixes this problem.

where $PI represents the top-level directory in which PI Universal Data

Also, install PI-API v1.3.4 to the directory

To link, use the C++ linker:

ARCflag_mark specification returns filtered values marked as "Filtered"

Another subsequent call to pisn_evmexceptionsx() with GETNEXT returns the

release now has both shared and archive PI-API

2. A bug in bufserv has been fixed such that filling a memory

will be dumped to a file in the PIHOME\dat directory for later

Each section name is separated by a null character from the

command is now, for example,

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

value as entered in the point configuration. This does not affect

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

Times returned from that function under those conditions were

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

piba_getunitswalias previously did not detect when the user had

going to the default server. If this is true it checks a flag in

whatever they passed if scan was off for the point.

Retrieve the digital state associated with

Bind a program variable to a query

Get the current time step value used

* Not currently implemented.

to the requested server.

Besides establishing a default server, the pilogin.ini file is

char hostname[25] = "pisystem:7777"

All access denied.

Added pinetinfo support for DECnet WINSOCK.

where port defines the port number. The default is 545.

Added function pipt_tagpreferred. This function returns the long

pt is the PI point number.

Added support for DEC Pathworks ver 5. The WINSOCK version is

; forces use of WINSOCK DECnet (pathworks vers 5 only)

Added message flags to prevent excess messages. Previously

Added function pipt_getapiversion. The function prototype is:

return values are:

was greater than 12 characters.

You might also like