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).
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.
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.
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.