Agilent Technologies 54621A Manual

Programmer’s Guide
Publication Number 54622-97038
September 2002
For Safety information see t e pages be ind t e Index.
© Copyrig t Agilent Tec nologies 2000-2002
All Rig ts Reserved
Agilent 54621A/22A/24A/41A/42A
Oscilloscopes and
Agilent 54621D/22D/41D/42D
Mixed- ignal Oscilloscopes

ii
Programming the Oscilloscope
W en you attac an interface module to t e rear of t e oscilloscope, it
becomes programmable. T at is, you can ook a controller (suc as a
PC or workstation) to it, and write programs on t at controller to
automate oscilloscope setup and data capture.
T e following figure s ows t e basic structure of every program you will
write for t e oscilloscope.
Initialize
To ensure consistent, repeatable performance, you need to start t e
program, controller, and oscilloscope in a known state. Wit out correct
initialization, your program may run correctly in one instance and not in
anot er. T is mig t be due to c anges made in configuration by previous
program runs or from t e front panel of t e oscilloscope.
• Program initialization defines and initializes variables, allocates
memory, or tests system configuration.
• Controller initialization ensures t at t e interface to t e oscilloscope
(eit er GPIB or RS-232) is properly set up and ready for data transfer.
• Oscilloscope initialization sets t e c annel configuration and labels,
t res old voltages, trigger specification and mode, timebase, and
acquisition type.

iii
Capture
Once you initialize t e oscilloscope, you can begin capturing data for
analysis. Remember t at w ile t e oscilloscope is responding to
commands from t e controller, it is not performing acquisitions. Also,
w en you c ange t e oscilloscope configuration, any data already
captured will most likely be rendered.
To collect data, you use t e :DIGitize command. T is command clears
t e waveform buffers and starts t e acquisition process. Acquisition
continues until acquisition memory is full, t en stops. T e acquired data
is displayed by t e oscilloscope, and t e captured data can be measured,
stored in trace memory in t e oscilloscope, or transferred to t e
controller for furt er analysis. Any additional commands sent w ile
:DIGitize is working are buffered until :DIGitize is complete.
You could also put t e oscilloscope into run mode, t en use a wait loop
in your program to ensure t at t e oscilloscope as completed at least
one acquisition before you make a measurement. Agilent does not
recommend t is because t e needed lengt of t e wait loop may vary,
causing your program to fail. :DIGitize, on t e ot er and, ensures t at
data capture is complete. Also, :DIGitize, w en complete, stops t e
acquisition process so t at all measurements are on displayed data, not
on a constantly c anging data set.
Analyze
After t e oscilloscope as completed an acquisition, you can find out
more about t e data, eit er by using t e oscilloscope measurements or
by transferring t e data to t e controller for manipulation by your
program. Built-in measurements include frequency, duty cycle, period,
and positive and negative pulse widt .
Using t e :WAVeform commands, you can transfer t e data to your
controller. You may want to display t e data, compare it to a known good
measurement, or simply c eck logic patterns at various time intervals in
t e acquisition.

iv
In This Book
T is Programmer’s Guide is your introduction to programming t e
oscilloscope using an instrument controller. T is book, wit t e Programmer’s
Reference, provides a compre ensive description of t e oscilloscope’s
programmatic interface. T e Programmer’s Reference is supplied as a
Microsoft Windows Help file on a 3.5" diskette.
T e oscilloscope as a built-in RS-232-C port for programming. To program t e
oscilloscope over GPIB, you need t e N2757A GPIB Interface Module. You also
need an instrument controller t at supports eit er t e IEEE-488 or RS-232-C
interface standards, and a programming language capable of communicating
wit t ese interfaces.
T is book contains t e following information:
Chapter 1 Introduction to Programming, gives a general overview of
oscilloscope programming.
Chapter 2 Programming Getting Started, s ows a simple program, explains
its operation, and discusses considerations for data types.
Chapter 3 GPIB, discusses t e general considerations for programming t e
instrument over an GPIB interface.
Chapter 4 Programming over RS-232-C, discusses t e general considerations
for programming t e instrument over an RS-232-C interface.
Chapter 5 Programming and Documentation Conventions, describes t e
conventions used in representing t e syntax of commands t roug out t is book
and t e Programmer’s Reference, and gives an overview of t e oscilloscope
command set.
Chapter 6 Status Reporting, discusses t e oscilloscope status registers and
ow to use t em in your programs.
Chapter 7 Installing and Using t e Programmer’s Reference, tells ow to
install t e Programmer’s Reference online elp file in Microsoft Windows, and
explains elp file navigation.
Chapter 8 Programmer’s Quick Reference, lists all t e commands and queries
available for programming t e oscilloscope.
For information on oscilloscope operation, see t e User’s Guide. For
information on interface configuration, see t e documentation for t e
oscilloscope interface module and t e interface card used in your controller (for
example, t e Agilent 82350A interface for IBM PC-compatible computers).

Contents
Contents-1
1 Introduction to Programming
Talking to t e Instrument 1-3
Program Message Syntax 1-4
Combining Commands from t e Same Subsystem 1-7
Duplicate Mnemonics 1-8
Query Command 1-9
Program Header Options 1-10
Program Data Syntax Rules 1-11
Program Message Terminator 1-13
Selecting Multiple Subsystems 1-14
2 Programming Getting tarted
Initialization 2-3
Autoscale 2-4
Setting Up t e Instrument 2-5
Example Program 2-6
Using t e DIGitize Command 2-7
Receiving Information from t e Instrument 2-9
String Variables 2-10
Numeric Variables 2-11
Definite-Lengt Block Response Data 2-12
Multiple Queries 2-13
Instrument Status 2-13
3 Programming over GPIB
Interface Capabilities 3-3
Command and Data Concepts 3-3
Addressing 3-4
Communicating Over t e Bus 3-5
Lockout 3-6
Bus Commands 3-6
4 Programming over R -232-C
Interface Operation 4-3
Cables 4-3
Minimum T ree-Wire Interface wit Software Protocol 4-4
Extended Interface wit Hardware Hands ake 4-5
Configuring t e Interface 4-6
Interface Capabilities 4-7
Lockout Command 4-8

Contents
Contents-2
5 Programming and Documentation Conventions
Command Set Organization 5-3
T e Command Tree 5-6
Obsolete and Discontinued Commands 5-10
Truncation Rules 5-15
Infinity Representation 5-16
Sequential and Overlapped Commands 5-16
Response Generation 5-16
Notation Conventions and Definitions 5-17
Program Examples 5-18
6 tatus Reporting
Status Reporting Data Structures 6-5
Status Byte Register (SBR) 6-8
Service Request Enable Register (SRER) 6-10
Trigger Event Register (TRG) 6-10
Standard Event Status Register (SESR) 6-11
Standard Event Status Enable Register (SESER) 6-12
Operation Status Register (OPR) 6-13
Arm Event Register (ARM) 6-13
Error Queue 6-14
Output Queue 6-15
Message Queue 6-15
Clearing Registers and Queues 6-15
7 Installing and Using the Programmer’s Reference
To install t e elp file under Microsoft Windows 7-3
To get updated elp and program files via t e Internet 7-4
To start t e elp file 7-5
To navigate t roug t e elp file 7-5
8 Programmer’s Quick Reference
Conventions 8-3
Suffix Multipliers 8-3
Commands and Queries 8-4

1
Introduction to Programming

1-2
Introduction to Programming
C apters 1 and 2 introduce t e basics for remote programming of an
oscilloscope. T e programming instructions in t is manual conform to
t e IEEE488.2 Standard Digital Interface for Programmable
Instrumentation. T e programming instructions provide t e means of
remote control.
To program t e oscilloscope you must add eit er a GPIB (N2757A)
interface, or program over t e built-in RS-232-C interface on t e rear
panel.
You can perform t e following basic operations wit a controller and an
oscilloscope:
• Set up t e instrument.
• Make measurements.
• Acquire data (waveform, measurements, configuration) from t e
oscilloscope.
• Send information (pixel images, configurations) to t e oscilloscope.
Ot er tasks are accomplis ed by combining t ese basic functions.
Languages for Program Examples
The programming examples for individual commands in this manual are written in
HPBASIC 6.3 or C.

1-3
Introduction to Programming
Talking to the Instrument
Talking to the Instrument
Computers acting as controllers communicate wit t e instrument by sending
and receiving messages over a remote interface. Instructions for programming
normally appear as ASCII c aracter strings embedded inside t e output
statements of a ost language available on your controller. T e input statements
of t e ost language are used to read in responses from t e oscilloscope.
For example, HPBASIC uses t e OUTPUT statement for sending commands
and queries. After a query is sent, t e response is usually read in using t e
ENTER statement.
Messages are placed on t e bus using an output command and passing t e
device address, program message, and terminator. Passing t e device address
ensures t at t e program message is sent to t e correct interface and
instrument.
T e following HP BASIC statement sends a command w ic turns on label
display.
OUTPUT < device address > ;":CHANNEL1:BWLIMIT ON"<terminator>
T e < device address > represents t e address of t e device being programmed.
Eac of t e ot er parts of t e above statement are explained in t e following
pages.

1-4
Introduction to Programming
Program Message Syntax
Program Message yntax
To program t e instrument remotely, you must understand t e command
format and structure expected by t e instrument. T e IEEE 488.2 syntax rules
govern ow individual elements suc as eaders, separators, program data, and
terminators may be grouped toget er to form complete instructions. Syntax
definitions are also given to s ow ow query responses are formatted. T e
following figure s ows t e main syntactical parts of a typical program
statement.
Figure 1-1
Program Message Syntax
Output Command
T e output command is entirely dependent on t e programming language.
T roug out t is manual, HPBASIC is used in most examples of individual
commands. If you are using ot er languages, you will need to find t e
equivalents of HP BASIC commands like OUTPUT, ENTER, and CLEAR to
convert t e examples. T e instructions listed in t is manual are always s own
between quotation marks in t e example programs.
Device Address
T e location w ere t e device address must be specified is also dependent on
t e programming language you are using. In some languages, t is may be
specified outside t e output command. In HP BASIC, t is is always specified
after t e keyword OUTPUT. T e examples in t is manual assume t e
oscilloscope is at device address 707 . W en writing programs, t e address
varies according to ow t e bus is configured.

1-5
Introduction to Programming
Program Message Syntax
Instructions
Instructions (bot commands and queries) normally appear as a string
embedded in a statement of your ost language, suc as BASIC, Pascal, or C.
T e only time a parameter is not meant to be expressed as a string is w en t e
instruction’s syntax definition specifies <block data>, suc as <learn string>.
T ere are only a few instructions t at use block data.
Instructions are composed of two main parts:
• T e eader, w ic specifies t e command or query to be sent.
• T e program data, w ic provide additional information needed to clarify
t e meaning of t e instruction.
Instruction Header
T e instruction eader is one or more mnemonics separated by colons (:) t at
represent t e operation to be performed by t e instrument. T e command tree
in c apter 5 illustrates ow all t e mnemonics can be joined toget er to form a
complete eader (see c apter 5, “Programming and Documentation
Conventions”).
T e example in Figure 1-1 is a command. Queries are indicated by adding a
question mark (?) to t e end of t e eader. Many instructions can be used as
eit er commands or queries, depending on w et er or not you ave included
t e question mark. T e command and query forms of an instruction usually
ave different program data. Many queries do not use any program data.
White pace ( eparator)
W ite space is used to separate t e instruction eader from t e program data.
If t e instruction does not require any program data parameters, you do not
need to include any w ite space. In t is manual, w ite space is defined as one
or more space c aracters. ASCII defines a space to be c aracter 32 (in decimal).
Program Data
Program data are used to clarify t e meaning of t e command or query. T ey
provide necessary information, suc as w et er a function s ould be on or off,
or w ic waveform is to be displayed. Eac instruction’s syntax definition s ows
t e program data, as well as t e values t ey accept. T e section “Program Data
Syntax Rules” in t is c apter as all of t e general rules about acceptable values.
W en t ere is more t an one data parameter, t ey are separated by commas(,).
Spaces can be added around t e commas to improve readability.

1-6
Introduction to Programming
Program Message Syntax
Header Types
T ere are t ree types of eaders:
• Simple Command eaders
• Compound Command eaders
• Common Command eaders
imple Command Header Simple command eaders contain a single
mnemonic. AUTOSCALE and DIGITIZE are examples of simple command
eaders typically used in t is instrument. T e syntax is:
<program mnemonic><terminator>
Simple command eaders must occur at t e beginning of a program message;
if not, t ey must be preceded by a colon.
W en program data must be included wit t e simple command eader (for
example, :DIGITIZE CHANNEL1), w ite space is added to separate t e data
from t e eader. T e syntax is:
<program mnemonic><separator><program data><terminator>
Compound Command Header Compound command eaders are a
combination of two program mnemonics. T e first mnemonic selects t e
subsystem, and t e second mnemonic selects t e function wit in t at
subsystem. T e mnemonics wit in t e compound message are separated by
colons. For example:
To execute a single function wit in a subsystem:
:<subsystem>:<function><separator>
<program data><terminator>
(For example :CHANNEL1:BWLIMIT ON)
Common Command Header Common command eaders control IEEE
488.2 functions wit in t e instrument (suc as clear status). T eir syntax is:
*<command header><terminator>
No space or separator is allowed between t e asterisk (*) and t e command
eader. *CLS is an example of a common command eader.

1-7
Introduction to Programming
Combining Commands from the Same Subsystem
Combining Commands from the ame ubsystem
To execute more t an one function wit in t e same subsystem, separate t e
functions wit a semicolon (;):
:<subsystem>:<function><separator><data>;
<function><separator><data><terminator>
(For example :CHANNEL1:COUPLING DC;BWLIMIT ON)

1-8
Introduction to Programming
Duplicate Mnemonics
Duplicate Mnemonics
Identical function mnemonics can be used in more t an one subsystem. For
example, t e function mnemonic RANGE may be used to c ange t e vertical
range or to c ange t e orizontal range:
:CHANNEL1:RANGE .4
sets t e vertical range of c annel 1 to 0.4 volts full scale.
:TIMEBASE:RANGE 1
sets t e orizontal time base to 1 second full scale.
CHANNEL1 and TIMEBASE are subsystem selectors and determine w ic
range is being modified.

1-9
Introduction to Programming
Query Command
Query Command
Command eaders immediately followed by a question mark (?) are queries.
After receiving a query, t e instrument interrogates t e requested function and
places t e answer in its output queue. T e answer remains in t e output queue
until it is read or anot er command is issued. W en read, t e answer is
transmitted across t e bus to t e designated listener (typically a controller).
For example, t e query :TIMEBASE:RANGE? places t e current time base
setting in t e output queue. In HP BASIC, t e controller input statement:
ENTER < device address > ;Range
passes t e value across t e bus to t e controller and places it in t e variable
Range.
Query commands are used to find out ow t e instrument is currently
configured. T ey are also used to get results of measurements made by t e
instrument. For example, t e command :MEASURE:RISETIME? instructs t e
instrument to measure t e rise time of your waveform and places t e result in
t e output queue.
T e output queue must be read before t e next program message is sent. For
example, w en you send t e query :MEASURE:RISETIME? you must follow
t at query wit an input statement. In HP BASIC, t is is usually done wit an
ENTER statement immediately followed by a variable name. T is statement
reads t e result of t e query and places t e result in a specified variable.
Read the Query Result First
Sending another command or query before reading the result of a query clears the
output buffer and the current response. It also generates a query interrupted error
in the error queue.

1-10
Introduction to Programming
Program Header Options
Program Header Options
You can send program eaders using any combination of uppercase or lowercase
ASCII c aracters. Instrument responses, owever, are always returned in
uppercase.
Program command and query eaders may be sent in eit er long form (complete
spelling), s ort form (abbreviated spelling), or any combination of long form
and s ort form.
TIMEBASE:DELAY 1US - long form
TIM:DEL 1US - short form
Programs written in long form are easily read and are almost self-documenting.
T e s ort form syntax conserves t e amount of controller memory needed for
program storage and reduces I/O activity.
Command Syntax Programming Rules
The rules for the short form syntax are shown in chapter 5, “Programming and
Documentation Conventions.”

1-11
Introduction to Programming
Program Data Syntax Rules
Program Data yntax Rules
Program data is used to convey a par ameter information r elated to t e command
eader. At least one space must separate t e command eader or query eader
from t e program data.
<program mnemonic><separator><data><terminator>
W en a program mnemonic or query as multiple program data, a comma
separates sequential program data.
<program mnemonic><separator><data>,<data><terminator>
For example, :CHANNEL:THRESHOLD POD1,TTL as two program data:
POD1 and TTL.
Two main types of program data are used in commands: c aracter and numeric.
Character Program Data
C aracter program data is used to convey parameter information as alp a or
alp anumeric strings. For example, t e :TIMEBASE:MODE command can be
set to normal, delayed, XY, or ROLL. T e c aracter program data in t is case
may be NORMAL, DELAYED, XY, or roll. T e command :TIMEBASE:MODE
DELAYED sets t e time base mode to delayed.
T e available mnemonics for c aracter program data are always included wit
t e instruction’s syntax definition. See t e online Programmer’s Reference for
more information. W en sending commands, you may eit er t e long form or
s ort form (if one exists). Uppercase and lowercase letters may be mixed freely.
W en receiving query responses, uppercase letters are used exclusively.
Numeric Program Data
Some command eaders require program data to be expressed numerically. For
example, :TIMEBASE:RANGE requires t e desired full scale range to be
expressed numerically.
For numeric program data, you ave t e option of using exponential notation
or using suffix multipliers to indicate t e numeric value. T e following numbers
are all equal:
28 = 0.28E2 = 280e-1 = 28000m = 0.028K = 28e-3K.
W en a syntax definition specifies t at a number is an integer, t at means t at
t e number s ould be w ole. Any fractional part be ignored, truncating t e
number. Numeric data parameters accept fractional values are called real
numbers.

1-12
Introduction to Programming
Program Data Syntax Rules
All numbers must be strings of ASCII c aracters. T us, w en sending t e
number 9, you would send a byte representing t e ASCII code for t e c aracter
9 (w ic is 57). A t ree-digit number like 102 would take up t ree bytes (ASCII
codes 49, 48, and 50). T is is andled automatically w en you include t e entire
instruction in a string.
Embedded trings
Embedded strings contain groups of alp anumeric c aracters, w ic are
treated as a unit of data by t e oscilloscope. For example, t e line of text written
to t e advisory line of t e instrument wit t e :SYSTEM:DSP command:
:SYSTEM:DSP "This is a message."
Embedded strings may be delimited wit eit er single (’) or double () quotes.
T ese strings are case-sensitive, and spaces act as legal c aracters just like any
ot er c aracter.

1-13
Introduction to Programming
Program Message Terminator
Program Message Terminator
T e program instructions wit in a data message are executed after t e program
message terminator is received. T e terminator may be eit er an NL (New Line)
c aracter, an EOI (End-Or-Identify) asserted in t e GPIB interface, or a
combination of t e two. Asserting t e EOI sets t e EOI control line low on t e
last byte of t e data message. T e NL c aracter is an ASCII linefeed (decimal
10).
New Line Terminator Functions
The NL (New Line) terminator has the same function as an EOS (End Of String) and
EOT (End Of Text) terminator.

1-14
Introduction to Programming
Selecting Multiple Subsystems
electing Multiple ubsystems
You can send multiple program commands and program queries for different
subsystems on t e same line by separating eac command wit a semicolon.
T e colon following t e semicolon enables you to enter a new subsystem. For
example:
<program mnemonic><data>;
:<program mnemonic><data><terminator>
:CHANNEL1:RANGE 0.4;:TIMEBASE:RANGE 1
Combining Compound and Simple Commands
Multiple commands may be any combination of compound and simple commands.