Checking Global Status After Each NI-488.2 Call

For applications accessing the NI4882 API, each NI-488.2 call updates three global functions to reflect the status of the device or board that you are using. These global status functions are the status word (Ibsta), the error function (Iberr), and the count function (Ibcnt). They contain useful information about the performance of your application. Your application should check these functions after each NI-488.2 call. For more information about each status function, refer to the following sections.

For applications accessing the older GPIB32 API (including the Visual Basic 6.0 application interface), use the equivalent global variables. These global status variables are the status word (ibsta), the error variable (iberr), and the count variables (ibcnt and ibcntl). ibcnt is defined to be the type int, while ibcntl is the size of type long int. For all cases, if the sizes of ibcnt and ibcntl are the same, ibcnt and ibcntl are equal. For cross-platform compatibility, all applications should use ibcntl.

For applications accessing the newer NI4882 API, use the global function calls rather than the global variables. The global functions replace the global variables with the newer NI4882 API.

Note If you are writing a multithreaded application, use the thread-specific copies of the status functions in your application. To access the thread-specific copies, use the ThreadIbsta, ThreadIberr, and ThreadIbcnt calls.

Status Word (Ibsta)

All NI-488.2 calls update a global status word, Ibsta. It contains information about the state of the GPIB and your GPIB hardware. The value stored in Ibsta is the return value of all the traditional NI-488.2 calls, except ibfind and ibdev. You can examine various status bits in Ibsta and use that information to determine what to do next in your application. For more information about the status bits in Ibsta, refer to the Ibsta Status Bit Values table.

The language header file which is installed defines each of the Ibsta status bits. You can test for an Ibsta status bit being set using the bitwise AND operator (& in C/C++). For example, the Ibsta ERR bit is bit 15 of Ibsta. To check for a GPIB error, use the following statement after each GPIB call:

if (Ibsta() & ERR)

printf("GPIB error encountered");

Error Function (Iberr)

Iberr is the NI-488.2 error function. If a call failed with an error, the ERR bit is set in Ibsta. The Iberr value describes the NI-488.2 error that occurred. For more information about the Iberr values, refer to the Error Codes and Solutions table.

Count Function (Ibcnt)

Ibcnt is the count function. It contains information about the number of bytes that went across the GPIB in the most recent I/O operation.

The count function is updated after each read, write, or command function. In addition, Ibcnt is updated after specific 488.2-style functions in certain error cases.

If the data that you are reading contains ASCII characters, you can use Ibcnt to NULL terminate the string and treat it like any other ASCII string. For example, you can use printf to print the result to the screen:

char rdbuf[21];

ibrd (ud, rdbuf, 20);

if (!(Ibsta() & ERR)){

rdbuf[Ibcnt()] = '\0';

printf ("Read in string: %s\n", rdbuf);

}

else {

// GPIB Error encountered!

}