Differences Between the GPIB32 API and the NI4882 API

Updated Sep 28, 2024

Reported In

Driver

  • NI-488.2

Operating System

  • Windows

Other


Primary Software: NI-488.2

Issue Details

What are the differences between the 32-bit GPIB API and the 64-bit 488.2 API?

Solution

The NI-488.2 for Windows 2.6 release has introduced a new API as part of the 64-bit application interface. Every effort has been made to have the new NI4882 API closely match the existing GPIB32 API while incorporating API design best practices. To use the new API, you must recompile applications using the new header and object files. The following list describes the major changes in the NI4882 API.  
  • Judicious application of the const keyword has been added where appropriate.
  • Wide variants of functions now use the wchar_t instead of unsigned short type.
  • Functions taking in parameters that describe a pointer length now use size_t types.
  • Status variables now use the unsigned long type.
  • ThreadIbcntl() has been removed. Macros redirect calls to ThreadIbcnt().
  • Global status functions have been added. These are Ibsta(), Iberr(), and Ibcnt(). New code should use these functions instead of ibsta, iberr, or ibcnt/ibcntl.
  • Long-term deprecated functions have been completely removed.
  • Most functions with an ibconfig have been removed. Using ibconfig is recommended for new code. Existing functions redirect to usingibconfig using macros. These are the affected functions: 
    • ibpad
    • ibsad
    • ibtmo
    • ibeot
    • ibrsc
    • ibsre
    • ibeos
    • ibdma
    • ibist
    • ibrsv
  • Many macro definitions have been improved for programmatic safety.

Modifying existing applications to use the NI4882 API should require minimal changes. In most cases, using the new include file (ni4882.h instead of windows.h and ni488.h) and linking to the new object file (ni4882.obj instead of gpib-32.obj) is sufficient to compile your application. There may still be warnings due to changes to the status variable type's signed property.

Complications may arise in several uncommon use cases. The following issues have been encountered.

  • Storing function pointers for the ibnotify callback. This causes a type mismatch on the assignment. To solve this, fix the function prototype of the callback to use unsigned long for the status parameters.
  • Using function pointers toibfind. This causes a preprocessor error because the ibfind macro requires a one-parameter argument. To solve this, point to ibfindA or ibfindW, depending on the unicode convention in your application.
  • Configuration functions show up in NI I/O Trace as ibconfig calls. This is because macros redirect those calls to use ibconfig. Avoid confusion by using ibconfig directly.

In most cases, applications written in the NI4882 API will continue to work on older versions of the NI-488.2 for Windows software, back to version 1.7. Certain new ibask and ibconfig options break this backwards compatibility, and those options are easily avoidable by using alternative options. Existing applications using the GPIB32 API continue to execute unchanged. The GPIB32 API will continue to exist, but are available only for 32-bit applications. Applications written in the NI4882 API compile on both 32-bit and 64-bit environments. To port an application to a 64-bit environment requires that the application migrate to the NI4882 API and be recompiled.

The following NI4882 API constructs break API compatibility with older versions of NI-488.2 for Windows.

  • ibask(IbaEOS)
  • ibconfig (IbcEOS)