HP st ard schematic

Download

Page 1

Contents

Agilent Standard Instrument Control Library

User’s Guide for Windows

Front Matter............................................................................................... 7

Notice... ....... ...... ....... .......................................................... ...... ..... 7

Warranty Information .................................................................... 7

U.S. Government Restricted Rights .............................................. 7

Trademark Information ................................. ....... ...... ....... ...... ...... 8

Printing History ............................................................................. 8

1. Introduction .......................................................................................... 9

What’s in This Guide?.................................................................. 11

SICL Overview.............................................................................13

2. Getting Started with SICL ................................................................. 15

Getting Started Using C...............................................................17

Getting Started Using Visual Basic..............................................23

3. Programming with SICL .................................................................... 25

Building a SICL Application ......................................................... 27

Opening a Communications Session........................................... 31

Sending I/O Commands ....................................... ...... ................. 35

Handling Asynchronou s Ev ents................................................... 5 5

Handling Errors..................... ...... ....... .......................................... 58

Using Locks ................................................................................. 64

4. Using SICL with GPIB ........................................................................ 69

Introduction.................................................................................. 71

Using GPIB Device Sessions ...................................................... 72

Using GPIB Interface Sessions ................................................... 78

Using GPIB Commander Sessions.............................................. 83

Writing GPIB Interrupt Handlers ..................................................85

5. Using SICL with GPIO ....................................................................... 89

Introduction.................................................................................. 91

Using GPIO Interface Sessions................................................... 94

6. Using SICL with VXI ......................................................................... 101

Introduction................................................................................ 103

Using VXI Device Sessions.......................................................105

Using VXI Interface Sessions.................................................... 117

Communicating with VME Devices............................................ 119

SICL Function Support with VXI................................................124

Page 2

VXI Backplane Memory I/O Performance...................................127

Using VXI-Specific Interrupts......................................................131

7. Using SICL with RS-232 ...................................................................135

Introduction.................................................................................137

Using RS-232 Device Sessions..................................................141

Using RS-232 Interface Sessions...............................................146

8. Using SICL with LAN ........................................................................153

LAN Overview.............................................................................155

Using LAN-gatewayed Sessions................................................160

Using LAN Interface Sessions....................................................167

Using Locks and Threads over LAN...........................................169

Using Timeouts with LAN...........................................................171

9. Troubleshooting SICL Programs ....... ...... ....... ...... ...... ....... ...... .......175

SICL Error Codes .......................................................................177

Common Windows Problems.....................................................180

Common RS-232 Problems........................................................181

Common GPIO Problems...........................................................182

Common LAN Problems.............................................................184

10. More SICL Example Programs ......................................................189

Example: Oscillosope Program (C)............................................191

Example: Oscillosope Program (Visual Basic) ...........................199

11. SICL Language Reference .............................................................203

Introduction.................................................................................205

IBLOCKCOPY............................................................................207

IBLOCKMOVEX .........................................................................209

ICAUSEERR...............................................................................211

ICLEAR.......................................................................................212

ICLOSE ......................................................................................213

IDEREFPTR...............................................................................214

IFLUSH.......................................................................................215

IFREAD ......................................................................................217

IFWRITE.....................................................................................219

IGETADDR.................................................................................221

IGETDATA..................................................................................222

IGETDEVADDR..........................................................................223

IGETERRNO..............................................................................224

IGETERRSTR ............................................................................225

IGETGATEWAYTYPE................................................................226

IGETINTFSESS..........................................................................227

Page 3

IGETINTFTYPE......................................................................... 228

IGETLOCKWAIT........................................................................ 229

IGETLU......................................................................................230

IGETLUINFO ............................................................................. 231

IGETLULIST .............................................................................. 233

IGETONERROR........................................................................ 234

IGETONINTR............................................................................. 235

IGETONSRQ ............................................................................. 236

IGETSESSTYPE ....................................................................... 237

IGETTERMCHR ........................................................................ 238

IGETTIMEOUT .......................................................................... 239

IGPIBATNCTL ........................................................................... 240

IGPIBBUSADDR........................................................................ 241

IGPIBBUSSTATUS.................................................................... 242

IGPIBGETT1DELAY.................................................................. 244

IGPIBLLO .................................................................................. 245

IGPIBPASSCTL.........................................................................246

IGPIBPPOLL.............................................................................. 247

IGPIBPPOLLCONFIG................................................................ 248

IGPIBPPOLLRESP....................................................................249

IGPIBRENCTL........................................................................... 250

IGPIBSENDCMD....................................................................... 251

IGPIBSETT1DELAY .................................................................. 252

IGPIOCTRL ............................................................................... 253

IGPIOGETWIDTH...................................................................... 257

IGPIOSETWIDTH...................................................................... 258

IGPIOSTAT................................................................................ 260

IHINT ......................................................................................... 263

IINTROFF .................................................................................. 265

IINTRON.................................................................................... 266

ILANGETTIMEOUT ................................................................... 267

ILANTIMEOUT........................................................................... 268

ILOCAL...................................................................................... 271

ILOCK........................................................................................ 272

IMAP.......................................................................................... 275

IMAPX........................................................................................ 278

IMAPINFO ................................................................................. 281

IONERROR ............................................................................... 283

IONINTR.................................................................................... 286

IONSRQ..................................................................................... 288

IOPEN........................................................................................ 289

IPEEK ........................................................................................ 291

IPEEKX8, IPEEKX16, IPEEKX32..............................................292

IPOKE........................................................................................293

Page 4

IPOKEX8, IPOKEX16, IPOKEX 32 .............................................294

IPOPFIFO................................................... ...... ...... ....... ...... .......295

IPRINTF............................ ...... ....... ...... ....... ...... ...... ....... ...... .......297

IPROMPTF.......................................................................... .......307

IPUSHFIFO ............................ ....... ...... ....... ................................308

IREAD........................ ....... ...... ....... ...... ....... ...... ...... ....... ...... .......310

IREADSTB........................ ...... ....... ...... ....... ...... .......................... 31 2

IREMOTE......................................................... ...... ....... ...... .......313

ISCANF ............................ ...... ....... ...... ....... ...... .......................... 31 4

ISERIALBREAK......... ....... ...... ....... ...... ....... ...... ...... ....... .............324

ISERIALCTRL ........................ ....... .............................................325

ISERIALMCLCTRL..................................... ...... ...... ....... ...... .......328

ISERIALMCLSTAT.... ....... ...... ....... ...... ....... ...... ...... ....................32 9

ISERIALSTAT............ ....... ...... ....... ...... ....... ...... ...... ....... ...... .......330

ISETBUF .......................... ...... ....... ...... ....... ...... ...... ....................33 4

ISETDATA........................ ..........................................................336

ISETINTR......................................................... ...... ....... ...... .......337

ISETLOCKWAIT......................................... ...... .......................... 34 4

ISETSTB.............. ...... ....... ...... ....... ...... ....... ...... ...... ....... ...... .......345

ISETUBUF.................................................. ...... ...... ....... ...... .......346

ISWAP....................... .......................................................... .......348

ITERMCHR....................... ...... ....................................................350

ITIMEOUT ..................................................................................351

ITRIGGER........................................................ ...... ....... ...... .......352

IUNLOCK.......................... ...... ....................................................354

IUNMAP..................... ....... ...... ....... ...... ....... ...... ...... ....... ...... .......355

IUNMAPX......................................................... ...... ....... .............357

IVERSION ........................ ...... ....... ...... ....... ................................359

IVXIBUSSTATUS ............................................. ...... ....... ...... .......360

IVXIGETTRIGROUTE ...................................... ...... ....... ...... .......363

IVXIRMINFO.............. ....... ...... ....... .............................................364

IVXISERVANTS ............... ...... ....... ...... ....... ...... ...... ....... ...... .......367

IVXITRIGOFF............ ....... ...... ....... ...... ....... ...... ...... ....... ...... .......368

IVXITRIGON........................................ ....... ...... ...... ....... .............370

IVXITRIGROUTE................................................................. .......372

IVXIWAITNORMOP... ....... ...... ....... ...... ....... ...... ...... ....... ...... .......374

IVXIWS...................... .......................................................... .......375

IWAITHDLR................................................ ...... ...... ....... ...... .......377

IWRITE...................... ....... ...... ....... ...... ....... ...... ...... ....... ...... .......379

IXTRIG....................... ....... ...... ....... ...... ....... ...... ...... ....... .............381

_SICLCLEANUP............... ...... ....... ...... ....... ...... ...... ....................38 4

Page 5

A. SICL System Information .............................................................. 385

Windows 95/Windows 98........................................................... 387

Windows NT/Windows 2000...................................................... 389

B. Porting to Visual Basic .................................................................. 391

C. SICL Error Codes ..........................................................................393

D. SICL Function Summary ............................................................... 397

E. RS-232 Cables ................................................................................ 403

Cable/Adapter Part Numbers..................................................... 405

Cable/Adapter Pinouts...............................................................407

Glossary ............................................................................................... 415

Index ...................................................................................................... 419

Page 6

Page 7

Notice

The information contained in this document is subject to change without notice.

Agilent Technologies shall not be liable for any errors contained in this document.

regard to this document, whether express or implied. Agilent Technologies specifically disclaims the implied warranties of merchantability and fitness for a particular purpose.

direct, indirect, special, incidental, or consequential damages, whether based on contract, tort, or any other legal theory, in connection with the furnishing of this document or the use of the information in this document.

Agilent Technologies makes no warranties of any kind with

Agilent Technologies shall not be liable for any

Warranty Information

A copy of the specific warranty terms applicable to your Agilent T echnologies product and replacement parts can be obtained from Agilent Technologies, Inc.

U.S. Government Restricted Rights

The Software and Documentation have been developed entirely at private expense. They are delivered and licensed as "commercial computer software" as defined in DFARS 252.227- 7013 (Oct 1988), DFARS 252.2117015 (May 1991) or DFARS 252.227-7014 (Jun 1995), as a "commercial item" as defined in FAR 2.101(a), or as "Restricted computer software" as defined in FAR 52.227-19 (Jun 1987)(or any equivalent agency regulation or contract clause), whichever is applicable. You have only those rights provided for such Software and Documentation by the applicable FAR or DFARS clause or the Agilent standard software agreement for the product involved.

Page 8

Trademark Information

Microsoft®, Windows ® 95, Windows ® 98, Windows ® 2000, and Windows NT® are U.S. registered trademarks of Microsoft Corporation. All other brand and product names are trademarks or registered trademarks of their respective companies.

Printing History

Edition 1 - April 1994 Edition 2 - September 1995 Edition 3 - May 1996 Edition 4 - October 1996 Edition 5 - July 2000

Agilent Technologies Standard Instrument Control Library

User’s Guide for Windows

Edition 5

Page 9

Introduction

Page 10

Introduction

This

Agilent Standard Instrument Control Libraries (SICL) User’s Guide

for Windows

applications on Microsoft Windows 95, Windows 98, Windows NT 4.0, and Windows 2000. A getting started chapter is provided to help you write and run your first SICL program. Then, this guide explains how to build and program SICL applications. Later chapters are interface-specific, describing how to use SICL with GPIB, GPIO, VXI, RS-232, and LAN interfaces.

NOTE

Before you can use SICL, you must install and configure SICL on your computer. See the

Guide for Windows

otherwise indicated, Windows NT refers to Windows NT 4.0.

If You Need Help:

n In the USA and Canada, you can reach Agilent Technologies at

describes Agilent SICL and how to use it to develop I/O

Agilent IO Libraries Installation and Configuration

for installation on Windows systems. Unless

these telephone numbers:

USA: 1-800-452-4844

Canada: 1-877-894-4414

n Outside the USA and Canada, contact your country’s Agilent support

organization. A list of contact information for other countries is available on the Agilent web site:

http://www.agilent.com/find/assist

10 Chapter 1

Page 11

Introduction

What’s in This Guide?

This chapter provides an overview of SICL. In addition, this guide contains the following chapters:

Chapter 2 - Getting Started with SICL

an example program in C/C++ and Visual BASIC.

Chapter 3 - Programming with SICL

application in a Windows environment and provides information on communications sessions, addressing, error handling, locking, etc..

Chapter 4 - Using SICL with GPIB

the GPIB interface.

Chapter 5 - Using SICL with GPIO

the GPIO interface.

Chapter 6 - Using SICL with VXI

the VXIbus interface.

shows how to build and run

shows how to build a SICL

shows how to communicate over

Chapter 7 - Using SICL with RS-232

over the RS-232 interface.

Chapter 8 - Using SICL with LAN

a Local Area Network (LAN).

Chapter 9 - Troubleshooting SICL Programs

common SICL programming problems and provides troubleshooting procedures.

Chapter 10 - More SICL Example Programs

example programs to help you develop SICL applications.

Chapter 11 - SICL Language Reference

and description for each SICL function.

Appendix A - SICL System Information

SICL software files and system interaction.

Chapter 1 11

shows how to communicate

shows how to communicate over

describes some

contains additional

provides function syntax

provides information on

Page 12

Introduction

What’s in This Guide?

Appendix B - Porting to Visual Basic

applications from earlier versions of Visual Basic (such as version

3.0) to Visual Basic version 4.0 and above.

Appendix C - SICL Error Codes

error strings along with a brief description of each error.

Appendix D - SICL Function Summary

features for each SICL function.

Appendix E - RS-232 Cables

diagrams for several RS-232 cables.

Glossary

includes major terms and definitions used in this guide.

explains how to move SICL

provides a list of error codes and

summarizes supported

lists part numbers and shows wiring

12 Chapter 1

Page 13

Introduction

SICL Overview

SICL is part of the Agilent IO Libraries. The Agilent IO Libraries consists of two libraries:

Agilent Standard Instrument Control Library (SICL).

Introducing VISA and SICL

n Agilent Virtual Instrument Software Architecture (VISA) is an I/O

Agilent Virtual Instrument Software Architecture (VISA)

library designed according to the VXI allows software developed from different vendors to run on the same system.

plug&play

System Allian c e t h at

and

n Use VISA if y ou wa nt t o use VXI

applications, or if you want the I/O applications or instrument drivers that you develop to be compliant with VXI are using new instruments or are developing new I/O applications or instrument drivers, we recommend you use Agilent VISA.

plug&play

instrument drivers in your

plug&play

standards. If you

n Agilent Standard Instrument Control Library (SICL) is an I/O library

developed by Hewlett-Packard and Agilent that is portable across many I/O interfaces and systems.

n You can use Agilent SICL if you have been using SICL and want to

remain compatible with software currently implemented in SICL.

NOTE

Since VISA and SICL are different libraries, using VISA functions and SICL functions in the same I/O application is not supported.

SICL Description

Agilent Standard Instrument Control Library (SICL) is an I/O library developed by Hewlett-Packard and Agilent that is portable across many I/O interfaces and systems. SICL is a modular instrument communications library that works with a variety of computer architectures, I/O interfaces, and operating systems. Applications written in C/C++ or Visual BASIC using this library can be ported at the source code level from one system to another with no (or very few) changes.

Chapter 1 13

Page 14

Introduction

SICL Overview

SICL uses standard, commonly used functions to communicate over a wide variety of interfaces. For example, a program written to communicate with a particular instrument on a given interface can also communicate with an equivalent instrument on a different type of interfac e.

6,&/6XSSRUW The 32-bit version of SICL is supported on this version of the Agilent IO

Libraries for Windows 95, Windows 98, Wi ndo ws NT, and Windows 2000. Support for the 16-bit version of SICL was removed in version H.01.00. However, versions through G.02.02 support 16-bit SICL. C, C++, and Visual BASIC are supported on all these Windows versions. SICL is supported on the GPIB, GPIO, VXI, RS-232, and LAN interfaces.

6,&/8VHUV SICL is intended for instrument I/O and C/C++ or Visual BASIC

programmers who are familiar with Windows 95, Windows 98, Windows 2000, or Windows NT. To perform SICL installation and configuration on Windows NT, you must have system administrator privileges on the Windows NT system.

6,&/ 'RFXPHQWDWLRQ

This table shows associated documentation you can use when programming with Agilent SICL.

Document Description

Agilent SICL User’s Guide for Windows

SICL Online Help SICL Example Programs

VXIbus Consortium specifications (when using VISA over LAN)

Agilent SICL Documentation

Shows how to use Agilent SICL and provides the SICL language reference.

Information is provided in the form of Windows Help. Example programs are provided online to help you develop

SICL applications. SICL ex ample programs are provided in the C\SAMPLES (for C/C++) subdirectory and in the VB\SAMPLES subdirectory (for Visual BASIC) under the base directory where SICL is installed. For example, under the C:\SICL95 or C:\SICLNT base directory if the default installation directory was used.

TCP/IP Instrument Protocol Specification TCP/IP-VXIbus Interface Specification TCP/IP-IEEE 488.1 Interface Specification TCP/IP-IEEE 488.2 Instrument Interface Specification

Rev. 1.0

- VXI-11, Rev. 1.0

- VXI-11.1, Rev. 1.0

- VXI-11.2, Rev. 1.0

- VXI-11.3,

14 Chapter 1

Page 15

Getting Started with SICL

Page 16

Getting Started with SICL

This chapter gives guidelines to help you to get started programming with SICL using the C/C++ language. This chapter provides example programs in C/C++ and in Visual Basic to help you verify your configuration and

introduce you to some of SICL’s basic features. The chapter contents are:

n Getting Started Using C n Getting Started Using Visual Basic

NOTE

This chapter is divided into two sections: the first section is for C programmers and the second section is for Visual BASIC programmers. See “Getting Started Using C” if you want to use SICL with the C/C++ programming language. See “Getting Started Using Visual Basic” if you want to use SICL with the Visual BASIC programming language.

You may want to see familiarize yourself with SICL functions. This reference information is also available as online help. To see the reference information online, doubleclick the Help icon in the

16 Chapter 2

Chapter 11 - SICL Language Reference

Agilent IO Libraries program group.

Page 17

Getting Started with SICL

Getting Started Using C

This section describes an example program called IDN that queries a GPIB instrument for its identification string. This example builds a console application for WIN32 programs (32-bit SICL programs on Windows 95, Windows 98, Windows 2000, or Windows NT) using the C programming language.

C Program Example Code

All files used to develop SICL applications in C or C++ are located in the

C subdirectory of the base IO Libraries directory. Sample C/C++

programs are located in the C\SAMPLES subdirectory of the base IO Libraries directory.

Each sample program subdirectory contains makefiles or project files that you can use to build each sample C program. You must first compile the sample C/C++ programs before you can execute them.

The IDN example files are located in the C\SAMPLES\IDN subdirectory under the base IO Libraries directory. This subdirectory contains the source program, IDN.C. The source file IDN.C is listed on the following pages. An explanation of the function calls in the example follows the program listing.

/* 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 on Windows 95, Windows 98, Windows 2000, or Windows NT. Edit the DEVICE_ADDRESS line to specify the address of the applicable device. For example:

hpib7,0: refers to a GPIB device at bus address 0 connected to

an interface named “hpib7” by the IO Config utility.

hpib7,9,0: refers to a GPIB device at bus address 9, secondary

address 0, connected to an interface named “hpib7” by the IO Config utility. */

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

Chapter 2 17

Page 18

Getting Started with SICL

Getting Started Using C

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

#if defined(__BORLANDC__) && !defined(__WIN32__)

_InitEasyWin();// required for Borland EasyWin programs.

#endif

/* Install a default SICL error handler that logs an error message and exits.

On Windows 95 or Windows 98, view messages with the SICL Message Viewer, and on Windows 2000 or Windows NT use 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);

/* This call is a no-op for WIN32 programs.*/ _siclcleanup(); }

18 Chapter 2

Page 19

Getting Started with SICL

Getting Started Using C

C Example 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 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

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 desired, a custom error handling routine could be specified instead.

NOTE

at the beginning of main. The type

On Windows 95, Windows 98, and Windows 2000, error messages may be viewed by executing the Message Viewer utility in the Agilent IO Libraries program group. On Windows NT, these messages may be viewed with the Event Viewer utility in the Agilent IO Libraries Control on the taskbar.

iopen. When an iopen call is made, the parameter string ”hpib7,0” passed to iopen specifies the GPIB interface followed by the bus address of the instrument. The interface name, ”hpib7”, is the name given to the interface during execution of the IO Config 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

SICL

for information on using SICL’s addressing capabilities.

Chapter 2 19

Chapter 3 - Programming with

Page 20

Getting Started with SICL

Getting Started Using C

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

iclose and _siclcleanup. The iclose function closes the device session to this instrument ( Windows 95, Windows 98, Windows 2000, or Windows NT do not require the _siclcleanup call.

NOTE

See

Chapter 11 - SICL Language Reference

more information on these SICL function calls.

20 Chapter 2

is no longer valid after this point). WIN32 programs on

or the SICL online Help for

Page 21

Getting Started with SICL

Getting Started Using C

Compiling the C Example Program

The C\SAMPLES\IDN subdirectory contains a number of files you can use to build the example with specific compilers. You will have a subset of the following files, depending on the Windows environment you are using.

IDN.C Example program source file. IDN.DEF Module definition file for the IDN example program. MSCIDN.MAK Windows 3.1 makefile for Microsoft C and Microsoft

SDK compilers.

VCIDN.MAK Windows 3.1 project file for Microsoft Visual C++. VCIDN32.MAK Windows 95 or Windows NT (32-bit) project file for

Microsoft Visual C++.

VCIDN16.MAK Windows 95 (16-bit) project file for Microsoft Vi sual

C++.

QCIDN.MAK Windows 3.1 project file for Microsoft QuickC for

Windows.

BCIDN.IDE Windows 3.1 project file for Borland C Integrated

Development Environment.

BCIDN32.IDE Windows 95 or Windows NT (32-bit) project file for

Borland C Integrated Development Environment.

BCIDN16.IDE Windows 95 (16-bit) project file for Borland C Integra ted

Development Environment.

Steps to compile the IDN example program follow.

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

2. Change directories to the location of the example.

3. The program assumes the GPIB interface name is hpib7 (s e t using IO Config) 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.

Chapter 2 21

Page 22

Getting Started with SICL

Getting Started Using C

4. Select and load the appropriate project or make file. Then, compile the program as follows:

q For Borland compilers, use Project | Open Project.

Then, select Project | Build All.

q For Microsoft compilers, use Project | Open. Next, set

the include file path by selecting Options | Directories. Then, in the Include File Path box, enter the full path to the C subdirectory. Finally, select Project | Re-build All.

Running the C Example Program

To run the IDN example program, execute the program from a console command prompt.

n For Borland, select Run | Run n For Microsoft, select Project | Execute or Run | Go

If the program runs correctly, an example of the output if connected to a 54601A oscilloscope is

HEWLETT-PACKARD,54601A,0,1.7

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

Chapter 9 - Troubleshooting SICL Programs

for guidelines to

Where to Go Next

Go to

Chapter 3 - Programming with SICL

chapter(s) that describe how to use SICL with your specific interface(s):

Chapter 4 - Using SICL with GPIB

Chapter 5 - Using SICL with GPIO

Chapter 6 - Using SICL with VXI

Chapter 7 - Using SICL with RS-232

Chapter 8 - Using SICL with LAN

You may also want to familiarize yourself with SICL functions, defined in

Chapter 11 - SICL Language Reference

provided in SICL online Help. If you have any problems, see

Troubleshooting SICL Programs

22 Chapter 2

. In addition, you should see the

and in the reference information

Chapter 9 -

Page 23

Getting Started with SICL

Getting Started Using Visual Basic

There is a collection of Visual Basic sample programs in the VB\SAMPLES subdirectory of the base IO Libraries directory. See these programs as examples of using SICL with Visual Basic.

Be sure to include the sicl4.bas file (in the VB directory) in your Visual Basic project. This file contains the necessary SICL definitions, function prototypes, and support procedures to allow you to call SICL functions from Visual Basic.

Where to Go Next

Go to

Chapter 3 - Programming with SICL

chapter(s) that describe how to use SICL with your specific interface(s):

Chapter 4 - Using SICL with GPIB

Chapter 5 - Using SICL with GPIO

Chapter 6 - Using SICL with VXI

Chapter 7 - Using SICL with RS-232

Chapter 8 - Using SICL with LAN

. In addition, you should see the

You may also want to familiarize yourself with SICL functions, defined in

Chapter 11 - SICL Language Reference

provided in SICL online Help. If you have any problems, see

Troubleshooting SICL Programs

Chapter 2 23

and in the reference information

Chapter 9 -

Page 24

Notes:

Getting Started with SICL

Getting Started Using Visual Basic

24 Chapter 2

Page 25

Programming with SICL

Page 26

Programming with SICL

This chapter describes how to build a SICL application and then describes SICL programming techniques. Example programs are also provided to help you develop SICL applications. The chapter includes:

n Building a SICL Application n Opening a Communications Session n Sending I/O Commands n Handling Asynchronous Events n Handling Errors n Using Locks

NOTE

Copies of the example programs are located in the C\SAMPLES\MISC subdirectory (for C/C++) or in the VB\SAMPLES\MISC subdirectory (for Visual Basic) under the base IO Libraries directory. For details on SICL functions, see online Help.

Chapter 11 - SICL Language Reference

or SICL

26 Chapter 3

Page 27

Programming with SICL

Building a SICL Application

This section gives guidelines to build a SICL application in a Windows environment.

Including the SICL Declaration File

For C and C++ programs, you must include the sicl.h header file at the beginning of every file that contains SICL function calls. This header file contains the SICL function prototypes and the definitions for all SICL constants and error codes.

#include “sicl.h”

For Visual Basic version 3.0 or earlier programs, you must add the SICL.BAS file to each project that calls SICL. For Visual Basic version 4.0 or later programs, you must add the SICL4.BAS file to each project that calls SICL.

Libraries for C Applications and DLLs

All WIN32 applications and DLLs that use SICL must link to the SICL32.LIB import library. (Borland compilers use BCSICL32.DLL.)

The SICL libraries are located in the C directory under the IO Libraries base directory (for example, C:\Program Files\Agilent\IO Libraries\C if you installed SICL in the default location). You may want to add this directory to the library file path used by your language tools.

Use the DLL version of the C run-time libraries, because the run-time libraries contain global variables that must be shared between your application and the SICL DLL.

If you use the static version of the C run-time libraries, these global variables will not be shared and unpredictable results could occur. For example, if you use isscanf with the %F format, an application error will occur. The following sections describe how to use the DLL versions of the run-time libraries.

Chapter 3 27

Page 28

Programming with SICL

Building a SICL Application

Compiling and Linking C Applications

A summary of important compiler-specific considerations follows for several C/C++ compiler products when developing WIN32 applications.

NOTE

If you are using a version of the Microsoft or Borland compilers other than those listed in this subsection, the menu structure and selections may be different than indicated here. However, the equivalent functionality exists for your specific version.

0LFURVRIW9LVXDO &&RPSLOHUV

1. Select Project | Settings or Build | Settings from

the menu (depending on the version of your compiler).

2. Click the C/C++ button. Then, select Code Generation from

the Category list box and select Multithreaded Using DLL from the Use Run-Time Library list box. Click OK to close the dialog box.

3. Select Project | Settings or Build | Settings from

the menu. Click the Link button. Then, add sicl32.lib to the Object/Library Modules list box. Click OK to close the dialog box.

4. You may want to add the SICL C directory (for example,

C:\Program Files\Agilent\IO Libraries\C to the include file and library file search paths. To do this, select Tools | Options from the menu and click the Directories button. Then:

q To set the include file path, select Include Files from

the Show Directories for: list box. Next, click the Add button and type in C:\Program Files\Agilent\IO Libraries\C. Then, click OK.

q To set the library file path, select Library Files from the

Show Directories for: list box. Next, click the Add button and type in C:\Program Files\Agilent\IO Libraries\C. Then, click OK.

28 Chapter 3

Page 29

Programming with SICL

Building a SICL Application

%RUODQG& 9HUVLRQ &RPSLOHUV

1. Link your programs with BCSICL32.LIB, BCSICL32.LIB is located in the C subdirectory under the SICL base directory (for example, C:\Program Files\Agilent\ IO Libraries\C if SICL is installed in the default location).

2. Edit the BCC32.CFG and TLINK32.CFG files, which are located in the BIN subdirectory of the Borland C installation directory.

not

SICL32.LIB.

q Add the following line to BCC32.CFG so the compi le r can find

the sicl.h file:

where

-IC:\

IO_base_dir

is the IO Libraries base directory.

q Add the following line to both files so the compiler and linker

can find BCSICL32.LIB:

where

IO_base_dir

-LC:\

IO_base_dir

is the IO Libraries base directory.

q For example, to create MYPROG.EXE from MYPROG.C, type:

BCC32 MYPROG.C BCSICL32.LIB

Loading and Running Visual Basic Applications

To load and run an existing Visual Basic application, first run Visual Basic. Then, open the project file for the program you want to run by selecting File | Open Project from the Visual Basic menu. Visual Basic project files have a .MAK file extension. After you haved opened the application’s

project file, you can run the application by pressing the Visual Basic Toolbar.

You can create a standalone executable (.EXE) version of this program by selecting File | Make EXE File from the Visual Basic menu. Once this is done, the application can be run stand-alone (just like any other .EXE file) without having to run Visual Basic.

Chapter 3 29

F5 or the Run button on

Page 30

Programming with SICL

Building a SICL Application

Thread Support for 32-bit Windows Applications

SICL can be used in multi-threaded designs and SICL calls can be made from multiple threads, in WIN32 applications. However, there are some important points:

n SICL error handlers (installed with ionerror) are

(not per thread) but are called in the context of the thread that caused the error to occur. Calling ionerror from one thread will overwrite any error handler presently installed by another thread.

per process

n The igeterrno is per thread and returns the last SICL error that

occurred in the current thread.

n You may want to make use of the SICL session locking functions

(ilock and iunlock) to help coordinate common instrument accesses from more than one thread.

n See

Chapter 8 - Using SICL with LAN

using SICL with LAN.

for thread information when

30 Chapter 3

Page 31

Programming with SICL

Opening a Communications Session

A communications session is a channel of communication with a particular device, interface, or commander:

n A device session is used to communicate with a device on an

interface. A device is a unit that receives commands from a controller. Typically a device is an instrument but could be a computer, a plotter, or a printer.

n An interface session is used to communicate with a specified

interface. Interface sessions allow you to use interface-specific functions (for example, igpibsendcmd).

n A commander session is used to communicate with the interface’s

commander. Typically a commander session is used when a computer is acting like a device.

Steps to Open a Communications Session

There are two parts to opening a communications session with a specific device, interface, or commander. First, you must declare a variable for the SICL session identifier. C and C++ programs should declare the session variable to be of type INST. Visual Basic programs should declare the session variable to be of type Integer. Once the variable is declared, you can open the communication channel by using the SICL iopen function, as shown in the following example.

C example:

INST id;

= iopen (

Visual Basic example:

Dim id As Integer

= iopen (

Where interface, or commander . The address, or the term cmdr for a commander session. See the sections that follow for details on creating the different types of communications sessions.

is the session identifier used to communicate to a device,

addr

);

)

addr

parameter specifies a device or interface

Chapter 3 31

Page 32

Programming with SICL

Opening a Communications Session

Y our program may have several sessions open at the same time by creating multiple session identifiers with the iopen function. Use the SICL iclose function to close a channel of communication.

Device Sessions

A device session allows you direct access to a device without knowing the type of interface to which the device is connected. On GPIB, for example, you do not have to address a device to listen before sending data to it. This insulation makes applications more robust and portable across interfaces, and is recommended for most applications.

Device sessions are the recommended way of communicating using SICL. They provide the highest level programming method, best overall performance, and best portability.

$GGUHVVLQJ'HYLFH 6HVVLRQV

To create a device session, specify the interface logical unit or symbolic name and a specific device logical address in the iopen function. The logical unit is an integer corresponding to the interface.

The device address generally consists of an integer that corresponds to the

device’s bus address. It may also include a secondary address which is an integer. (Secondary addressing is not supported on RS-232 interfaces.) The following are valid device addresses:

7,23 Device at address 23 connected to an interface card at

logical unit 7.

7,23,1 Device at address 23, secondary address 1, connected

to an interface card at logical unit 7.

hpib,23 GPIB device at address 23. hpib2,23,1 GPIB device at address 23, secondary address 1,

connected to a second GPIB interface card.

com1,488 RS-232 device

The interface logical unit and symbolic name are set by running the IO Config utility from the Agilent IO Libraries Control (on the

taskbar) for Windows 95, Windows 98, Windows 2000, or Windows NT. See the

Windows

Agilent IO Libraries Installation and Configuration Guide for

for information on the IO Config utility.

addr

parameter of the

32 Chapter 3

Page 33

Programming with SICL

Opening a Communications Session

([DPSOHV2SHQLQJ D'HYLFH6HVVLRQ

$GGUHVVLQJ,QWHUIDFH 6HVVLRQV

The following examples open a device session with a GPIB device at address 23.

C example:

INST dmm;

dmm = iopen (“hpib,23”);

Visual Basic example:

Dim dmm As Integer dmm = iopen (“hpib,23”)

Interface Sessions

An interface sessi on allows direct, low-level control of the specified interface. A full set of interface-specific SICL functions existds for programming features that are specific to a particular interface type (GPIB, Serial, etc.). This provides full control of the activities on a given interface, but does create less portable code.

To create an interface session, specify the particular interface logical unit or symbolic name in the logical unit and symbolic name are set by running the IO Config utility from the Agilent IO Libraries Control (on the taskbar) for Windows 95, Windows 98, Windows 2000, or Windows NT. See the

Libraries Installation and Configuration Guide for Windows

the IO Config utility.

addr

parameter of the iopen function. The interface

Agilent IO

for information on

The logical unit is an integer that corresponds to a specific interface. The symbolic name is a string which uniquely describes the interface. The following are valid interface addresses:

7 Interface card at logical unit 7 hpib GPIB interface card. hpib2 Second GPIB interface card. com1 RS-232 interface card.

Chapter 3 33

Page 34

Programming with SICL

Opening a Communications Session

([DPSOHV2SHQLQJ DQ,QWHUIDFH6HVVLRQ

$GGUHVVLQJ &RPPDQGHU 6HVVLRQV

These examples open an interface session with an RS-232 interface.

C example:

INST com1;

com1 = iopen (“com1”);

Visual Basic example:

Dim com1 As Integer com1 = iopen (“com1”)

Commander Sessions

A commander sess ion allows your computer to talk to the interface controller. Typically, the controller is the computer used to communicate with devices on the interface. When the computer is not active controller, commander sessions can be used to talk to the computer that is active controller. In this mode, the computer is acting like a device on the interface.

To create a commander session, specify a valid interface address followed by a comma and then the string cmdr in the iopen function. The following are valid commander addresses:

hpib,cmdr GPIB commander session. 7,cmdr Commander session on interface at logical unit 7.

([DPSOHV&UHDWLQJ D&RPPDQGHU 6HVVLRQ

These examples create a commander session with the GPIB interface. The function calls open a session of communication with the commander on a GPIB interface.

C example:

INST cmdr; cmdr = iopen(“hpib,cmdr”);

Visual Basic example:

Dim cmdr As Integer cmdr = iopen (“hpib,cmdr”)

34 Chapter 3

Page 35

Programming with SICL

Sending I/O Commands

Once you have established a communications session with a device, interface, or commander, you can start communicating with that session

using SICL’s I/O routines. SICL provides formatted I/O and non-formatted I/O routines.

n Formatted I/O converts mixed types of data under the control of a

format string. The data is buffered, thus optimizing interface traffic. The formatted I/O routines are geared towards instruments, and reduce the amount of I/O code.

n Non-formatted I/O sends or receives raw data to a device, interface,

or commander. With non-formatted I/O, no format or conversion of the data is performed. Thus, if formatted data is required, it must be done by the user.

Formatted I/O in C Applications

The SICL formatted I/O mechanism is similar to the C stdio mechanism. SICL formatted I/O, however, is designed specifically for instrument communication and is optimized for IEEE 488.2 compatible instruments. The three main functions for formatted I/O in C applications are:

n The iprintf function formats according to the format string and

sends data to a device:

iprintf(

id, format [,arg1][,arg2][,...]

);

n The iscanf function receives and converts data according to the

format string:

iscanf(

id, format [,arg1][,arg2][,...]

);

n The ipromptf function formats and sends data to a device and

then immediately receives and converts the response data:

ipromptf(

The formatted I/O functions are buffered. Also, there are two non-buffered and non-formatted I/O functions called iread and iwrite. (See “Non- Formatted I/O” later in this chapter.) These are raw I/O functions and do not intermix with formatted I/O functions.

Chapter 3 35

id, writefmt, readfmt [,arg1][,arg2][,...]

);

Page 36

Programming with SICL

Sending I/O Commands

If raw I/O must be mixed, use the ifread/ifwrite functions. These functions have the same parameters as iread and iwrite, but read or

write raw output data to the formatted I/O buffers. See “Formatted I/O Buffers” in this section for more details.

)RUPDWWHG,2 &RQYHUVLRQ

Formatted I/O functions convert data under the control of the format string. The format string specifies how the argument is converted before it is input or output. A typical format string syntax is:

%[format flags][field width][. precision][, array size][argument modifier]conversion character

See iprintf, ipromptf, and iscanf in

Reference

for more information on how data is converted under the control

Chapter 11 - SICL Language

of the format string

Format Flags. Zero or more flags may be used to modify the meaning of

the conversion character. The format flags are only used when sending formatted I/O (iprintf and ipromptf). Supported format flags are:

Format

Flag

@1 Converts to a 488.2 NR1 number. @2 Converts to a 488.2 NR2 number. @3 Converts to a 488.2 NR3 number. @H Converts to a 488.2 hexadecimal number. @Q Converts to a 488.2 octal number.

Description

@B Converts to a 488.2 binary number. + Prefixes number with sign (+ or –).

– Left justifies result. space Prefixes number with blank space if positive or with – if negative.

# Uses alternate form. For o conversion , it prin t s a l ead ing ze ro. For x

or X, a nonzero will have 0 x or 0X as a pre fix. Fo r e, E, f, g, or G, the result will always have one digit on the right of the decimal point.

0 Causes left pad character to be a zero for all numeric conversion

types.

36 Chapter 3

Page 37

Programming with SICL

Sending I/O Commands

This example converts numb into a 488.2 floating point number and sends the value to the session specified b y

int numb = 61; iprintf (

, “%@2d&\n”, numb);

Sends: 61.000000

Field Width. Field width is an optional integer that specifies how many

characters are in the field. If the formatted data has fewer characters than specified in the field width, it will be padded. The padded character is dependent on various flags. You can use an asterisk (*) in place of the integer to indicate that the integer is taken from the next argument.

This example pads numb to six characters and sends the value to the session specified by

long numb = 61; iprintf (

, “%6ld&\n”, numb);

Pads to six characters: 61

. Precision. Precision is an optional integer preceded by a period. When

used with conversion characters e, E, and f, the number of digits to the right of the decimal point are specified. For the d, i, o, u, x, and X conversion characters, the minimum number of digits to appear is specified. For the s and S conversion characters, the precision specifies the maximum number of characters to be read from the argument. This field is only used when sending formatted I/O (iprintf and ipromptf). You can use an asterisk (*) in place of the integer to indicate that the integer is taken from the next argument.

This example converts numb so that there are only two digits to the right of the decimal point and sends the value to the session specified by

float numb = 26.9345; iprintf (

, “.2f\n”, numb);

Sends : 26.93

, Array Size. The comma operator is a format modifier which allows you to

read or write a comma-separated list of numbers (only valid with %d and %f conversion characters). It is a comma followed by an integer. The integer indicates the number of elements in the array. The comma operator has the format of ,

where dd is the number of elements to read or write.

Chapter 3 37

Page 38

Programming with SICL

Sending I/O Commands

This example specifies a comma-separated list to be sent to the session specified by

int list[5]={101,102,103,104,105}; iprintf (

, “%,5d\n”, list);

Sends: 101,102,103,104,105

Argument Modifier. The meaning of the optional argument modifier

h, l, w, z, or Z is dependent on the conversion character.

Argument Modifiers in C Applications

Argument

Modifier

h d,i Corresponding argument is a short integer. hf Corresponding argum ent is a float for iprintf

l d,i Corresponding argument is a long integer. l b,B Corresponding argument is a pointer to a block

lf Co rrespon ding argu me nt is a double for iprintf

w b,B Corresponding argument is a pointer to a block

z b,B Corresponding argument is a pointer to a block

Z b,B Corresponding argument is a pointer to a block

Conversion Characters. The conversion characters for sending and receiving

Conversion

Character

Description

or a pointer to a float for iscanf.

of long integers.

or a pointer to a double for iscanf.

of short integers.

of floats.

of doubles.

formatted I/O are different. The following tables summarize the conversion characters for each.

38 Chapter 3

Page 39

Programming with SICL

Sending I/O Commands

iprintf and ipromptf Conversion Characters in C Applications

Conversion

Character

d,i Corresponding argument is an integer. f Corresponding argument is a float. b,B Corresponding argument is a pointer to an arbitrary block

of data.

c,C Corresponding argument is a character. t Controls whether the END indicator is sent with each LF

character in the format string.

s,S Corresponding argument is a pointer to a null terminated

string.

% Sends an ASCII percent (%) character. o,u,x,X Corresponding argument will be treated as an unsigned

integer.

e,E,g,G Corresponding argument is a double. n Corresponding argument is a pointer to an integer. F Corresponding argument is a pointer to a FILE descriptor

opened for reading.

Description

This example sends an arbitrary block of data to the session specified by the

parameter. The asterisk (*) is used to indicate that the number is taken

from the next argument:

int size = 1024; char data [1024]; . . iprintf (

, “%*b&\n”, size, data);

Sends 1024 characters of block data.

Chapter 3 39

Page 40

Programming with SICL

Sending I/O Commands

iscanf and ipromptf Conversion Characters in C Applications

([DPSOH)RUPDWWHG ,2&

Conversion

Character

d,i,n Corresponding argument must be a pointer to an integer. e,f,g Corresponding argument must be a pointer to a float. c Corresponding argument is a pointer to a character. s,S,t Corresponding argument is a pointer to a string. o,u,x Corresponding argument must be a pointer to an unsigned

integer.

[ Corresponding argument must be a character pointer. F Corresponding argument is a pointer to a FILE descriptor

opened for writing.

Description

This example receives data from the session specified by the id parameter and converts the data to a string:

char data[180]; iscanf (

, “%s”, data);

This C program example shows one way to send and receive formatted I/O. This example opens an GPIB communications session with a multimeter and uses a comma operator to send a comma-separated list to the multimeter. The

conversion characters are used to receive a double from

the multimeter.

/* formatio.c

This example program makes a multimeter measurement with a comma-separated list passed with formatted I/O and prints the results */

#include <sicl.h> #include <stdio.h>

main() {

INST dvm; double res;

double list[2] = {1,0.001};

#if defined(__BORLANDC__) && !defined(__WIN32__) _InitEasyWin(); /*Required for Borland EasyWin programs*/ #endif

40 Chapter 3

Page 41

Programming with SICL

Sending I/O Commands

/* Log message and terminate on error */ ionerror (I_ERROR_EXIT);

/* Open the multimeter session */

dvm = iopen (“hpib7,16”); itimeout (dvm, 10000);

/*Initialize dvm*/ iprintf (dvm, “*RST\n”);

/*Set up multimeter and send comma-separated list*/ iprintf (dvm, “CALC:DBM:REF 50\n”); iprintf (dvm, “MEAS:VOLT:AC? %,2lf\n”, list);

/* Read the results */ iscanf (dvm,”%lf”,&res);

/* Print the results */ printf (“Result is %f\n”,res);

/* Close the multimeter session */ iclose (dvm);

/* This is a no-op for WIN32 programs.*/

_siclcleanup(); return 0; }

)RUPDW6WULQJ The format string for iprintf puts a special meaning on the newline

character (\n). The newline character in the format string flushes the output buffer to the device. All characters in the output buffer will be written to the device with an END indicator included with the last byte (the newline character). This means you can control at what point you want the data written to the device.

If no newline character is included in the format string for an iprintf call, the characters converted are stored in the output buffer. It will require another call to iprintf or a call to iflush to have those characters written to the device.

This can be very useful in queuing up data to send to a device. It can also raise I/O performance by doing a few large writes instead of several smaller

Chapter 3 41

Page 42

Programming with SICL

Sending I/O Commands

writes. This behavior can be changed by the isetbuf and isetubuf

functions. See “Formatted I/O Buffers” for details. The format string for iscanf ignores most white-space characters.

Two white-space characters that it does not ignore are newlines (\n) and carriage returns (\r). These characters are treated just like normal characters in the format string, which character read from the device.

must

match the next non-white-space

)RUPDWWHG,2 %XIIHUV

The SICL software maintains both a read and write buffer for formatted I/O operations. Occasionally, you may want to control the actions of these buffers. See the isetbuf function for other options for buffering data.

The write buffer is maintained by the iprintf and the write portion of the ipromptf functions. It queues characters to send to the device so that they are sent in large blocks, thus increasing performance. The write buffer automatically flushes when it sends a newline character from the format string (see the %t conversion character to change this feature).

The write buffer also flushes immediately after the write portion of the ipromptf function. It may occasionally be flushed at other nondeterministic times, such as when the buffer fills. When the write buffer flushes, it sends its contents to the device.

The read buffer is maintained by the iscanf and the read portion of the ipromptf functions. The read buffer queues the data received from a device until it is needed by the format string. The read buffer is automatically flushed before the write port ion of an ipromptf. Flushing the read buffer destroys the data in the buffer and guarantees that the next call to iscanf or ipromptf reads data directly from the device rather than data that was previously queued.

NOTE

Flushing the read buffer also includes reading all pending response data from a device. If the device is still sending data, the flush process will continue to read data from the device until it receives an END indicator from the device.

42 Chapter 3

Page 43

Programming with SICL

Sending I/O Commands

5HODWHG)RUPDWWHG ,2)XQFWLRQV

A set of functions related to formatted I/O follows.

ifread Obtains raw data directly from the read formatted I/O buffer.

This is the same buffer that iscanf uses.

ifwrite Writes raw data dire ctly to the write fo rmatted I/O bu ffer. This is

the same buffer that iprintf uses.

iprintf Converts data via a format string and writes the arguments

appropriately.

iscanf Reads data from a device/interface, converts this data via a

format string, and assigns the values to your arguments.

ipromptf Sends, then receives, data from a device/instrument. It also

converts data via format strings that are identical to iprintf and iscanf.

iflush Flushes the formatted I/O rea d an d wr it e bu f fe r s. A flu sh of th e

read buffer means that any data in the buffer is lost. A flush of the write buffer means that any data in the buffer is written to

the session’s target address.

isetbuf Sets the size of the formatted I/O read and the write buffers.

A size of zero (0) means no buffering. If no buffering is used, performance can be severely affected.

isetubuf Sets the read or the write buffer to your allocated buffer.

The same buffer cannot be used for both reading and writing. Also you should be careful when using buffers that are automatically allocated.

Chapter 3 43

Page 44

Programming with SICL

Sending I/O Commands

Formatted I/O in Visual Basic Applications

SICL formatted I/O is designed specifically for instrument communication and is optimized for IEEE 488.2 compatible instruments. The two main functions for formatted I/O in Visual Basic applications are:

n The ivprintf function formats according to the format string and

sends data to a device:

Function ivprintf(

As Integer,

As Any) As Integer

n The ivscanf function receives and converts data according to the

format string:

Function ivscanf(

NOTE

As Integer,

As Any) As Integer

fmt

As String,

fmt

As String,

There are certain restrictions when using ivprintf and ivscanf with Visual Basic. For details about these restrictions, see “Restrictions Using ivprintf in Visual Basic” in the iprintf function or “Restrictions Using ivscanf in Visual Basic” in the iscanf function in

SICL Language Reference

The formatted I/O functions are buffered. There are two non-buffered and non-formatted I/O functions called iread and iwrite. (See “Non-

Formatted I/O” later in this chapter.) These are raw I/O functions and do not intermix with the formatted I/O functions.

If raw I/O must be mixed, use the ifread/ifwrite functions. They have the same parameters as iread and iwrite, but read or write raw output data to the formatted I/O buffers. See “Formatted I/O Buffers” for details.

Chapter 11 -

44 Chapter 3

Page 45

Programming with SICL

Sending I/O Commands

)RUPDWWHG,2 &RQYHUVLRQ

The formatted I/O functions convert data under the control of the format string. The format string specifies how the argument is converted before it is input or output. The typical format string syntax is:

%[format flags][field width][. precision][, array

size][argument modifier]conversion character

See iprintf and iscanf in

Chapter 11 - SICL Language Reference

for more information on how data is converted under the control of the format string.

Format Flags. Zero or more flags may be used to modify the meaning of the

conversion character. The format flags are only used when sending formatted I/O (ivprintf). Supported format flags are:

Format Flags for ivprintf in Visual Basic Applications

Format

Flag

@1 Converts to a 488.2 NR1 number. @2 Converts to a 488.2 NR2 number. @3 Converts to a 488.2 NR3 number. @H Converts to a 488.2 hexadecimal number. @Q Converts to a 488.2 octal number. @B Converts to a 488.2 binary number.

Description

+ Prefixes number with sign (+ or –).

– Left justifies result. space Prefixes number with blank space if positive or with – if

negative.

# Uses alternate form. For o conversion, it prints a leading zero.

For x or X, a n onzero will have 0x or 0X as a prefix. For e, E, f, g, or G, the result will always have one digit on the right of the decimal point.

0 Causes left pad character to be a zero for all numeric

conversion types.

Chapter 3 45

Page 46

Programming with SICL

Sending I/O Commands

This example converts numb into a 488.2 floating point number to the session specified by

. The function return values must be assigned to variables for all Visual Basic function calls. Also, + Chr$(10) adds the newline character to the format string to indicate that the formatted I/O write buffer should be flushed. (This is equivalent to the \n cha racter sequence used for C/C++ programs.

Dim numb As Integer Dim ret_val As Integer

numb = 61 ret_val = ivprintf(

, “%@2d” + Chr$(10), numb)

Sends: 61.000000

Field Width. Field width is an optional integer that specifies how many

characters are in the field. If the formatted data has fewer characters than specified in the field width, it will be padded. The padded character is dependent on various flags.

This example pads numb to six characters and sends the value to the session specified by

Dim numb As Integer Dim ret_val As Integer

numb = 61 ret_val = ivprintf(

, “%6d” + Chr$(10), numb)

Pads to six characters: 61

. Precision. Precision is an optional integer preceded by a period. When

This example converts decimal point and sends the value to the session specified by

numb

so there are only two digits to the right of the

Dim numb As Double Dim ret_val As Integer

numb = 26.9345 ret_val = ivprintf(

, “%.2lf” + Chr$(10), numb)

Sends : 26.93

46 Chapter 3

Page 47

Programming with SICL

Sending I/O Commands

, Array Size. The comma operator is a format modifier which allows you to

where dd is the number of elements to read or write.

This example specifies a comma separated list to be sent to the session specified by

Dim list(4) As Integer Dim ret_val As Integer

list(0) = 101 list(1) = 102 list(2) = 103 list(3) = 104 list(4) = 105

ret_val = ivprintf(

, “%,5d” + Chr$(10), list(0))

Sends: 101,102,103,104,105

Argument Modifier. The meaning of the optional argument modifier

h, l, w, z, or Z is dependent on the conversion character.

Argument Modifiers in Visual Basic Application

Argument

Modifier

h d,i Corresponding argument is an Integer. hf Corresponding argument is a Single. l d,i Corresponding argument is a Long. l d,B Corresponding argument is an array of Long. lf Corresponding argument is a Double. w d,B Corresponding argument is an array of Integer. z d,B Corresponding argument is an array of Single. Z d,B Corresponding argument is an array of Double.

Conversion Characters. The conversion characters for sending and receiving

Conversion

Character

Description

formatted I/O are different. The following tables summarize the conversion characters for each:

Chapter 3 47

Page 48

Programming with SICL

Sending I/O Commands

ivprintf Conversion Characters in Visual Basic Applications

Conversion

Character

d, i Corresponding argument is an Integer. b, B Not supported on Visual Basic. c,C Not supported on Visual Basic. t Not supported on Visual Basic. s,S Not supported on Visual Basic. % Sends an ASCII percent (%) character. o,u,x,X Corresponding argument will be treated as an Integer. f,e,E,g,G Corresponding argument is a Double. n Corresponding argument is an Integer. F Corresponding arg is a pointer to a FILE descriptor.

Description

ivscanf Conversion Characters in Visual Basic Applications

Conversion

Character

d,i,n Corresponding argument must be an Integer. e,f,g Corresponding argument must be a Single. c Corresponding argument is a f ixed length String.

Description

s,S,t Corresponding argument is a f ixed length String. o,u,x Corresponding argument must be an Integer. [ Corresponding argument must be a fixed length character String. F Not supported on Visual Basic.

48 Chapter 3

Page 49

Programming with SICL

Sending I/O Commands

This example receives data from the session specified by the id parameter and converts the data to a string:

Dim ret_val As Integer Dim data As String * 180

ret_val = ivscanf(

([DPSOH)RUPDWWHG ,29LVXDO%DVLF

‘ formatio.bas ‘ The following subroutine makes a multimeter measurement with a comma‘ separated list passed with formatted I/O and prints the results. ‘ Sub main()

Dim dvm As Integer Dim res As Double ReDim list(2) As Double Dim nRetVal As Integer

On Error GoTo ErrorHandler

‘ Initialize values in list list(0) = 1 list(1) = 0.001

‘ Open the multimeter session dvm = iopen(“hpib7,0”) Call itimeout(dvm, 10000)

This Visual Basic program example sends and receives formatted I/O. The example opens a GPIB communications session with a multimeter and uses a comma operator to send a comma-separated list to the multimeter. The lf conversion characters are then used to receive a Double from the multimeter.

, “%180s”, data)

‘ Initialize dvm. nRetVal = ivprintf(dvm, “*RST” + Chr$(10), 0&)

‘ Set up multimeter and send comma separated list nRetVal = ivprintf(dvm, “CALC:DBM:REF 50” + Chr$(10)) nRetVal = ivprintf(dvm, “MEAS:VOLT:AC? %,2lf” + Chr$(10), list())

‘ Read the results. nRetVal = ivscanf(dvm, “%lf”, res)

Chapter 3 49

Page 50

Programming with SICL

Sending I/O Commands

‘ Display the results MsgBox “Result is “ + Format$(res)

‘ Close the multimeter session Call iclose(dvm)

‘ Tell SICL to clean up for this task Call siclcleanup End

ErrorHandler:

‘ Display the error message MsgBox “*** Error : “ + Error$, MB_ICON_EXCLAMATION ‘ Tell SICL to clean up for this task Call siclcleanup End

End Sub

)RUPDW6WULQJ In the format stri ng for ivprintf, when the special characters Chr$(10)

is used the output buffer to the device is flushed. All characters in the output buffer will be written to the device with an END indicator included with the last byte. This means you can control at what point you want the data written to the device.

If no Chr$(10) is included in the format string for an ivprintf call, the characters converted are stored in the output buffer. It will require another call to ivprintf or a call to iflush to have those characters written to the device. This can be very useful in queuing up data to send to a device. It can also raise I/O performance by doing a few large writes instead of several smaller writes.

The format string for ivscanf ignores most white-space characters. Two white-space characters that it does not ignore are newlines (Chr$(10)) and carriage returns (Chr$(13)). These characters are treated just like normal characters in the format string, which character read from the device.

50 Chapter 3

must

match the next non-white-space

Page 51

Programming with SICL

Sending I/O Commands

)RUPDWWHG,2 %XIIHUV

5HODWHG)RUPDWWHG ,2)XQFWLRQV

The SICL software maintains both a read and write buffer for formatted I/O operations. Occasionally, you may want to control the actions of these buffers.

The write buffer is maintained by the ivprintf function. It queues characters to send to the device so that they are sent in large blocks, thus increasing performance. The write buffer automatically flushes when it sends a newline character from the format string. The write buffer may occasionally be flushed at other non-deterministic times, such as when the buffer fills. When the write buffer flushes, it sends its contents to the device.

The read buffer is maintained by the ivscanf function. It queues the data received from a device until it is needed by the format string. Flushing the read buffer destroys the data in the buffer and guarantees that the next call to ivscanf reads data directly from the device rather than data that was previously queued.

NOTE

This set of functions are related to formatted I/O in Visual Basic:

ifread Obtains raw data directly from the read formatted

I/O buffer. This is the same buffer that ivscanf uses.

ifwrite Writes raw data directly to the write formatted I/O buffer .

This is the same buffer that ivprintf uses.

ivprintf Converts data via a format string and converts the

arguments appropriately.

ivscanf Reads data from a device/interface, converts this data

via a format st ring, and assigns the value to your arguments.

iflush Flushes the format ted I/O read and write buf fers. A flush

of the read buffer means that any data in the buffer is lost. A flush of the write buffer means that any data in

the buffer is written to the sess ion’s target address.

Chapter 3 51

Page 52

Programming with SICL

Sending I/O Commands

Non-Formatted I/O

There are two non-buffered, non-formatted I/O functions called iread and iwrite. These are raw I/O functions and do not intermix with the formatted

I/O functions. If raw I/O must be mixed, use the ifread and ifwrite functions that have the same parameters as iread and iwrite, but read/write raw data from/to the formatted I/O buffers.

iread

DQGiwrite

)XQFWLRQV

([DPSOH1RQ )RUPDWWHG,2&

The iread function reads raw data from the device or interface specified by the

parameter and stores the results in the location where

C example:

iread(

Visual Basic example:

Call iread(

The iwrite function sends the data pointed to by device specified by

C example:

iwrite(

Visual Basic example:

Call iwrite(

This C language program illustrates using non-formatted I/O to communicate with a multimeter over the GPIB interface. The SICL nonformatted I/O functions iwrite and iread are used for communication. A similar example was used to illustrate formatted I/O earlier in this chapter.

/* nonfmt.c

This example program measures AC voltage on a multimeter and prints the results*/

id, buf, bufsize, reason, actualcnt

id, buf, datalen, end, actualcnt

);

)

buf

to the interface or

)

buf

is pointing.

#include <sicl.h> #include <stdio.h>

main() {

INST dvm; char strres[20]; unsigned long actual;

52 Chapter 3

Page 53

Programming with SICL

Sending I/O Commands

#if defined(__BORLANDC__) && !defined(__WIN32__) _InitEasyWin(); /*required for Borland EasyWin

programs*/

#endif

/* Log message and terminate on error */ ionerror (I_ERROR_EXIT);

/* Open the multimeter session */

dvm = iopen (“hpib7,16”); itimeout (dvm, 10000);

/*Initialize dvm*/ iwrite (dvm, “*RST\n”, 5, 1, NULL);

/*Set up multimeter and take measurements*/ iwrite (dvm,”CALC:DBM:REF 50\n”,16,1,NULL); iwrite (dvm,”MEAS:VOLT:AC? 1, 0.001\n”,23,1,NULL);

/* Read measurements */ iread (dvm, strres, 20, NULL, &actual);

/* NULL terminate result string and print the results*/ /* This technique assumes the last byte sent was a line-

feed */

if (actual){

strres[actual - 1] = (char) 0; printf(“Result is %s\n”, strres);

}

/* Close the multimeter session */

iclose(dvm); /* This call is a no-op for WIN32 programs.*/ _siclcleanup();

return 0; }

Chapter 3 53

Page 54

Programming with SICL

Sending I/O Commands

([DPSOH1RQ )RUPDWWHG,2 9LVXDO%DVLF

‘ nonfmt.bas ‘ The following subroutine measures AC voltage on a ‘ multimeter and prints the results. ‘

Sub Main ()

Dim dvm As Integer Dim strres As String * 20 Dim actual As Long

‘ Open the multimeter session

dvm = iopen(“hpib7,16”) Call itimeout(dvm, 10000)

‘ Initialize dvm

Call iwrite(dvm,ByVal “*RST” + Chr$(10), 5, 1, 0&)

‘ Set up multimeter and take measurements

Call iwrite(dvm,ByVal “CALC:DBM:REF 50” +

Chr$(10),16,1, 0&)

Call iwrite(dvm,ByVal “MEAS:VOLT:AC? 1, 0.001” + Chr$(10),23,1, 0&)

‘ Read measurements

Call iread(dvm,ByVal strres, 20, 0&, actual)

‘ Print the results

Print “Result is “ + Left$(strres, actual)

‘ Close the multimeter session

Call iclose(dvm)

‘ Tell SICL to clean up for this task

Call siclcleanup

Exit Sub

End Sub

54 Chapter 3

Page 55

Programming with SICL

Handling Asynchronous Events

Asynchronous events are events that happen outside the control of your application. These events include Service ReQuests (

interrupts. An SRQ is a notification that a device requires service. Both

devices and interfaces can generate SRQs and interrupts.

NOTE

SICL allows installation of SRQ and interrupt handlers in C programs, but does not support them in Visual Basic programs.

By default, asynchronous events are enabled. However, the library will not generate any events until the appropriate handlers are installed in your program.

If an application uses asynchronous events (ionsrq, ionintr), a callback thread is created by the underlying SICL implementation to service the asynchronous event. This thread will not be terminated until some other thread of the application performs an ExitProcess on Windows 95 or Windows 98 or calls iclose on Windows NT or Windows 2000.

SRQs) and

Example declarations:

void SICLCALLBACK my_int_handler(INST id, int reason,

long sec) {

/* your code here */

}

void SICLCALLBACK my_srq_handler(INST id) {

/* your code here */

}

Chapter 3 55

Page 56

Programming with SICL

Handling Asynchronous Events

SRQ Handlers

The ionsrq function installs an SRQ handler. The currently installed SRQ

handler is called any time its’ corresponding device generates an SRQ. If an interface is unable to determine which device on the interface generated the SRQ, all SRQ handlers assigned to that interface will be called.

Therefore, an SRQ handler cannot assume that its’ corresponding device generated an SRQ. The SRQ handler should use the ireadstb function to determine whether its device generated an SRQ. If two or more sessions refer to the same device, the handlers for each of the sessions are called.

Interrupt Handlers

Two distinct steps are required for an interrupt handler to be called. First, the interrupt handler must be installed. Second, the interrupt event or events need to be enabled. The ionintr function installs an interrupt handler. The isetintr function enables the interrupt event or events.

An interrupt handler can be installed with no events enabled. Conversely, interrupt events can be enabled with no interrupt handler installed. Only when both an interrupt handler is installed and interrupt events are enabled will the interrupt handler be called.

Temporarily Disabling/Enabling Asynchronous Events

To temporarily prevent the iintroff function to disable all asynchronous handlers for all sessions in the process.

To re-enable asynchronous SRQ and interrupt handlers previously disabled by iintroff, use the iintron function. This enables all asynchronous handlers for all sessions in the process that had been previously enabled. These functions do not affect the isetintr values or the handlers (ionsrq or ionintr). The default value for both functions is on.

For operating systems that support multiple threads such as Windows 95, Windows 98, Windows 2000, and Windows NT, SRQ and interrupt handlers execute on a separate thread (a thread created and managed by SICL). This means a handler can be executing when the iintroff call is made. If this occurs, the handler will continue to execute until it has completed.

all

SRQ and interrupt handlers from executing, use

56 Chapter 3

Page 57

Programming with SICL

Handling Asynchronous Events

An implication of this is that the SRQ or interrupt handler may need to

synchronize its operation with the application’s primary thread. This could be accomplished via WIN32 synchronization methods or by using SICL locks, where the handler uses a separate session to perform its work.

Calls to iintroff/iintron may be nested, meaning that there must be an equal number of ons and offs. Thus, calling the iintron function may not actually re-enable interrupts.

Occasionally, you may want to suspend a process and wait until an event occurs that causes a handler to execute. The iwaithdlr function causes the process to suspend until an enabled SRQ or interrupt condition occurs and the related handler executes. Once the handler completes its operation, this function returns and processing continues.

For this function to work properly, your application (i.e., use iintroff). The iwaithdlr function behaves as if interrupts are enabled. Interrupts are still disabled after the iwaithdlr function has completed.

Interrupts must be disabled if you use iwaithdlr. Use iintroff to disable interrupts. The reason for disabling interrupts is that there may be a race condition between the isetintr and iwaithdlr. If you only expect one interrupt, it might come before the iwaithdlr. This may or may not have the desired effect. For example:

... ionintr (hpib, act_isr); isetintr (hpib, I_INTR_INTFACT, 1); ... iintroff (); igpibpassctl (hpib, ba); while (!done)

iwaithdlr (0); iintron (); ...

must

turn interrupts off

Chapter 3 57

Page 58

Programming with SICL

Handling Errors

This section gives guidelines to handle errors in SICL, including:

n Logging SICL Error Messages n Using Error Handlers in C n Using Error Handlers in Visual Basic

Logging SICL Error Messages

This section shows how to use the Event Viewer (Windows 2000 and Windows NT) or the Message Viewer (Windows 95 and Windows 98) to log SICL error messages.

n To use the Event Viewer (Windows 2000 and Windows NT),

run the Event V

iewer

n To use the Message Viewer (Windows 95 and Windows 98),

run the Message V

after

iewer

you run the SICL program.

before

you run the SICL program.

8VLQJWKHEvent

Viewer

8VLQJWKHMessage

Viewer

For Windows NT and Windows 2000, SICL logs internal messages as Windows NT/Windows 2000 events. This includes error messages logged by the I_ERROR_EXIT and I_ERROR_NOEXIT error handle rs. Whi le developing your SICL application or tracking down problems, you can view these messages by opening the the Agilent IO Libraries Control (on the taskbar) and clicking Run Event V application messages can be logged to the Event Viewer from SICL. SICL messages are identified by SICL LOG or by the driver name (e.g., ag341i32).

For Windows 95 or Windows 98, you can use the Message Viewer utility. This utility provides a debug window to which SICL logs internal messages during application execution, including those logged by the I_ERROR_EXIT and I_ERROR_NOEXIT error handlers. The Message Viewer utility provides menu selections for saving the logged messages to a file, and to clear the message buffer. To start the Message Viewer utility, open the

Agilent IO Libraries Control (on the taskbar) and click Run Message V

58 Chapter 3

iewer.

iewer. Both system and

Page 59

Programming with SICL

Handling Errors

Using Error Handlers in C

When a SICL function call in a C/C++ program results in an error, it typically returns a special value such as a NULL pointer or a non-zero error code. SICL allows you to install an error handler for all SICL functions within a C/C++ application to provide a convenient mechanism for handling errors.

Installing an error handler allows your application to ignore the return value, and permits the error procedure to detect errors and recover. The error handler is called before the function that generated the error completes. Eerror handlers are per process (

not

per session or per thread).

ionerror

)XQFWLRQ The function ionerror used to install an error handler is defined as:

int ionerror ( void (*

where:

void SICLCALLBACK INST int

The routine occurs. Two special reserved values of

ionerror function

I_ERROR_EXIT This value installs a special error handler which will

I_ERROR_NOEXIT This value installs a special error handler which will

This mechanism has substantial advantages over other I/O libraries, because error handling code is located away from the center of your application.

error

proc

;

proc

);

)();

proc (id, error

is the error handler and is called whenever a SICL error

log a diagnostic message and then terminate the process.

log a diagnostic message and then allow the process to continue execution.

);

proc

may be passed to the

Chapter 3 59

Page 60

Programming with SICL

Handling Errors

([DPSOH,QVWDOOQJ DQ(UURU+DQGOHU &

Typically, error handling code is intermixed with the I/O code in an application. However, with SICL error handling routines no special error handling code is inserted between the I/O calls.

Instead, a single line at the top (calling ionerror) installs an error handler that gets called any time an error occurs. In this example, a standard, system-defined error handler is installed that logs a diagnostic message and then exits.

/* errhand.c

This example demonstrates how a SICL error handler can be installed. */

#include <sicl.h> #include <stdio.h>

main () {

INST dvm; double res;

#if defined(__BORLANDC__) && !defined(__WIN32__)

_InitEasyWin(); /* Required for Borland EasyWin

programs */

#endif

ionerror (I_ERROR_EXIT);

dvm = iopen (“hpib7,16”); itimeout (dvm, 10000); iprintf (dvm, “%s\n”, “MEAS:VOLT:DC?”); iscanf (dvm, “%lf”, &res); printf (“Result is %lf\n”, res); iclose (dvm);

/* This call is a no-op for WIN32 programs.*/ _siclcleanup();

return 0;

}

60 Chapter 3

Page 61

Programming with SICL

Handling Errors

([DPSOH:ULWLQJDQ (UURU+DQGOHU&

This is an example of writing and implementing your own error handler.

NOTE

If an error occurs in iopen, the valid.

/* errhand2.c

This program shows how you can install your own error handler*/

#include <sicl.h> #include <stdio.h> #include <stdlib.h>

void SICLCALLBACK err_handler (INST id, int error) {

fprintf (stderr, “Error: %s\n”, igeterrstr (error)); exit (1);

} main () {

INST dvm; double res;

#if defined(__BORLANDC__) && !defined(__WIN32__) _InitEasyWin(); /* Required for Borland EasyWin

programs */

#endif

passed to the error handler may not be

ionerror (err_handler); dvm = iopen (“hpib7,16”); itimeout (dvm, 10000); iprintf (dvm, “%s\n”, “MEAS:VOLT:DC?”); iscanf (dvm, “%lf”, &res); printf (“Result is %lf\n”, res); iclose (dvm);

/* This call is a no-op for WIN32 programs*/ _siclcleanup();

return 0; }

Chapter 3 61

Page 62

Programming with SICL

Handling Errors

Using Error Handlers in Visual Basic

Typically in an application, error handling code is intermixed with the I/O

code. However, by using Visual Basic’s error handling capabilities, no special error handling code need be inserted between the I/O calls. Instead, a single line at the top (On Error GoTo) installs an error handler in the subroutine that gets called any time a SICL or Visual Basic error occurs.

When a SICL call results in an error, the error is communicated to Visual Basic by setting Visual Basic’s Err variable to the SICL error code and Error$ is set to a human-readable string that corresponds to Err. This allows SICL to be integrated with Visual Basic’s built-in error handling capabilities. SICL programs written in Visual Basic can set up error handlers with the Visual Basic On Error statement.

The SICL ionerror function for C programs is not used with Visual Basic. Similarly, the I_ERROR_EXIT and I_ERROR_NOEXIT default handlers used in C programs are not defined for Visual Basic.

When an error occurs within a Visual Basic program, the default behavior is to display a dialog box indicating the error and then halt the program. If you want your program to intercept errors and keep executing, you will need to install an error handler with the On Error statement. For example:

On Error GoTo MyErrorHandler

This will cause your program to jump to code at the label MyErrorHandler when an error occurs. Note that the error handling code must exist within the subroutine or function where the error handler was declared.

If you do not want to call an error handler or have your application terminate when an error occurs, you can use the On Error statement to tell Visual Basic to ignore errors. For example:

On Error Resume Next

This tells Visual Basic to proceed to the statement following the statement in which an error occurs. In this case, you could call the Visual Basic Err function in subsequent lines to find out which error occurred.

Visual Basic error handlers are only active within the scope of the subroutine or function in which they are declared. Each Visual Basic subroutine or function that wants an error handler must declare its own error handler. This is different than the way SICL error handlers installed with ionerror work in C programs. An error handler installed with ionerror remains active within the scope of the whole C program.

62 Chapter 3

Page 63

Programming with SICL

Handling Errors

Example: (UURU

+DQGOHUV9LVXDO %DVLF

In this Visual Basic example, the error handler displays the error message in a dialog box and then terminates the program. When an error occurs, the Visual Basic Err variable is set to the error code and the Error$ variable is set to the error message string for the error that occurred.

‘ errhand.bas ‘ Sub Main()

Dim dvm As Integer Dim res As Double

On Error GoTo ErrorHandler

dvm = iopen(“hpib7,16”) Call itimeout(dvm, 10000) argcount = ivprintf(dvm, “MEAS:VOLT:DC?” + Chr$(10)) argcount = ivscanf(dvm, “%lf”, res) MsgBox “Result is “ + Format(res) iclose (dvm)

‘ Tell SICL to clean up for this task Call siclcleanup End

ErrorHandler:

‘ Display the error message

MsgBox “*** Error : “ + Error$, MB_ICON_EXCLAMATION ‘ Tell SICL to clean up for this task Call siclcleanup End

End Sub

Chapter 3 63

Page 64

Programming with SICL

Using Locks

Because SICL allows multiple sessions on the same device or interface, the action of opening does not mean you have exclusive use. In some cases this is not an issue, but should be a consideration if you are concerned with program portability.

What are Locks?

The SICL ilock function is used to lock an interface or device. The SICL iunlock function is used to unlock an interface or device.

Locks are performed on a per-session (device, interface, or commander) basis. Also, locks can be nested. The device or interface only becomes unlocked when the same number of unlocks are done as the number of locks. Doing an unlock without a lock returns the error I_ERR_NOLOCK.

What does it mean to lock? Locking an interface (from an interface session) restricts other device and interface sessions from accessing this interface. Locking a device restricts other device sessions from accessing this device; however, other interface sessions may continue to access the interface for this device. Locking a commander (from a commander session) restricts other commander sessions from accessing this commander.

CAUTION

It is possible for an interface session to access a device locked from a device session. In such a case, data may be lost from the device session that was underway. For example,

Environment (VEE)

I/O operations from VEE applications can supercede any device session that has a lock on a particular device.

Not all SICL routines are affected by locks. Some routines that set or return session parameters never touch the interface hardware and therefore work without locks. For information on using locks in multi-threaded SICL applications over LAN, see

64 Chapter 3

applications use SICL interface sessions. Therefore,

Chapter 8 - Using SICL with LAN

Agilent Visual Engineering

Page 65

Programming with SICL

Using Locks

Lock Actions

If a session tries to perform any SICL function that obeys locks on an interface or device currently locked by another session, the default action is to suspend the call until the lock is released or, if a timeout is set, until the call times out.

This action can be changed with the isetlockwait function (see

11 - SICL Language Reference

function is called with the changed. Rather than causing SICL functions to suspend, an error will be returned immediately.

To return to the default action, to suspend and wait for an unlock, call the isetlockwait function with the

for a description). If the isetlockwait

flag

parameter set to 0 (zero), the default action is

flag

set to any non-zero value.

Chapter

Locking in a Multi-User Environment

In a multi-user/multi-process environment where devices are being shared, it is a good idea to use locking to ensure exclusive use of a particular device

or set of devices. However, as explained in “Using Locks”, an interface session can access a device locked from a device session.

In general, it is not good programming practice to lock a device at the beginning of an application and unlock it at the end. This can result in deadlocks or long waits by others who want to use the resource.

The recommended procedure to use locking is per transaction. Per transaction means that you lock before you setup the device, then unlock after all desired data have been acquired. When sharing a device, you cannot assume the state of the device, so the beginning of each transaction should have any setup needed to configure the device or devices to be used.

Chapter 3 65

Page 66

Programming with SICL

Using Locks

Example: Locking (C Program)

/* locking.c

This example shows how device locking can be used to gain exclusive access to a device*/

#include <sicl.h> #include <stdio.h>

main() {

INST dvm;

char strres[20]; unsigned long actual;

#if defined(__BORLANDC__) && !defined(__WIN32__) _InitEasyWin(); /* required for Borland EasyWin

programs */

#endif

/* Log message and terminate on error */ ionerror (I_ERROR_EXIT);

/* Open the multimeter session */

dvm = iopen (“hpib7,16”); itimeout (dvm, 10000);

/* Lock the multimeter device to prevent access

from other applications*/

ilock(dvm);

/* Take a measurement */ iwrite (dvm, “MEAS:VOLT:DC?\n”, 14, 1, NULL);

/* Read the results */ iread (dvm, strres, 20, NULL, &actual);

/* Release the multimeter device for use by others */ iunlock(dvm); /* NULL terminate result string and print results */ /* This technique assumes the last byte sent was a

line-feed */

66 Chapter 3

Page 67

Programming with SICL

if (actual) {

strres[actual - 1] = (char) 0;

printf(“Result is %s\n”, strres);

}

/* Close the multimeter session */

iclose(dvm);

/* This call is a no-op for WIN32 programs.*/ _siclcleanup();

return 0;

}

Example: Locking (Visual Basic)

‘ locking.bas Sub Main ()

Dim dvm As Integer Dim strres As String * 20 Dim actual As Long

Using Locks

‘ Install an error handler

On Error GoTo ErrorHandler

‘ Open the multimeter session

dvm = iopen(“hpib7,16”) Call itimeout(dvm, 10000)

‘ Lock the multimeter device to prevent access from other applications

Call ilock(dvm)

‘ Take a measurement

Call iwrite(dvm,ByVal “MEAS:VOLT:DC?” + Chr$(10), 14,

1, 0&)

‘ Read the results

Call iread(dvm,ByVal strres, 20, 0&, actual)

‘ Release the multimeter device for use by others

Call iunlock(dvm)

Chapter 3 67

Page 68

Programming with SICL

Using Locks

‘ Display the results

MsgBox “Result is “ + Left$(strres, actual)

‘ Close the multimeter session

Call iclose(dvm)

‘ Tell SICL to clean up for this task

Call siclcleanup

End

ErrorHandler:

‘ Display the error message.

MsgBox “*** Error : “ + Error$

‘ Tell SICL to clean up for this task

Call siclcleanup

End

End Sub

68 Chapter 3

Page 69

Using SICL with GPIB

Page 70

Using SICL with GPIB

This chapter shows how to open a communications session and communicate with GPIB devices, interfaces, or controllers. The example programs in this chapter are also provided in the C\SAMPLES\MISC (for C/C++) or VB\SAMPLES\MISC (for Visu al Basic) o f the IO Libraries base directory. This chapter includes:

n Introduction n Using GPIB Device Sessions n Using GPIB Interface Sessions n Using GPIB Commander Sessions n Writing GPIB Interrupt Handlers

70 Chapter 4

Page 71

Using SICL with GPIB

Introduction

This section provides an introduction to using SICL with the GPIB interface, including:

n Selecting a GPIB Communications Session n SICL GPIB Functions

Selecting a GPIB Communications Session

When you have determined the GPIB system is set up and operating correctly, you can start programming with the SICL functions. First, you must determine what type of communications session to use.

The three types of communications sessions are

commander. To use a device session, see “Using GPIB Device Sessions”.

To use an interface session, see “Using GPIB Interface Sessions”. To use a commander session, see “Using GPIB Commander Sessions”.

device, interface, and

SICL GPIB Functions

Function Name Action

igpibatnctl Sets or clears the ATN line igpibbusaddr Changes bus address igpibbusstatus Returns requested bus data igpibgett1delay Returns the current T1 setting for the interface igpibllo Sets bus in Local Lockout Mode igpibpassctl Passes active control to specified address igpibppoll Performs a parallel poll on the bus igpibppollconfig Configures device for PPOLL response igpibppollresp Sets PPOLL state igpibrenctl Sets or clears the REN line igpibsendcmd Sends data with ATN line set igpibsett1delay Sets the T1 delay value for this interface

Chapter 4 71

Page 72

Using SICL with GPIB

Using GPIB Device Sessions

A device session allows you direct access to a device without knowing the type of interface to which it is connected. The specifics of the interface are hidden from the user.

Addressing GPIB Devices

To create a device session, specify the interface logical unit or symbolic name and a particular device logical address in the iopen function. The interface logical unit and symbolic name are set by running the IO Config utility. To open IO Config, open the Agilent IO Libraries Control (on the taskbar) and click Run I See the

Windows

Agilent IO Libraries Installation and Configuration Guide for

for information on the IO Config utility.

addr

parameter of the

O Config.

3ULPDU\DQG 6HFRQGDU\ $GGUHVVHV

9;,0DLQIUDPH &RQQHFWLRQV

SICL supports both primary and seco ndar y ad dres si ng on GP IB inte rf aces . The primary address must be between 0 and 30 and the secondary address must be between 0 and 30. The primary and secondary addresses correspond to the GPIB primary and secondary addresses. Some example GPIB addresses for device sessions are:

GPIB,7 A device address corresponding to the device at

primary address 7

hpib,3,2 A device address corresponding to the device at

primary address 3, secondary address 2

For connections to a VXI mainframe via an E1406 Command Module (or equivalent), the primary address passed to iopen corresponds to the address of the Command Module and the secondary address must be specified to select a specific instrument in the card cage.

Secondary addresses of 0, 1, 2, ... 30 correspond to VXI instruments at

logical addresses of 0, 8, 16, ... 240, respectively. See “GPIB Device Session Examples” in this chapter for an example program to communicate with a VXI mainframe via the GPIB interface.

72 Chapter 4

Page 73

Using SICL with GPIB

Using GPIB Device Sessions

Examples to open a device session with an GPIB device at bus address 16 follow.

C example:

INST dmm;

dmm = iopen (“hpib,16”);

Visual Basic example:

Dim dmm As Integer dmm = iopen (“hpib,16”)

SICL Function Support for GPIB Device Session

This section shows how some SICL functions are implemented for GPIB device sessions. The data transfer functions work only when the GPIB interface is the Active Controller. Passing control to another GPIB device causes this device to lose active control.

iwrite Causes all devices to untalk and unlisten. It sends this

controller’s talk address followed by unlisten and then the listen address of the correspo nding dev ice sess ion. Then, it sends th e data over the bus.

iread Causes all devices to untalk and unlisten. It sends an unlisten,

then sends this controller’s listen address followed by the talk address of the corresponding device session. Then, it reads the data from the bus.

ireadstb Performs a GPIB serial poll (SPOLL). itrigger Performs an addressed GPIB group execute trigger (GET). iclear Performs a GPIB selected device clear (SDC) on the device

corresponding to this session.

Chapter 4 73

Page 74

Using SICL with GPIB

Using GPIB Device Sessions

*3,%'HYLFH 6HVVLRQVDQG 6HUYLFH5HTXHVWV

There are no device-specific interrupts for the GPIB interface, but GPIB device sessions do support Service Requests (SRQs). On the GPIB interface, when one device issues an SRQ, the library informs device sessions that have SRQ handlers installed (see ionsrq in

11 - SICL Language Reference

This is an artifact of how GPIB handles the SRQ line. The interface cannot distinguish which device requested service. Therefore, the library acts as if

all devices require service. The SRQ handler can retrieve the device’s

all

GPIB

Chapter

status by te by using the ireadstb function. For more information, see

“Writing GPIB Interrupt Handlers” in this chapter.

Example: GPIB Device Session (C)

This example opens two GPIB communications sessions with VXI devices (via a VXI Command Module). Then, a scan list is sent to a switch and measurements are taken by the multimeter every time a switch is closed.

/* hpibdev.c

This example program sends a scan list to a switch and, while looping, closes channels and takes measurements. */

#include <sicl.h> #include <stdio.h>

main() {

INST dvm; INST sw;

double res; int i;

#if defined(__BORLANDC__) && !defined(__WIN32__) _InitEasyWin(); /* Required for Borland EasyWin

programs */

#endif

/* Log message and terminate on error */ ionerror (I_ERROR_EXIT);

/* Open the multimeter and switch sessions*/

dvm = iopen (“hpib7,9,3”);

74 Chapter 4

Page 75

Using GPIB Device Sessions

sw = iopen (“hpib7,9,14”); itimeout (dvm, 10000); itimeout (sw, 10000);

/*Set up trigger*/ iprintf (sw, “TRIG:SOUR BUS\n”);

/*Set up scan list*/ iprintf (sw,”SCAN (@100:103)\n”); iprintf (sw,”INIT\n”);

for (i=1;i<=4;i++) {

/* Take a measurement */

iprintf (dvm,”MEAS:VOLT:DC?\n”);

/* Read the results */

iscanf (dvm,”%lf”,&res);

/* Print the results */

printf (“Result is %lf\n”,res);

Using SICL with GPIB

/* Trigger to close channel */

iprintf (sw, “TRIG\n”); } /* Close the multimeter and switch sessions */ iclose (dvm); iclose (sw);

/* This call is a no-op for WIN32 programs*/ _siclcleanup();

return 0; }

Chapter 4 75

Page 76

Using SICL with GPIB

Using GPIB Device Sessions

Example: GPIB Device Session (Visual Basic)

‘hpibdev.bas ‘ This example program sends a scan list to a switch and ‘ while looping closes channels and takes measurements.

Sub Main ()

Dim dvm As Integer Dim sw As Integer Dim res As Double Dim i As Integer Dim argcount As Integer

‘ Open the multimeter and switch sessions dvm = iopen(“hpib7,9,3”) sw = iopen(“hpib7,9,14”) Call itimeout(dvm, 10000) Call itimeout(sw, 10000)

‘ Set up trigger argcount = ivprintf(sw, “TRIG:SOUR BUS” + Chr$(10))

‘ Set up scan list argcount = ivprintf(sw, “SCAN (@100:103)” + Chr$(10))

argcount = ivprintf(sw, “INIT” + Chr$(10))

‘ Display form1 and print voltage measurements form1.Show

For i = 1 To 4

‘ Take a measurement argcount = ivprintf(dvm, “MEAS:VOLT:DC?” + Chr$(10))

‘ Read the results argcount = ivscanf(dvm, “%lf”, res)

‘ Print the results form1.Print “Result is “ + Format(res)

76 Chapter 4

Page 77

Using GPIB Device Sessions

‘ Trigger to close channel argcount = ivprintf(sw, “TRIG” + Chr$(10))

Next i

‘ Close the voltmeter session Call iclose(dvm)

‘ Close the switch session Call iclose(sw)

‘ Tell SICL to clean up for this task Call siclcleanup

End Sub

Using SICL with GPIB

Chapter 4 77

Page 78

Using SICL with GPIB

Using GPIB Interface Sessions

Interface sessions allow direct, low-level control of the specified interface, but

the programmer must provide all bus maintenance settings for the interface and must know the technical details about the interface. Also, when using interface sessions, interface-specific functions must be used. Thus, the program cannot be used on other interfaces and becomes less portable.

Addressing GPIB Interfaces

To create an interface session on your GPIB system, specify the particular interface logical unit or symbolic name in the function. The interface logical unit and symbolic name are set by running the IO Config utility. To open IO Config, open the Agilent IO Libraries Control (on the taskbar) and click Run I the

Agilent IO Libraries Installation and Configuration Guide for Windows

information on the IO Config utility. Example interface addresse s foll ow.

addr

parameter of the iopen

O Config. See

for

GPIB An interface symbolic name. hpib An interface symbolic name. gpib2 An interface symbolic name. IEEE488 An interface symbolic name. 7 An interface logical unit.

These examples open an interface session with the GPIB interface.

C example:

INST hpib;

hpib = iopen (“hpib”);

Visual Basic example:

Dim hpib As Integer hpib = iopen (“hpib”)

78 Chapter 4

Page 79

Using SICL with GPIB

Using GPIB Interface Sessions

SICL Function Support for GPIB Interface Sessions

This section describes how some SICL functions are implemented for GPIB interface sessions.

iwrite Sends the specified bytes directly to the interface without

performing any bus addressing. The iwrite function always clears the ATN line before sending any bytes, thus ensuring that the GPIB interface sends the bytes as data, not as command bytes.

iread Reads the data directly from the interface without performing

any bus addressing.

itrigger Performs a broadcast GPIB group execute trigger (GET)

without additional addressing. Use this function with igpibsendcmd to send a UNL followed by the appropriate device addresses. This will allow the itrigger function to be used to trigger multiple GPIB devices simultaneously.

*3,%,QWHUIDFH 6HVVLRQV,QWHUUXSWV

*3,%,QWHUIDFH 6HVVLRQVDQG 6HUYLFH5HTXHVWV

Passing the I_TRIG_STD value to the ixtrig function also causes a broadcast GPIB group execute trigger (GET). There are no other valid values for the ixtrig function.

iclear Performs a GPIB interface clear (pulses IFC), which resets the

interface.

There are specific interface session interrupts that can be used. See isetintr in

the interface session interrupts for GPIB. Also, see “Writing GPIB Interrupt Handlers” in this chapter for more information.

GPIB interface sessions support Service Requests (SRQs). On the GPIB interface, when one device issues an SRQ, the library will inform interface sessions that have SRQ handlers installed (see ionsrq in

Chapter 11 - SICL Language Reference

“Writing GPIB Interrupt Handlers” in this chapter.

Chapter 11 - SICL Language Reference

). For more information, see

for information on

all

GPIB

Chapter 4 79

Page 80

Using SICL with GPIB

Using GPIB Interface Sessions

Example: GPIB Interface Session (C)

/* hpibstat.c

This example retrieves and displays GPIB bus status information. */

#include <stdio.h> #include <sicl.h>

main() {

INST id; /* session id */ int rem; /* remote enable */ int srq; /* service request */ int ndac; /* not data accepted */ int sysctlr; /* system controller */ int actctlr; /* active controller */ int talker; /* talker */ int listener; /* listener */ int addr; /* bus address */

#if defined(__BORLANDC__) && !defined(__WIN32__) _InitEasyWin(); / * Req ui re d f or B orland E as yW in pr ogra ms */ #endif

/* exit process if SICL error detected */ ionerror(I_ERROR_EXIT);

/* open GPIB interface session */

id = iopen(“hpib”);

itimeout (id, 10000);

/* retrieve GPIB bus status */ igpibbusstatus(id, I_GPIB_BUS_REM, &rem); igpibbusstatus(id, I_GPIB_BUS_SRQ, &srq); igpibbusstatus(id, I_GPIB_BUS_NDAC, &ndac); igpibbusstatus(id, I_GPIB_BUS_SYSCTLR, &sysctlr); igpibbusstatus(id, I_GPIB_BUS_ACTCTLR, &actctlr); igpibbusstatus(id, I_GPIB_BUS_TALKER, &talker); igpibbusstatus(id, I_GPIB_BUS_LISTENER, &listener); igpibbusstatus(id, I_GPIB_BUS_ADDR, &addr);

80 Chapter 4

Page 81

Using SICL with GPIB

Using GPIB Interface Sessions

/* display bus status */

printf(“%-5s%-5s%-5s%-5s%-5s%-5s%-5s%-5s\n”,

“REM”, “SRQ”,“NDC”, “SYS”, “ACT”, “TLK”, “LTN”,

“ADDR”);printf(“%2d%5d%5d%5d%5d%5d%5d%6d\n”,

rem, srq, ndac, sysctlr, actctlr, talker, listener,

addr);

/* This call is no-op for WIN32 programs.*/

_siclcleanup();

return 0;

}

Example: GPIB Interface Session (Visual Basic)

‘hpibstat.bas ‘ The following example retrieves and displays ‘ GPIB bus status information. Sub main ()

Dim id As Integer ‘ session id

Dim remen As Integer ‘ remote enable

Dim srq As Integer ‘ service request

Dim ndac As Integer ‘ not data accepted

Dim sysctlr As Integer‘ system controller

Dim actctlr As Integer‘ active controller

Dim talker As Integer ‘ talker

Dim listener As Integer‘ listener

Dim addr As Integer ‘ bus address

Dim header As String ‘ report header

Dim values As String ‘ report output

‘ Open GPIB interface session

id = iopen(“hpib7”)

Call itimeout(id, 10000)

‘ Retrieve GPIB bus status

Call igpibbusstatus(id, I_GPIB_BUS_REM, remen)

Call igpibbusstatus(id, I_GPIB_BUS_SRQ, srq)

Call igpibbusstatus(id, I_GPIB_BUS_NDAC, ndac)

Call igpibbusstatus(id, I_GPIB_BUS_SYSCTLR, sysctlr)

Call igpibbusstatus(id, I_GPIB_BUS_ACTCTLR, actctlr)

Call igpibbusstatus(id, I_GPIB_BUS_TALKER, talker)

Call igpibbusstatus(id, I_GPIB_BUS_LISTENER, listener)

Chapter 4 81

Page 82

Using SICL with GPIB

Using GPIB Interface Sessions

Call igpibbusstatus(id, I_GPIB_BUS_ADDR, addr)

‘ Display form1 and print results

form1.Show form1.Print “REM”; Tab(7); “SRQ”; Tab(14); “NDC”; Tab(21);“SYS”; Tab(28); “ACT”; Tab(35); “TLK”; Tab(42); “LTN”; Tab(49);“ADDR” form1.Print remen; Tab(7); srq; Tab(14); ndac; Tab(21);sysctlr; Tab(28); actctlr; Tab(35); talker; Tab(42); listener; Tab(49); addr

‘ Tell SICL to clean up for this task Call siclcleanup

End Sub

82 Chapter 4

Page 83

Using SICL with GPIB

Using GPIB Commander Sessions

Commander sessions are intended for use on GPIB interfaces that are not the

active controller. In this mode, a computer that is not the controller is acting like a device on the GPIB bus. In a commander session, the data transfer routines only work when the GPIB interface is not active controller.

Addressing GPIB Commanders

To create a commander session on your GPIB interface, specify the particular interface logical unit or symbolic name in the followed by a comma and the string cmdr in the iopen function.

The interface logical unit and symbolic name are set by running the IO

Config utility. To open IO Config, open the Agilent IO Libraries Control (on the taskbar) and click Run I

O Config. See the

Libraries Installation and Configuration Guide for Windows

the IO Config utility. Example GPIB addresses for commander sessions follow.

addr

parameter

Agilent IO

for information on

GPIB,cmdr A commander session with the GPIB interface. hpib2,cmdr A commander session with the hpib2 interface. 7,cmdr A commander session with the interface at logical unit 7.

These examples open a commander session with the GPIB interface.

C example:

INST hpib;

hpib = iopen (“hpib,cmdr”);

Visual Basic example:

Dim hpib As Integer hpib = iopen (“hpib,cmdr”)

Chapter 4 83

Page 84

Using SICL with GPIB

Using GPIB Commander Sessions

SICL Function Support for GPIB Commander Sessions

This section describes how some SICL functions are implemented for GPIB commander sessio ns .

iwrite If the interface has been addressed to talk, the data is written

directly to the interface. If the interface has not been addressed to talk, it will wait to be addressed to talk before writing the data.

iread If the interface has been addressed to listen, the data is read

directly from the interface. If the interface has not been addressed to listen, it will wait to be addressed to listen before reading the data.

isetstb Sets the status value that will be returned on a ireadstb call

(that is, when this device is SPOLLed). Bit 6 of the status byte has a special meaning. If bit 6 is set, the SRQ line will be set. If bit 6 is clear, the SRQ line will be cleared.

*3,%&RPPDQGHU 6HVVLRQV,QWHUUXSWV

There are specific commander session interrupts that can be used. See isetintr in

commander session interrupts. Also see “Writing GPIB Interrupt Handlers” for more information.

Chapter 11 - SICL Language Reference

for information on

84 Chapter 4

Page 85

Using SICL with GPIB

Writing GPIB Interrupt Handlers

This section provides some additional information for writing interrupt handlers for GPIB applications in SICL.

Multiple I_INTR_GPIB_TLAC Interrupts

This interrupt occurs whenever a device has been addressed to talk or untalk, or a device has been addressed to listen or unlisten. Due to hardware limitations, your SICL interrupt handler may be called twice in response to any of these events.

Your GPIB application should be written to handle this situation gracefully. This can be done by keeping track of the current talk/listen state of the interface card and ignoring the interrupt if the state does not change. For more information, see the function in

Chapter 11 - SICL Language Reference

secval

parameter definition of the isetintr

Handling SRQs from Multiple GPIB Instruments

GPIB is a multiple-device bus and SICL allows multiple device sessions open at the same time. On the GPIB interface, when one device issues a Service Request (SRQ), the library will inform have SRQ handlers installed (see ionsrq in

Reference

This is an artifact of how GPIB handles the SRQ line. The underlying GPIB hardware does not support session-specific interrupts like VXI does. Therefore, your application must reflect the nature of the GPIB hardware if you expect to reliably service SRQs from multiple devices on the same GPIB interface.

It is vital that you never exit an SRQ handler without first clearing the SRQ line. If the multiple devices are all controlled by the same process, the easiest technique is to service all devices from one handler. The pseudocode for this follows. This algorithm loops through all the device sessions and does not exit until the SRQ line is released (not asserted).

while (srq_asserted) {

serial_poll (device1)

if (needs_service) service_device1

serial_poll (device2)

if (needs_service) service_device2

all

GPIB device sessions that

Chapter 11 - SICL Language

Chapter 4 85

Page 86

Using SICL with GPIB

Writing GPIB Interrupt Handlers

... check_SRQ_line

}

([DPSOH6HUYLFLQJ 5HTXHVWV&

This example shows a SICL program segment that implements this algorithm. Checking the state of the SRQ line requires an interface session. Only one device session need s to execute ionsrq because that handler is invoked regardless of which instrument asserted the SRQ line. Assuming IEEE-488 compliance, an ireadstb is all that is needed to clear the

device’s SRQ. Since the program cannot leave the handler until all devices have released

SRQ, it is recommended that the handler do as little as possible for each device. The previous example assumed that only one iscanf was needed to service the SRQ. If lengthy operations are needed, a better technique is to perform the ireadstb and set a flag in the handler. Then, the main program can test the flags for each device and perform the more lengthy service.

Even if the different device sessions are in different processes, it is still important to stay in the SRQ handler until the SRQ line is released. However, it is not likely that a process which only knows about Device A can do anything to make Device B release the SRQ line.

In such a configuration, a single unserviced instrument can effectively disable SRQs for all processes attempting to use that interface. Again, this is a hardware characteristic of GPIB. The only way to ensure true independence of multiple GPIB processes is to use multiple GPIB interfaces.

/* Must be global */ INST id1, id2, bus;

void handler (dummy) INST dummy; {

int srq_asserted = 1; unsigned char statusbyte;

/* Service all sessions in turn until no one is

requesting service */

while (srq_asserted) {

ireadstb(id1, &statusbyte); if (statusbyte & SRQ_BIT)

{

86 Chapter 4

Page 87

Using SICL with GPIB

Writing GPIB Interrupt Handlers

/* Actual service actions depend upon application */

iscanf(id1, “%f”, &data1); } ireadstb(id2, &statusbyte); if (statusbyte & SRQ_BIT){ iscanf(id2, “%f”, &data2); } igpibbusstatus(bus, I_GPIB_BUS_SRQ, &srq_asserted); }

}

main() {

. . /* Device sessions for instruments */ id1 = iopen(“hpib, 17”); id2 = iopen(“hpib, 18”);

/* Interface session for SRQ test */ bus = iopen(“hpib”);

/* Only one handler needs to be installed */ ionsrq(id1, handler); . .

Chapter 4 87

Page 88

Notes:

Using SICL with GPIB

Writing GPIB Interrupt Handlers

88 Chapter 4

Page 89

Using SICL with GPIO

Page 90

Using SICL with GPIO

This chapter shows how to open an interface communications session and communicate with an instrument over a GPIO connection. The example programs in this chapter are also provided in the C\SAMPLES\MISC (for C/C++) and VB\SAMPLES\MISC (for Visual Basic) subdirectories. This chapter includes:

n Introduction n Using GPIO Interface Sessions

90 Chapter 5

Page 91

Using SICL with GPIO

Introduction

This section provides an introduction to using SICL with the GPIO interface, including:

n Selecting a GPIO Communications Session n SICL GPIO Functions

Selecting a GPIO Communications Session

GPIO is a parallel interface that is flexible and allows a variety of custom connections. Although GPIO typically requires more time to configure than GP-IB, the speed and versatility of GPIO make it the perfect choice for many tasks.

NOTE

GPIO is Windows 2000, and Windows NT. GPIO is via LAN.

Once you have configured your system for GPIO communications, you can start programming with the SICL functions. If you have programmed GPIO before, you will probably want to open the interface and start sending commands.

With GPIB, there can be multiple devices on a single interface. These interfaces support a connection called a one device is connected to the interface. Therefore, communication with GPIO devices m ust be using an

only

supported with SICL on Windows 95, Windows 98,

not

supported with SICL

device session. With GPIO, only

interface session.

SICL GPIO Functions

Function Name Action

igpioctrl Sets the following characteristics of the GPIO

interface:

Chapter 5 91

Page 92

Using SICL with GPIO

Introduction

Request Characteristic Settings

I_GPIO_AUTO_HDSK Auto-Handshake mode 1 or 0 I_GPIO_AUX Auxiliary Control lines 16-bit mask I_GPIO_CHK_PSTS Check PSTS before

read/write

I_GPIO_CTRL Control lines I_GPIO_CTRL_CTL0

I_GPIO_DATA Data Output lines 8-bit or 16-bit mask I_GPIO_PCTL_DELAY PCTL delay time 0-7 I_GPIO_POLARITY Logical polarity 0-31 I_GPIO_READ_CLK Data input latching See

I_GPIO_READ_EOI END termination pattern I_GPIO_EOI_NONE or

I_GPIO_SET_PCTL Start PCTL handshake 1

igpiogetwidth

igpiosetwidth

Returns the current width (in bits) of the GPIO data ports.

Sets the width (in bits) of the GPIO data ports. Either 8 or 16.

1 or 0

I_GPIO_CTRL_CTL1

Chapter 1 1 - SICL

Language Reference

8-bit or 16-bit mask

92 Chapter 5

Page 93

Using SICL with GPIO

Introduction

igpiostat Gets the following information about the GPIO

interface

Request Characteristic Value

I_GPIO_CTRL Control Lines I_GPIO_CTRL_CTL0

I_GPIO_CTRL_CTL1

I_GPIO_DATA Data In lines 16-bit mask I_GPIO_INFO GPIO information I_GPIO_AUTO_HDSK

I_GPIO_CHK_PSTS I_GPIO_EIR I_GPIO_ENH_MODE I_GPIO_PSTS I_GPIO_READY

I_GPIO_READ_EOI E ND termination pattern I_GPIO_EOI_NONE

or 8-bit or 16-bit mask

I_GPIO_STAT Status lines I_GPIO_STAT_STI0

I_GPIO_STAT_STI1

Chapter 5 93

Page 94

Using SICL with GPIO

Using GPIO Interface Sessions

GPIO Interface sessions are used for GPIO data transfer, interrupt, status,

and control operations. When communicating with a GPIO interface session, the programmer must specify the interface name.

Addressing GPIO Interfaces

To create an interface session on GPIO, specify the interface logical unit or symbolic name in the logical unit and symbolic name are defined by running the IO Config utility. To open IO Config, click the Agilent IO Libraries Control (on the taskbar) and click Run I

Installation and Configuration Guide for Windows

IO Config. Some example addresses for GPIO interface sessions are:

gpio An interface symbolic name

addr

parameter of the iopen function. The interface

O Config. See the

Agilent IO Libraries

for information on

12 An interface logical unit

This example opens an interface session with the GPIO interface.

INST intf;

intf = iopen (“gpio”);

SICL Function Support with GPIO Interface Sessions

This section describes how some SICL functions are implemented for GPIO interface sessions.

94 Chapter 5

Page 95

*3,2,QWHUIDFH 6HVVLRQV6,&/ )XQFWLRQV

iwrite, iread

Using SICL with GPIO

Using GPIO Interface Sessions

The

size

parameters for non-formatted I/O functions are always byte counts, regardless of the current data width of the interface.

iprintf, iscanf

itermchr For 16-bit data widths, only low (least-significant) byte is use d. ixtrig Provides a method of triggering using either the CTL0 or CTL1

itrigger Same as ixtrig (I_TRIG_STD). Pulses the CTL0 control line.

iclear

ionsrq Installs a service request handler for this session. The concept

All formatted I/O functions work with GPIO. When formatted I/O is used with 16-bit data widths, the formatting buffers reassemble the data as a stream of bytes. On Windows, these bytes are ordered: high-low-high-low... Because of this

“unpacking” operation, 16-b it data widths may not be appropriate for formatted I/O operations. For iscanf termination, an END value must be specified using igpioctrl. See

control lines. This function pulses the specified control line for approximately 1 or 2

I_TRIG_STD Pulse CTL0 line I_TRIG_GPIO_CTL0 P ulse CTL0 line I_TRIG_GPIO_CTL1 Pulse CTL1 line

Pulses the P_RESET line for at least 12 pending writes, discards any data in the receive buffer, and resets any error conditions. Optionally, clears the Data Out port, depending on the configuration specified via IO Config.

of service request (SRQ) originates from GPIB. On a GPIB interface, a device can request service from the controller by asserting a line on the interface bus. On GPIO, the EIR line is assumed to be the service request line.

Chapter 11 - SICL Language Reference

µsec. The following constants ar e defined:

µsec, aborts any

*3,2,QWHUIDFH 6HVVLRQV,QWHUUXSWV

ireadstb Although ireadstb is for device sessions only, since GPIO

has no device sessions, ireadstb is allowed with GPIO interface sessions. The interface status byte has bit 6 set if EIR is asserted. Otherwise, the status byte is 0 (zero). This allows normal SRQ programming techniques in GPIO SRQ handlers.

There are specific interface session interrupts that can be used. See isetintr in

Chapter 11 - SICL Language Reference

for information on the

interface session interrupts for GPIO.

Chapter 5 95

Page 96

Using SICL with GPIO

Using GPIO Interface Sessions

Example: GPIO Interface Session (C)

/* gpiomeas.c This program:

- Creates a GPI O session with ti meout an d erro r checki ng

- Signals the device with a CTL0 pulse

- Reads the device’s response using formatted I/O */

#include <sicl.h>

main() {

INST id; /* interface session id */ float result; /* data from device */

#if defined (__BORLANDC__) && !defined (__WIN32__) _InitEasyWin(); / * r e q u i r e d f o r B o r la n d E a s y W i n p r o g r a m s */ #endif

/* log message and exit program on error */ ionerror(I_ERROR_EXIT);

/* open GPIO interface session, with 3 sec timeout*/ id = iopen(“gpio”); itimeout(id, 3000);

/* setup formatted I/O configuration */ igpiosetwidth(id, 8); igpioctrl(id, I_GPIO_READ_EOI, ‘\n’);

/* monitor the device’s PSTS line */ igpioctrl(id, I_GPIO_CHK_PSTS, 1);

/* signal the device to take a measurement */ itrigger(id);

/* get the data */ iscanf(id, “%f%*t”, &result); printf(“Result = %f\n”, result); /* This call is a no-op for WIN32 applications. */ _siclcleanup();

/* close session */ iclose (id); }

96 Chapter 5

Page 97

Using SICL with GPIO

Using GPIO Interface Sessions

Example: GPIO Interface Session (Visual Basic)

‘ This program: ‘ - Creates a GPIO sessio n with timeout and er ror checking ‘ - Signals the device with a CTL0 pulse ‘ - Reads the device’s response using formatted I/O ‘ Sub cmdMeas_Click ()

Dim id As Integer ‘ device session id Dim retval As Integer ‘ function return value Dim buf As String ‘ buffer for displaying Dim real_data As Double ‘ data from device

‘ Set up an error handler within this subrouti ne that will ‘ be called if a SICL error occurs.

On Error GoTo ErrorHandler

‘ Disable the button used to initiate I/O while I/O is ‘ being performed.

cmdMeas.Enabled = False

‘ Open an interface session using a known symbolic name

id = iopen(“gpio12”)

‘ Set the I/O timeout value for this session to 3 sec

Call itimeout(id, 3000)

‘ Setup formatted I/O configuration

Call igpiosetwidth(id, 8) Call igpioctrl(id, I_GPIO_READ_EOI, 10)

‘ Signal the device to take a measurement

Call itrigger(id)

‘ Get the data

retval = ivscanf(id, “%lf%*t”, real_data)

‘ Display the response as string in a Message Box

buf = Str$(real_data) retval = MsgBox(buf, MB_OK, “GPIO Data”)

‘ Close the device session.

Call iclose(id)

Chapter 5 97

Page 98

Using SICL with GPIO

Using GPIO Interface Sessions

‘ Enable the button used to initiate I/O

cmdMeas.Enabled = True

Exit Sub

ErrorHandler: ‘ Display the error message string in a Message Box

retval = MsgBox(Error$, MB_ICONEXCLAMATION, “SICL Error”)

‘ Close the device session if iopen was successful.

If id <> 0 Then

iclose (id)

End If

‘ Enable the button used to initiate I/O

cmdMeas.Enabled = True Exit Sub

End Sub

‘ The following routine is called when the application’s ‘ Start Up form is unloaded. It calls siclcleanup to ‘ release resources allocated by SICL for this ‘ application. ‘

Sub Form_Unload (Cancel As Integer)

Call siclcleanup ‘ Tell SICL to clean up for this task

End Sub

Example: GPIO Interrupts

/* gpiointr.c

This program:

- Creates a GPIO session with error checking

- Installs an interrupt hand ler and enables EIR i nterrupts

- Waits for EIR; invokes the han dler for each interrupt

#include <sicl.h>

void SICLCALLBACK handler(id, reason, sec) INST id; int reason, sec; {

98 Chapter 5

Page 99

Using SICL with GPIO

Using GPIO Interface Sessions

if (reason == I_INTR_GPIO_EIR) {

printf(“EIR interrupt detected\n”);

/* Proper protocol is for the peripheral device to hold * EIR asserted until the controller “acknowledges” the * interrupt. The method for ack nowledging and/or resp onding * to EIR is very device-dependent. Perhaps a CTLx line is * pulsed, or data is read, etc. The response should be * executed at this point in the program. */ } else

printf(“Unexpected Interrupt; reason=%d\n”, reason);

}

main() {

INST intf; /* interface session id */

#if defined (__BORLANDC__) && !defined (__WIN32__) _InitEasyWin(); /* required for Borland EasyWin programs */ #endif

/* log message and exit program on error */ ionerror(I_ERROR_EXIT);

/* open GPIO interface session */ intf = iopen(“gpio”);

/* suspend interrupts until configured */ iintroff();

/* configure interrupts */ ionintr(intf, handler); isetintr(intf, I_INTR_GPIO_EIR, 1);

/* wait for interrupts */ printf(“Ready for interrupts\n”); while (1) {

iwaithdlr(0); / * optional timeout can be specified here*/

}

Chapter 5 99

Page 100

Using SICL with GPIO

Using GPIO Interface Sessions

/* iwaithdlr pe rforms an automatic iin tron(). If your progra m * does concurr ent processing, instead of waiting you need * to execute i intron() when you are r eady for interrupts. */

/* This simplified ex ample loops forever. Most real applic ations

* would have termi nation conditions that cause the loop to exit. */ iclose(id);

/* This call is a no-op for WIN32 applications. */

_siclcleanup();

}

100 Chapter 5

HP st ard schematic

Specifications and Main Features

Frequently Asked Questions

User Manual

Introduction

What’s in This Guide?

SICL Overview

Introducing VISA and SICL

SICL Description

Getting Started with SICL

Getting Started Using C

C Program Example Code

C Example Code Description

Compiling the C Example Program

Running the C Example Program

Where to Go Next

Getting Started Using Visual Basic

Where to Go Next

Programming with SICL

Building a SICL Application

Including the SICL Declaration File

Libraries for C Applications and DLLs

Compiling and Linking C Applications

Loading and Running Visual Basic Applications

Thread Support for 32-bit Windows Applications

Opening a Communications Session

Steps to Open a Communications Session

Device Sessions

Interface Sessions

Commander Sessions

Sending I/O Commands

Formatted I/O in C Applications

Formatted I/O in Visual Basic Applications

Non-Formatted I/O

Handling Asynchronous Events

SRQ Handlers

Interrupt Handlers

Temporarily Disabling/Enabling Asynchronous Events

Handling Errors

Logging SICL Error Messages

Using Error Handlers in C

Using Error Handlers in Visual Basic

Using Locks

What are Locks?

Lock Actions

Locking in a Multi-User Environment

Example: Locking (C Program)

Example: Locking (Visual Basic)

Using SICL with GPIB

Introduction

Selecting a GPIB Communications Session

SICL GPIB Functions

Using GPIB Device Sessions

Addressing GPIB Devices

SICL Function Support for GPIB Device Session

Example: GPIB Device Session (C)

Example: GPIB Device Session (Visual Basic)

Using GPIB Interface Sessions

Addressing GPIB Interfaces

SICL Function Support for GPIB Interface Sessions

Example: GPIB Interface Session (C)

Example: GPIB Interface Session (Visual Basic)

Using GPIB Commander Sessions

Addressing GPIB Commanders

SICL Function Support for GPIB Commander Sessions

Writing GPIB Interrupt Handlers

Multiple I_INTR_GPIB_TLAC Interrupts

Handling SRQs from Multiple GPIB Instruments

Using SICL with GPIO

Introduction

Selecting a GPIO Communications Session

SICL GPIO Functions

Using GPIO Interface Sessions

Addressing GPIO Interfaces

SICL Function Support with GPIO Interface Sessions

Example: GPIO Interface Session (C)

Example: GPIO Interface Session (Visual Basic)

Example: GPIO Interrupts