Setting the Value of the istat Argument

The PI-API (including the extended functions) uses a 32-bit integer istat argument for putting digital state values into PI. This argument is used for both values of digital points, and status information for numeric or string points.

In general, the rules for setting the value of the istat argument are as follows:

· if istat is negative, the value is taken to be an exact digital state code number. There are slight differences between PI for OpenVMS and PI for Windows NT and UNIX, which are explained below.

· if istat is zero or positive, the value is taken to be an offset into the defined range of states for a digital point. If the point is numeric or string-valued, the value is taken to be an offset into the system set of digital states (that is, the same as if istat had been negative).

Note For digital points, an istat value of zero is valid. This means a zero offset into the defined range of digital state codes.

PI for OpenVMS

A negative istat argument is an exact digital state code value in all cases.

If a positive offset is passed for a digital point which is out of range for the point, the value is taken to be an offset into the digital state table. The effect is the same as if istat had been negative.

Digital state values should always be added to numeric points as negative numbers. If positive istat values are added to integer points, they will be interpreted as data values.

Note Even though the extended PI-API functions have separate ival and istat arguments, neither PI for OpenVMS nor PI for Windows NT and UNIX can distinguish between a positive istat value and an integer data value when adding data values to integer points.

PI for Windows NT and UNIX

For digital points, digital state set number and offset can be passed together in the istat argument. To do this, you can call the PI-API function pipt_digpointers to obtain the values digcode and dignumb. In PI for Windows NT and UNIX, digcode is the digital state set number, shifted to the upper 16 bits of the integer. dignumb is the number of offsets in the digital state set minus 1. To construct an exact istat value, use the formula:

istat = - (digcode + offset)

This is the form in which the PI-API returns the istat value when reading the PI for Windows NT and UNIX snapshot and archive.

Note The digital state set number appears in the upper 16 bits of the istat. If the set number passed this way does not match the set number defined for the point, an error is returned and no data value is put into the Snapshot.

You can choose to pass the offset directly as a positive istat value. The PI for Windows NT and UNIX server will look up the correct digital state set and store the value.

If the offset is out of range for the digital point’s state set, an error is returned, and no data value is put into the snapshot.

Note This is an important difference change from PI for OpenVMS. In that system, an out-of-range offset is stored as an offset into the digital state table, which is the same as if istat had been negative.

Enabling Operational Intelligence