Getting Started Using C

This topic describes a sample program called idn that queries a GPIB instrument for its identification string. This sample builds a console application for programs using the C programming language.

Subtopics are:

C Sample Program Code

All files used to develop SICL applications in C or C++ are located in the C subdirectory of the base Keysight IO Libraries Suite installation directory. Sample C/C++ programs for SICL are available at http://www.keysight.com/find/iosuite.

You must first compile the sample C/C++ programs before you can execute them. Some sample programs include makefiles or project files that you can use to build the programs.

The idn sample files include the source program, IDN.C. The source file IDN.C is listed on the following pages. An explanation of the function calls in the sample follows the program listing.

This sample applies to Windows and Linux, with the exception of the comment referencing the Event Viewer, which is available in Windows only.

/* This program uses the Standard Instrument Control Library to query a GPIB instrument for an identification string and then prints the result. This program is to be built as a WIN32 console application. Edit the DEVICE_ADDRESS line to specify the address of the applicable device. For example:
gpib0,0: refers to a GPIB device at bus address 0 connected to an interface named ‘gpib0’ by Connection Expert.

gpib0,9,0: refers to a GPIB device at bus address 9, secondary address 0, connected to an interface named “gpib0” by Connection Expert. */

#include <stdio.h> /* for printf() */
#include “sicl.h” /* SICL routines */
#define DEVICE_ADDRESS “gpib0,0” /* Modify for
setup */

void main(void)
{

INST id; /* device session id */
char buf[256] = { 0 }; /* read buffer for idn
string */

/* Install a default SICL error handler that logs an error message and exits. View messages with the Event Viewer. */

ionerror(I_ERROR_EXIT);

/* Open a device session using the
DEVICE_ADDRESS */
id = iopen(DEVICE_ADDRESS);

/* Set the I/O timeout value for this session to
1 second */
itimeout(id, 1000);

/* Write the *RST string (and send an EOI
indicator) to put the instrument into a known
state. */
iprintf(id, “*RST\n”);

/* Write the *IDN? string and send an EOI indicator, then read the response into buf.*/
ipromptf(id, “*IDN?\n”, “%t”, buf);

printf(“%s\n”, buf);
iclose(id);

}

C Sample Code Description

sicl.h

The sicl.h file is included at the beginning of the file to provide the function prototypes and constants defined by SICL.

INST

Notice the declaration of INST id at the beginning of main. The type INST is defined by SICL and is used to represent a unique identifier that will describe the specific device or interface that you are communicating with. The id is set by the return value of the SICL iopen call and will be set to 0 if iopen fails for any reason.

ionerror

The first SICL call, ionerror, installs a default error handling routine that is automatically called if any of the subsequent SICL calls result in an error. I_ERROR_EXIT specifies a built-in error handler that will print out a message about the error and then exit the program. If you wish, you can specify a custom error handling routine instead.

NOTE: You can view SICL error messages with the Event Viewer utility.To launch Event viewer, first open the Keysight IO Control application from Application Finder and then selectEvent Viewer.

iopen

When an iopen call is made, the parameter string “gpib0,0” passed to iopen specifies the GPIB interface followed by the bus address of the instrument. The interface name gpib0 is the name given to the interface during execution of the Connection Expert utility. The bus (primary) address of the instrument follows (0 in this case) and is typically set with switches on the instrument or from the front panel of the instrument.

NOTE: To modify the program to set the interface name and instrument address to those applicable for your setup, see Programming with SICL for information on using SICL’s addressing capabilities.

itimeout

itimeout is called to set the length of time (in milliseconds) that SICL will wait for an instrument to respond. The specified value will depend on the needs of your configuration. Different timeout values can be set for different sessions as needed.

iprintf and ipromptf

SICL provides formatted I/O functions that are patterned after those used in the C programming language. These SICL functions support the standard ANSI C format strings, plus additional formats defined specifically for instrument I/O.

The SICL iprintf call sends the Standard Commands for Programmable Instruments (SCPI) command *RST to the instrument that puts it in a known state. Then, ipromptf queries the instrument for its identification string. The string is read back into buf and then printed to the screen. (Separate iprintf and iscanf calls could have been used to perform this operation.)

The %t read format string specifies that an ASCII string is to be read back, with end indicator termination. SICL automatically handles all addressing and GPIB bus management necessary to perform these reads and writes to the instrument.

iclose

The iclose function closes the device session to this instrument (id is no longer valid after this point).

Compiling and Running the C Sample Program in Windows

Compiling

The idn sample program files (available at http://www.keysight.com/find/iosuite) include the idn.c source file. Steps required to compile the idn sample program in Microsoft Visual C++ 6.0 follow:

  1. Connect an instrument to a GPIB interface that is compatible with IEEE 488.2.

  2. In Visual C++, select File > New.. to create a new project. Select Win32 Console Application for this sample program and type in a name for your project.

  3. Select Project > Settings from the menu. Click the Link tab and add sicl32.lib to the Object/Library Modules list box. Optionally, you may add the library directly to your project file. Click OK to close the dialog box.

  4. You may want to add the include files and library files search paths:
    1. Select Tools > Options from the menu.
    2. Click the Directories tab to set the include file path.
    3. Select Include Files from the Show Directories For list box.
    4. Click at the bottom of the list box and type:
      C:\Program Files\Agilent\IO Libraries Suite\include
      (This assumes that you used the default installation location for IO Libraries Suite.)
    5. Select Library Files from the Show Directories For list box.
    6. Click at the bottom of the list box and type:
      C:\Program Files\Agilent\IO Libraries Suite\lib
      (This assumes that you used the default installation location for IO Libraries Suite.)

  5. Add or create your C or C++ source files. For this sample program, select Project > Add to Project > Files... and type or browse to the location of the downloaded idn.c file.

  6. The program assumes the GPIB interface name is gpib0 (set using the Connection Expert utility) and the instrument is at bus address 0. If necessary, modify the interface name and instrument address on the DEVICE_ADDRESS definition line in the IDN.C source file.

  7. Click Build > Rebuild All to build the SICL program.

Running the C Sample Program

To run the idn sample program, execute the program from a console command prompt by selecting Project > Execute or Run > Go.

If the program runs correctly and is connected to a 54622A oscilloscope, the following would be a sample of the output:

AGILENT TECHNOLOGIES,54622A,22457869,A.01.50

If the program does not run, see the message logger for a list of run-time errors, and see Troubleshooting SICL Programs for guidelines to correct the problem.

Compiling and Running the C Sample Program in Linux

Compiling

The idn sample program files (available at http://www.keysight.com/find/iosuite) include the idn.c source file. Steps required to compile the idn sample program with GCC follow:

1. Connect an instrument to a GPIB interface that is compatible with IEEE 488.2.

2. Install GCC compiler on your system

3. The program assumes the GPIB interface name is gpib0 (set using the Connection Expert utility) and the instrument is at bus address 0. If necessary, modify the interface name and instrument address on the DEVICE_ADDRESS definition line in the IDN.C source file.

4. Run command on command line terminal: gcc idn.c -I/opt/Keysight/iolibs/include -lsicl -o idn

5. You should be able to see an executable file “idn” created on the same directory as idn.c source file.

Running

To run the idn sample program, execute the program from a command line terminal: ./idn

If the program runs correctly and is connected to a 54622A oscilloscope, the following would be a sample of the output:

AGILENT TECHNOLOGIES,54622A,22457869,A.01.50

If the program does not run, see the message logger for a list of run-time errors, and see Troubleshooting SICL Programs for guidelines to correct the problem.

Where to Go Next

 

In addition, see the chapter(s) that describe how to use SICL with your specific interface(s):

You may also want to familiarize yourself with SICL functions, which are defined in the reference information provided elsewhere in the SICL online Help. If you have any problems, see Troubleshooting SICL Programs for more information.