Able OF Ontents: IMAGE Base Language
Uploaded by
andi vlog'sAble OF Ontents: IMAGE Base Language
Uploaded by
andi vlog'sIMAGE Base Language: Table of Contents
Table of Contents Index Home Master Index Search Help
TABLE OF CONTENTS
1. Getting Started
2. UNIX and Solaris
3. IMAGE Tester Environment
4. Configuring IMAGE
5. Loading and Running Test Programs
6. Data Collection
7. Debugging Test Programs
8. Production Environment
9. Production Menu Control
10. Wafer Mapping
11. GPIB Programming
12. Simulator
13. IMAGE Test Language Overview
14. Test Program Structure
15. Testing and Classifying Devices
16. Input and Output Functions
17. Multisite Testing
18. Digital Signal Processing
19. Checkers
20. Device Focussed Checkers
21. Calibration
22. Test System Alarms
23. Reserved Word List
24. Standard Test Data Format
25. STDF Utilities and Filters
26. Base IMAGE Functions
27. FlexDSP Programmer’s Reference
28. Tester API
29. Custom Directory
Index
IMAGE Solutions V8.3 TOC-1
IMAGE Base Language: Getting Started
Table of Contents Index Home Master Index Search Help
1 GETTING STARTED
This section provides an overview of the basic procedures for using IMAGE and the test
system. It presents the major features of the Catalyst and Catalyst Tiger hardware and
IMAGE software. It describes basic procedures you must follow to use the hardware and
software and where you can go from that point.
This section includes the following:
• “Catalyst Hardware” on page 1-2
• “Catalyst Software” on page 1-3
• “Getting Started—Logging In and Using the Test System” on page 1-5
• “What to Read Next” on page 1-7
IMAGE Solutions V8.3 1-1
IMAGE Base Language: Getting Started: Catalyst Hardware
Table of Contents Index Home Master Index Search Help
Catalyst Hardware
Catalyst test systems use a dual computer architecture. This architecture, based on Sun
Microsystems’ Sun computer, uses two separate computers with dedicated functions.
The user/network computer is dedicated to user and network functions. It provides a user-
friendly and interactive interface for fast test program development. Because it is dedicated
to user functions, it can handle CPU-intensive graphics tools required for developing test
programs and managing device data.
The test computer is dedicated to controlling the tester hardware. This means that A5xx
test systems can provide the memory and high processing speed required in testing. At the
same time, you can use the tester’s graphics tools without affecting throughput.
A Sun Microsystems workstation provides your communications link to the tester, its test
heads, and ultimately the device under test (DUT). Through it, you convey instructions to
the test system computer, which, in turn, activates the test system hardware to carry out
your instructions.
IMAGE Solutions V8.3 1-2
IMAGE Base Language: Getting Started: Catalyst Software
Table of Contents Index Home Master Index Search Help
Catalyst Software
The Interactive Menu Assisted Graphics Environment (IMAGE) is based on a set of
software programs known collectively as Solaris. Solaris includes the Solaris operating
system and the OpenWindows 3.0 window system. Solaris is based on the UNIX operating
system. Solaris manages the software and hardware resources of the test system
computer.
OpenWindows 3.0 is based on the X Window System, Version 11 Release 4 (X11R4), an
industry-standard windowing system. OpenWindows allows you to divide your Sun
workstation screen into work areas (windows) for performing general purpose activities,
such as editing ASCII files, running Solaris shell commands, running and debugging C
programs, and sending and receiving mail.
Running in the OpenWindows environment, IMAGE adds additional features for device
testing. IMAGE is an integrated collection of programs that allows you to load, compile, and
run test programs written in the IMAGE Test Language (ITL), examine and analyze test
program output, gather data, modify hardware, and debug programs. IMAGE is fully
integrated with OpenWindows. Any task performed in OpenWindows can be performed in
IMAGE.
The IMAGE software system has the following basic components:
• Test system executive software that controls the following IMAGE and Solaris software:
– Solaris operating system and standard utility programs
– High-resolution graphics window system
– Customized ATE dual-computer operating environment
– Instrumentation drivers to control tester instrumentation. One version of IMAGE
controls advanced mixed-signal and Catalyst test systems
– Ethernet TCP/IP Networking Software with Network File System (NFS)
• Test program language compiler that is interactive and includes:
– Incremental compilation
– C language
– Test program organization structured around specific functions
– Device pin-oriented language oriented toward the device
• Interactive test program editor and debugger for developing test programs, including:
– Complete source level debugger
– Mouse-oriented, window-based editor
– Immediate statement execution that allows you to try out code during debugging
• Interactive digital and analog design and debug tools that include:
– Digital pattern spreadsheet-style editor which understands digital patterns
– Digital pattern debugger that provides pattern debug and edit capability from the
same window
– History RAM for storing the history of pattern execution
IMAGE Solutions V8.3 1-3
IMAGE Base Language: Getting Started: Catalyst Software
Table of Contents Index Home Master Index Search Help
– Digital Pattern Logic Analyzer
– Analog waveform editor and debugger
– Graphic instrumentation status displays
• Data analysis and characterization tools allow you to produce:
– Datalog reports
– Summary reports
– Real-time histograms
– Shmoo and 3-D shmoo plots
• IMAGE stand-alone workstation tester simulation software, including a digital simulator,
that allows you to develop and debug text programs off-line
• Computer-aided test development (CATD) tools including IMAGE ExPress code-
producing debug displays that automate generation of program code
• Sun Ethernet networking software to support extensive off-line test program
development
• Access to Factory Integration and Resource Management System (FIRMS). This
optional software integrates the test floor with tools for data management and analysis
and tools for automation.
IMAGE Solutions V8.3 1-4
IMAGE Base Language: Getting Started: Getting Started—Logging In and Using the Test System
Table of Contents Index Home Master Index Search Help
Getting Started—Logging In and Using the Test System
This subsection describes the basic procedures for using A500 Family test systems and
IMAGE. The information in this subsection assumes the following:
• The test system hardware, including a test head and a Sun workstation, is properly
installed. (See the A5xx or Catalyst Installation Guide for information.)
• The test system is powered up and functional. (See the Software Installation Guide for
information.)
• IMAGE and Sun software is properly installed. (See the Software Installation Guide for
information.)
• Test system checkers have been run to determine that the tester hardware is functioning
to specifications. (See “Checkers” on page 19-1 and the Software Installation Guide for
information.)
• You have a valid user account and password on the test system. (Consult your system
manager or the Software Installation Guide for more information.)
• You have built and installed a device interface board (DIB) with a device socket for the
device you are testing.
If the workstation connected to the test system is set up correctly, its screen displays a
system login prompt, such as:
bandit login:
where bandit is the name of a particular workstation, also known as its machine name or
hostname. This is the starting point for all testing activities.
In general, to use the test system:
1. Invoke IMAGE.
2. Log into a test station.
3. Load a new or existing test program.
4. Plug your device into the device socket on the test head.
5. Debug and run your test program.
Invoking IMAGE
The first step in using the test system, whether you are writing test programs or testing
devices or performing system maintenance, is to invoke IMAGE:
1. Enter your username after the system login prompt.
2. Enter your password after the password prompt.
3. In response to the operating system command prompt, type image to invoke IMAGE.
(See “Solaris and the Shell” on page 2-2.)
IMAGE Solutions V8.3 1-5
IMAGE Base Language: Getting Started: Getting Started—Logging In and Using the Test System
Table of Contents Index Home Master Index Search Help
Loading a New or Existing Test Program
After invoking IMAGE, the screen changes and the window for station 1 appears. At this
point:
1. Log in to this IMAGE station window (or another one) using your account name and
password. (See “Solaris and the Shell” on page 2-2.)
2. Load a new or existing test program into the station. (See “Loading Test Programs” on
page 5-2.)
If your workstation is connected to a tester, IMAGE checks your password and the
instrumentation present and brings up the correct type of IMAGE. This can be Catalyst or
Catalyst Tiger depending on the type of tester you have. If you are running IMAGE in
simulation on an off-line workstation, IMAGE checks your password and the simulation
configuration file, confsim, to indicate which type of IMAGE to bring up. (See “Configuring
IMAGE” on page 4-1.)
From this point, you have a number of options. For instance, you can:
• Edit the test program (see “Editing and Compiling Functions” on page 7-23).
• Debug the test program (see “Debugging Test Programs” on page 7-1).
• Run the test program (see “Running Test Programs” on page 5-21).
• Run the test program and datalog the test results (see section “Data Collection” on page
6-1).
• Run the test program and datalog and plot the test results (see “Real Time Yield Trend
Monitor” on page 6-112).
IMAGE Solutions V8.3 1-6
IMAGE Base Language: Getting Started: What to Read Next
Table of Contents Index Home Master Index Search Help
What to Read Next
As a starting point, learn how to use Sun’s windowing system. Select the HELP item in the
IMAGE Workspace menu. This is an introduction to using the Sun desktop and its utilities.
Next, read the following:
1. Part I (chapters 1 through 12) of this manual, which is a starting point for learning about
Catalyst test systems. Sections in this part of the manual cover such topics as invoking
IMAGE, logging in to a test station, creating a test program directory, and writing,
compiling, and debugging a test program.
2. Part II (chapters 13 through 18) of this manual. The sections in this part give an overview
of the C programming language and the IMAGE Test Language (ITL), which is an
extension of the C language adapted for device testing.
3. The instrumentation manual for your test system, which covers specific Catalyst or
Catalyst Tiger programming. Catalyst test systems also have a test head manual which
describes pinmap programming and use of the test head. (This information is included
as part of the instrumentation manual for Catalyst Tiger.)
4. Chapters 21 and 22 of this manual. “Calibration” on page 21-1 describes calibrating the
instruments. “Test System Alarms” on page 22-1 describes using alarms to detect
problems in your test program or the tester hardware.
For More Information
At this point, you should have enough information to design, debug, and run IMAGE test
programs. To learn more about the Solaris and UNIX operating systems, we recommend
the following books and manuals:
• Sun Microsystems AnswerBook. This on-line documentation utility includes Sun’s
complete documentation set. The following manuals in this set are particularly
recommended:
– Sun Microsystems OpenWindows Version 3 Users’ Guide
– Sun Microsystems OpenWindows Version 3 Deskset Reference Guide
– Sun Microsystems Getting Started with Solaris: Beginner’s Guide
– Sun Microsystems Doing More with Solaris: Beginner’s Guide
• UNIX Primer Plus by Mitchell Waite, Donald Martin, and Stephen Prata
• Advanced UNIX —A Programmer’s Guide by Stephen Prata
• UNIX System Administration by David Fiedler and Bruce H. Hunter
• UNIX System Security by Patrick H. Wood and Stephen G. Kochan
To learn more about UNIX shell programming, we recommend:
• UNIX Shell Programming by Stephen G. Kochan and Patrick H. Wood (Bourne shell and
Korn shell)
• UNIX Programming Environment by Brian W. Kernighan and Rob Pike (Bourne shell)
• The UNIX C Shell Field Guide by Gail Anderson and Paul Anderson
IMAGE Solutions V8.3 1-7
IMAGE Base Language: Getting Started: What to Read Next
Table of Contents Index Home Master Index Search Help
To learn more about C language programming, we recommend:
• Programming in C by Stephen G. Kochan
• C Programming Language by Brian W. Kernighan and Dennis M. Ritchie
• C Primer Plus by Mitchell Waite, Stephen Prata, and Donald Martin
• C – The Complete Reference by Herbert Schildt
For detailed hardware diagrams of the test system instruments and test head, refer to the
following Teradyne manuals:
• Catalyst Instrumentation Manual
• Catalyst Test Head Manual
• Catalyst Tiger Instrumentation Manual
For hardware installation information, refer to:
• A580 Site Installation Manual (part #553-240-17)
• Catalyst Site Prep Guide (part #553-700-60)
For applications programming techniques, Teradyne supplies a collection of Test
Technique Notes written by its application engineers. These test technique notes cover, in
depth, issues pertaining to device testing.
Help
For quick reference to programming syntax, IMAGE includes an on-line help system. To
bring up the on-line help window, click SELECT on the HELP button in the station window.
IMAGE also uses the Spot Help utility, allowing you to place the pointer over a feature in an
IMAGE window and press the Help button on the keyboard.
For complete on-line information (including this manual), select USER MANUALS from the
help button menus or type imagesolutions -manuals in any station window. This brings
up the IMAGE Solutions on-line documentation. It includes the complete set of IMAGE
manuals, as well as search, hypertext links, and other features. For help in navigating
IMAGE Solutions, click the HELP link at the top of any page. For reference to Sun
information, use the AnswerBook utility. To bring up AnswerBook, type answerbook in any
station or shell window.
IMAGE Solutions V8.3 1-8
IMAGE Base Language: UNIX and Solaris
Table of Contents Index Home Master Index Search Help
2 UNIX AND SOLARIS
Catalyst and Catalyst Tiger test systems use the Solaris operating system, a version of the
UNIX operating system that includes other Sun enhancements.
Most work performed at the tester (writing, debugging, and running test programs) is done
using the IMAGE window environment. (See “IMAGE Tester Environment” on page 3-1.)
Solaris, however, is always present, and a fundamental knowledge of the operating system
is needed to do the common tasks associated with any user account.
This section includes the following:
• “Introduction to Solaris” on page 2-2
• “File and Directory Commands” on page 2-17
• “Stopping and Rebooting the Test System” on page 2-32
IMAGE Solutions V8.3 2-1
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
Introduction to Solaris
Sun UNIX on-line documentation (AnswerBook) is included with the test system. Sun
manuals are issued on CD-ROM disk to allow you to access the documentation on line. To
bring up AnswerBook, select PROGRAMS>ANSWERBOOK... from the Workspace menu or type
answerbook in any station or shell window. In CDE, you can also get help for the
environment and Sun-supplied tools by selecting PROGRAMS>HELP... from the Workspace
menu.
Solaris and the Shell
The shell is the part of Solaris that interprets your commands and executes them. It acts as
a command line interpreter, taking what you type in and sending the command to the
computer in a form the computer can act on. The Solaris operating system supports several
varieties of shells. However, the C shell is the one you use when working with IMAGE.
Solaris commands issued to the C shell are in lower case. Names of files or directories can
be in either all upper case, all lower case, or a mixture of both.
The characters used in file names or directory names can be a mix of alphabetic and
numeric, but the first character should be alphabetic. The period (.) and the underscore (_)
are legal characters.
Issuing commands causes the computer to perform tasks for you. These tasks are
processes or jobs. Editing a file, compiling a program, creating a directory, or listing files are
all considered jobs.
Special Key Sequences
The Control key, used simultaneously with certain alphabetic keys, provides some
important nonprinting functions known as control functions. These functions are:
CONTROL-C Halts the current process and places the shell prompt on the
screen.
CONTROL-D Causes the executing program to receive an EOF (end of file)
marker.
CONTROL-Z Halts current process or job. To resume processing, use
command fg. For more information on stopping jobs, foreground
processing and background processing see the AnswerBook
documentation.
CONTROL-S Stops the screen from scrolling.
CONTROL-Q Resumes screen scroll.
IMAGE Solutions V8.3 2-2
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
Solaris Directory Structure
You can think of the Solaris directory system as a branching or inverted tree structure,
beginning with a base directory called root. Other directories extend from the root directory
and from these directories extend more directories, including your home directory. Your
home directory usually has the same name as your account name and is the starting point
for your personal directory structure. Directories contained in a directory are called
subdirectories.
Any directory can contain other directories and files. Figure 2-1 shows an illustration of the
directory structure.
root
/
bin etc home
/bin /etc /home
bill jack bob
/home/bill /home/jack /home/bob
dir1 dir2
/home/bob/dir1 /home/bob/dir2
codedir
/home/bob/dir2/codedir
Figure 2-1. Directory Branching Structure
The branching structure allowing subdirectories to be contained within a directory is useful
when organizing files. You can create directories within your home directory to group files
for specific purposes. For example:
• A directory for text files
• A directory for data files
• Directories for computer language source code and object code files
• A directory for each test program
IMAGE Solutions V8.3 2-3
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
Think of the directory within a directory structure in terms of levels. A directory contained
within another directory is one level “down” from the directory where it resides. In figure 2-
1 directory dir2 is contained in or resides in directory bob, so directory dir2 is one level
below directory bob. Directory codedir resides in directory dir2, therefore, directory
codedir is one level below directory dir2 and two levels below directory bob.
Going from level to level traces a path to a directory where you want to do some work,
perhaps create a file to be stored in that directory or create another directory. The route to
a specific directory or to a file in a specific directory is called a path. A path describes the
route to follow through the levels of directories to a desired directory or file. The path
provides the information, “Begin at this directory and end at this directory.”
The path not only tells how to get somewhere in the directory structure but also locates
where in the directory structure the work is to be done.
In figure 2-2 the path to the file goodfile is:
/home/bob/dir2/codedir/abcdir/goodfile
IMAGE Solutions V8.3 2-4
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
root
/
bin etc home
/bin /etc /home
bill jack bob
/home/bill /home/jack /home/bob
dir1 dir2
/home/bob/dir1 /home/bob/dir2
codedir
/home/bob/dir2/codedir
myfile1 myfile2
abcdir
/home/bob/dir2/codedir/myfile1 /home/bob/dir2/codedir/abcdir
/home/bob/dir2/codedir/myfile2
goodfile
/home/bob/dir2/codedir/abcdir/goodfile
Figure 2-2. Locating a File Using a Path
The first / stands for the root directory; the following /’s are delimiters for each succeeding
directory in the path to reach file goodfile. Because this path begins with the root directory,
it is a rooted path.
File and directory commands always use some sort of path. Depending on where you are
in the directory structure, you may need to use a rooted path to get to a directory or file, or
you may only need to use a relative path. A rooted path always begins at the root directory,
so a / always begins a rooted path. A relative path begins at the directory that you are
IMAGE Solutions V8.3 2-5
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
working in at that moment, the current working directory. In figure 2-2, if you are working
in directory dir2, the relative path to file goodfile is:
codedir/abcdir/goodfile
Getting Help
For help with Solaris commands, an on-line manual (a duplicate of the Solaris Reference
Manual) is available. To display information from the manual, type man man at a command
prompt and press Return. (You must always press the Return key after entering a
command. This lets the operating system know that you are finished typing.) The header for
the manual appears on your screen and you can page forward through the information by
pressing the space bar or backward by pressing b. To get information about a specific
command, type man followed by the command you are interested in, then press Return.
Information on that command is displayed. To exit from the on-line manual at any time, type
q.
When working in the IMAGE environment, you can get help with Solaris commands by
selecting Help from the IMAGE Workspace menu. This displays Sun’s on-line help utility.
You can also get help on line from Sun’s AnswerBook. Select PROGRAMS>ANSWERBOOK
from the Workspace menu or type answerbook to invoke this utility.
Typing help at the station window prompt or clicking on the HELP button displays the IMAGE
Help window. This window can display information for basic Solaris commands, IMAGE
commands, or IMAGE test program syntax. IMAGE also includes Spot Help, allowing you
to place the pointer over any IMAGE window feature and press the Help key. (See “Getting
Help in IMAGE” on page 3-25.)
Login Procedures
The two login procedures for working with the tester Sun terminal are:
• The standard Solaris login which logs you in to Solaris (including CDE)
• The IMAGE station window login which logs you in to a specific test station
On login, whether directly to Solaris or an IMAGE station window, you are placed by the
operating system in the home directory of your account. Your home directory is part of the
system’s directory structure and is the same directory regardless of how you log in.
If your terminal or workstation screen looks like figure 2-3, Teradyne’s IMAGE environment
is not running and you must perform a standard login to Solaris before calling the IMAGE
environment and logging in to a test station.
IMAGE Solutions V8.3 2-6
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
ariel login:
Figure 2-3. Workstation Screen, Standard Solaris Text-Only Login
Standard Login to Solaris
To log in to Solaris, type the account name assigned to you by your system manager and
press Return. The operating system checks to see if you have an account and if the account
has a password. If your account has a password, you are prompted for it. If your account
does not have a password, you are required to define one. Type in your password and press
Return.
The appearance of the login prompt depends on your choice of graphical environment. If
you have CDE installed and enabled, you receive a graphical login prompt called the
“desktop login.” This lets you specify various options (such as which window manager to
launch and what language to choose for system prompts). From here you can also choose
to enable the command-line only login for the current session. (For information on disabling
the desktop login, see “Disabling and Enabling the Desktop Login” on page 2-10.)
Regardless of the appearance of the login prompts, you must supply a username and
password for Solaris to authenticate you.
If your account name and password are correct, you are logged in and the operating system
prompt (generally a word followed by the % character) appears on the screen (if you logged
in under CDE, this prompt appears in a Console window, or may not appear at all). If your
account name or password is incorrect, or if you do not have an account, the operating
system displays an error message and does not allow you to log in. If you have difficulty
logging in, see your system manager.
After logging in, you can type in and execute any Solaris commands.
IMAGE Environment—Access
How you start IMAGE depends on where the system leaves you after you log in to Solaris.
IMAGE Solutions V8.3 2-7
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
If you have only a command prompt after a standard login to Solaris, type image at a
command prompt and press Return to enter the IMAGE environment. The operating system
starts the OpenWindows window manager, then invokes IMAGE.
If you have a graphical environment (either OpenWindows or CDE) after a standard login to
Solaris, you need a command prompt from which to start IMAGE. If there is not one already
open, invoke a Console window. (To invoke a Console window, right click on the desktop,
then choose PROGRAMS>CONSOLE... from the Workspace Menu.) At the command prompt,
type image and press Return to enter the IMAGE environment. The operating system starts
IMAGE.
A pointer and a station window containing the station window login prompt appear on your
screen. The station window is similar to figure 2-4. Use the same user account name and
password to log in to the station window.
Figure 2-4. IMAGE Station Window
Logging In to the Station Window
To log in to the station window, use the mouse to move the pointer into the part of the station
window containing the login prompt (figure 2-4.) When the pointer is placed properly, log in
by typing your user account name and password.
Logging Off
When you finish your work, log off so the terminal is available for other users. If you called
the IMAGE window environment after your standard login to Solaris (that is, you did not start
IMAGE from within a Console or Shell Tool), you must exit IMAGE before logging out. To
exit the IMAGE environment, move the pointer to the gray area of the screen and hold down
the MENU button of the mouse. This displays the IMAGE Workspace menu (figure 2-5).
Choose EXIT from this menu. (See “IMAGE Workspace Menu” on page 3-5.)
IMAGE Solutions V8.3 2-8
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
Figure 2-5. IMAGE Workspace Menu Showing the Exit Command
If you started IMAGE from within a graphical environment (that is, you started the program
from within a Console or Shell Tool), you need to exit IMAGE before you can log out. To exit
IMAGE but not the underlying graphical environment, close all programs and tools, then
click the Exit IMAGE button on the IMAGE Control Window.
Figure 2-6. IMAGE Control Window (in CDE)
Logging Out of a Station Window
If you began your work by logging in to a station window, you need only log out of the station;
you do not have to exit IMAGE. Move the pointer into the station window and type logout
and press Return. You are logged out and the station login prompt replaces the system
prompt.
Logging Out of Solaris
How you log out of your station depends on how you logged in.
If you logged in to Solaris using the text-only command line, type logout or exit at the
command prompt after you have closed your graphical environment. When logout has
occurred, the system prompt is replaced on the screen with the login prompt and the
terminal is ready for the next user.
If you logged in to Solaris using OpenWindows without the text-only command line (that is,
using the graphical login screen), click MENU on the desktop, then click EXIT from the
Workspace Menu.
To log out of Solaris using CDE, click the EXIT button on the Front Panel or click MENU on
the backdrop and select LOG OUT... from the Workspace Menu.
IMAGE Solutions V8.3 2-9
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
Disabling and Enabling the Desktop Login
If you prefer the text-only login, you can disable the graphical desktop login. Doing so also
disables the automatic start of any graphical environment. (If you use the text-only
command line login, you can start OpenWindows from the command prompt by typing
openwin, but you cannot start CDE.) Disabling the desktop login requires root access to
your system.
To disable the desktop login:
1. Log in to your system as root.
2. At a command prompt, type /usr/dt/bin/dtconfig -d and press Return.
3. Reboot the computer.
You can also specify the text-only login from within the desktop login. To do so, choose
OPTIONS>COMMAND LINE LOGIN from the desktop login window. Solaris removes the
graphical environment and displays a text login prompt for the current session only.
To enable the desktop login:
1. Log in to your system as root.
2. At a command prompt, type /usr/dt/bin/dtconfig -e and press Return.
3. Reboot the computer.
Differences Between OpenWindows and CDE
As of version 7.0, IMAGE supports both the OpenWindows, version 3.5.1, and Common
Desktop Environment (CDE), version 1.0.2, window managers. Your choice of window
manager affects how you start and interact with IMAGE in a number of ways. Table 2-1 and
the following sections describe some of the major differences. These descriptions assume
you are familiar with the relevant OpenWindows conventions and commands and explain
only the CDE methods.
Table 2-1. Differences between OpenWindows and Common Desktop Environment (CDE)
Item OpenWindows Common Desktop Environment
Login method Command line login only Choice of graphical login screen
(allows command line,
OpenWindows, or CDE) or
command line only login
Sourcing of Automatic Manual or by inclusion of directive
$HOME/.login in $HOME/.dtprofile
Window X Windows style Motif style (follows CDE
management conventions, as does Microsoft
procedures Windows)
IMAGE Solutions V8.3 2-10
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
Table 2-1. Differences between OpenWindows and Common Desktop Environment (CDE)
Item OpenWindows Common Desktop Environment
Manipulation of text X Windows style commands Motif style commands
within a window
Method of starting Launch IMAGE or IMAGE Launch IMAGE from within
IMAGE and OpenWindows from graphical environment only
command line
IMAGE-specific IMAGE items included IMAGE items not included
WorkSpace Menu
Reporting of errors All messages go to console Alarm Manager allows control of
and alarms or terminal window from message destination
which IMAGE was launched
Login Method
The Common Desktop Environment (CDE) provides a number of ways to log in to the
system. You can use the standard text-only login, or you can use the graphical login screen.
If you use the text-only login, the system works as it does without CDE installed; you can
start OpenWindows alone or you can invoke IMAGE and OpenWindows together. If you use
the graphical login screen (see figure 2-8), you can choose OpenWindows, CDE, or a one-
time use of the text-only login. Figure 2-7 describes your login choices.
CAUTION
Do not use the graphical login screen on any computer connected directly to a tester.
Enabling the graphical login screen on the user computer can cause unpredictable
results and is not supported.
CDE Installed
Login Screen
Login Screen Enabled
Disabled
Command Line Graphical
Login Only Login Screen
OpenWindows CDE OpenWindows Command Line
Login (one time)
Figure 2-7. Login choices with CDE installed
IMAGE Solutions V8.3 2-11
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
If you use the graphical login screen, the IMAGE additions to the WorkSpace Menu do not
appear.
Figure 2-8. The graphical login screen provided with the Common Desktop Environment
To choose your window manager from the graphical login screen, click Options>Session,
then select the window manager you want to use for this session. If you do not select a
window manager, the login sequence uses the same one you used in your previous
session.
If you want to use the text-only login for one session, choose OPTIONS>COMMAND LINE LOGIN
from the Desktop Login screen. If you log in this way, you cannot start either window
manager or IMAGE.
See “Disabling and Enabling the Desktop Login” on page 2-10 for instructions on disabling
and enabling the graphical login screen. The IMAGE install process disables the graphical
login screen.
Sourcing of Local Configuration Files
When you use the graphical login screen, Solaris does not automatically source your
.login or .profile configuration files. To have Solaris include these files in your startup
procedure, include the following line in .dtprofile in your $HOME directory:
DTSOURCEPROFILE=true
Note that any user interaction in the .login or .profile files fails because the operating
system interprets your configuration files before it assigns a terminal type. If this prevents
you from logging in successfully, choose OPTIONS>SESSIONS>FAILSAFE SESSION from the
graphical login screen and try again.
Manipulation of Text Within a Window
The procedures for two commonly used text functions, selecting and finding text, are
different.
To select text within a window:
IMAGE Solutions V8.3 2-12
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
1. Click SELECT at the start of the text you want to highlight.
2. Drag the mouse pointer to the end of the selection. The text is highlighted as you drag
the pointer.
3. Release the mouse button.
or
1. Click SELECT at the start of the text you want to highlight.
2. Move the mouse pointer to the end of the selection.
3. SHIFT-click at the end of the selection. All text between the start point and the end of the
selection is highlighted.
You can also paste the selected text at the insertion point by clicking ADJUST.
To select text in an XView (OpenWindows-style) window and find that text in a Motif (CDE-
style) window:
1. Highlight the text in the XView window.
2. Press the COPY key.
3. Select the EDIT>FIND function in the Motif window.
4. Click in the text field in the Find popup window.
5. Click the FIND button to perform the search.
To select text in a Motif (CDE-style) window and find that text in an XView (OpenWindows-
style) window:
1. Select the text in the Motif window.
2. Press the COPY key.
3. Make the XView window the active window.
4. Press the FIND key.
Starting IMAGE
How you start IMAGE depends largely on how you started your window manager.
If you use the text-only login, type image to launch OpenWindows with IMAGE together.
You can also start OpenWindows separately, then invoke IMAGE from within a shell tool.
If you use the graphical login screen, your window manager starts automatically as soon as
the system authenticates you. Therefore, OpenWindows or CDE will already be running
when you want to start IMAGE. To invoke IMAGE from within the window manager, open a
terminal window (or shell tool) and type image there. See “Sourcing of Local Configuration
Files”, “IMAGE-Specific WorkSpace Menus”, and “Displaying Alarm and Error Messages”
for more information about starting IMAGE after using the graphical login.
IMAGE Solutions V8.3 2-13
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
IMAGE-Specific WorkSpace Menus
If you log in using the graphical login screen, the IMAGE extensions to the WorkSpace
Menu do not appear. To use these extensions, you must disable the graphical login and log
in using the text-only procedure.
Window Management Procedures
Window management commands differ significantly between OpenWindows and the
Common Desktop Environment. For the entire set of commands for your environment, refer
to the Sun manuals OpenWindows Version 3 User’s Guide or CDE 1.0 User's Guide.
Following is a brief discussion of some of the more noticeable differences.
• Pushpins do not exist in CDE. However, it is still possible for some aspects of a
program’s interface to allow the use of pushpins, mostly in menus. The pinned item
becomes a normal window; you can then use all the standard window management
commands on it.
One often-pinned window that is no longer pinnable is the text editor’s Find dialog box.
Under CDE, the window closes as soon as you click FIND>FORWARD or
FIND>BACKWARD. However, there is a workaround for this issue. When you perform the
search, click MENU on the action (FORWARD or BACKWARD). Find searches for the
specified text and the dialog box remains open.
• Double-clicking a window’s title bar maximizes the window (enlarges it to cover the
entire screen) in CDE. In OpenWindows, double-clicking a window’s title bar caused it
to expand to the height but not the width of the screen.
• The Front Panel (see figure 2-9) is a CDE-specific feature. This contains single-click
shortcuts to a number of common applications, such as the mail tool, the text editor, and
desktop properties, as well as common functions, such as locking the screen and
logging out. It also includes the selector buttons for the various workspaces.
Figure 2-9. CDE’s Front Panel
• CDE introduces multiple workspaces. Workspaces function as “virtual desktops.” Each
workspace can have its own backdrop. Programs usually start in one workspace, but
they can occupy two or more workspaces (or all workspaces). You can add, rename,
and delete workspaces; CDE normally starts with four. For more information on
managing workspaces, please see the CDE 1.0 User's Guide.
• Pull-down menus use different mouse actions. In OpenWindows, you click MENU to pull
down the menu. In CDE, you click SELECT to pull down the menu.
IMAGE Solutions V8.3 2-14
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
Displaying Alarm and Error Messages
When running under OpenWindows, IMAGE directs alarms and status and error messages
to the console or terminal from which you invoked IMAGE. However, this is not always
possible when running under the Common Desktop Environment. To allow for a common
collection point for system messages, IMAGE includes the Alarm Manager. For more on
Alarm Manager, please see “Reporting Alarms” on page 22-5.
Basic User Commands
Once you log in, whether you perform a standard login to Solaris or log in to Solaris through
an IMAGE station window, you can type in and execute Solaris commands. If you performed
a standard login, type in the command and press RETURN. If you are in the IMAGE
environment, you must place the pointer within the area bordering the station window login
prompt which contains the system prompt after login. Place the pointer into this area to
“activate” the station window. If you do not place the pointer in this area, the material you
type is not received by the system and is not executed.
Changing Passwords
NOTE
Before changing your password, check with your system manager. Your system may be
networked to other systems, requiring a different command to change passwords.
To give yourself a password or to change your existing password, type passwd. The system
prints a message on your screen that a password change for your account is in progress.
If you have a current password, the system prompts you to enter it. Type in your old
password and press RETURN. If you do not have an existing password, you do not receive
the prompt for an old password.
The system then prompts you for your new password. Type in the new password, (the
system requires passwords of six or more characters) and press RETURN. The system
prompts you again for the new password. Type in your new password a second time and
press RETURN. The system checks the spelling against the first new password entry. If the
spelling of both entries matches, the system accepts your new password as the password
for your future logins.
Clearing the Screen
As you work on the workstation, typing in commands and printing to the screen, the screen
fills and scrolls downward placing the system prompt further to the bottom of the screen. To
clear the screen and place the system prompt at the top of the screen, type clear.
IMAGE Solutions V8.3 2-15
IMAGE Base Language: UNIX and Solaris: Introduction to Solaris
Table of Contents Index Home Master Index Search Help
Showing the Date and Time
To print the date and time on your screen, type date.
IMAGE Solutions V8.3 2-16
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
File and Directory Commands
Working With Directories
Finding Out What Directory You are In
After login, the system places you in your user account and in your home directory. At this
point the home directory is the current working directory and any file or directory commands
issued without a path affect only the current working directory. You can change or move to
another directory at any time.
To verify what directory you are in, type pwd. The command pwd stands for “print working
directory.” The working directory is the directory you are in at that moment. When pwd is
executed, the system prints the path of the current working directory on the screen.
Your home directory is usually not the directory where work is done. You generally will have
several levels of directories in your home directory and will move to a specific subdirectory
to do the tasks you want to accomplish.
To move to a directory one level down from the current working directory, type the command
cd followed by the name of the directory, then press RETURN. That directory becomes the
current working directory.
In figure 2-10 user bill starts in his home directory which is named after his user account
name. To move to directory dir1, one level down from his home directory, he types cd
dir1.
IMAGE Solutions V8.3 2-17
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
root
/
bin etc home
/bin /etc /home
bill
/home/bill
dir1 dir2
/home/bill/dir1 /home/bill/dir2
codedir
/home/bill/dir1/codedir
myfile1.tl myfile2.tl
/home/bill/dir1/codedir/myfile1.tl /home/bill/dir1/codedir/myfile2.tl
Figure 2-10. Moving to a Different Directory
At that point, directory dir1 becomes his working directory. To get to directory codedir,
which is where his source code programming files are, he types cd codedir. At that point,
directory codedir becomes his working directory. He can issue commands or use an editor
and all his work will be associated with directory codedir.
Using the cd command with a directory name contained within the current working directory
only shifts one level downward at a time. To jump to a subdirectory several levels
downward, or to go upwards by several levels, you must use a relative or rooted path. In
figure 2-10, for example, to move directly from directory bill to subdirectory codedir, you
would type cd dir1/codedir.
To return to your home directory from any subdirectory, simply type cd and press Return.
IMAGE Solutions V8.3 2-18
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
Listing Directory Contents to the Screen
To list the contents of a directory, enter the command ls. This puts the contents of the
current working directory on your screen. To see the contents of a directory other than the
current working directory, you must use a path.
If user bill is in his home directory (figure 2-10) and wants a list of its contents, he types
ls. If he is in his home directory and wants a list of the contents of any of the directories
contained in his home directory, he types ls, the name of directory he wants, and presses
Return. (The name of the directory is all the path needed at this point because the desired
directory is only one level down.)
For example, ls dir2 can access directory dir2 because it is one level down from user
bill’s home directory and at this point the home directory is the current working directory.
If he is in his home directory and wishes a list of the contents of directory codedir, he can
use the cd command to move down the levels to directory codedir, then use the ls
command. A more direct approach is to type
ls dir1/codedir
The ls command as used in the previous paragraphs lists the names of the contents (file
names and directory names) of a directory in alphabetical order. However, the ls command
has options or switches which can be used to get additional information about the contents
of a directory. Options include
-a Lists all entries including “hidden” files that begin with a period
(.).
-c Lists by time of file creation.
-l Lists in long format.
-m Lists in stream output, entries separated by commas.
-r Reverses order of listing.
-s Gives size in blocks.
-F Marks directories with /, executable files with an asterisk (*).
-R Lists recursively all directories downward and their contents.
Each directory name along the recursive path is printed on the
screen followed by a colon (:). The contents of that directory are
listed on the next line.
You can use one or more of these options. For example, command ls -acl lists all the
current working directory’s entries by time of file creation and in the long format. When
several options are combined in this manner, you can also precede each option by -. For
example, you can type:
ls -a -c -l
This is a good practice, since tester command options follow the same format.
IMAGE Solutions V8.3 2-19
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
Creating New Directories
One of the first tasks you will want to do is to create directories within your home directory
to organize various file types. Following that, you may want to create more levels of
directories to further organize and categorize your files.
The command mkdir creates one or more directories. You can use a path to create
directories at a level other than the current working directory. However, the directories in the
path must already exist; mkdir will not create them.
For example, figure 2-11 shows a list of commands and their results in text and graphic form.
User bill is in his home directory and has no other directories or files at this point. He types
mkdir sourcedir. Then he issues an ls command; directory sourcedir is shown as the
contents of his home directory. He uses the cd command to move to directory sourcedir.
Directory sourcedir now becomes the current working directory. Directory sourcedir is
empty at this point because it was just created and no work has been done in it. The
following mkdir command is issued to create a group of directories to be contained in
sourcedir:
mkdir testpro1 testpro2 testpro3
These directories will hold the source and object code files for test programs. An ls
command is issued and the three directories are shown as the contents of directory
sourcedir. User bill can now cd to any one of these directories and create files or more
subdirectories.
Removing Directories
To delete empty directories (containing no files or other directories), you must be in the
directory that contains the directory you want to delete or use a path.
Type rmdir then the names or paths of the directories to be deleted and press Return. If
the directories are empty, you can delete one or more directories with the rmdir command.
For example, the following command deletes directories dir1, dir2, and dir3:
rmdir dir1 dir2 dir3
To delete a directory and all its contents, type rm -r and the name or path of the directory
where you want deletion to begin and press Return. Beginning with the named directory,
that directory and all its contents, including all subdirectories and files, will be deleted.
Working With Files
Matching Characters for Selection, Wildcards
To list the contents of any directory (the names of the files and the subdirectories contained
in that directory), use the ls command. However, ls does not allow you to choose a
grouping of selected names. This is done using wildcards. The two wildcard characters are
the question mark (?) and the asterisk (*). The ? matches any single character in a file or
directory name. The * matches any group of zero or more characters except a name that
IMAGE Solutions V8.3 2-20
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
begins with a period (.) (The period is used for certain system files. So, for protection’s
sake, it cannot be matched.)
% mkdir sourcedir % ls % ls
sourcedir testpro1 testpro2 testpro3
% cd sourcedir
% mkdir testpro1 testpro2 testpro3
root root root
/ / /
home home home
/home /home /home
bill bill bill
/home/bill /home/bill /home/bill
sourcedir sourcedir
/home/bill/sourcedir /home/bill/sourcedir
testpro1
/home/bill/sourcedir/testpro1
testpro2
/home/bill/sourcedir/testpro2
testpro3
/home/bill/sourcedir/testpro3
Figure 2-11. Creating Directories
For example, to list all files beginning with lower case “a” type
ls a*
IMAGE Solutions V8.3 2-21
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
The display shows only the names that match, such as: abcfile, abigfile, a1_file,
a_new_directory.
Creating Files
You have several ways of getting files into your directories. You can create your own files
using one of the available text editors (such as TextEdit, the window environment editor,
and vi, a standard Solaris editor). For information on Text-Edit see Sun’s on-line Help
Viewer.
Redirection Operator
To quickly create a small text file in your current working directory, you can use the
command cat with the redirection operator greater-than (>). Type cat > and a filename and
press Return. The cursor drops down one line on your screen and you can type in any text
you wish, pressing Return to end each line. When you finish typing in the text, press Return
and Control-D. The system prompt returns to the screen. Use the ls command to verify that
the file has been stored.
To combine text files, adding one or more files to the end of another file, type cat and the
name or names of the files you want to be appended, >>, then the name of the file to which
you want to append. For example, if you have a file called records and you want to add the
text of a file called extrarecords, type:
cat extrarecords >> records
This command appends the text of extrarecords to the text of records. For more
information on redirection operators, refer to AnswerBook.
Protection Against Overwriting Files
Solaris provides minimal protection against overwriting files. If you use cat > several times,
using the same filename each time, the only text in the file is the last text you saved. The
same holds true for any command that writes to a file or for any of the editors. (An exception
is the IMAGE debug editor that automatically saves the next to the latest version for you.)
To prevent overwriting or clobbering an existing file when using redirection, each time you
log in and before you do any work, type: set noclobber. This causes the system to stop
execution of a command and tell you that you issued a command that will overwrite an
existing file. The noclobber command can also be inserted by your system manager into a
special file that executes each time a shell is created. If this is done, you need not issue the
noclobber command yourself, the system does it for you automatically.
noclobber prevents overwriting of files when using redirection operators. It does not
prevent overwriting when using commands such as cp, the copy command.
IMAGE Solutions V8.3 2-22
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
Viewing the Contents of Files
To look at the text of a file and edit that text, you must use an editor. If, however, you only
wish to view the contents of a file, type cat and the name of the file you want to view, then
press RETURN. The entire text of the file is scrolled on your screen. If the file is longer than
one screenful of text, use CONTROL-S to stop scrolling and CONTROL-Q to resume scrolling.
To cause the text to “page” one screen at a time, use the more command. Type more and
the name of the file you want to see. One screenful is displayed on your screen and a
message telling you what percentage of text has been viewed. To page through the text,
press the space bar once for each page.
Copying Files
To make a duplicate copy of a file, type cp and the name of the file to be copied, followed
by the name of the duplicate. For example, to duplicate a file called text and name the copy
duptext, type:
cp text duptext
You now have an exact duplicate of the file text under the name duptext in your current
working directory.
To copy a file from a directory on one level to a directory on another level, use the correct
path in front of each filename.
The -i or query option for cp causes Solaris to check if the duplicate filename you have
chosen already exists. If it does, Solaris displays a message asking if you want to overwrite
the contents of the existing file. If you answer y (yes) the file is overwritten. Any other answer
aborts cp.
Deleting Files
To delete a file or a group of files in a current working directory, type rm followed by the
name of the file or the names of a group of files you wish to delete, and press RETURN.
To delete files in a directory other than the current working directory, use the appropriate
paths in front of the file names.
rm has three options: -i, -r, and -f. -i is a query option. For each file in the list, Solaris
asks whether to delete or not. Type y for yes (delete), n for no (do not delete). -r deletes a
directory and all its contents (files and subdirectories). -f forces files to be deleted without
asking questions or reporting errors.
Renaming and Relocating Files
To rename a file from a current working directory, type mv and the present name of the file,
then the new name, and press Return. For example, in your current working directory you
have a file called textfile and you want to rename it to asciifile. Type:
mv textfile asciifile
IMAGE Solutions V8.3 2-23
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
To rename files outside the current working directory, you must use a path in front of both
the present filename and the new filename.
An option for mv is -i. This queries you if the new filename already exists.
You can also use the mv command to transfer files from a current working directory to any
directory one level down. The command mv newfile xdir moves the file newfile from the
current working directory to directory xdir as long as xdir resides in the current working
directory. A group of files can be moved in this same manner. For example:
mv file1 file2 file3 file4 xdir
To move files from a current working directory to a directory several levels down, you must
use a path in front of the directory name. Files can only be moved within the same file
system.
File Protection
See the AnswerBook documentation for information on file and directory security using the
chmod command.
Text Utilities
Printing Files
To print a file in a current working directory, type lpr and the name of the file and press
Return. For example, for a file called goodfile, type: lpr goodfile. The lpr command
sends the file to the default printer queue. Your file is printed with any other files in the
queue. To print a file in a directory other than the current working directory, you must use a
path in front of the file.
To print several files, type lpr and the names of the files you want printed and press
RETURN.
To check the contents of a printer queue, type lpq. A message appears on your screen
giving the files queued up to be printed by rank, owner, queue file number, filename, and
number of characters in the file.
To delete a file from a queue, use the lpq command to find out the ID number, then type
lprm and the file ID number for your file, and press RETURN. Your file is removed from the
queue. If you have several files in a queue, you can remove all of them by typing lprm -.
If you are using Solaris 2, the print commands are different. Use the command lp to print a
file. Use the lpstat command to get the status of the queue, and use the cancel command
to remove a file from the print queue. You can also select PROGRAMS>PRINT TOOL from the
Workspace menu to access these printer functions.
IMAGE Solutions V8.3 2-24
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
Formatting Files
The lpr (or lp) command sends the file as it is to the printer. There is no paginating or other
formatting of the contents of the file. Simple formatting can be done using the pr command
and the > redirection operator, as in:
pr myfile > myfile.pr
This formats the file myfile by pr and places the results in a file called myfile.pr. Adding
the extension .pr is a convention that tells you that the contents of a file have been
formatted by pr. Once a file is formatted, the formatted version can be sent to the printer.
The pr command formats are:
• 66 lines to a page with a two line margin at the top
• Heading of: date/time, filename, page number after top margin
• Two blank lines after heading
• Five line bottom margin
After formatting a file, you can send the formatted version to the printer using lpr, for
example, lpr myfile.pr. (If you are using Solaris 2, the command would be lp
myfile.pr.)
Locating Files
Starting from a named directory, find begins at the named directory and recursively
searches through that directory and all subdirectories downward from the named directory
to try to locate a file or group of files. If find is successful in its search, it displays the path
or paths where the search criterion found a match. A model for the find command is:
find <directory path> <search criterion> <action>
For example, in a system called temple, the path for the home directory of a user named
bill is: /user/temple/bill. (To find your user path, use the pwd command when you are
in your home directory.) Bill has over twenty subdirectories in his directory structure and
hundreds of files. He has forgotten where a file named textfile44 is and wants to use the
find command to search out, locate, and report to him textfile44’s path. He types:
find /home/temple/bill -name textfile44 -print
The path for the search begins in his home directory, /home/temple/bill. The -name
option followed by textfile44 means “match this name.” The -print option means “print
to the screen the full path or paths of the location of any match of textfile44.”
When the search is finished, the display shows:
/home/temple/bill/newdir/textdir/textfile44
This means that textfile44 resides in subdirectory textdir, one level down from
subdirectory newdir which resides in the home directory.
For more uses of find, see the AnswerBook documentation.
IMAGE Solutions V8.3 2-25
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
Searching Files for Character Patterns
The grep command searches a named file or files for a given string of characters, and prints
out the lines from the file where there is a match. If a group of files is searched, the name
of each file and the lines where there is a match are printed. If, for example, you have a file
called mytext in your current working directory and are wondering if you had edited the file
and put in the word superscript, type:
grep superscript mytext
After grep finishes executing, any lines in file mytext containing the word superscript are
displayed on the screen. This is useful, but not as useful as knowing the line numbers of
each line as well as the line itself. The -n option does that for you by printing the line number
of each line where a match exists as well as the line itself. grep -n superscript mytext
prints the line number of each line which contains the word superscript, then the actual
text of each line containing superscript. To use a phrase as a search criterion, put the
phrase between single quotes, as in:
grep -n 'Four score and twenty' lincolnfile
You can search several files for a pattern string by just listing the files. For example, to
search files mytext, yourtext, hertext use:
grep -n 'a horse, a horse' mytext yourtext hertext
To search files in other than the current working directory, use the correct path for each
directory.
For more information on grep see the AnswerBook documentation.
Comparing Files
You may want or need to compare the contents of two files. Perhaps you have edited a file
and kept a copy of the original. You would like to compare the original file against the edited
file to learn what edits you made. The diff command does this by providing you with line
numbers and markers plus displaying nonmatching lines on the screen.
For example, two files are named firstfile and secfile. The contents of firstfile is:
able
baker
charles
donald
The contents of secfile is:
able
baker
charles
douglas
Typing diff firstfile secfile causes diff to compare the files and put this message
on the screen:
IMAGE Solutions V8.3 2-26
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
4c4
<donald
---
>douglas
This needs some interpretation. 4c4 means there is a change between line 4 of the first file
(firstfile) and line 4 of the second file (secfile). <donald means the text donald is the
contents of line 4 from the first file. >douglas means the text douglas is the contents of line
4 from the second file. This allows you to quickly scan through and find the differences
between the two files. For more information on diff see the AnswerBook documentation.
Working With the C Shell
A shell not only acts as a command line interpreter, but also provides shortcuts for doing
work. These include useful abbreviations and special files that can make work easier and
more efficient.
A shell also has a set of special variables called shell variables. You can set the values of
these variables on a one-time individual basis by issuing a command from the keyboard, or
you can access them from files such as .login or .cshrc. Using the values of the shell
variables (or in some cases, a feature alone, like the alias feature described below), an
action or feature can be performed which saves time and typing.
Directory Abbreviations
Three short forms for directories are:
. (period) Is the current working directory.
.. (double period) Is the directory one level above the current working directory.
~ (tilde) Is the home directory.
A user named bill has the following directory path:
/home/temple/bill/dirA/dirB/dirC
His home directory is /home/temple/bill. Contained in his home directory is dirA.
Contained in dirA is subdirectory dirB. Contained in dirB is subdirectory dirC.
Bill is working in dirC, so dirC is the current working directory. Bill wants a quick check on
the contents of his home directory. He could go to his home directory and then do an ls
command, but then he would have to get back to dirC. Instead, he just types ls ~. The
contents of his home directory appear on his screen because ~ represents the full path of
his home directory.
He then wants to check the contents of dirB. To do this he must go to dirB or use a path.
However, dirB is one level above his current working directory so he just types:
ls ..
and the contents of dirB are displayed on his screen.
IMAGE Solutions V8.3 2-27
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
While doing this work, bill has remained in dirC. At this point, he would like to copy a file
named goodtext from his home directory to dirC. Rather than having to type out the full
paths for both directories, he types:
cp ~/goodtext .
The system interprets this command as “get the file goodtext from the home directory
(/home/temple/bill) and put a copy of goodtext, using the same filename, into the
current working directory (/home/temple/bill/dirA/dirB/dirC).”
Shell Variable history
You can set the history variable to store a list of commands that have been issued to the
shell. The number of commands stored depends on the value of the history variable. For
example, to have history to store 40 commands, type:
set history=40
Until you log off, history will store the latest 40 commands typed in and executed. To use
the history feature and view the stored commands, type history. A list of the commands
used up to that point is displayed on the screen. The commands are displayed in order from
oldest to newest and are numbered.
Not only can you get a list of what was previously done, but you can also use the history
feature to re-execute a command from the history list. To re-execute the most recent
command type !!. To re-execute any command from the history list type !, the number of
the command, and press Return.
More information and examples on using the history variable are in the AnswerBook
documentation.
Shell alias Feature
The alias feature enables you to create abbreviations and a kind of shorthand for a
command or a group of commands. For example, to log out of Solaris you must type logout
or exit. If you have worked with other systems, however, you may be accustomed to using
lo or bye to log out. You can set this up on a one-time basis, meaning the alias functions
until you log out, by typing:
alias lo logout
To use bye as the alias type:
alias bye logout
When you are ready to log out, type the alias name and press Return, and the alias will
function exactly as the true command functions.
As another example, perhaps you rarely use the ls command without one or more options.
You could type the following:
alias ls ls -aFR
IMAGE Solutions V8.3 2-28
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
Now any time you issue the command ls it will be interpreted as the alias and will execute
using the designated options.
Shell .login and .cshrc Files
Your system manager may have set up two utility files in your home directory. Use the ls
command with the -a option and to see if the files .login and .cshrc are in your home
directory. You must use the -a option with ls to see these file names because they begin
with a period and this “hides” them from casual use of the ls command.
The .login file generally contains information for setting up your specific terminal
environment. It is the place where you check and set environment variables. It includes
special paths and perhaps a routine that puts a login message on your screen each time
you log in. The .login file is executed only once, at login.
The .cshrc file contains specific information involving the C shell. It is the place where you
set aliases and shell-specific variables. You can work with several shells at a time and the
.cshrc file is executed each time a new shell is opened. For example, when working in the
window environment, each time you open a new window, a shell is created to take care of
the commands issued from that window.
If you have a .cshrc file in your home directory, use the cat or more command to look at
the text of the file. You may see some aliases in the file which were put there by your system
manager. This file can do some convenient work for you. Either you or your system manager
can edit this file and add commands for setting the values of the shell variables and
executing some shell features. You might enter some of your favorite aliases and set the
value for history in the .cshrc file. When this is done, the system will automatically perform
these commands for you each time a shell is opened. You then need not type them in after
each login or after moving to a new shell.
Using .login and .cshrc Files to Customize Your Environment
IMAGE ships with a central site .login file (/image/common/.login) and also allows site
administrators to tailor users’ work environments using a customizable
/image/custom/.login file.
Specifically, /image/common/.login modifies each user’s PATH variable to include IMAGE
binary paths. It also provides default settings for the environment variables
LM_LICENSE_FILE, OPENWINHOME, IMAGEBIN, and CKRBIN and some operating-system-
dependent variables.
You must have the line /image/common/.login in your .login file if you use IMAGE. (It
should already be there at this point.) If it is not, source it at the beginning of your .login
file by adding the following:
if (-e /image/common/.login) then
source /image/common/.login
endif
/image/common/.login sources the site-specific /image/custom/.login file if it exists.
You can use this file to set site-specific environment variables such as LM_LICENSE_FILE,
IMAGE Solutions V8.3 2-29
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
to modify your path to include a local binary search path, to create site-specific aliases, to
modify users’ shell prompt, and so on.
Administrators should be careful to check the state of an environment variable before
setting it to avoid clobbering any user’s specific setup. (Examples of this are in the
/image/common/.login file.)
You can start a different version of IMAGE by changing one or two environment variables.
For example, to create an alias for starting the version of IMAGE you commonly use, use a
statement such as:
alias Image.5.6 'setenv IMAGEBIN /image/bin.5.6;image'
This statement creates an alias for starting IMAGE V5.6.
IMAGE also functions using the Korn shell (ksh). The implementation is similar to the way
csh is organized. In your .profile file, insert the lines:
if [-f /image/common/.profile]; then
. /image/common/.profile
fi
The /image/common/.profile file executes the site-specific /image/custom/.profile
file if it exists.
Versions of IMAGE before V6.0 have no built-in method to allow subshells to inherit aliases.
Therefore, once a window system (OpenWindows) is started from the console, the
predefined aliases in /image/[common|custom]/.login are no longer defined in most
windows. This is confusing and makes site-specific aliases difficult to set up.
IMAGE V6.0 and later includes built-in support for site-specific aliases for the csh and the
ksh shells. A predefined /image/common/.cshrc file sources a site-specific
/image/custom/.cshrc file if it exists. To use this feature, add the following line to the
beginning of your .cshrc file:
source /image/common/.cshrc
If you frequently work on testers or workstations that do not have IMAGE installed, check
for this file before sourcing it to prevent errors. You can use:
if (-e /image/common/.cshrc) then
source /image/common/.cshrc
endif
/image/common/.cshrc defines aliases for starting all supported versions of IMAGE.
IMAGE includes a similar /image/common/.kshrc file. If you use a .kshrc file or
equivalent, you can include this file using:
if [-f /image/common/.kshrc]; then
. /image/common/.kshrc
fi
If you do not use this file, you can create a .kshrc file in your home directory. It will be
executed if you add the following lines to your .profile file:
IMAGE Solutions V8.3 2-30
IMAGE Base Language: UNIX and Solaris: File and Directory Commands
Table of Contents Index Home Master Index Search Help
export ENV
ENV=$HOME/.kshrc
Note that the execution order of .login/.cshrc is different than that of .profile/.kshrc.
When a csh login shell executes, the .cshrc file is executed first followed by .login. When
using ksh, the .profile is executed first followed by .kshrc if you have set the ENV
environment variable.
Note that the files /image/custom/.login and /image/custom/.cshrc are not included
on your IMAGE distribution media. They need not exist at all. These files can be created by
site administrators to implement site customizations and will be checked for by the existing
Teradyne startup files.
IMAGE Solutions V8.3 2-31
IMAGE Base Language: UNIX and Solaris: Stopping and Rebooting the Test System
Table of Contents Index Home Master Index Search Help
Stopping and Rebooting the Test System
IMAGE is built around Solaris. This operating system includes several commands that you
can use to halt system operation and to reboot test system hardware.
To provide test system operators with some simple tools, IMAGE includes several
commands that you can use for halting and rebooting both the tester and the user
computers while you are working in the IMAGE environment. This section describes these
commands and explains their relation to equivalent Solaris commands.
These commands are located in the subdirectory /image/common. Therefore, you must be
able to source this subdirectory. See “Using .login and .cshrc Files to Customize Your
Environment” on page 2-29.
Procedures for Rebooting
This section provides two procedures for rebooting a tester. The procedures are presented
here and are explained in some detail in the following sections.
When you need to reboot, the reboot procedure you use depends on the situation you are
presented with. The following descriptions tell you which reboot procedure is appropriate:
• The software is not functioning and will not respond to commands, but the cursor will
respond to keyboard commands or to the mouse (if you are in a window environment).
In this situation, use reboot procedure A.
• The software is not functioning and will not respond to commands, and the cursor will
not respond to keyboard commands or to the mouse (if you are in a window
environment). In this situation, use reboot procedure B.
Reboot Procedure A
Use the following procedure to reboot the tester if the terminal still responds to keyboard
strokes or mouse movement:
1. Type reboot_sys or reboot_sys -fast. (The -fast parameter reboots the tester
without doing disk checks. Take the time, however, to do disk checks if you suspect file
system corruption.) You will see a series of messages that tell you that the tester is
rebooting. If you cannot type any command, or if you get the message command not
found, go to reboot procedure B.
2. When the tester reboots and the login prompt appears, log in to the tester.
Reboot Procedure B
Use the following procedure to reboot the tester if you cannot type commands or you get a
command not found message when you enter the command reboot_sys:
IMAGE Solutions V8.3 2-32
IMAGE Base Language: UNIX and Solaris: Stopping and Rebooting the Test System
Table of Contents Index Home Master Index Search Help
CAUTION
The following procedure issues an uncontrolled halt that can be dangerous to the
test system software and to any data you have on your disk. An emergency halt can
corrupt the disk, forcing you to reinstall the software. Use of this command is not
advisable under most circumstances.
1. Hold down the STOP (L1) key on the left side of the keyboard and press a. The display
reads:
Abort at <address>
2. When you see the ok prompt, type sync and press Return. (You may get the > prompt
at this point. If you do, type n to change the > to the ok prompt.) The display reads:
Panic Zero
3. This command synchronizes the file systems, dumps all pages, and performs the
reboot.
4. When the tester reboots and the login prompt appears, log in to the tester.
Rebooting the Tester and User Computers
At times, you may need to reboot the tester or the user computer or both. This may occur
because some event has caused IMAGE to operate improperly and you cannot fix this
problem any other way.
The easiest way to reboot the tester computer or the user computer is to use one of the
following commands:
reboot_sys
reboot_tst
These commands are somewhat similar to the halt and reboot commands in Solaris. They
are, however, relatively easy to use because they leave the computers in a known state and
require no special privileges.
You can use the commands reboot_sys and reboot_tst from either the window
environment or the console. You need access to the /image/common/.login directory
where these commands are stored. See “Using .login and .cshrc Files to Customize Your
Environment” on page 2-29.
When you issue one of these commands, you are asked to confirm your choice:
Are you sure? (y/n)
Type y to confirm your choice and start the reboot. Type n to cancel the operation.
Rebooting Using the reboot_sys Command
The reboot_sys command reboots both the tester computer and the user computer. It
stops all jobs, synchronizes the system to make sure that all data writes to disk are
IMAGE Solutions V8.3 2-33
IMAGE Base Language: UNIX and Solaris: Stopping and Rebooting the Test System
Table of Contents Index Home Master Index Search Help
complete, reboots both computers, and gives you the Solaris login prompt. You can now
issue the image command to start the Solaris and get back to the IMAGE environment.
The reboot_sys command proceeds in the following order:
1. Halt the tester computer (the client).
2. Halt the user computer (the server).
3. Reboot the user computer.
4. Reboot the tester computer.
Once this process is complete, you may want to check that the tester computer has been
rebooted. To do this, log in to the user computer and use the tip hardwire command to
log in to the tester computer. (See “Connecting to the Tester CPU” on page 2-35.)
reboot_tst Command
The reboot_tst command allows you to reboot only the tester computer. The tester
computer’s bootup log is displayed as the tester reboots. If the bootup is successful, a
confirmation message is displayed on the screen. The syntax is:
reboot_tst [-q] [-o <filename>]
where:
-q Stops the bootlog from echoing on the screen.
-o Specifies the name of an output file. This file contains a copy of
the bootlog information.
You can interrupt the bootup process, by pressing the letter q on the keyboard three times
in a row.
Once the tester computer is rebooted, use the tip hardwire command to check it. (See
“Connecting to the Tester CPU” on page 2-35.)
Halting in IMAGE
Sometimes you may need to halt the tester or user computers without rebooting. For this
purpose, IMAGE includes the following commands:
halt_sys
halt_tst
The halt_sys command halts both the tester computer and the user computer. The
halt_tst command halts only the tester computer. When you issue one of these
commands, you are asked to confirm your choice:
Are you sure? (y/n)
Type y to confirm your choice and start the halt. Type n to cancel the operation.
These commands are somewhat similar to the halt command in Solaris. Like reboot_sys
and reboot_tst, there are no restrictions on the halt_sys and halt_tst command.
IMAGE Solutions V8.3 2-34
IMAGE Base Language: UNIX and Solaris: Stopping and Rebooting the Test System
Table of Contents Index Home Master Index Search Help
When you use the halt_tst command, a few lines from the tester computer are displayed
on the screen. If the halt is successful, a confirmation message is also displayed on the
screen. The syntax is:
halt_tst [-q] [-o <filename>]
where:
-q Stops the messages from echoing on the screen.
-o Specifies the name of an output file. This file contains a copy of
the messages displayed on the screen.
You can interrupt the bootup process by pressing the letter q on the keyboard three times
in a row.
Both the halt_sys and the halt_tst commands provide a controlled halt. They stop all
jobs, synchronize the system to make sure that all data writes to disk are complete, and give
you the Solaris greater-than prompt (also called the “PROM monitor” prompt). At this point,
you can reboot the user computer by entering b and pressing Return. (The benefit of using
the reboot_sys and reboot_tst commands is that the reboot is performed automatically.)
Emergency Halt
One other command available is an emergency halt (abort) command. This command
performs an uncontrolled halt.
CAUTION
Issuing an uncontrolled halt can be dangerous to the system software and to any
data you have on your disk. An emergency halt can corrupt the disk, forcing you to
reinstall the software. Use of this command is not advisable under most
circumstances.
To perform an emergency halt on a SPARC terminal, press STOP+A. This gives you the
greater-than prompt and the system prompts you with the following menu:
>Select one: b (boot) n (new command) c (continue)
To sync the system files, enter n. The system will display ok. You must then type sync.
Connecting to the Tester CPU
You may need to connect to the tester CPU if you have rebooted or halted the tester
computer. You do this using the command tip hardwire after logging into the system. This
command allows you to see the state of the tester computer and to execute a number of
commands on the tester computer.
IMAGE Solutions V8.3 2-35
IMAGE Base Language: UNIX and Solaris: Stopping and Rebooting the Test System
Table of Contents Index Home Master Index Search Help
To use tip hardwire, execute the following sequence of commands (user entries are in
bold print):
Login: <username><cr>
Password: xxxxxx<cr>
hostnamet# tip hardwire<cr>
connected
When you press Return, the response on the screen varies, depending on the state of the
tester CPU. You see one of the following displayed:
• PROM monitor prompt (>)—the tester CPU is halted and is at the PROM monitor. It has
not rebooted.
• Text about the boot process—the tester CPU is booting.
• Login prompt—the tester CPU is up and running.
In this mode of operation, you can use escape sequences listed in table 2-2. Of these
sequences, only ~# (send break) and ~. (exit from tip) are typically used.
Table 2-2. tip hardwire Escape Sequences
Command Action
~! Shell
~< Receive file from remote host
~> Send file to remote host
~t Take file from remote UNIX
~p Put file to remote UNIX
~| Pipe remote file
~C Connect program to remote host
~c Change directory
~. Exit from tip
~^D Exit from tip
~^Z Suspend tip
~s Set variable
~? Get this summary
~# Send break. This command brings you back to the >
prompt and connects to the test computer. Type b at this
point to boot.
IMAGE Solutions V8.3 2-36
IMAGE Base Language: IMAGE Tester Environment
Table of Contents Index Home Master Index Search Help
3 IMAGE TESTER ENVIRONMENT
The Interactive Menu-Assisted Graphics Environment (IMAGE) is the interface between the
test system user and the test system hardware. It is an integrated collection of programs
that allows you to load and run test programs, look at program output, gather data, modify
hardware operation, and debug programs. This section describes major features of IMAGE.
This section includes the following:
• “Features of the Tester Environment” on page 3-2
• “Invoking IMAGE” on page 3-3
• “Using the IMAGE Control Window” on page 3-8
• “Using Station Windows” on page 3-12
• “Getting Help in IMAGE” on page 3-25
• “Changing IMAGE” on page 3-33
• “Changing IMAGE Display Modes” on page 3-49
• “Exiting IMAGE” on page 3-54
• “IMAGE Licensing” on page 3-56
• “Using IMAGE From Remote Terminals” on page 3-67
• “Using IMAGE With FIRMS” on page 3-76
IMAGE Solutions V8.3 3-1
IMAGE Base Language: IMAGE Tester Environment: Features of the Tester Environment
Table of Contents Index Home Master Index Search Help
Features of the Tester Environment
The environment described in this section is actually the engineering mode version of
IMAGE. IMAGE also supports a production mode, described in “Production Environment”
on page 8-1, used by production operators.
Another aspect of IMAGE is the IMAGE simulator. IMAGE used with tester hardware and
the IMAGE simulator used on stand-alone workstations are almost identical.
IMAGE runs under either of two Sun windowing environments, OpenWindows or the
Common Desktop Environment (CDE). OpenWindows is documented in the Sun manual
OpenWindows Version 3 User’s Guide. CDE is documented in the CDE 1.0 User's Guide.
You should be familiar with the subjects covered in the manual appropriate to the windowing
environment you run, including using windows, menus, mouse control buttons, and scroll
bars. The Sun manuals also describe textedit, a Sun-supplied editor you can use for
general text editing.
IMAGE supports all features of the underlying windowing environments and adds many
more. Major differences between IMAGE and its host environment include the following:
• The command to start IMAGE is image. (Start OpenWindows without IMAGE using the
openwin command. If you start IMAGE from the Solaris command line, it invokes
OpenWindows prior to starting IMAGE. CDE starts automatically when you log in.)
• IMAGE uses a startup file called .image-init. (The OpenWindows start-up file is called
.openwin-init.) Programs you place in the .image-init file in your home directory
are brought up automatically when you start IMAGE.
• In certain circumstances, IMAGE uses a different Workspace menu from the window
manager. The file that specifies this root menu is located in
$IMAGEBIN/custom/.image-menu. (The environment variable IMAGEBIN stores the
path where IMAGE files are stored. To see this path use the printenv command.)
• The initial window configurations are different.
The .image files are discussed in “Additional Ways to Customize Your Environment” on
page 3-42.
For purposes of consistency, this manual assumes IMAGE is running under OpenWindows.
Where possible, the manual notes differences between OpenWindows and CDE. If you
operate under CDE, some of the displays may appear slightly different and some of the
window management commands may differ. However, IMAGE functionality and interface
do not change.
IMAGE Solutions V8.3 3-2
IMAGE Base Language: IMAGE Tester Environment: Invoking IMAGE
Table of Contents Index Home Master Index Search Help
Invoking IMAGE
Once you log in to a workstation (see “Login Procedures” on page 2-6), invoke IMAGE by
typing image from a command prompt. The syntax for this command is:
image [-production | -engineering] [-source <dir>] [-nographics]
[-nomouse] [-help]
where:
-production Starts IMAGE in production mode. (See “Starting IMAGE in
Production Mode” on page 8-5.)
-engineering Starts IMAGE in engineering mode. This mode is described in
this chapter. (This is the default.)
-source <dir> Specifies the directory from which to start IMAGE. You may need
to use this command when starting IMAGE from other than the
standard directory.
-nographics Starts IMAGE in the mode used with nongraphics terminals.
(See “Shell Station” on page 3-73.)
-nomouse Starts IMAGE in the type of production mode that does not use
a mouse. (This option requires that you also use the
-production option in the same command.)
-help Lists additional command options.
When you start IMAGE, the screen changes and a station window (station 1), the IMAGE
Control window (see “Using the IMAGE Control Window” on page 3-8), and a console
appear on the desktop’s background (figure 3-1). (See “Using Station Windows” on page
3-12.)
IMAGE Solutions V8.3 3-3
IMAGE Base Language: IMAGE Tester Environment: Invoking IMAGE
Table of Contents Index Home Master Index Search Help
Station
IMAGE Control Icon
window
Station
window
Console
window
Figure 3-1. IMAGE Window Environment in OpenWindows
When the station window first appears, the control panel is blank as shown in figure 3-1.
When you log in to the window (by entering your account name and password), the station
changes to include control panel buttons, as shown in figure 3-6 on page 3-12.
Figure 3-2 on page 3-5 shows a CDE desktop with a new station window.
IMAGE Solutions V8.3 3-4
IMAGE Base Language: IMAGE Tester Environment: Invoking IMAGE
Table of Contents Index Home Master Index Search Help
Icon on desktop Console window
IMAGE
Control
window
Station
window
Front
Panel
Figure 3-2. The IMAGE Window Environment in CDE
Authentication Security
By default, Solaris 2 starts IMAGE or OpenWindows with authentication security (the -auth
switch) which prevents another user from logging in to the station window. To override this
do either of the following:
• On IMAGE startup, enter xhost + <hostname> (do xhost - <hostname> on exit).
• When starting IMAGE or OpenWindows, use the -noauth switch.
IMAGE Workspace Menu
Like OpenWindows, IMAGE includes a Workspace menu for the window environment
(figure 3-6). To display this menu, move the pointer to the gray background area of the
screen and press the MENU mouse button.
IMAGE Solutions V8.3 3-5
IMAGE Base Language: IMAGE Tester Environment: Invoking IMAGE
Table of Contents Index Home Master Index Search Help
NOTE
The IMAGE-specific Workspace menu is available only if you start IMAGE from a text-only
login. If you start IMAGE any other way, it uses the window manager’s default Workspace
menu, which does not include the IMAGE-specific items.
Figure 3-3. IMAGE Workspace Menu
Six menu items are the same as for OpenWindows. INITIALIZE, NEW STATION, and IMAGE
CONTROL are specific to IMAGE. Items on the IMAGE Workspace menu include:
PROGRAMS> Gives you a menu of tools, including TextEdit, CommandTool,
and Sun Desktop items.
NEW STATION> Creates a new IMAGE station window. (See “Opening a New
Station” on page 3-15.)
UTILITIES> Provides a menu of services helpful in daily work, including
refresh, screen locking, and saving the workspace.
PROPERTIES> Modifies OpenWindows and IMAGE defaults. See “Setting
IMAGE Properties” on page 3-34.
IMAGE CONTROL... Displays the IMAGE Control window. The IMAGE Control
window is used to configure the IMAGE simulator (see “Using
the IMAGE Control Window” on page 3-8), modify IMAGE
properties, create a new IMAGE station window, access Help,
and exit IMAGE.
INITIALIZE Initializes the test system hardware. This command scans the
tester to determine the hardware configuration so that IMAGE
can communicate with the hardware properly. After invoking
INITIALIZE, a confirmation message appears in the console
window telling you initialization is complete. See “Initialize
Command” on page 4-15.
HELP Provides help on the Sun Desktop programs and utilities.
DESKTOP INTRO Provides help to new users of the OpenWindows environment.
IMAGE Solutions V8.3 3-6
IMAGE Base Language: IMAGE Tester Environment: Invoking IMAGE
Table of Contents Index Home Master Index Search Help
EXIT Exits the IMAGE executive and the windowing environment.
(See “Exiting IMAGE” on page 3-54.)
Locking a Workstation Screen
If you need to leave your workstation unattended, you may want to lock the system to
prevent unauthorized access. When you lock a screen, the system blanks the display and
ignores any keystrokes except Return, but any processes you have running continue as
normal.
To lock the station from the OpenWindows desktop, open the Workspace Menu and select
UTILITIES>LOCK SCREEN. You can also lock the workstation screen by typing xlock
-allowaccess in any window with a shell prompt (such as a station window, a Shell Tool,
or the console).
To lock the station from the CDE desktop, click the lock icon on the Front Panel.
To unlock the screen, press RETURN and enter your password when prompted.
IMAGE Solutions V8.3 3-7
IMAGE Base Language: IMAGE Tester Environment: Using the IMAGE Control Window
Table of Contents Index Home Master Index Search Help
Using the IMAGE Control Window
The IMAGE Control window includes options to configure the IMAGE simulator. For more
information on configuring IMAGE, see “Configuring IMAGE” on page 4-1.
The IMAGE Control window is especially useful if you start IMAGE from the OpenWindows
environment. The window provides access to the following IMAGE functions:
• New Stations
• IMAGE Properties
• Initialize
These IMAGE functions are not available on the Workspace menu if you log in to the
OpenWindows environment and start IMAGE from a console window.
Accessing the IMAGE Control Window
You can access the IMAGE Control window in three ways:
• Invoke IMAGE after you log in to a workstation (see “Invoking IMAGE” on page 3-3).
• Invoke IMAGE from a console window while in the OpenWindows environment. That is,
use the openwin command to launch the OpenWindows environment after you log in to
a workstation and then type image in the console window.
• Invoke the IMAGE Control window using the imagecontrol command in a station
window.
Figure 3-4 below shows the IMAGE Control window. This window includes a namestripe
with the IMAGE version number, several menu buttons, and a message that gives the
current IMAGE configuration.
Figure 3-4. IMAGE Control Window
IMAGE Control Window Menu Items
The following sections describe menu items in the IMAGE Control window.
File Menu
READ CONFIG FROM FILE...
Displays a window that allows you to read a confsim file from
any directory. (This is the default.)
IMAGE Solutions V8.3 3-8
IMAGE Base Language: IMAGE Tester Environment: Using the IMAGE Control Window
Table of Contents Index Home Master Index Search Help
$HOME Reads a confsim file from your home directory. You can change
this accelerator to another directory using the PROPERTIES
button. See “Changing Configuration Properties” on page 4-15.
$IMAGEBIN/CUSTOM Reads a default confsim file from the directory
$IMAGEBIN/custom.
$IMAGEBIN/CUSTOM/CFG_BDS
Reads a confsim file for a config board description file from the
directory $IMAGEBIN/custom/cfg_bds.
$IMAGEBIN/CUSTOM/DIB_ADAPTORS
Reads a confsim file for a config board description file from the
directory $IMAGEBIN/custom/dib_adaptors.
WRITE CONFIG TO FILE...
Brings up a window that allows you to write the current IMAGE
configuration to any directory. For a more information on
configuring IMAGE, see “Reading and Writing Configuration
Files” on page 4-3.
INITIALIZE Initializes the test system (see “Initialize Command” on page
4-15).
IMAGE PROPERTIES Brings up the IMAGE properties window (see “Changing IMAGE”
on page 3-33).
View Menu
The VIEW menu options include the following:
SHOW BASE CONFIGURATION...
Shows a summary of the hardware in the current configuration.
(This is the default.)
SHOW DETAILED CONFIGURATION...
Shows a detailed report of the current configuration in confsim
file format.
SHOW SKELETON PINMAP
Shows a pinmap for the current configuration and station with
entries for all available channels.
SHOW CURRENT CONFIG BOARD FILE
Shows the contents of the configuration board file corresponding
to the currently mounted configuration board.
SHOW OTHER CONFIG BOARD FILE
Shows the contents of any configuration board description file
either in your home directory or in the directory
$IMAGEBIN/custom/cfg_bds.
IMAGE Solutions V8.3 3-9
IMAGE Base Language: IMAGE Tester Environment: Using the IMAGE Control Window
Table of Contents Index Home Master Index Search Help
EXTRACT CONFIG BOARD FILE...
Lets you specify a configuration board file to extract (see
“Extracting Config Board Files” on page 4-13).
SHOW CONFCHANGES... Shows the contents of the confchanges file if on tester
hardware. For information on viewing the current configurations,
see “Viewing Configuration Files and Pinmaps” on page 4-8.
SHOW SYSTEM & COPYRIGHT INFO...
Displays the System and Copyright Information window (figure
3-5). This window shows the current IMAGE and IMAGE checker
version, current CPU, current Solaris, and relevant copyright
messages.
Figure 3-5. Test System and Copyright Information
Stations
The STATIONS menu includes the following:
NEXT STATION... Allows you to open a new station window. Station windows are
numbered 1-10 (see “Opening a New Station” on page 3-15).
IMAGE Solutions V8.3 3-10
IMAGE Base Language: IMAGE Tester Environment: Using the IMAGE Control Window
Table of Contents Index Home Master Index Search Help
Help
HELP Allows you to access the IMAGE Help window (QUICK HELP) or
IMAGE Solutions (MANUALS). (See “Getting Help in IMAGE” on
page 3-25.)
Exit IMAGE
EXIT IMAGE Exits the current IMAGE session. The OpenWindows
environment does not exit. (See “Exiting IMAGE” on page 3-54.)
IMAGE Solutions V8.3 3-11
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
Using Station Windows
A IMAGE station window is a window from which you control testing and debugging and
into which test programs are loaded.
Parts of the Station Window
Figure 3-6 shows an IMAGE station window after logging in with no test program loaded. A
station window includes the following areas:
• The namestripe at the top of the window includes information about the station
including the name of the tester, the station number, the name of any test program you
have loaded into the station, and the environment mode (Engineering or Production).
• The control panel contains items for mouse commands and the station window icon
and allows drag and drop operations with the File Manager.
• The terminal pane is used for entering command lines.
• The scrollbar (if window is set for scrolling) allows you to move up and down through
text. (See “Using a Scrollable Station Window” on page 3-17.)
When you load a test program and enter debug, the Source window appears above the
station window. (See “Using the Source Window” on page 7-5.)
Namestripe
Control Panel
Terminal pane
Figure 3-6. Parts of an IMAGE Station Window
Each station window initially appears with the station login prompt in the terminal pane. (You
can disable this login prompt. See “Global Station Window Options” on page 3-34.) Log in
to each station separately. (See “Logging In and Out of Station Windows” on page 3-23.)
Station Window Icon
When a station window is closed, the icon for that station (figure 3-1 on page 3-4) includes
the station’s number and the name of the tester. At the bottom, stations 1–4 also show the
type of test head:
• CATALYST
IMAGE Solutions V8.3 3-12
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
• TIGER
If a test program is loaded into the station, the icon shows the name of a test program.
(Because of limited space, only the first nine letters of a program name are displayed.)
Auxiliary station icons only include the name of any program loaded.
When stations connected to a test head are open, the icon (located in the control panel)
always lists the test head type. Any test program loaded is displayed in the namestripe of
an open window. Auxiliary stations only display loaded test programs in the namestripe.
Station Window Control Panel
The station window control panel contains two rows of buttons (three when you are in debug
mode) that allow you to invoke IMAGE commands using the mouse. Invoke these
commands by clicking SELECT. When you click SELECT, the command is issued and
executed immediately.
Some buttons are menu buttons. When you press MENU, the menu appears and you can
select a command. The command you get by clicking SELECT is the same as you would
get by selecting the default menu item with MENU. You cannot access buttons that are
inactive (grayed out).
The station window has the following buttons:
LOAD> Allows you to load a test program. See “Loading and Running
Test Programs” on page 5-1.
RUN> Runs a test program. This item is grayed out if no program is
loaded. See “Running Test Programs” on page 5-21.
START LOOP> Starts running a test program repeatedly. This item is grayed out
if no program is loaded. See “Looping a Test Program” on page
5-26.
DEBUG Enters debug mode for a test program. This item is grayed out if
no program is loaded. See “Entering Debug” on page 7-2.
ABORT Stops any command to the test program. This item is grayed out
if no program is loaded. See “Aborting a Test Program” on page
5-28.
HELP> Brings up the IMAGE Help window or IMAGE Solutions. See
“Getting Help in IMAGE” on page 3-25.
CATD> Allows you to enter the ProGen utility. You must have purchased
a license to use ProGen. See the ProGen Users’ Manual.
USER POWER> Controls power to application circuitry on the device interface
board on the test head. This item is grayed out if no program is
loaded. See “Controlling User Power” on page 5-28.
DATA> Sets up data collection from the test program. This item is grayed
out if no program is loaded. See “Datalog Setup Using the Data
Collection Setup Display” on page 6-14.
IMAGE Solutions V8.3 3-13
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
DISPLAY> Selects a debug display for debugging a test program. This item
is grayed out if no program is loaded. See “Debug Displays” on
page 7-47.
USER> Available for user-defined commands. To change this menu,
copy $IMAGEBIN/custom/.usermenu to $HOME and edit it. See
“Defining the User Button” on page 3-45.
PROD Changes from engineering environment to production
environment. See “Switching Between Production Mode and
Engineering Mode” on page 8-5.
CHECKERS> Loads and runs programs which check test system hardware.
See “Checkers” on page 19-1.
COMM> Allows you to select the handler/prober communications
displays. See “Debugging the Handler/Prober Interface” on page
3-1 in the Handler/Prober Manual.
Station window buttons work by issuing a command line. When you click on a button, you
see the equivalent IMAGE command line displayed in the terminal pane. (The exception is
the abort command. See “Aborting a Test Program” on page 5-28.)
Terminal Pane
The terminal pane allows you to enter command lines, either IMAGE commands or Solaris
commands. Test program inputs and outputs (such as commands you input and datalog or
summary output) are displayed in this region. By default, tester commands refer to the
station at which they were typed. The terminal pane has its own pop-up menu that allows
you to control such functions as scrolling and editing.
Displaying Station Window Information
IMAGE includes a command to display information about any station window. This
information includes whether the station is in engineering or production mode, whether it is
in debug, what test program is loaded, and the test head type of the station. The syntax is
station_info [-station #] [-mode] [-debugmode] [-program] [-type]
where:
-station # Specifies the station number. This parameter is not required
when the command is run in a station window.
-mode Displays the station mode, either ENGINEERING or PRODUCTION.
Note that the station window mode may differ from the mode of
the current lot. See the showlot command in “Displaying Lot
Information” on page 6-11.
-debugmode Displays whether the station is in debug (DEBUG) or not in debug
(NODEBUG).
IMAGE Solutions V8.3 3-14
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
-program Displays the name of the loaded test program or NO_PROGRAM if
none is loaded.
-type Displays station tester type as one of the following:
Catalyst—Catalyst station
Tiger—Catalyst Tiger station
Empty—Station has no test head type (used for auxiliary
stations)
Unknown—Unknown station type
If you issue this command with any parameters, output is returned on one line without
keywords. An example would be:
% station_info -debugmode -program
DEBUG dc_dual_site
If you issue the station_info command with no parameters, all station information is
returned. An example would be:
% station_info
Mode: ENGINEERING
Debug: DEBUG
Program: dc_dual_site
Type: Tiger
Opening a New Station
You can open a new station using the IMAGE Workspace menu, the IMAGE Control
window, or the station command.
You can open and log in to as many as seven station windows at one time. If you attempt
to open more than seven, IMAGE displays a message that the station you are trying to open
is in use, as in:
Station #8 is already in use
Using the IMAGE Workspace Menu
You can open a new station by selecting NEW STATION on the IMAGE Workspace menu
(figure 3-7). Click SELECT on NEW STATION to open the next numbered station (the default)
or press MENU and select a station.
IMAGE Solutions V8.3 3-15
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
Figure 3-7. IMAGE Workspace NEW STATION Pull-right Menu
Using the IMAGE Control Window
You can open a new station using the STATIONS button on the IMAGE Control window
(figure 3-8). Click SELECT on STATIONS to open the next numbered station (the default) or
press MENU and select a station. Use this option if you have started IMAGE from the
console window.
Figure 3-8. IMAGE Control Window NEW STATION Pull-right Menu
Using the station Command
You can also open station windows using the following command:
station [-station #] [-nographics] [<window attributes>]
where:
-station # Opens the specified station number.
-nographics Opens a nongraphics station window for use with a remote shell.
window attributes Are standard X or Sun command line arguments for specifying
the size and position of the window. See the OpenWindows3
User’s Guide.
IMAGE Solutions V8.3 3-16
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
Types of IMAGE Stations
IMAGE includes several types of stations.
Test stations are permanently connected to the corresponding test heads on the tester:
• On a Catalyst tester, stations 1–2 are connected to Catalyst test heads 1–2.
• On a Catalyst Tiger tester, station 1 is connected to Catalyst test head 1.
Auxiliary stations are as follows:
• Stations 3–10 for Catalyst testers
• Stations 2–10 for Catalyst Tiger testers
Auxiliary stations are not connected to a test head. Use these stations to load additional test
programs and attach these stations to a test head later. (See “Choosing Test-Head Type
When Loading an Auxiliary Station” on page 5-10.)
Remote station windows and shell windows allow you to perform operations on a test
program loaded on the tester from a remote workstation. (See “Using IMAGE From Remote
Terminals” on page 3-67.)
The type of station windows displayed (Catalyst or Catalyst Tiger) is determined by the type
of tester to which your workstation is connected. If you are running IMAGE in simulation, the
type of station windows displayed is determined by the content of the confsim file you are
using. (See “Configuring IMAGE” on page 4-1.) By default, the IMAGE simulator displays
an advanced mixed-signal station 1 window when you log in to IMAGE.
Using a Scrollable Station Window
You can configure a station window in one of two modes: nonscrollable (figure 3-1 on page
3-4) and scrollable (figure 3-6 on page 3-12). The default configuration is a nonscrollable
station window, but you can change the default to a scrollable station window using the
IMAGE Properties window.
The scrollable station window is similar to the Sun CommandTool in appearance and
function, but you cannot edit the output displayed in the scrollable station window. Data is
written to the station window until the maximum display size is reached, then the oldest
output is erased. You can select the maximum display size before bringing up a station
window using the IMAGE Properties window. After the station window is brought up, you
cannot change the display size for the life of the station window.
The scrollable station window maintains its display using files kept in the /tmp directory.
These files remain a specific size and do not fill up the directory. If you inadvertently delete
these files, the scrollable station window reverts to nonscrollable mode. The /tmp directory
can be filled by other files in the /tmp directory. If this occurs, the station window also reverts
to nonscrollable mode.
IMAGE Solutions V8.3 3-17
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
NOTE
Directory listings and other listings in the station window may appear uneven. Type stty
-tabs in the station window to correct the tab stops.
Selecting a Scrollable Station Window
To select scrollable station windows as the default do the following:
1. Press MENU to display the IMAGE Workspace menu and select PROPERTIES>IMAGE
PROPERTIES. This displays the IMAGE Properties window.
2. In the IMAGE Properties window, press MENU on the menu button next to CATEGORY
at the top of the window and select PER-USER STATION WINDOW OPTIONS. The window
changes to display the options (figure 3-9).
3. Press MENU on the SCROLLABLE STATION WINDOW menu button and select TRUE.
Figure 3-9. IMAGE Properties Scrolling Window Options
4. Change the SIZE OF COMMAND LOG option by clicking SELECT on the number and
changing it. This option determines how many bytes are saved in a scrollable station
window. The default is 50,000 bytes. The maximum size is 100,000 bytes.
5. Click SELECT APPLY to set the new defaults or click RESET to set the defaults to the
values as they were set the last time your clicked APPLY.
IMAGE Solutions V8.3 3-18
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
Enabling Scrolling for a Station Window
A station window has a menu in its terminal pane. A scrolling window has a menu similar to
a Sun Command Tool menu. A nonscrolling window has a menu similar to a Shell Tool
window. Each of these menus has a scrolling item that you can use to enable or disable
scrolling.
To enable scrolling:
1. Move the pointer to the terminal pane of the nonscrolling station window.
2. Press MENU. The terminal pane menu appears.
3. Select ENABLE SCROLLING and release MENU. The window changes to scrolling.
To disable scrolling:
1. Move the pointer to the terminal pane of the scrolling station window.
2. Press MENU. The terminal pane menu appears.
3. Select SCROLLING>DISABLE SCROLLING and release the button.
NOTE
When switching between scrolling and nonscrolling station windows, previously displayed
output is lost.
Printing Windows in IMAGE
IMAGE V5.7 and later includes a print option in debug displays. The print option can be
found on most IMAGE displays, except the Immediate window, the station window, and the
simdbase window. This feature allows you to easily take a snapshot of a window as it is
displayed on your screen and send it to either a PostScript printer or a PostScript file.
Using the Print Option
The print option is in one of two places in each debug display: in the FILE menu or displayed
as a separate PRINT button.
If the display has a FILE menu button, the print option is in the menu for that button, with a
submenu providing the choice of printing to the default destination or to another destination.
Selecting the PRINT menu choice or selecting DEFAULT PRINTER from the submenu sends
the printout to the default printer.
If the display has no FILE button, a PRINT menu button is placed on the far right of the first
row of buttons. The menu for this button allows you to print to the default destination or to
another destination. Click the PRINT button or select DEFAULT PRINTER from the menu to
send the printout to the default destination.
If you choose OTHER DESTINATION from any PRINT menu, the IMAGE Window Printing
display appears (figure 3-10). This display allows you to send PostScript image to either a
IMAGE Solutions V8.3 3-19
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
file or to any printer you specify and to control color printing. The display includes the
following items:
CAPTURED WINDOW Lists the type of window.
OUTPUT WINDOW IMAGE TO
Selects whether to send the window to a POSTSCRIPT PRINTER
(the default) or to a POSTSCRIPT FILE. If you select a printer, you
need to fill in the PRINTER NAME item. If you select a file, the
PRINTER NAME item changes to DIR and FILE entries. You can
specify a directory and a filename in these fields. You can also
navigate directories using the menu for the DIR item.
Figure 3-10. IMAGE Window Printing Display
COLOR OUTPUT Selects color printing. OFF produces a gray scale image or file.
The default is OFF.
COMPRESSION Reduces the size of the PostScript file. This option saves disk
space but increases the time needed to print the file. The default
is OFF.
PRINTER NAME Specifies the name of the printer to print the PostScript image.
The display puts the lw entry in this field by default. If you do not
change this entry, the image is sent to the lw printer.
PRINT COMMAND (TO $DEST)
Specifies the command line of the process to use for printing. All
occurrences of the keystring $DEST in the command line are
replaced by the printer name. If left blank, the print command
defaults to
lpr -P$DEST in Solaris 1 or
lp -d$DEST in Solaris 2.
PRINT Sends the image to a printer or file. Click on this button when you
finish specifying items in the display.
CANCEL Cancels the print request. The window disappears.
IMAGE Solutions V8.3 3-20
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
Setting Window Printing Properties
The print option can manipulate a captured window image before sending it to its final
destination. The IMAGE Properties tool allows you to change how the image is manipulated.
Select WINDOW PRINTING from the IMAGE Properties window (figure 3-11). (See “Setting
IMAGE Properties” on page 3-34 for more information on IMAGE properties.)
Figure 3-11. IMAGE Window Printing Properties
The window printing properties are as follows:
DEFAULT PRINTER Specifies the default printer. Choice of:
ALWAYS SEND TO SPECIFIED PRINTER
The printer named in the field PRINTER NAME is the default
destination.
USE $GFXPRINTER ENVIRONMENT VARIABLE
The value of the GFXPRINTER environment variable is used as
the default printer. (This is the default.)
PRINTER NAME Specifies the default printer choice. This item is grayed out if you
choose USE $GFXPRINTER ENVIRONMENT VARIABLE.
PRINT COMMAND Specifies the command line of the process to use for printing. All
occurrences of the keystring $DEST in the command line are
replaced by the printer name. If left blank, the print command
defaults to
IMAGE Solutions V8.3 3-21
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
lpr -P$DEST in Solaris 1 or
lp -d$DEST in Solaris 2.
ORIENTATION Specifies printout orientation as one of the following:
APPROPRIATE FOR CAPTURED WINDOW
Chooses the best orientation for the printout based on the
window dimensions. Windows longer than they are wide are
printed in portrait. Windows wider than they are long are printed
in landscape. The resulting image is the maximum possible size.
(This is the default.)
ALWAYS LANDSCAPE (WIDE) Prints the image in
landscape regardless of the window dimensions.
ALWAYS PORTRAIT (LONG) Prints the image in portrait
regardless of the window dimensions.
MARGINS Selects margins for printing as one of the following:
MARGIN FOR BINDER HOLES Adds a 3/4 in (1.9 cm)
border around the printout. (This is the default.)
MAXIMUM PRINTABLE AREA Prints to the maximum
printable area defined by the smallest common dimensions
between A4 and 8.5 x 11" paper.
COLOR PRINTING Selects color or gray scale printing.
ON Generates a color PostScript file for color monitors and
tries to print in color if the file is sent to a color printer, converting
at print time as necessary.
CONVERT TO GRAY SCALE Always converts color
images into gray scale. (This is the default.)
COMPRESSION Reduces the size of the PostScript file. This option saves disk
space but increases the time needed to print the file. The default
is OFF.
Tips on Printing
Because the print option takes screen snapshots of the window, it will not print the entire
contents of a scrollable window. It only prints what you see on the screen.
Parts of a window obscured by other windows or off-screen are not printed correctly. IMAGE
detects this and warns you with a pop-up if you are printing to the default printer or with a
message in the footer of the printing pop-up if you are printing to another destination.
When using a color monitor and a gray scale printer, choose window colors carefully. Some
colors map to the same or similar gray scale value, making the printout difficult to read.
IMAGE Solutions V8.3 3-22
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
Color PostScript files are large. If you are using a color monitor but are printing to a gray
scale printer (standard level 1 PostScript), choosing the CONVERT TO GRAY SCALE option
converts the display colors to gray scale. The resulting file is about 1/3 the size of a color file.
Leave the COLOR PRINTING option set to CONVERT TO GRAY SCALE unless you are using a
color printer. At print time, IMAGE automatically detects whether the destination printer can
print color. If the printer is a gray scale printer, IMAGE converts the color image to gray scale
at the printer. This takes additional time.
Printing Using Sun’s Snapshot
Printing windows in IMAGE is also possible using Sun’s desktop tool Snapshot. This tool
allows you to quickly create a raster file of a window, a region of the screen, or the entire
screen. Then you can save the file and print it or just print it. For more information, select
HELP from the IMAGE Workspace menu and read the handbook on Snapshot.
Logging In and Out of Station Windows
You can open several station windows and log in to each separately, up to a maximum of
seven. Thus, different users can be logged in on different stations. For example, a
production operator can be logged in on station 1 to test devices, while an engineer is
logged in on station 2 to troubleshoot a problem. Alternately, one user can load different test
programs on different stations.
You can open a station window using any of the following:
• NEW STATION menu item (IMAGE Workspace menu) has a pull-right menu that allows
you to select the station to open.
• STATIONS menu item (IMAGE Control window) has a pull-right menu that allows you to
select the station to open.
• select -station # command. Enter this command in a station window to open the
specified station if that station is not already open. (See “Switching Between Windows”
on page 8-6.)
• station -station # command. Enter this command in a station window to open the
specified station. The command station without parameters opens the next unopened
station.
When you first invoke a station window, a Station login prompt appears in the terminal
pane. (It does not appear if you have set the IMAGE Properties parameter to eliminate the
login prompt. See “Global Station Window Options” on page 3-34.) Log in to the station
window by typing your name and password. Once you have logged in, your default directory
is your top-level directory.
When you finish using a station, log out of the station by typing logout in the station
window. If a test program is loaded in the station, it is automatically deleted when you log
out. After logging out, a new Station login prompt appears in the terminal pane.
IMAGE Solutions V8.3 3-23
IMAGE Base Language: IMAGE Tester Environment: Using Station Windows
Table of Contents Index Home Master Index Search Help
If you log out with a test program loaded in the station that has unsaved changes, a warning
is displayed in the station window. You can ignore this warning by typing logout -nosave.
(See “Exiting IMAGE” on page 3-54.)
IMAGE Solutions V8.3 3-24
IMAGE Base Language: IMAGE Tester Environment: Getting Help in IMAGE
Table of Contents Index Home Master Index Search Help
Getting Help in IMAGE
IMAGE includes several sources of help. For help on IMAGE see:
• Quick Help. Using the HELP button in a station window or the HELP button in the IMAGE
Control window, brings up the IMAGE Help window. (See “Using the IMAGE Help
Window for Quick Help” on page 3-25.)
• IMAGE Solutions. Selecting HELP>USER MANUALS in the station window or from the
HELP button menu in the IMAGE Control window brings up the IMAGE Solutions
window. IMAGE Solutions contains the complete on-line IMAGE manual set. (See
“Using IMAGE Solutions to View the User Manuals” on page 3-30.)
• Spot Help. Pressing the HELP keyboard button when the pointer is over a feature in an
IMAGE window pops up a window with a brief description of the feature’s use. Clicking
MORE in this window brings up the IMAGE Help window. (See “Using Spot Help” on page
3-29.)
• The -usage switch. Enter -usage after any IMAGE command in a station window to
display the syntax for that command.
For help on Sun, see:
• Solaris AnswerBook. Sun’s AnswerBook is an on-line information system containing the
full set of Sun documentation. Invoke it by selecting PROGRAMS>ANSWERBOOK from the
Workspace menu or by typing answerbook in a window.
• The HELP and DESKTOP INTRO selections on the IMAGE Workspace menu. These
selections bring up introductory help on the available Sun utilities. “Desktop Intro” is a
basic introduction to the OpenWindows desktop.
• The Solaris man facility (see “Getting Help” on page 2-6). Access help on Solaris
commands by typing man or man man.
Using the IMAGE Help Window for Quick Help
The IMAGE Help window (figure 3-12) provides a way to get quick help on IMAGE features
and syntax. You can also cut and paste from the window to your test program. The content
of the help window changes depending on which test system you are using.
IMAGE Solutions V8.3 3-25
IMAGE Base Language: IMAGE Tester Environment: Getting Help in IMAGE
Table of Contents Index Home Master Index Search Help
Figure 3-12. IMAGE Help Window
To display the IMAGE Help window you can:
• Click the HELP button in a station window or select QUICK HELP from the button menu.
• Select HELP>QUICK HELP in the IMAGE Control window and pull right to choose help for
a specific test system type. Clicking the HELP button displays the Linear Help window.
• Type imagesolutions -quick in a station window.
• Click the MORE button in Spot Help. (See “Using Spot Help” on page 3-29.)
Help Window Features
The Help window has the following buttons:
BASE LANGUAGE Includes information on IMAGE test program syntax.
INSTRUMENTS Includes information on IMAGE test program syntax for
instruments on all types of testers. The list of instruments
depends on the type of test system you specified in the
HELP>QUICK HELP menu.
TOOLS Includes information on IMAGE window-based tools, including:
Source window menu (debug), Wave Display, sync pulses,
pattern editor, Simulator DataBase, interactive displays, IMAGE
ExPress, Histogram tool, and Shmoo tool.
IMAGE COMMANDS Includes information on IMAGE commands that can be typed
into a station window.
UNIX Includes information on common UNIX and Solaris commands,
as well as some IMAGE and CDE-related topics.
USER MANUALS Starts the IMAGE Solutions on-line utility.
CHECKERS Includes information on current checkers and checker utilities.
IMAGE Solutions V8.3 3-26
IMAGE Base Language: IMAGE Tester Environment: Getting Help in IMAGE
Table of Contents Index Home Master Index Search Help
To display help information on a topic, press MENU on a help window control panel button
and select a topic from the pull-right menu. This displays the beginning of the help text for
that topic. Use the scrollbar to scroll through the text.
The header (namestripe) of the Help window displays the type of help you are using, such
as CATALYST or CATALYST TIGER. The window’s footer displays the title of the help file you
are viewing.
Customizing Help Window Buttons
You can add your own buttons and menus to the IMAGE Help window. You cannot,
however, change the buttons already defined in the window.
Add buttons to the control panel in either of the following ways:
• Use an old custom.buttonlist file and its associated *.helplist files from an
$IMAGEBIN/custom_helpdir directory for a previous IMAGE version. To do this, create
an /image/custom_helpdir directory and copy the old files into it.
• Use cp to copy the file $IMAGEBIN/helpdir/custom.menu.example to
/image/custom_helpdir/custom.menu and modify the new file.
You can use only one of these methods at a time. If the custom.menu file exists, a
custom.buttonlist file is ignored.
The syntax of the custom.menu file is similar to that of the description files for the station
window USER buttons (see “Defining the User Button” on page 3-45) and the IMAGE
Workspace menu (see “Changing the IMAGE Workspace Menu” on page 3-44). The set of
legal keywords differs, reflecting the different purpose.
The following keywords are legal at the beginning of a line:
# This line is a comment.
NEWLINE Starts a new line of buttons.
SPACE <n> Specifies the number of screen pixels of horizontal space to put
before buttons specified after this point. For example, SPACE 2
produces a tight layout. The default spacing is 10 pixels.
GAP <n> Specifies the interline gap. This is the number of screen pixels of
vertical space to put above lines started after this point. For
example, GAP 20 gives a loose layout. The default interline gap
is 5 pixels.
MENU Begins a menu description section. The next string (usually in
double quotes) is the label for a button which invokes a menu. All
buttons specified between this line and the matching END line are
on this menu or a submenu. You can nest MENUs to any depth.
END [PIN] Indicates the end of the menu started by the last unmatched
MENU line. The optional keyword PIN, following END, makes the
menu pinnable. That is, the menu will have a pushpin on it.
IMAGE Solutions V8.3 3-27
IMAGE Base Language: IMAGE Tester Environment: Getting Help in IMAGE
Table of Contents Index Home Master Index Search Help
"any other string" A button label. Begins a line which specifies a button or menu
item and its function.
The following button function keywords are legal on a line beginning with a button label:
SHOW_FILE The next string is the name of a help file to display. IMAGE looks
for this first in $IMAGEBIN/helpdir, then the customer help
directory $IMAGEBIN/custom_helpdir. The file name should
have a .help extension to distinguish it from other types of files
in these directories, but this is not required.
EXEC The remainder of the line (stripped of leading spaces) is
executed as a UNIX command line. Use this keyword carefully.
The command’s output goes to the associated station or terminal
window. It will not always be clear which window this is. Only run
commands which either produce no output (such as mv or lpr)
or which, like help itself, create a window for all user interaction.
Note that the custom.menu file’s syntax is line oriented. For example, PIN only has meaning
when it is the second word on a line whose first word is END. Spacing, however, is
unimportant. The amount of space before, between, or after words is ignored.
Most “words” are delimited by spaces, tabs, and newline characters. For use in specifying
button and menu labels, quoted strings are also treated as one word; the quotes are not
part of the string. Within quoted strings, spacing matters. Thus, the line
MENU " My Menu "
produces a larger-than-normal menu button, useful if you want to make all your buttons of
uniform size.
Following are the contents of the custom.menu.example file in $IMAGEBIN/helpdir:
# Example Help customer button/menu definition file.
# For illustrative purposes, the "DC Inst." menu is left unpinnable.
# In most cases all menus should be pinnable.
# Make a larger than normal line spacing, to separate custom buttons.
GAP 20
# Start the new line.
NEWROW
# Reset the line spacing back to the default value.
GAP 10
# A button which loads a file directly.
"Startlot" SHOW_FILE startlot.help
# This menu has three items on it; two of them have pull-right menus.
MENU "A few instruments"
MENU "AC Inst."
"Reference source" SHOW_FILE
REFsource_syntax.help
IMAGE Solutions V8.3 3-28
IMAGE Base Language: IMAGE Tester Environment: Getting Help in IMAGE
Table of Contents Index Home Master Index Search Help
"Low freq. source" SHOW_FILE ax.help
"Low freq. digitizer" SHOW_FILE LFdig_syntax.help
"Enhanced LF source" SHOW_FILE
ENLFsource_syntax.help
"Precision LF source" SHOW_FILE plfsrc.help
"Precision LF digitizer" SHOW_FILE PLFdig_syntax.help
"High freq. source" SHOW_FILE HFsource_syntax.help
"High freq. digitizer" SHOW_FILE HFdig_syntax.help
END PIN
"Analog Pin Unit" SHOW_FILE apu.help
MENU "DC Inst."
"DC sources" SHOW_FILE dcsource_syntax.help
"DC voltmeter" SHOW_FILE
dcvoltmeter_syntax.help
END
END PIN
# This button runs a command which creates its own window.
# The full pathname for helpopen may be needed in your installation.
"Sun Textedit" EXEC helpopen handbooks/textedit.handbook
Using Spot Help
Spot Help is a feature of Sun’s window managers. It displays brief help messages when you
press the Help button on the left keypad while the pointer is over a window feature which
has a help message defined for it (figure 3-13). In some cases the pop-up window has a
MORE button on it. Clicking SELECT on this button opens another window to provide more
detailed information. For IMAGE-specific windows, MORE links to the IMAGE Help window.
Figure 3-13. IMAGE Spot Help Window
The remainder of this section discusses IMAGE support for Spot Help. This discussion does
not refer to the behavior of Spot Help in any other application.
A MORE button associated with an IMAGE window opens the IMAGE Help window with the
appropriate file displayed. This window looks much like the Help window displayed by
clicking on the station window’s HELP button. However, it has a pushpin in its header and
behaves a little differently.
IMAGE Solutions V8.3 3-29
IMAGE Base Language: IMAGE Tester Environment: Getting Help in IMAGE
Table of Contents Index Home Master Index Search Help
Normally, you can bring up several copies of an IMAGE Help window, allowing you to look
at several files at once. Using MORE buttons, however, only brings up one window. This
window is used to display all requests from Spot Help MORE buttons associated with IMAGE
windows. This allows you use Spot Help as an alternative to IMAGE help menu buttons for
displaying help files.
Using IMAGE Solutions to View the User Manuals
IMAGE Solutions is the IMAGE on-line information tool. Using IMAGE Solutions you can:
• View and print current IMAGE manuals
• Search for topics using a word search tool and on-line indexes
• Use hypertext links in the documents to go directly to cross-references
• Copy and paste code examples and syntax from on-line documents to your test program
• View Help files which describe how to use IMAGE Solutions
To invoke IMAGE Solutions:
• Select HELP>USER MANUALS
• Type imagesolutions -manuals in a station window
The HELP button is located on both the station window and the IMAGE Control window.
Select HELP>WHAT IS IMAGE SOLUTIONS... to get a summary of Solutions features.
The syntax for the imagesolutions command is:
imagesolutions [-manuals [manswitches] | -whatis | -usage |
-quick [-station # | -linear | -adv_linear | -mixsig | -adv_mixsig
| -catalyst]]
where:
-manuals Starts IMAGE Solutions and brings up the user manuals. The
Adobe Acrobat Reader appears containing a main menu of the
entire user document set (figure 3-14).
[manswitches] 6.4 | 6.3.ir1 | 6.3 | 6.2 | 6.1 | 6.0 | 5.7 | 5.6 |
5.5 | 5.4
Starts and opens the IMAGE Answers (V6.4 to V5.4) user
documentation.
IMAGE Solutions V8.3 3-30
IMAGE Base Language: IMAGE Tester Environment: Getting Help in IMAGE
Table of Contents Index Home Master Index Search Help
Figure 3-14. IMAGE Solutions Main Menu Window
-quick Brings up the IMAGE Help window. (See “Using the IMAGE Help
Window for Quick Help” on page 3-25.)
-station # Selects the station from which to bring up the IMAGE Help
window. You can omit this parameter if you use the -quick
parameter and run the command from a station window.
-whatis Brings up a window with a brief explanation of IMAGE Solutions.
-usage Displays the command syntax. For additional help on
manswitches, type imageanswers -manuals -usage.
When you start Answers in IMAGE versions before V6.4, a menu bar appears (figure 3-15)
with the following selections:
Figure 3-15. IMAGE Answers Menu Bar
MANUALS Displays the list of manuals you can access.
SEARCH Brings up the Search window.
IMAGE Solutions V8.3 3-31
IMAGE Base Language: IMAGE Tester Environment: Getting Help in IMAGE
Table of Contents Index Home Master Index Search Help
HELP Brings up IMAGE Answers on-line help.
EXIT Exits from IMAGE Answers.
IMAGE Solutions V8.3 3-32
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
Changing IMAGE
You can change properties of both OpenWindows and IMAGE. Many of these properties
can be changed using the Properties utility. Others can be changed using certain
environment files. These changes are discussed in this section. (For more information on
the OpenWindows Properties window, see the Sun manual OpenWindows Version 3 User’s
Guide.)
The general procedure for changing a default property using the Properties window is as
follows:
1. Open the Properties window (figure 3-16) in any of the following ways:
– Select FILE>IMAGE PROPERTIES... in the IMAGE Control window.
– Select PROPERTIES>IMAGE PROPERTIES or PROPERTIES>OPENWINDOWS
PROPERTIES from the IMAGE Workspace menu.
– Type the image_props command in any station window.
Figure 3-16. IMAGE Properties Window
2. Press MENU on the CATEGORY abbreviated menu button at the top of the window and
select a category.
3. Change the option in the window.
IMAGE Solutions V8.3 3-33
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
4. Click APPLY to set the new defaults or click RESET to set the property to its original value
(the value you set the last time you clicked APPLY).
The following sections describe changes you can make using the IMAGE Properties
window, as well as other features of IMAGE you can customize.
Setting IMAGE Properties
When the IMAGE Properties window (figure 3-16) first appears, it displays the global station
window options. Use the CATEGORY abbreviated menu button to display and select other
options. The following sections describe the IMAGE properties you can change.
Global Station Window Options
The global station window properties are as follows:
AUTOMATIC LOGIN Controls the station window login. When set to TRUE, you do not
have to log in to each station window. The default is FALSE.
USE PRODUCTION FONT Selects whether to use the font defined in the PRODUCTION_FONT
item in the station window command region when in production
mode. FALSE uses the regular screen font. The default is TRUE.
PRODUCTION FONT Defines the font type and size to be used in the station window
command region when in production mode. The default is
SCREEN.B.16.
ENABLE FUNCTION KEYS Defines whether function keys F1 to F5 are mapped to the
IMAGE functions RUN, HALT, CONT, STEP, and NEXT. (See “Using
Function Keys” on page 7-20.) The default is TRUE. (To remap
keyboard function keys, see “Remapping Function Keys” on
page 3-47.)
MAXIMUM MENU ITEMS BEFORE SUB-MENU CREATION
Defines the number of menu items to display before creating a
submenu for any IMAGE button. The presence of the submenu
is indicated by MORE at the end of the menu. The default is 60.
Legal values are 20 to 90. Any submenu created will contain at
least 12 items. For example:
<60 menu items = one menu
61 menu items = 49 items on main menu + 12 items on submenu
This property affects the LOAD button menus, the change file (in
station debug), CHECKERS button menus, DISPLAY button menu,
and the usermenu.
ACTION ON PMC ATTACH
Controls the station window when Production Menu Control
(PMC) attaches. (See “IMAGE Properties” on page 9-4.) The
settings are
IMAGE Solutions V8.3 3-34
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
DO NOTHING TO STATION
Nothing is done to the station window (default).
ICONIFY STATION WINDOW
Causes the station window to close down to an icon.
UNICONIFY STATION WINDOW
Reverses the iconify action.
ACTION ON PMC DETACH
Controls the station window when Production Menu Control
(PMC) detaches. (See “IMAGE Properties” on page 9-4.) The
settings are
DO NOTHING TO STATION
Nothing is done to the station window (default).
ICONIFY STATION WINDOW
Causes the station window to close down to an icon.
UNICONIFY STATION WINDOW
Reverses the iconify action.
SHOW USED LICENSES Shows or hides all licenses used by the current test program.
Select TRUE to enable display of licenses. Select FALSE (default)
to disable display of licenses.
Per-User Station Window Options
The per-user station window properties are as follows:
SCROLLABLE STATION WINDOW
Controls station window scrolling. TRUE enables scrolling. (See
“Enabling Scrolling for a Station Window” on page 3-19.) The
default is FALSE.
SIZE OF COMMAND LOG Determines number of bytes saved for a scrollable station
window. (See “Selecting a Scrollable Station Window” on page
3-18.) Default is 50,000 bytes.
LOAD FILE SELECTS Changes the pull-right menu for the LOAD button. The default is
to display all .tl and .load files. You can change the LOAD pull-
right menu to display only .tl files or only .load files.
INSERTION FOLLOWS PROGRAM
Affects operation of the source window where test program text
is displayed during debug. If this item is set to true, the source
region insertion point automatically moves to the halt line when
the test program stops running. The default is TRUE.
ICONIFY BEHAVIOR Selects how the source window is closed to an icon in relation to
the station window (the command region). The default is to close
the source window automatically when the station window
IMAGE Solutions V8.3 3-35
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
closes, but not to close the command region when you close the
source region. You can also have them close separately, have
the command region close when you close the source window,
or have them always close together.
Miscellaneous Options
The miscellaneous properties are as follows:
DEBUG DISPLAY OPTIONS
SCALE
Selects the size of debug display windows. Default size is
MEDIUM.
ERROR HANDLING
Selects the way in which debug display windows handle test
program runtime errors. DEFAULT (the default setting) handles
runtime errors in the normal way. IGNORE ignores errors. (See
“Run-Time Errors” on page 7-54.)
IMMEDIATE WINDOW OPTIONS
IMMEDIATE WINDOW FEEDBACK
Specifies the feedback given in an immediate window after an
immediate command. (See “Changing the Immediate Display
Prompt” on page 7-66.) You can change this to feedback in
comment form where the message is inserted as an IMAGE
comment (/*- imm -*/). Or you can select the message form
(--- imm ---). The default is no feedback.
CONSOLE OPTIONS TESTER OUTPUT ACTION
Specifies what the console does when a message is sent to it.
The console can open from an icon, beep, open and beep, or do
nothing. Default is OPEN.
GPIB OPTIONS ASSERT IFC DURING RESET
Specifies assertion of the IFC signal to GPIB-based handlers
and probers during a GPIB reset. FALSE asserts IFC only at
IMAGE startup. Default is TRUE. (See “Resetting the GPIB” on
page 11-13.)
CONFIG OPTIONS CONFIG DIRECTORY
Allows you to set the second item in the FILE button menu of the
IMAGE Control window. The default for this item is $HOME, but
you can use another directory to store confsim files.
HANDLER/PROBER STARTUP OPTIONS
RESET MAPPING ON STARTUP
When set to TRUE, forces IMAGE to start with all handlers and
probers disconnected. The default is FALSE, in which case
IMAGE tries to connect to whatever handlers and probers it was
connected to before exiting IMAGE.
IMAGE Solutions V8.3 3-36
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
PMC OPTIONS USE J9 STYLE PATH NAMES
Allows you to choose the ICD (default) or J9 style (IG900) path
variable settings in PMC MDL files. (See “Variable Styles” on
page 9-14.)
LOAD OPTIONS ABORT ON CONFIG MISMATCH
Tells IMAGE whether to abort (TRUE) or continue (FALSE; default)
when it detects a configuration mismatch. This performs the
same function as the -halt_on_config_mismatch option to the
load command.
Production Setup Options
The production setup properties are as follows:
TEST PROGRAM LOAD & DEBUG OPTIONS
TEST PROGRAM DIRS
Specifies the directory to use when loading test programs in
production mode.
ENABLE DEBUG COMMAND
Permits (TRUE) or prohibits (FALSE) use of the debug command
when IMAGE is in Production mode.
DATALOGGING TO FILE OPTIONS
TEST DATA DIRS
Specifies what directory to use when storing datalog data files. If
you specify a directory, all datalog, STDF, histogram,
datastream, summary, and summary STDF files are sent to this
directory.
MAX FILENAME LENGTH
Specifies the maximum number of characters for a data
filename.
RUNTIME ERROR AND ALARM HANDLING
ERROR ALARM HANDLING
Specifies where error and alarm messages are sent. The default
is sending them to the screen (SCREEN_DISPLAY). They can also
go to a log file (RECORD_IN_LOG) or to the screen and to a log file
(SCREEN_AND_LOG). See “Run-Time Error and Alarm Messages”
on page 8-43.
ALARM MESSAGE HANDLING
Specifies where alarm messages are sent. Allows you to handle
alarm messages separately from error messages. The
SAME_AS_ERROR_MESSAGES option (the default) sends alarms to
the destination set by the ERROR ALARM HANDLING property. The
SCREEN_DISPLAY option sends alarms to the screen. The
RECORD_IN_LOG option sends alarms to a log file. Format of the
alarm log name and its content are the same as for the
IMAGE Solutions V8.3 3-37
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
error/alarm log. The SCREEN_AND_LOG option sends alarms to
both the screen and a log file. The IGNORE option means do not
log or print alarm messages.
ERROR ALARM LOG LIFETIME (DAYS)
Specifies the maximum number of days before an error or alarm
log file is automatically trimmed. The default is 21 days.
Auto Checker Run Options
The auto checker run property is as follows:
REBOOT ALWAYS Specifies whether a remote tester is always rebooted before an
auto checker run. The default is TRUE.
FIRMS Interface Options
The FIRMS interface properties are as follows:
SEND NON-FIRMS FILESSpecifies whether non-FIRMS files are sent to the FIRMS host.
Default is TRUE.
SEND DATASTREAM STDF FILES TO FIRMS
Specifies whether datastream files are sent to the FIRMS host.
Default is FALSE.
SEND TESTER UTIL EVENT
Specifies whether to send t_tester_util events to the FIRMS
host. Other options (grayed out unless you select a time-based
schedule) allow you to specify event timing. Default is NEVER
(never send the events). See “Using Tester Utilization Events to
Measure Computer Usage” on page 5-34 for more information.
Datalog/Summary Options
The datalog/summary properties are as follows:
DEFAULT DATALOG FORMAT
Specifies the default format for datalog output sent to the station
window or to a text file. Options are LABEL ONLY, NO LIMITS and
LABEL, LIMITS AND TESTNAME. The default is LABEL ONLY, NO
LIMITS. For more information on datalog formats, see “Output
Format” on page 6-41. (This does not change the default format
or the options available when using tl_set_datalog.)
DEFAULT DATAWIN VERSION
Specifies the version of the Datalog Output Window that IMAGE
should start. Options are XVIEW (OpenWindows-style) and
MOTIF (CDE-style). For more information on configuring the
IMAGE Solutions V8.3 3-38
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
Datalog Output Window, see “Datalog Output Window” on page
6-24. The default is XVIEW.
SIZE OF DATAWIN TEXT LOG
Specifies the size (in bytes) of the text log for the Data Collection
window. The default is 20000.
DISPLAY FAILING TESTS ONLY
Specifies whether only failing tests are displayed in datalog
summary reports. This option does not affect data collection. The
default is FALSE.
DEFAULT DATALOG PRINTER
Specifies the default datalog printer. The default is lp.
DATALOG IF TEST PROGRAM MODIFIED
Specifies in the datalog that the program has been modified. A
string is printed that indicates this. The default is FALSE.
CREATE LOCKFILE WITH STDF DATALOG
Specifies that a STDF locked file is created with an STDF
datalog file. This locked file is removed when the STDF datalog
file is complete. The lock file has the same name as the STDF
file, but with the extension .stdf.lock. The default is FALSE.
STRICT CONFORMANCE OF STDF FILENAMES
Specifies that STDF filenames follow standard naming
conventions. (See the Standard Test Data Format (STDF)
Specification.) The default is FALSE.
SITE SPECIFIC SUMMARIES
Specifies how IMAGE generates text-based summary reports
with regard to site specific information. The default is FALSE in
which case only the merged data for the summary appears. If
you choose TRUE, summary data for each site tested during the
lot and the merged data will appear in the text of the summary.
This option is grayed out (inactive) when MULTI SITE SUMMARY IN
STDF FILES is set to FALSE.
MULTI SITE SUMMARY IN STDF FILES
Specifies whether summary data includes site-specific records
(if set to TRUE) or only the merged data for all sites (if set to
FALSE). If you choose FALSE, you will be unable to generate site-
specific summaries by using the -sites switch in the summary
or autosum commands. The default for this option is FALSE.
Window Printing Options
The window printing properties are as follows:
DEFAULT PRINTER Specifies the printer to use for printing. The default is USE
$GFXPRINTER ENVIRONMENT VARIABLE.
IMAGE Solutions V8.3 3-39
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
PRINTER NAME Specifies a printer name to use. This selection is grayed out if
$GFXPRINTER is chosen.
PRINT COMMAND Specifies the command line of the process to use for printing. All
occurrences of the keystring $DEST in the command line are
replaced by the printer name. If left blank, the print command
defaults to
lpr -P$DEST in Solaris 1 or
lp -d$DEST in Solaris 2.
ORIENTATION Specifies printout orientation. The default is APPROPRIATE FOR
CAPTURED WINDOW.
MARGINS Specifies whether to use the maximum area or to leave room for
binder holes. The default is MARGIN FOR BINDER HOLES.
COLOR PRINTING Specifies whether to print the color version of the window or to
convert the window picture to gray scale. The default is CONVERT
TO GRAY SCALE.
COMPRESSION Specifies whether to reduce the size of the PostScript file. This
option saves disk space but increases the time needed to print
the file. The default is OFF.
For more information, see “Printing Windows in IMAGE” on page 3-19.
IMAGE Behavior Chooser Options
The IMAGE Behavior Chooser property is as follows:
CREATE .IBCLOG FILE Tells IMAGE to automatically create a .ibclog log file of
changes affecting the IMAGE Behavior Chooser. See “Keeping
a History of Behavior Changes” on page 5-16. The default is
FALSE.
Setting Color Options
IMAGE includes color properties in the IMAGE Properties window and a Color Manager for
selecting colors.
Color Properties
The color properties are as follows:
PASS/FAIL/ERROR COLORS
Specifies the color of pass, fail, and error items.
INTERACTIVE DISPLAY COLORS
Specifies the color of panel items in IMAGE interactive debug
displays. The STORED color appears if the current state of an
item does not differ from its stored state. The RUNNING color
IMAGE Solutions V8.3 3-40
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
appears when you select an item and the display is executing the
resulting command. The MODIFIED color appears if an item is not
currently running and its state differs from its stored state.
Interactive items use the ERROR color if selecting an item causes
an error.
MODIFY... Access the IMAGE Color Manager to change colors.
Highlighted items in a debug display do not change color. They appear inverted in their
default color or in the color appropriate to their state.
Color Manager
The Color Manager window (figure 3-17) displays colors you can apply to the color
properties.
Figure 3-17. Color Manager Window
The Color Manager window has eight pages of colors, with 64 colors each, for a total of 512
selections. It also includes the following controls that allow you to move from one page to
another and to apply your color selections:
Properties button Selects which property to assign a color. Press MENU to see the
menu.
PREVIOUS PAGE Takes you back one page in the color palette. On the first page,
this item is grayed out.
PREVIOUS PAGE>ONE PAGE BACK
Takes you one page back in the color menu.
PREVIOUS PAGE>TO FIRST PAGE
Takes you back to the first page in the color menu.
NEXT PAGE Takes you forward in the color menu. On the last page, this item
is grayed out.
IMAGE Solutions V8.3 3-41
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
NEXT PAGE>ONE PAGE AHEAD
Takes you one page forward in the color menu.
NEXT PAGE>TO LAST PAGE
Takes you forward to the last page in the color menu.
APPLY>NOW AND DEFAULTS
Sets the color you choose to the current property now and
changes the default for that property.
APPLY>CURRENT SESSION
Sets the color you choose to the current property temporarily.
Does not change the property default.
To change a color property:
1. Press MENU in the workspace and select IMAGE PROPERTIES from the IMAGE
Workspace menu. The IMAGE Properties window appears.
2. Press MENU on the CATEGORY menu button and select COLOR. The color properties
page appears.
3. Click MODIFY. The Color Manager window appears (figure 3-17).
4. Press MENU on the menu button and select a property from the menu.
5. Click a color to select it.
6. Click the APPLY button to confirm your choice.
When you change pages using the PREVIOUS PAGE or NEXT PAGE buttons, you
automatically select a new color at the same location on the screen as the currently selected
color, and the tag (EDITED) appears in the lower right corner. This change does not actually
take effect until you press the APPLY button. If you return to the original screen, the original
color is automatically reselected, and the (EDITED) tag disappears.
Additional Ways to Customize Your Environment
You can customize your environment in other ways. Table 3-1 lists files used to customize
your environment. Standard versions of these files are in $IMAGEBIN/custom for IMAGE,
and /usr/openwin/lib for OpenWindows.
Table 3-1. IMAGE V6.X and OpenWindows Environment Default Files
IMAGE OpenWindows Description
.image-init .openwin-init Tools to start up when entering window system.
Overwritten by SAVE WORKSPACE. See “Saving
Your Workspace” on page 3-44.
.image-menu .openwin-menu IMAGE Workspace menu description. See
“Changing the IMAGE Workspace Menu” on
page 3-44.
IMAGE Solutions V8.3 3-42
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
Table 3-1. IMAGE V6.X and OpenWindows Environment Default Files (Continued)
IMAGE OpenWindows Description
.image-xinitrc .xinitrc Window system init file, for advanced use only.
See “Using an IMAGE Simulator on a Sun3” on
page 3-68.
.Xdefaults .Xdefaults Window system defaults. See “Other Window
System Defaults” on page 3-43.
OpenWindows Properties
The IMAGE Workspace menu has an OpenWindows properties selection that allows you to
change some properties associated with OpenWindows. See the OpenWindows Version 3
User’s Guide for more information on these options.
Other Window System Defaults
The file $IMAGEBIN/custom/.Xdefaults includes all defaults listed in the properties
windows and some additional IMAGE and window manager defaults. These selections
include some commonly used defaults and some color options. Each color listing includes
three values for color, gray-scale, and black-and-white monitors. Selections include the
following:
• Text.Tabwidth sets the width of tabs. The default is 4 spaces.
• The .progen options set ProGen parameters.
• The .shmoo and color.percent options set colors for shmoo plots when using IMAGE
with a color display.
• The color.trace options set colors for Wave Display plots when using IMAGE with a
color display.
To edit any of these defaults in your home directory, type xrdb ~/.Xdefaults after
manually editing the .Xdefaults file. For more information, see the OpenWindows Version
3 User’s Guide or the CDE 1.0 User's Guide.
An .Xdefaults file is located in $IMAGEBIN. Another optional .Xdefaults file may exist for
each tester containing tester-specific defaults. You can also have a copy in your home
directory. IMAGE looks for defaults in the following order:
1. $IMAGEBIN/custom/.Xdefaults
2. /image/tester/<tester_computer_name>/.Xdefaults
3. $HOME/.Xdefaults
To determine defaults, IMAGE uses a technique called merging. IMAGE first looks in
custom and gets the lists of defaults. When it looks in the tester directory, any defaults in
this file override the defaults in custom. Finally, IMAGE looks in your home directory. If it
finds any defaults there, these defaults override any found previously. This allows you to
have personal defaults located in your home directory. For each setting you do not define,
default settings are in place in another file.
IMAGE Solutions V8.3 3-43
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
Saving Your Workspace
You can set the position of the windows in the workspace and determine which windows will
automatically display when you start IMAGE. For example, you may want the station
window to appear at the top of the screen in a certain position, and you may want the clock
to appear every time you enter IMAGE.
To customize windows and their positions:
1. Bring up any windows you want included and position them.
2. Press MENU in the workspace and select UTILITIES>SAVE WORKSPACE from the IMAGE
Workspace menu.
This automatically generates a file containing the commands to bring up your windows. You
can do this as often as you like.
SAVE WORKSPACE creates a file called .image-init. This file includes a listing of the
windows in your environment and the position of each (including the position of the icon for
the window). You can edit the entries in this file. Remember, however, that your edits will
be lost the next time you use SAVE WORKSPACE.
Changing the IMAGE Workspace Menu
The IMAGE Workspace menu is the main IMAGE menu. Access it by placing the pointer in
the background area on the screen and pressing MENU. This menu is defined in the file
$IMAGEBIN/custom/.image-menu.
If you start IMAGE without an .image-menu file in your home directory, IMAGE uses the
.image-menu file in $IMAGEBIN/custom.
You can create a copy of this file in your home directory and edit it. Copy
$IMAGEBIN/custom/.image-menu to $HOME/.image-menu and make changes. (Users of
STEPS compatibility mode must do this to add entries for STEPS station windows to the
NEW STATION menu.)
The first time you create an .image-menu file in your home directory, you must restart
IMAGE to use the new file. If you start IMAGE with an .image-menu file in your home
directory, IMAGE uses it immediately. If you then edit that file, the changes take effect right
away without the need to restart IMAGE.
For more information on the Workspace menu, see the OpenWindows Version 3 User’s
Guide.
NOTE
The IMAGE-specific Workspace menu is available only if you start IMAGE from a text-only
login. If you start IMAGE any other way, it uses the window manager’s default Workspace
menu and does not include the IMAGE-specific items.
IMAGE Solutions V8.3 3-44
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
Changing Button Menu Defaults
All IMAGE button menus have a default selection. This is the selection executed if you click
SELECT on a button instead of pressing MENU and selecting from the button menu. To see
this default selection, press MENU on the button. The default is the item with a border
around it. (If you press SELECT on a button, the default selection is displayed in the button.)
The default is often the first menu item but may also be another item used frequently.
You can change the default for any menu item as follows:
1. Place the pointer on the button.
2. Hold down both MENU and the Control key on the keyboard.
3. Move the selection up or down to the item you want as the default and release MENU
and Control.
Defining the User Button
The USER button in the station window control panel is a button provided for your use. It
allows you to define custom programs and commands for use from within IMAGE.
$IMAGEBIN/custom/.usermenu contains the standard user menu definitions, but you can
customize this for your own use or for a particular test program.
To change the menu for this button, copy $IMAGEBIN/custom/.usermenu to a local
directory and edit it. You can place this file in your home directory or in the working directory
for your test program. IMAGE automatically searches your home directory for this file; to
specify a different location for an individual test program, modify the program’s .load file to
include the following line:
-usermenu <program-menu>.menu
where <program-menu> is a name of your choosing and can include path names. (The file
name should end in .menu.)
In a .usermenu file, the following keywords are legal:
# Marks the line as a comment.
MENU Begins a menu description section. The next string (usually in
double quotes) is the label for a submenu item. All items
specified between this line and the matching END line are on this
submenu. You can nest menus to any depth.
END [PIN] Indicates the end of the menu started by the last unmatched
MENU line. The optional keyword PIN, following END, makes the
menu pinnable. That is, the menu will have a pushpin on it.
"any other string"
Names a menu item. Begins a line that specifies a menu item
and its function.
For example, the following file would produce a USER button menu with CALIBRATION,
DATALOG, DEBUG, and DSP submenus. The DEBUG menu also illustrates nesting menus.
Each submenu is pinnable.
IMAGE Solutions V8.3 3-45
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
"Calibration" MENU
"dc" calibrate -dc;
"vhfawg" calibrate -vhfawg;
"Autocal" calibrate -station 1 -autocal
"HSD50 Cal" calibrate -station 1 -hsd50
"Disable hsd50 calfile" imm "tl_h50_disable_calfile(1)"
"Enable hsd50 calfile" imm "tl_h50_disable_calfile(0)"
"Calibration" END PIN
"Datalog" MENU
"SHOW" datalog -show
"TO FILE" datalog -on -file
"TO STATION" datalog -on -statwin
"FAIL TESTS" datalog -test fail
"PASS TESTS" datalog -test pass
"ALL TESTS" datalog -test all
"LONG FORM" datalog -format fulldlgfmt
"SHORT FORM" datalog -format dlgfmt
"OFF" datalog -off
"TO WINDOW" datalog -on -station 1 -statwin -test all -format fulldlgfmt&
"Datalog" END PIN
"Debug Tools" MENU
"First_run=1" imm First_run=1
"First_run=0" imm First_run=0
"tl_init()" imm "tl_init()"
"Switchvars" MENU
"Read values" switchvar
"switchvar 1" MENU
"switchvar 1=0" switchvar 1=0
"switchvar 1=1" switchvar 1=1
"switchvar 1=2" switchvar 1=2
"switchvar 1=3" switchvar 1=3
"switchvar 1=4" switchvar 1=4
"switchvar 1=5" switchvar 1=5
"switchvars to 1" END PIN
"switchvar 2" MENU
"switchvar 2=0" switchvar 2=0
"switchvar 2=1" switchvar 2=1
"switchvar 2=2" switchvar 2=2
"switchvar 2=3" switchvar 2=3
"switchvar 2=4" switchvar 2=4
"switchvar 2=5" switchvar 2=5
"switchvars to 2" END PIN
"Switchvars" END PIN
"dsim -ignore_errors" dsim -ignore_errors
"Debug Tools" END PIN
"DSP" MENU
"Show memory usage" imm "tl_dsp_check_mem();"
"Dump the data dictionary" imm "tl_dsp_dump_dd();"
"Consistency check" imm "tl_dsp_dd_check();"
"DSP" END PIN
IMAGE Solutions V8.3 3-46
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
Note that the .usermenu file’s syntax is line oriented. For example, PIN only has meaning
when it is the second word on a line whose first word is END. Spacing, however, is
unimportant. Any space before, between, or after words is ignored.
Changing the Station Window Control Panel
You can modify the control panel of a station window by adding buttons or menus, modifying
existing ones, or changing the position of the buttons. You do this by editing either of two
files located in $IMAGEBIN/custom:
production_station_buttons
engineering_station_buttons
For more information, see “Changing the Station-Window Control Panel” on page 8-10.
Remapping Function Keys
You can remap the Sun keyboard function keys F1-F12 by editing a .ttyswrc file. Copy the
file $IMAGEBIN/custom/operator2.ttyswrc to your home directory, ~/.ttyswrc, and
edit the file to remap the keys.
The .ttyswrc file affects shelltool windows only. To make the newly mapped function keys
active in a station window, scrolling must be disabled (like a ShellTool). You can disable
scrolling by selecting PER-USER STATION WINDOW OPTIONS from the IMAGE Properties
window and setting SCROLLABLE STATION WINDOW to FALSE (see “Enabling Scrolling for a
Station Window” on page 3-19), or you can edit your .Xdefaults file to include the following
line:
image.station.scrollable_station_window: False
In IMAGE, function keys F1 to F5 are mapped to the IMAGE functions RUN, HALT, CONT,
STEP, and NEXT. (See “Using Function Keys” on page 7-20.) To remap function keys F1-F5,
you must first disable the IMAGE mapped functions. Select GLOBAL STATION WINDOW
OPTIONS from the IMAGE Properties window and set ENABLE FUNCTION KEYS to FALSE (see
“Global Station Window Options” on page 3-34) or edit your .Xdefaults file to include the
following line:
image.station.enable_function_keys: False
Note that for these changes (disabling scrolling and disabling the IMAGE-mapped
functions) to take effect, you must quit the station window and select it again from the
STATIONS menu on the IMAGE Control window. You need not relaunch IMAGE.
The following are example mappings for F6 to F12:
#mapi F6 runtotrap\n
#mapi F7 step -alarm\n
#mapi F8 step -failedtest\n
#mapi F9 listtrap\n
#mapi F10 usrpower -show\n
#mapi F11 tmode -cont_on_fail\n
#mapi F12 delete\n
IMAGE Solutions V8.3 3-47
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE
Table of Contents Index Home Master Index Search Help
These functions will not appear in the Function Keys display window (select
UTILITIES>FUNCTION KEYS from the IMAGE Workspace menu) but will now work for every
station window that is open.
Using the IMAGE Simulator
IMAGE is designed to work with a test system, but it can also be used off line. The IMAGE
simulator allows you to perform much of the development of test programs away from the
tester at a workstation. To maintain a consistent work environment, the simulator is as much
like the tester environment as possible. In fact, invoking the simulator requires no special
commands or procedures.
In some situations, however, simulator operation is different from working with tester
hardware:
• Hardware configuration. If you are running the simulator, IMAGE cannot tell the
configuration of your tester. You can, however, create a confsim file to model the
configuration.
• Test result values. When run on the simulator, IMAGE returns zero values because it is
not receiving values from the hardware. You can use the simulator database feature to
supply missing values. (See “Customizing Simulation” on page 12-2.) You can also use
the optional IMAGE ExChange software package to exchange information with other
simulators.
• Instrument software. A number of operations are not performed in simulation. An
example is instrument calibration.
Tools for manipulating IMAGE configurations are described in “Configuring IMAGE” on page
4-1. The digital simulator is discussed in “Digital Subsystem Simulator” on page 3-1 the
IMAGE Software Tools Manual.
Switching to the Production Environment
IMAGE has an engineering mode for test program development and debugging and a
production mode for production testing. The default mode is engineering. To switch to
production mode, click SELECT on the PROD button or type the production command in
any station window.
When you enter production mode, the PROD button changes to ENG. To change back to
engineering, click ENG or type engineering in a station window. You are prompted for a
password. (The default password is engineering.) If you have no account or type the
incorrect password, the request to switch to engineering mode is denied.
For information on production mode, see “Production Environment” on page 8-1. For
information on switching between environments, see “Switching Between Production Mode
and Engineering Mode” on page 8-5.
IMAGE Solutions V8.3 3-48
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE Display Modes
Table of Contents Index Home Master Index Search Help
Changing IMAGE Display Modes
This section describes how to run IMAGE using extended display modes. In addition to the
standard single monitor 8-bit-color mode, IMAGE can take advantage of display controllers
that support 24-bit-color and two monitors.
You can run IMAGE in 24-bit-color mode on testers with user computers that support the
enhanced display. This allows for smoother graphics and can resolve some problems
created by the limited number of colors in 8-bit displays. IMAGE supports running 24-bit-
color on the following computers:
• Sun Ultra 5
• Sun Ultra 10
• Sun Ultra 1 Creator
You may be able to use 24-bit color on other computers with display controllers that support
24-bit mode. You cannot use this feature on computers that have 8-bit framebuffers only.
This procedure requires Solaris 2.5.1, and all patches required for IMAGE 7.0 must be
applied. You must also be running IMAGE 7.0.D3, 7.0.tiger6, or later.
Even if your computer supports 24-bit color, you may want to set it to 8-bit mode to ensure
compatibility with older applications.
Before You Check or Change Your Setup
Before you check or change your setup, do the following:
1. Close all programs and exit from any windowing environment (such as OpenWindows
or CDE).
2. Log in as root from the console.
3. If you use CDE, stop the desktop login monitor:
/etc/init.d/dtlogin stop
4. Set the IMAGEBIN environment variable to point to your IMAGE installation.
• For Bourne shell:
IMAGEBIN=/image/bin.7.0;export IMAGEBIN
• For csh:
setenv IMAGEBIN /image/bin.7.0
You can now check or change your setup.
Determine Your Configuration
To determine your current configuration:
1. Complete the steps listed in “Before You Check or Change Your Setup”.
2. Type the following command and press RETURN:
$IMAGEBIN/custom/fb_setup -status
IMAGE Solutions V8.3 3-49
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE Display Modes
Table of Contents Index Home Master Index Search Help
You should see a report similar to the following:
There are 1 monitor(s) configured to run at color depth 24
The main framebuffer is m640
DISPLAY is not set, indicating that you are running this on
the system console. The current framebuffer resolution may
not be the same as the resolution that will be used in
windows
Framebuffer 0 is m640 - current resolution is 1152x900x76
current depth is 24
The last group of lines (two lines if you have a single monitor, four lines if you have a dual-
monitor system) tell you your current display resolution and color depth.
Configuring IMAGE for a Single Monitor Test System
If you have a single monitor test system, do the following to set the display color depth:
1. Complete the steps listed in “Before You Check or Change Your Setup”.
2. Type the following command and press RETURN:
$IMAGEBIN/custom/fb_setup -setup -<depth>
where <depth> is 8 or 24. For example, to set the display to 8-bit-color, type the
command $IMAGEBIN/custom/fb_setup -setup -8 and press RETURN.
3. Verify that your changes have taken effect:
$IMAGEBIN/custom/fb_setup -status
4. Restart the system.
• If you use CDE, start the desktop login monitor:
/etc/init.d/dtlogin start
• If you use OpenWindows, reboot the computer to implement the changes:
boot
When the computer starts, it uses the color depth you specified.
Configuring IMAGE for a Dual Monitor Test System
IMAGE supports the use of two monitors with Catalyst and Tiger test systems. This includes
activating both monitors when you start IMAGE and a menu option (OTHER SCREEN) in the
station window DISPLAY menu and in the IMAGE Control window STATIONS menu. The
OTHER SCREEN option allows you to specify that the window should appear on the other
screen rather than the active screen.
If you have a dual monitor system, do the following to set the display color depth:
1. Complete the steps listed in “Before You Check or Change Your Setup”.
2. Type the following command and press RETURN:
$IMAGEBIN/custom/fb_setup -setup -<depth>
IMAGE Solutions V8.3 3-50
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE Display Modes
Table of Contents Index Home Master Index Search Help
where <depth> is 8 or 24. For example, to set the display to 24-bit-color, type the
command $IMAGEBIN/custom/fb_setup -setup -24 and press RETURN.
fb_setup displays information about the second framebuffer and issues the following
menu:
Please enter:
s - if you have a single monitor
l - if you have two monitors and this monitor is on the left
r - if you have two monitors and this monitor is on the right
s, l, or r ->
3. Select the letter that represents your configuration and press RETURN.
Because of problems in Solaris drivers, some types of display controllers must be the
primary video board. fb_setup notifies you in this case and assigns the primary and
secondary video boards according to the driver restrictions.
4. Verify that your changes have taken effect:
$IMAGEBIN/custom/fb_setup -status
5. Restart the system.
• If you use CDE, start the desktop login monitor:
/etc/init.d/dtlogin start
• If you use OpenWindows, reboot the computer to implement the changes:
boot
When the computer starts, it uses the settings you specified.
Using IMAGE on Two Monitors
IMAGE running under OpenWindows provides a Workspace menu on each screen which
allows you to operate various processes on either monitor. This is not available when
running under CDE.
In a station window, you can invoke a display on the other monitor using the <displayname>
-display switch. To start a display on the secondary monitor, use the -display :0.1
switch. The -display :0.0 switch activates the display on the primary monitor (the one on
which the console appears).
For example, vbacdisp -display :0.0 invokes the AC Instrument Setup display on the
primary monitor; vbacdisp -display :0.1 invokes the display on the secondary monitor.
Starting a Dual-Monitor System with One Monitor
You can force a dual-monitor test system to start up with a single monitor by adding the
-dev /dev/fb0 (or -dev /dev/fb1) switch to the image or openwin commands. You must
do this from a command line only login; see “Before You Check or Change Your Setup” for
more information. This affects the current session only; the next time you start IMAGE or
OpenWindows, it will start with two monitors.
IMAGE Solutions V8.3 3-51
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE Display Modes
Table of Contents Index Home Master Index Search Help
fb_setup Command Line Options
You can run fb_setup with or without command line options. If you do not include any
options, the script presents a menu and asks you to select an option.
The general syntax is as follows:
/$IMAGEBIN/custom/fb_setup [ -option_1 ... -option_n ]
NOTE
You must include the dash (“-”) before each option even when you issue the option at a
menu prompt; for example, -v.
fb_setup supports the following options:
-status Prints current display settings and capabilities to the screen,
then exits. This takes precedence over -setup.
-setup Starts a setup procedure. fb_setup tries to determine the
optimal settings and perform your instructions without asking you
any questions, but it may need to ask you for certain information.
-8 Sets the framebuffers and saved files into 8-bit-color mode. This
operation is silent unless you include the -verbose or -debug
options, this is the first time you have run setup, or you force
setup mode by including the -setup option. You cannot specify
-8 and -24 on the same command line.
-24 Sets the framebuffers and saved files into 24-bit-color mode. The
command is silent except certain conditions (see the description
of the -8 option). You cannot specify -24 and -8 on the same
command line.
-v Sets verbose mode; this displays additional information when
combined with the -8 or -24 options.
-debug Displays the contents of the files written directly by the script.
Also turns on verbose mode.
-usage Prints all command line options to the screen.
fb_setup Messages
fb_setup displays two types of messages: informational messages and errors. This section
describes these messages.
IMAGE Solutions V8.3 3-52
IMAGE Base Language: IMAGE Tester Environment: Changing IMAGE Display Modes
Table of Contents Index Home Master Index Search Help
Informational Messages
• DISPLAY is set to <status>, not to :0, :0.0, $host:0, or $host:0.0 as
expected. Any current frame buffer resolutions displayed will be for
$host, not for <status>, and may be incomplete. The current windows
resolution, however, will be for $disp.
This usually indicates that you are running fb_setup after telnet or rlogin to another
computer.
• You have a PGX32 board as a second video board. Because of errors in
the Solaris drivers, we will treat this board as if it is the primary
video board
This occurs on specific framebuffers and explains why the designation of “primary video
board” may be reassigned.
• DISPLAY is not set, indicating that you are running this on the
system console. The current framebuffer resolution may not be the
the same as the resolution that will be used in windows
This confirms that you are not executing the script inside a windowing environment.
Error Messages
• Only root may setup or change display modes
You are not logged in as root. Log in as root and try again.
• DISPLAY is set, indicating that you are not running this on the system
console. If you are on the console use unsetenv or unexport DISPLAY
(for csh or sh/ksh command shells) and try again
You are probably not in a command line mode login, and you are attempting to set up
or change the display mode. Drop to a command line login (see “Before You Check or
Change Your Setup”) and try again. Unset DISPLAY only if you are sure you are at a
command line login (that is, without the graphical login monitor running in the
background); otherwise this procedure may adversely affect the windowing system.
• The graphical login process, dtlogin, is running, you can not setup or
change display modes. You can stop dtlogin by entering:
/etc/init.d/dtlogin stop
When the desktop login monitor, dtlogin, is running, the procedure labeled “command
line login” is actually a simulation of a command line login but maintains dtlogin in the
background. Halt dtlogin with the /etc/init.d/dtlogin stop command and try
again.
• More than 2 framebuffers!! Exiting.
fb_setup does not support more than two framebuffers.
• IMAGEBIN needs to be set
fb_setup needs files that are in IMAGE 7.0.D3, 7.0.tiger6, or later.
• /image/bin.x.y/m64size not found, check IMAGE version
fb_setup needs files that are in IMAGE 7.0.D3, 7.0.tiger6, or later.
IMAGE Solutions V8.3 3-53
IMAGE Base Language: IMAGE Tester Environment: Exiting IMAGE
Table of Contents Index Home Master Index Search Help
Exiting IMAGE
IMAGE runs within the OpenWindows and CDE windowing systems, but it is not part of
either system. Therefore, you can exit IMAGE and the windowing system entirely or only
exit from IMAGE while keeping the windowing system running.
Exiting IMAGE and the Windowing System
If you started IMAGE from the text-only command prompt, you can exit IMAGE and the
windowing system at the same time. Press MENU and select EXIT from the Workspace
menu or type imageexit at the station window prompt. When you exit, IMAGE requests a
confirmation. This is done as a safety feature to make sure you do not exit accidentally with
unsaved changes to a test program.
To bypass the confirmation dialog, you can use the -noninteractive option. The
imageexit -noninteractive command quits IMAGE only if there are no unsaved edits.
Table 3-2 lists imageexit return codes:
Table 3-2. Return codes for imageexit -noninteractive
Return Code Meaning
0 Success
1 No permission to exit IMAGE session
2 User answered NO to confirmation question
3-7 are only used in noninteractive mode
3 Unsaved edits exist (test program or a combination of
test program, pattern, and VX)
4 Unsaved pattern edits
5 IMAGE is not running
6 Unsaved VX edits
7 Unknown edits
Exiting IMAGE Without Exiting the Windowing System
To exit IMAGE within the windowing system (OpenWindows or CDE), close all tools and test
programs, then do one of the following:
• Click the EXIT IMAGE button on the IMAGE Control Window
• Type imageexit at a station window prompt
• Quit the IMAGE Control Window
IMAGE Solutions V8.3 3-54
IMAGE Base Language: IMAGE Tester Environment: Exiting IMAGE
Table of Contents Index Home Master Index Search Help
If you started IMAGE from the text-only command prompt, you can exit IMAGE without
quitting the windowing system. To do this, use the following command in the console
window:
imageexit -keep_windows
You can also exit IMAGE without exiting OpenWindows by pressing the EXIT button on the
IMAGE Control window.
To restart IMAGE while still in OpenWindows, type image. IMAGE then uses the settings in
the .image-tools file to start and configure IMAGE.
IMAGE Solutions V8.3 3-55
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
IMAGE Licensing
To use IMAGE software, you must purchase an IMAGE license. If you have purchased a
license, a valid IMAGE password is installed at your site when you install IMAGE. A
separate license is also required to use some IMAGE software options, including Advanced
Shmoo, ProGen, IMAGE ExPress, and IMAGE ExChange.
You can load IMAGE and even log in to a station window without a valid password. When
you load a test program, however, IMAGE checks the password file and validates your
password. If the password is invalid, a message saying that no licenses were available is
displayed and test program loads are disabled.
IMAGE uses the FLEX license manager (FLEXlm) from Macrovision (formerly
GLOBEtrotter Software) to handle licenses. This common license manager may already be
in use at your location. This section describes the features of FLEXlm and is intended for
system administrators and other users who have sufficient test system privileges to manage
licenses. For additional information on installing FLEXlm, see the Software Installation
Guide.
License System Structure
Macrovision’s FLEXlm has two components: license daemons and license files.
License Daemons
The Macrovision FLEXlm security system uses two daemons to administer IMAGE licenses.
The first daemon is called lmgrd. With the default Teradyne installation this daemon is
located in /etc on your security server. If you already have the FLEXlm installed on your
network, you need not install this daemon unless you install the Teradyne-specific license
daemon.
The second license daemon is specific to Teradyne and is called icdterd. It is located in
/image/common. The IMAGE install script creates a link to the appropriate executable in
/image/common called icdterd. If you upgrade this, you must also upgrade lmgrd (the
lmgrd version must be equal to or greater than the icdterd version).
License Files
FLEXlm uses an environment variable called LM_LICENSE_FILE to store the path of the
license file or files. The default path for the Teradyne license file is
/image/common/license.dat. To see the location of license.dat, use the command:
ls $LM_LICENSE_FILE
If you are already using FLEXlm, /image/common/.login appends this Teradyne license
path to the LM_LICENSE_FILE path. If the variable is not set, it is set to Teradyne’s default
path. If you need to append another path to the Teradyne default path, do this in
/image/custom/.login by duplicating the code that sets the variable in
/image/common/.login.
IMAGE Solutions V8.3 3-56
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
You can also specify the license path in a local file. This gives you greater flexibility in setting
licensing options for each user. To do this, create a file called .flexlmrc in the user’s $HOME
directory. The contents of this file have the same format (a colon-separated list of paths) as
the data in the $LM_LICENSE_FILE environment variable. Settings in .flexlmrc override
settings in the $LM_LICENSE_FILE environment variable.
Note that the license file is only read when icdterd is started. If changes are made to the
license file, the daemon must be informed to reread the license file with the lmreread
command. (See “Rereading the License File” on page 3-61.)
You can set up the FLEXlm license server to use redundant machines as license servers.
If all end user data is on a single file server, redundant servers are not needed, and
Macrovision recommends using a single server node for the FLEXlm daemons. The default
Teradyne installation for FLEXlm does not use redundant servers. If your site is already
using FLEXlm in a redundant configuration, you must give Teradyne the hostid and name
of each server for your licenses to work.
Starting the License Server
Once the license file and the daemons are in place, all that is required is to start the lmgrd
daemon when the machine boots. This is done in the rc.Teradyne file, which is executed
at boot time by the /etc/rc file. The /etc/rc.Teradyne file only starts the lmgrd if the
machine sees that it is named as a server in the license file.
Performance-on-Demand Licensing
On Catalyst Tiger test systems, you can enable additional features or speeds temporarily
without having to purchase additional permanent licenses. Performance-on-Demand
Licensing allows you to purchase a license for a software feature or other enhancement for
a specified amount of time, in one-week increments. After the time has passed, the license
expires and you must purchase an additional license if you want to continue to use the
enhancement.
For more information on Performance-on-Demand Licensing, contact your local Teradyne
sales representative.
License Administration Tools
FLEXlm provides tools to help you control and supervise licensing on your test system or
network. To use these tools, cd to the directory containing the license files. (Use the
command ls $LM_LICENSE_FILE to display the path to the license file.)
Viewing License Status
The lmstat utility simplifies license administration. Using lmstat allows you to monitor
license management operations instantly, including:
• which daemons are running
IMAGE Solutions V8.3 3-57
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
• users of individual features
• users of features served by a specific daemon
The syntax for using lmstat is as follows:
lmstat [-a] [-S [daemon_name]] [-f [<feature_name>]]
[-s [<server_name>]] [-t <value>] [-c <license_file>] [-A]
[-l [<regular expression>]
where:
-a Displays everything.
-A Lists all active licenses.
-c <license_file> Specifies the license file to use.
-S [daemon_name] Lists users of daemon_name features, where daemon_name is
defined by a DAEMON line in the license file. (See “The License
File” on page 3-63.)
-f [<feature_name>]
Lists users of the specified feature or features.
-l [<regular expression>]
Lists users of matching license or licenses.
-s [<server_name>] Displays status of specified server node or nodes.
-t <value> Sets lmstat timeout to value (in seconds).
The following is an example of the status display showing active licenses:
capra% lmstat -A
lmstat - Copyright (C) 1989-1999 GLOBEtrotter Software, Inc.
Flexible License Manager status on Tue 11/7/2000 15:41
License server status: 7310@galleon
License file(s) on galleon: /export/gal1/licenses/image/logs/license.dat:
galleon: license server UP (MASTER) v7.0
Vendor daemon status (on galleon):
icdterd: UP v7.0
suntechd: UP v6.1
Feature usage info:
Users of ENABLE_CPD: (Total of 400 licenses available)
"ENABLE_CPD" v2.000, vendor: icdterd
floating license
gibbens buzz /dev/pts/2 (v2.000) (galleon/7310 27442), start Tue 11/7 13:21
IMAGE Solutions V8.3 3-58
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
checkers qit /dev/pts/4 (v2.000) (galleon/7310 41847), start Tue 11/7 14:06
hsieh fiedlerpp /dev/pts/2 (v2.000) (galleon/7310 34006), start Tue 11/7 14:57
hahn vogon /dev/pts/10 (v2.000) (galleon/7310 11980), start Tue 11/7 14:58
chowc a570 /dev/pts/2 (v2.000) (galleon/7310 5715), start Tue 11/7 15:13
bakr avatar /dev/pts/9 (v2.000) (galleon/7310 53693), start Tue 11/7 15:22
trunk souzapp /dev/pts/2 (v2.000) (galleon/7310 13371), start Tue 11/7 15:24
joels mrburns /dev/pts/2 (v2.000) (galleon/7310 2702), start Tue 11/7 15:25
The lmstat utility replaces the image_check command used in older versions of IMAGE.
Shutting Down License Daemons
The lmdown utility allows you to shut down all license daemons (both lmgrd and all vendor
daemons) gracefully on all nodes. The lmdown utility has the following syntax:
lmdown [-c <license_file_path>]
where:
-c <license_file_path>
Specifies the license file.
NOTE
Protect the execution of lmdown, since shutting down the servers causes loss of licenses.
When IMAGE loses its license, it waits 10 minutes before disabling test program loads.
IMAGE tries to reconnect to the icdterd every two minutes and prints a warning on the
console if it cannot connect. If the connection is established before the 10 minute timeout
limit, test program loads are not disabled.
If the server comes back up after the 10 minute time limit, you can get a new license using
the initialize command.
Removing the License for a Specified Feature
The lmremove utility allows you to remove a single user’s license for a specified feature.
This may be required in the case where the licensed user was running the software on a
node that subsequently crashed. This situation sometimes causes the license to remain
unusable. The lmremove utility allows the license to return to the pool of available licenses.
The lmremove utility has the following syntax:
lmremove [-c <file>] <feature> <user> <host> [display]
where:
-c <file> Specifies the license file.
feature Specifies the feature to remove.
user Specifies the user name.
IMAGE Solutions V8.3 3-59
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
host Specifies the node.
display Specifies the display.
NOTE
Protect execution of lmremove since removing a user’s license can be disruptive.
For example, we want to remove a mixed-signal simulator license from user lyle. First, we
can check licensing status using the lmstat command for the feature
ENABLE_uWave6000_PNA to see what license lyle is using:
lyle@sunterm% lmstat -f ENABLE_uWave6000_PNA
lmstat - Copyright (C) 1989-1999 GLOBEtrotter Software, Inc.
Flexible License Manager status on Fri 11/10/2000 12:51
Users of ENABLE_uWave6000_PNA: (Total of 50 licenses available)
"ENABLE_uWave6000_PNA" v2.000, vendor: icdterd
floating license
porter t2 /dev/console (v2.000) (galleon/7310 73008), start Fri 11/10 10:18
lyle sunterm /dev/console (v2.000) (galleon/7310 34940), start Fri 11/10 10:36
trunk pp2 /dev/console (v2.000) (galleon/7310 12261), start Fri 11/10 11:13
boehm gunner /dev/console (v2.000) (galleon/7310 66778), start Fri 11/10 11:25
friery holmes /dev/console (v2.000) (galleon/7310 58116), start Fri 11/10 12:10
orlep t5 /dev/pts/3 (v2.000) (galleon/7310 20544), start Fri 11/10 12:38
This status says that user lyle is using a mixed-signal simulator license on host sunterm,
and the display name is /dev/console. Since we know that the licenses are located in:
/image/common/license.dat, we can use the following lmremove command to remove
the license:
lyle@sunterm% lmremove -c /image/common/license.dat
ENABLE_uWave6000_PNA lyle sunterm /dev/console
If we do another status check for mixed-signal simulator licenses, we see that the license
for user lyle was removed:
lyle@sunterm% lmstat -f ENABLE_uWave6000_PNA
lmstat - Copyright (C) 1989-1999 GLOBEtrotter Software, Inc.
Flexible License Manager status on Fri 11/10/2000 12:51
Users of ENABLE_uWave6000_PNA: (Total of 50 licenses available)
"ENABLE_uWave6000_PNA" v2.000, vendor: icdterd
floating license
porter t2 /dev/console (v2.000) (galleon/7310 73008), start Fri 11/10 10:18
trunk pp2 /dev/console (v2.000) (galleon/7310 12261), start Fri 11/10 11:13
boehm gunner /dev/console (v2.000) (galleon/7310 66778), start Fri 11/10 11:25
IMAGE Solutions V8.3 3-60
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
friery holmes /dev/console (v2.000) (galleon/7310 58116), start Fri 11/10 12:10
orlep t5 /dev/pts/3 (v2.000) (galleon/7310 20544), start Fri 11/10 12:38
Rereading the License File
The lmreread utility causes the license daemon to reread the license file and start any new
vendor daemons that have been added. In addition, all pre-existing daemons are signaled
to reread the license file for changes in feature licensing information. Usage is:
lmreread [-c <license_file>]
where:
-c <license_file> Reread the indicated file.
NOTE
If you use the -c option, lmreread (not lmgrd) reads the specified license file. lmgrd
rereads the file it read originally. Also, you cannot use lmreread to change server node
names or port numbers. Vendor daemons do not reread their option files as a result of
lmreread.
Simulator Licenses
Simulators request a specific license based on the confsim file. Licenses exist for Catalyst
and Catalyst Tiger configurations. Catalyst licenses are valid for Catalyst simulators.
Catalyst Tiger licenses are valid for Catalyst Tiger simulators.
When a simulator is initialized (either by loading a test program, by using the Configtool,
or by typing initialize), the confsim file is read and the security daemon is called. If the
exact license, based on the confsim file, is not available, the daemon looks for a higher-
level license that supports the configuration. If it finds such a license, it grants the higher-
level license.
If the confsim file is changed, you must reinitialize. (If you change files using Configtool,
reinitializing is done automatically. See “Selecting a Configuration File” on page 4-4.) If a
simulator does not get a license when IMAGE is first started, loads are disabled. The
console window displays a message saying that no license was available.
Catalyst Simulator Licenses
IMAGE supports simulation of FLEX license limitations on Catalyst and Catalyst Tiger
simulators. You can set or clear the state of licenses that limit the use of hardware resources
in the tester by placing correctly formatted comments in your confsim file.
The confsim entry has three parts. The first is a keyword that signifies a license line. The
second is the license name as it is found in the license.dat file. The third part is the value
assigned to the license. For example:
IMAGE Solutions V8.3 3-61
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
#IMAGE_LICENSE {license name} {ENABLED|DISABLED}
#IMAGE_LICENSE ENABLE_Catalyst55 DISABLED
Valid license names are: ENABLE_CatalystMEM1M, ENABLE_CatalystMEM4M,
ENABLE_CatalystMEM16M, ENABLE_CatalystDRATE50, ENABLE_CatalystDRATE100,
ENABLE_CatalystDRATE200, ENABLE_CatalystDRATE400, ENABLE_CatalystMT,
ENABLE_CatalystSCAN
You must select the confsim file before you load the test program for the new license
information to be recognized. If the confsim file is changed after the test program is loaded,
the new license information is ignored.
If you specify license information in the confsim file, the default state of all licenses is set
to DISABLED. Therefore, even if you reference only one license in the confsim file, others
that had previously been set to ENABLED are now DISABLED. You must respecify the state
of each one.
If you do not specify any license information in the confsim file, the default setting (all
licenses ENABLED) remains unchanged. To write a configuration file which includes
licensing information, see “Writing a Configuration File Including License Information” on
page 4-7.
Sample Confsim File
#Confsim file created on: 10/07/99 14:16:20
#
Catalyst simulator
#
Hardware Restricting license configuration
#
#IMAGE_LICENSE ENABLE_CatalystMEM1M ENABLED
#IMAGE_LICENSE ENABLE_CatalystMEM4M DISABLED
#IMAGE_LICENSE ENABLE_CatalystMEM16M DISABLED
#IMAGE_LICENSE ENABLE_CatalystDRATE50 ENABLED
#IMAGE_LICENSE ENABLE_CatalystDRATE100 DISABLED
#IMAGE_LICENSE ENABLE_CatalystDRATE200 DISABLED
#IMAGE_LICENSE ENABLE_CatalystDRATE400 DISABLED
#IMAGE_LICENSE ENABLE_CatalystMT DISABLED
#IMAGE_LICENSE ENABLE_CatalystSCAN DISABLED
Option Licenses
A software option also calls the security daemon, but requests a license for the specific
option. If the host raymond starts IMAGE with an A565 confsim file and then brings up three
IMAGE ExPress Code Producing Displays (CPDs), the lmstat command displays an entry
for one MIXSIG_SIM license and one ENABLE.CPD license for raymond.
All licenses that a specific simulator signs out are returned when IMAGE exits.
IMAGE Solutions V8.3 3-62
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
Tester Licenses
A tester requests a tester license that matches the hostid of the user computer. The value
of that license is returned if there is a valid license. If not, test program loads are disabled.
The License File
The license file contains lines that define:
• The name of the license server
• The applications that FLEXlm supports
• The path to the daemons for each application
• The Internet port number to use for communication
• A password for each feature
The following is an example license file:
SERVER raymond 17007ea8 1700
DAEMON icdterd /image/bin.5.0/icdterd
FEATURE TESTER icdterd 1.000 01-jan-1989 1 1EF890030EABF324 "" 52203fa8
FEATURE ENABLE_CPD icdterd 1.000 01-jan-1989 10 0784561FE98BA073 ""
The format of this file is any number of SERVER lines followed by any number of DAEMON
server-program lines, followed by one or more FEATURE lines.
The following sections describe each line in the file. All data in the license file is case
sensitive, unless otherwise indicated. Any amount of white space of any type can separate
the components of a line, and a line can be entered using any text editor. This allows
vendors to distribute license data using FAX or telephone.
SERVER Lines
A SERVER line has the following format:
SERVER <nodename> hostid [<port_number>]
where:
<nodename> Is the string returned by the UNIX hostname command.
hostid Is the string returned by the hostid command.
<port_number> Specifies the TCP port number to use.
You can edit the nodename and specify the optional port number. The hostid is part of the
input to the encryption algorithm and cannot be edited.
DAEMON Lines
A vendor DAEMON line has the following format:
DAEMON daemon_name <pathname> <options_path>
IMAGE Solutions V8.3 3-63
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
where:
daemon_name Is the name of the daemon used to serve some feature or
features in the file.
<pathname> Is the pathname to the executable code for this daemon.
<options_path> Is the pathname of the options file for this daemon. (See
“Additional License Options” on page 3-65.)
You can edit the pathname and the options pathname. The daemon_name is part of the input
to the encryption algorithm and cannot be edited.
FEATURE Lines
A FEATURE line has the following format:
FEATURE <name> <daemon> <version> START=<start_date> <exp_date> <#users>
<code> <hostid>
where:
<name> Is the name of the feature.
<daemon> Is the daemon name from a DAEMON line. The specified daemon
serves this feature.
<version> Is the latest (highest-numbered) version of this feature that is
supported (three decimal places).
<start_date> Is the starting date in the format:
dd-mmm-yyyy
<exp_date> Is the expiration date in the format:
dd-mmm-yyyy
For example:
31-mar-2003
If the year is set to 0, the license has no expiration date.
<#users> Is the number of licenses for this feature.
<code> Is the encryption code for this feature. Note that the start date is
encoded into the code. Thus, identical codes with different start
dates will be different.
<hostid> Is the string returned by the hostid command. Use if this feature
is to be bound to a particular host, whether its use is counted or
not. (Case insensitive).
All entries on this line are part of the input to the encryption algorithm and cannot be edited.
IMAGE Solutions V8.3 3-64
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
Node Locking
Specify node locking (that is, single node use) by using a hostid on the FEATURE lines that
represents node-locked features. If the number of users is set to 0, then unlimited use on
the specified host is allowed and no daemons are required. (The license file can contain only
FEATURE lines in this case.). The following license file would allow unlimited usage of feature
f1 on the nodes with host IDs of 12001234 and 1700ab12:
FEATURE f1 xxx1.000 1-jan-90 0 code1 "" 12001234
FEATURE f1 xxx 1.000 1-jan-90 0 code2 "" 1700ab12
Additional License Options
You can customize use of IMAGE licenses using the daemon options file feature of FLEXlm.
This options file allows you to:
• Reserve licenses for specified users or groups of users
• Allow or disallow use of software to certain people
• Set software timeouts
• Log activity for the use of an optional report writer
To use the daemon options feature, create a daemon options file and list its pathname in
the options_path field on the DAEMON line for your vendor daemon. (See “DAEMON Lines”
on page 3-63.)
A daemon options file consists of lines in the following format:
RESERVE <number> <feature> {USER | HOST | DISPLAY | GROUP} <name>
INCLUDE <feature> {USER | HOST | DISPLAY | GROUP} <name>
EXCLUDE <feature> {USER | HOST | DISPLAY | GROUP} <name>
GROUP <name> <list_of_users>
TIMEOUT <feature> <timeout_in_seconds>
NOLOG {IN | OUT | DENIED | QUEUED}
REPORTLOG <file>
where:
RESERVE Specifies licenses to be reserved to one or more users or on one
or more host computer systems.
INCLUDE Specifies one or more users or host computer systems who are
allowed access to the software.
EXCLUDE Disallows one or more users or host computer systems use of
the software.
GROUP Specifies a group of users for use with the other commands.
TIMEOUT Specifies an amount of time (in seconds) after which idle
licenses are returned to the free pool for use by another user.
REPORTLOG Specifies that a log file be written suitable for use by the
Enhanced User Tools report writer.
IMAGE Solutions V8.3 3-65
IMAGE Base Language: IMAGE Tester Environment: IMAGE Licensing
Table of Contents Index Home Master Index Search Help
NOLOG Filters out messages of the specified type from the daemon’s log
output.
Lines beginning with the pound sign (#) are ignored and can be used as comments. If the
filename in the REPORTLOG line starts with a + character, the old report log file will be opened
for appending.
The following is an example options file:
RESERVE 1 ENABLE_CPD USER pat
RESERVE 3 ENABLE_CPD USER lee
RESERVE 1 ENABLE_CPD HOST terry
EXCLUDE ENABLE_CPD USER joe
NOLOG QUEUED
This file reserves a copy of feature ENABLE_CPD for user pat, three copies for user lee, and
a copy for anyone on a computer with the hostname terry. It also causes QUEUED
messages to be omitted from the log file and does not allow user joe to use the feature
ENABLE_CPD.
If this data were in file /usr/local/icdterd.options, you would modify the license file
DAEMON line to read:
DAEMON icdterd /image/bin.rls/icdterd /usr/local/icdterd.options
IMAGE Solutions V8.3 3-66
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
Using IMAGE From Remote Terminals
IMAGE is based on the OpenWindows window system, Sun’s version of the industry-
standard X Window System (also referred to as “X”). (CDE also implements the X protocols
on Sun systems.) It can, therefore, be used from any platform that supports X. This includes
most other UNIX workstations, IBM PC compatibles, Macintoshes, and X terminals.
NOTE
IMAGE must still run on a Sun system, but windows such as station windows and the pattern
editor can appear on any platform that supports X.
The method for running X applications remotely is described in the OpenWindows User’s
Guide. It involves three basic steps:
1. Allow remote access to your display using the xhost command.
2. Log in remotely to the machine where you want to run your application.
3. Set the environment variable DISPLAY to point to your display:
setenv DISPLAY <myhost>
Once you complete these steps, any X application started on the remote host will appear
on your display.
The /image/common/.login login initialization tries to set the DISPLAY variable
automatically when you log in remotely to another machine. When you log in remotely, you
will see a message indicating what your DISPLAY environment variable has been set to. For
example:
myhost% rlogin remotehost
Last login: Fri Sep 4 17:18:23 from myhost
Sun Microsystems Inc. Solaris 5.0 fcs June 1992
DISPLAY is myhost:0
remotehost%
Once DISPLAY is set, you should be able to start any X application on the remote host (such
as a ShellTool or a Text Editor) and have them appear on your display.
Running an IMAGE Simulator on a Remote Server
You may want to run IMAGE on a machine other than the workstation on your desk, perhaps
on a more powerful server machine. To start IMAGE on a remote machine, do the following:
1. Make sure that a window manager is running on your workstation.
2. In a Shell Tool or Command Tool, type xhost +<servername>, where <servername>
is the name of the machine you want to run IMAGE on.
3. Log in remotely to that machine by typing rlogin <servername> and enter your
password if necessary. You should see the message DISPLAY is <myhost>:0 during
the remote login initialization.
IMAGE Solutions V8.3 3-67
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
4. If necessary, set up IMAGEBIN with your usual alias, such as Image.7.0.
5. Type image to start IMAGE.
When you start IMAGE on a remote machine, the file .image-tools is used to determine
which IMAGE programs to start. The default .image-tools file, located in
$IMAGEBIN/custom, starts up the IMAGE Control Window and station 1.
You can now load and edit test programs as with a normal IMAGE simulator. To start
additional station windows, you must invoke them by typing:
station &
in the ShellTool or Command Tool that is logged in remotely to the server. You cannot start
remote station windows from the IMAGE Workspace menu.
When you finish using the remote simulator, type imageexit in the ShellTool or Command
Tool logged in remotely to the server. You can also type imageexit in your remote station
window. You cannot exit a remote IMAGE session from the background menu. When you
type imageexit, any station windows or other IMAGE windows disappear. You can then log
out from the remote host.
NOTE
When using IMAGE simulators on a remote host, do not change any files in the
/image/tester/<servername> directory. For example, if you need to change confsim
files, edit a copy of the confsim file you want in your home directory. Do not edit the
confsim file (or other files) in /image/tester/<servername> since this may affect other
users running IMAGE on that machine.
When using IMAGE simulators on a remote host, you cannot type IMAGE commands in any
window except the station window. For example, if you bring up a ShellTool or Command
Tool from a remote host, you cannot type load testprog -station 1 in the ShellTool to
load a test program in station 1. You must type the load command in the station window.
Using an IMAGE Simulator on a Sun3
Although IMAGE V5.0 and later versions will not run on Sun3 computers, you can use a
Sun3 to run IMAGE remotely from a Sun4 server machine. To run IMAGE remotely, you
must have OpenWindows V2.0 installed on your Sun3. If you are already running
OpenWindows V2.0 on your Sun3, follow the directions in “Running an IMAGE Simulator
on a Remote Server” on page 3-67.
You can automatically start OpenWindows V2.0 with IMAGE running on a remote Sun4
server using the image_sun3 startup script.
IMAGE Solutions V8.3 3-68
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
NOTE
The image_sun3 script does not work properly if you are running IMAGE under Solaris 2.
You can, however, start OpenWindows on the Sun3 host and run IMAGE using an X-
window remote session.
First, before you can use the image_sun3 startup script, you or the system administrator
must do the following:
1. Copy the image_sun3 script from the /image/common directory on the Sun4 server to
the /image/common directory on your Sun3 machine.
2. Copy the file called .image-xinitrc.sun3 into the Sun3’s /image/custom or
/image/bin/custom or into your own directory. This file is located in
/image/bin.5.X/custom.
3. Mount the /image/bin.5.X directory from the Sun4 server on your Sun3 machine as
/image/bin.5.X. This will create a link in /image pointing to the Sun4’s
/image/bin.5.X.
To use the image_sun3 startup script do the following:
1. Select a Sun4 server where you would like to run IMAGE, and make sure you can log
in remotely to that server without typing a password. (You may want to ask your system
administrator to set this up for you. You may need to create a .rhosts file in your home
directory containing the name of the Sun3 computer you are using.)
2. Set up IMAGEBIN to point to the mounted /image/bin.5.X. For example use
setenv IMAGEBIN /image/bin.5.X
3. Type image_sun3 <sun4_server_name>, where <sun4_server_name> is the name of
the Sun4 server where IMAGE should run.
The image_sun3 script automatically starts OpenWindows V2.0, performs a remote login to
the Sun4 server, and starts the version of IMAGE specified by your IMAGEBIN variable. The
following applications appear on your screen:
• All applications in the .openwin-init file on your Sun3 (which you can create using the
SAVE WORKSPACE option on the IMAGE Workspace menu).
• All IMAGE applications in the .image-init.remote file on the Sun4 server. If you do
not have a .image-init.remote file, you get station 1 and an IMAGE Control window.
Note that these applications will be running on the Sun4 server.
• An IMAGE console window, which appears in the upper right corner of your screen. This
window, which is also running on the Sun4 server, displays IMAGE configuration and
error messages.
You can now load test programs and operate the IMAGE simulator normally, with the
restriction that you must type all IMAGE commands in the station window, which is running
on the remote Sun4 server.
When you finish using IMAGE, be sure to type imageexit in the IMAGE console window.
Otherwise, you may leave IMAGE running on the server. You can also exit IMAGE by
choosing the EXIT IMAGE button on the IMAGE Control window. Note that quitting the
IMAGE Solutions V8.3 3-69
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
station window does not exit IMAGE. You must type imageexit in the IMAGE console
window. Also note that the IMAGE console window remains even after you exit IMAGE.
To restart IMAGE at this point, type image in the console window. Or exit the window system
by selecting the EXIT option on the IMAGE Workspace menu.
Using IMAGE Simulators on Other X Platforms
If you do not have access to a Sun workstation, you can run IMAGE from other X platforms
(such as other UNIX workstations, IBM PC compatibles, and Macintoshes with X software).
Adapt the instructions in “Running an IMAGE Simulator on a Remote Server” on page 3-67.
There are two problems you may face when running IMAGE from other X platforms. First,
the IMAGE Setup Display and Station Monitor programs require special IMAGE fonts. To
use the Setup Display or Station Monitor, you must download the IMAGE fonts onto your X
workstation or PC. IMAGE fonts are provided in standard BDF format in the directory
$IMAGEBIN/fonts. Your X workstation or PC should have a program which converts from
standard BDF format into the format required for your X platform. (Note that if you do not
need the Setup Display or Station Monitor, the remaining IMAGE software runs normally
without these fonts.)
IMAGE uses some fonts no longer standard in X11R5. If you get error messages referring
to fonts in the screen family, you may want to download the fonts in
$IMAGEBIN/fonts/bsdcompat (on a Solaris 4 IMAGE machine). These are provided in
X11/NeWS bitmap font format (.fb files). You may need to convert them first on the Sun
using the utility convertfont.
A second problem is that your environment variables may not be set correctly. The
/image/common/.login file tries to set the variables DISPLAY and IMAGE_GRAPHICS based
on attributes of the terminal or window on which you logged in. To start IMAGE properly, the
DISPLAY variable must be set to the correct display, and the IMAGE_GRAPHICS variable must
be set to TRUE. (If IMAGE_GRAPHICS is not set to TRUE, you will get a shell station when you
try to start a station window.)
Remote Use of a Test System
You can use IMAGE to control a tester from a remote site, either with someone at the
remote site (the recommended way) or without someone at the site.
Running Remotely With Someone at the Tester Site
To use a tester remotely, have a person at the console of the tester to initiate the session.
Having a person at the tester helps ensure that no one else is using the tester, that no one
interferes with the tester while it is being used remotely, and that no one is accidentally hurt
by actions of the remote user.
The person at the tester starts IMAGE normally and brings up a station window on the
remote user’s terminal by setting the DISPLAY environment variable to the remote terminal
IMAGE Solutions V8.3 3-70
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
or by using the -display command line switch to the station window. The remote user can
then operate the tester normally. The remote user can exit the session when finished by
typing imageexit.
Running Remotely With the Tester Unattended
In the case where a person cannot be at the tester, you can run IMAGE remotely
unattended.
WARNING
Remote tester operation is dangerous, since a remote operator directly controls
potentially lethal tester voltages and currents. Be careful when operating a tester
remotely. Notify all other tester users. If possible, have someone near the tester to
warn others while it is operated remotely. If possible, use the “attended” method of
remote operation described above instead of “unattended” operation.
For safety and security, remote use of IMAGE on testers is password protected. To use
IMAGE remotely, an account called IMAGERMT must exist on the tester. This account is not
created automatically, so, by default, remote use of IMAGE on testers is disabled. Have the
system administrator open the account and set a password. An example entry in the
password file is:
IMAGERMT:EA2q/gcTkSuPg:-2:-2:Remote tester access:
/bin/false:/bin/false
Since this account is not used for logging in to the tester, set the UID to -2 and the shell to
/bin/false. This prevents the account from being used for anything but its intended
purpose.
To operate a tester remotely do the following:
1. In a ShellTool or Command Tool, type xhost +<servername>, where <servername> is
the name of the machine you want to run IMAGE on.
2. Log in remotely to the tester by typing rlogin <servername> and enter your password
if necessary. You should see the message DISPLAY is <myhost>:0 during the remote
login initialization.
3. If necessary, set up IMAGEBIN with your usual alias, such as image.5.0.
4. Type image to start IMAGE.
When you try to start IMAGE on the tester from a remote terminal, IMAGE checks to ensure
that the tester is not already in use. If the tester is in use, an error message appears
indicating that IMAGE is already running. Otherwise, you are prompted to enter the
password for the IMAGERMT account. (To allow unconditional remote use of the tester, set
the IMAGERMT password to null. However, we strongly recommend that this password be
IMAGE Solutions V8.3 3-71
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
set. If this password is set to null, you still receive a warning message and a confirmation
request before IMAGE is started.)
If the password is correct, IMAGE starts as it would during remote operation of a simulator.
IMAGE applications in the .image-init.remote file are started, and tester operation can
proceed normally.
When you finish operating the tester remotely, type imageexit in the window in which you
started IMAGE. This makes the tester available for the next user.
Remote Station Window
In versions of IMAGE before V5.0, the remote capability of X did not exist, so a different
method of remote operation was available. This feature, called “remote station window,” is
different from X in that it turns any networked workstation into the system computer of a two-
computer tester. (The normal system computer is not used.)
This remote station window feature still exists in V5.0; however, it is no longer the
recommended way of operating testers remotely.
WARNING
This method of operating a tester can be dangerous. It is most appropriate when the
workstation being used to replace the system computer is in the same room as the
tester, so that you can warn other people that the tester is in use.
Before you can use the remote station window feature, the system administrator must
ensure that the /image/tester/<testcomp_name> directory, where <testcomp_name> is
the name of the tester computer, is mounted on the workstation that will serve as the system
computer.
Duties of the System Administrator
For a remote station window to work properly, the system administrator must provide a way
for IMAGE, on a Sun workstation, to gain access to the tester directory
/image/tester/<hostname_t>. The system administrator may choose to put an entry into
the /etc/fstab file which will always automatically mount the
/image/tester/<hostname_t> directory on the workstation. Also, the mount command
can be used as in the following example:
/etc/mount system2_s:/home/system2_s/image/tester/
system2_t /image/tester/system2_t
The system administrator can combine commands into a script file to mount the directory.
Make the script file available to IMAGE users who must execute it before starting IMAGE.
IMAGE Solutions V8.3 3-72
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
Starting IMAGE With Remote Station Windows
To start IMAGE using station windows on a remote tester computer, type:
image -tester <testcomp_name>
This starts IMAGE normally as though you were sitting at the tester.
NOTE
In some older IMAGE releases, starting IMAGE using a remote station window required that
you create a .cluster_setup configuration file. Remove this file. It is no longer useful.
Shell Station
In some cases, you may need to run IMAGE from a nonwindowing environment. For
example, you may wish to run IMAGE from a VT100-style terminal or from a remote modem
connection. The “shell station” feature addresses this need. You can use this feature with
both IMAGE simulators and testers.
WARNING
Operating a tester from a remote shell station can be dangerous. If you must operate
remotely (for example, using a modem for diagnostic purposes), be sure that
someone is near the tester to warn other users that the tester is in use.
Starting IMAGE
When you log in to a workstation or a tester, the /image/common/.login initialization tries
to determine if you are using a windowing or nonwindowing environment, and sets the
IMAGE_GRAPHICS environment variable accordingly. For example, if you are logged in on a
VT100-style terminal, IMAGE_GRAPHICS is set to FALSE.
If IMAGE_GRAPHICS is set correctly, you should be able to simply type image to start IMAGE.
If necessary, you can type the command image -nographics to indicate that you are
starting in a nonwindowing environment.
NOTE
If you try to start a nonwindowing IMAGE session on a tester, you will be asked to enter the
IMAGERMT password as described in “Remote Use of a Test System” on page 3-70.
When you start a nonwindowing IMAGE session, no applications are invoked automatically
(the .image-init.remote file is not used). If the variable IMAGE_GRAPHICS is set correctly,
IMAGE Solutions V8.3 3-73
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
you should be able to type station to start a shell station. If necessary, you can type
station -nographics to ensure that a shell station is started.
Once the station login process is complete, you can load and run any test programs,
including checkers, from the shell station. Any IMAGE or Solaris commands that try to bring
up windows are ignored or generate error messages. You cannot enter debug in the shell
station; however, commands for controlling test heads and datalog are accepted.
Exiting IMAGE
To exit the shell station when you are finished, type logout. You may get a Solaris error
message after you log out from the shell station. You can ignore this message.
To exit IMAGE after using the shell station, type imageexit. (The command imageexit
-nographics still exists, but it is identical to a normal imageexit.)
Administering Multiple Copies of IMAGE on a Server
NOTE
This section is written mostly for system administrators.
When many users are running IMAGE on a Sun4 server, some users may forget to exit
IMAGE before they log out. (Note that quitting all IMAGE windows does not cause IMAGE
to exit. You must use the imageexit command to exit IMAGE.) Thus, you may have several
unused copies of IMAGE running on your server.
To list all copies of IMAGE running on a server, use the imageexit -list command. For
example:
serverhost% imageexit -list
User user1 is running IMAGE on tester number 1
User user2 is running IMAGE on tester number 4
User user3 is running IMAGE on tester number 6
serverhost%
If no copies of IMAGE are running on a server, the following is displayed:
serverhost% imageexit -list
IMAGE is not running on this host.
serverhost%
Each copy of IMAGE on a server is given a virtual “tester number” which identifies it. Virtual
tester number 0 (zero) is always assigned to the local copy of IMAGE which is started on
the console. Remote sessions are assigned tester numbers based on the tty number on
which they were started, plus one. You can find out who is logged in to which tty using the
finger command:
serverhost% finger
Login Name TTY Idle When Where
IMAGE Solutions V8.3 3-74
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE From Remote Terminals
Table of Contents Index Home Master Index Search Help
user1 User 1 p0 3 Thu 13:19 anyhost1
user2 User 2 p3 40 Wed 12:51 anyhost2
serverhost%
By comparing the output of finger and imageexit -list, you can determine which user
has started each copy of IMAGE. In the examples above, user1 started the copy running
on tester number 1, and user2 started the copy that is running on tester number 4, while
user3 seems to have logged out and forgotten to exit the copy started on tester number 6.
If a copy of IMAGE is running but no one is using the associated tty, the system
administrator can use the imageexit -tester_num command to exit that copy of IMAGE:
serverhost# imageexit -tester_num 6
WARNING: You have requested to exit an IMAGE session that was not started
from this terminal. This may affect other users.
Are you sure you want to exit IMAGE [Y/N]? y
serverhost#
NOTE
The imageexit -tester_num command can only be used by the user who started the copy
of IMAGE or by the super-user.
NOTE
Be careful when using the imageexit -tester_num command. It can cause users to lose
unsaved edits to their test programs.
IMAGE Solutions V8.3 3-75
IMAGE Base Language: IMAGE Tester Environment: Using IMAGE With FIRMS
Table of Contents Index Home Master Index Search Help
Using IMAGE With FIRMS
IMAGE can also be used with the Factory Integration and Resource Management System
(FIRMS), Teradyne’s software for computer-integrated manufacturing (CIM). FIRMS
provides tools for data management, data analysis, and test-floor automation; standard
formats for test result data and test-floor event messages; and test-floor connectivity. For
details, see the FIRMS documentation.
In a typical configuration, IMAGE communicates with a FIRMS node, which serves as a
central engine for data management and analysis and as a central controller that responds
in real time to test-system events. To communicate with the FIRMS node, IMAGE runs the
FIRMS Automation Control Tools (ACT) LP300 Software. The major component of this
software is the Automatic Control Tools. It includes, among other tools, the FIRMS Event
Dispatcher, which forwards messages about test system events to the FIRMS engine. See
the FIRMS Automation Control Tools LP300 for Sun Systems—Manager’s and User’s
Manual.
Creating STDF Files
Teradyne has defined the Standard Test Data Format (STDF) for writing test result data.
FIRMS data management and analysis software takes STDF files as input. All Teradyne
Sun-based test systems can write test result data in STDF. For information on STDF, see
“Standard Test Data Format” on page 24-1 or the “Introduction to STDF” in the Standard Test
Data Format Manual.
Sending Event Messages
Teradyne has also defined the Standard Event Message Format (SEMF) for use in test-floor
automation. Any test-system activity is an event that can trigger the sending of an event
message. The FIRMS Event Dispatcher can respond to event messages that conform to
SEMF format.
The IMAGE executive automatically sends an SEMF message when certain events occur,
such as test-program load or start of a lot. If FIRMS is running on the IMAGE system, the
executive calls the FIRMS Event Dispatcher to process the event message. (If FIRMS is not
running, the call has no effect.) In addition, the FTSIS software, if installed, generates other
SEMF messages in response to events on the IMAGE system. Finally, the IMAGE library
contains tl_ functions for sending SEMF messages from any ITL test program.
For tl_ subroutines to send SEMF messages, see “Base IMAGE Functions” on page 26-1.
For messages that IMAGE can send, see the FIRMS Test System Interface Software
(FTSIS) Installation Guide. For SEMF, see the Standard Event Message Format (SEMF)
Specification.
IMAGE Solutions V8.3 3-76
IMAGE Base Language: Configuring IMAGE
Table of Contents Index Home Master Index Search Help
4 CONFIGURING IMAGE
IMAGE supports multiple A5xx, Catalyst, and Tiger testers and testing environments. This
flexibility requires that IMAGE determine at startup on what type of tester it is running to
provide the correct software tools for that tester’s environment. On the tester this decision
is made by interrogating the hardware to determine what type of tester is present.
On a simulator workstation, determination of testing environment is made by reading a file
called a confsim file in place of interrogating the hardware. A confsim file provides detailed
information on the configuration of a given tester. Once the file is read, IMAGE behaves
identically for a test system or a simulator workstation simulating that tester.
On the tester, you may need to make hardware changes while continuing to use IMAGE for
testing. For example, you may need to remove a board for repair. At such times, you can
write a confchanges file that, in effect, tells IMAGE about hardware changes. This file
allows you to continue as if the hardware you removed is still present or as if the hardware
you added does not exist. (See “confchanges Files” on page 4-18.)
IMAGE provides commands to help you configure IMAGE for both simulator and tester
operation. They are described in this section.
This section includes the following:
• “IMAGE Control Window” on page 4-2
• “Hardware Configuration Checking” on page 4-18
IMAGE Solutions V8.3 4-1
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
IMAGE Control Window
The simulator uses confsim files to model the hardware. The IMAGE Control window is
used to create and manipulate confsim files. You can:
• Simulate different configurations
• Change configurations without exiting IMAGE
• View the current configuration
• View a skeleton pinmap for the current test system and station
• View the contents of the current configuration board description file (for advanced
mixed-signal configurations or DIB adaptor configuration file for Catalyst) and read a
confsim file for that board
• Get updated configuration board files
• View confchanges files (on test systems only)
• Write the current configuration to a file
• Use all configuration functions in scripts. All functions have command line equivalents.
(See the initialize, tconfig, show_tconfig, and dump_pinmap commands.)
Invoking the IMAGE Control Window
When you first start IMAGE, the IMAGE Control window (figure 4-1) comes up automatically.
If the IMAGE Control window or its icon does not appear on your screen, press MENU in
the workspace to display the IMAGE Workspace menu and select IMAGE CONTROL. If you
are running IMAGE from inside OpenWindows as an application or you are running under
the Common Desktop Environment, the IMAGE workspace menu is not displayed on the
workspace. You can also type imagecontrol in any station window.
Figure 4-1. IMAGE Control Window
The IMAGE Control window includes the following configuration controls:
FILE Selects a configuration to use. You can also read and write
configuration files.
VIEW Displays the IMAGE configuration you are using, the contents of
the associated configuration board description file (for advanced
mixed-signal or DIB adaptor configuration file for Catalyst), and
the contents of the current confchanges file if you are on a
tester. This selection can also display a skeleton pinmap and the
contents of other configuration board files.
IMAGE Solutions V8.3 4-2
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
Reading and Writing Configuration Files
Selecting the testing environment provided at your simulator workstation involves selecting
the correct confsim file. You can select a confsim file from the set of default confsim files
provided by IMAGE. You can also select a file you have written yourself. (You can use a
default confsim file as a template.)
The FILE button in the IMAGE Control window allows you to manipulate configuration files.
Hold down MENU on FILE to display a pop-up menu with the following selections:
READ CONFIG FROM FILE...
Displays a window that allows you to read a confsim file from
any directory. (This is the default.)
$HOME Reads a confsim file from your home directory. You can change
this environment variable to another directory using IMAGE
Properties. See “Changing Configuration Properties” on page
4-15.
$IMAGEBIN/CUSTOM Reads a default confsim file from the directory $IMAGEBIN/
custom.
$IMAGEBIN/CUSTOM/CFG_BDS
Reads a confsim file for a config board description file from the
directory $IMAGEBIN/custom/cfg_bds.
$IMAGEBIN/CUSTOM/DIB_ADAPTORS
Reads a confsim file for a config board description file from the
directory $IMAGEBIN/custom/dib_adaptors.
WRITE CONFIG TO FILE...Brings up a window that allows you to write the current IMAGE
configuration to any directory.
Location of confsim Files
The confsim file is read once at IMAGE startup and then again each time the initialize
command is given. When IMAGE reads the confsim file, it looks for the file in the following
places in the order listed:
• The home directory ($HOME) of the user who started IMAGE. If you want to always use
one tester configuration for off-line simulator development, put that confsim file in this
directory.
• /image/tester/<hostname>, where <hostname> is the name of the simulator
workstation on which IMAGE is running. This directory allows you to set up a default
configuration for a given simulator workstation.
• $IMAGEBIN/custom. This directory contains default confsim files supplied with IMAGE.
(IMAGEBIN is a C-shell environment variable which is set when you start IMAGE. To
examine its setting, type printenv IMAGEBIN in a station window command region.)
IMAGE Solutions V8.3 4-3
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
Selecting a Configuration File
The IMAGE Control window allows you to select and initialize an IMAGE confsim file
outside the normal confsim file search path. If you have no test programs loaded, you can
change to any configuration you want, regardless of tester or head type. (Licensing is still
checked, however, to ensure you have a license for that tester.) If you have a test program
loaded, you can change to a new configuration file only if it is of the same tester and test
head types as the loaded program.
To read a default confsim file from $IMAGEBIN/custom:
1. Hold down MENU on FILE, select $IMAGEBIN/CUSTOM, and pull right. This displays the
list of default confsim files. If you are working on a tester, no files are displayed.
2. Select a confsim file and release. IMAGE is initialized using the new file.
The list of standard confsim files includes the following:
CONFSIM.CATALYST Catalyst configuration
CONFSIM.CATALYST400 Catalyst 400 configuration
CONFSIM.CATALYST_RESTRICTED
Catalyst restricted configuration
CONFSIM.TIGER Catalyst Tiger configuration
CONFSIM.TRAINING Advanced mixed-signal configuration (for training and tutorials)
CONFSIM.A565 Advanced analog VLSI configuration
CONFSIM.A567 Advanced analog VLSI configuration
CONFSIM.A569 Linear configuration with Image Sensor options
CONFSIM.A570 Advanced mixed-signal configuration
CONFSIM.A580 Advanced mixed-signal configuration
By default, the confsim file in IMAGEBIN/custom is a link to the confsim.a540 file.
When you select a file, IMAGE reads the new file and initializes the software. When
initialization is complete, the window displays the following message in the footer:
Initialization Complete
If the test system cannot be initialized using the specified confsim file, the window displays
the following message in the footer:
Initialization FAILED (see console)
Look in the console window for a complete error message. By default, the console window
opens automatically. You can change this default using the IMAGE Properties window.
For example, an advanced mixed-signal test program is loaded in station 1. If you try to load
confsim.catalyst (a Catalyst configuration file which specifies station 1 as a Catalyst
station), you get this error message:
IMAGE Solutions V8.3 4-4
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
tcinit: Cannot change test head type with test program loaded on any station.
(Attempt to change test head 1 from type Adv_MixSig to type Catalyst)
tcinit: configuration changes ignored
Selecting a confsim File From Your Home Directory
You can select a confsim file from your home directory ($HOME) as follows:
1. Press MENU on FILE, select $HOME, and pull right. This displays the list of the confsim
files in your home directory. If you are working on a tester confchanges files are
displayed.
2. Select a confsim file and release. IMAGE is initialized using the new file.
If you have another directory where you store confsim files, you may want to change the
custom accelerator menu (initially set to $HOME for each user) to another directory. You can
do this using IMAGE Properties. See “Changing Configuration Properties” on page 4-15.
Reading a Configuration File
The IMAGE Control window allows you to read files from directories other than the default
directory or your home directory. To read in a file in any directory:
1. Select FILE>READ CONFIG FROM FILE... The Read Configuration window is displayed
(figure 4-2).
2. Select a directory and a file. Only files starting with confsim are shown in the FILE menu
(although you can type any filename on the text line).
3. Click SELECT on READ CONFIGURATION. IMAGE is initialized using the new file.
Figure 4-2. Read Configuration Window
Note, however, that the initialize command uses the standard search path when looking
for confsim files. If you read a confsim file outside that search path and then type
initialize, IMAGE reads the first file named confsim found in the standard path and
initializes using that configuration. A configuration change using the IMAGE Control window
is not retained by an ordinary initialization. (See “Initialize Command” on page 4-15.)
Selecting a confsim File for a Config Board
IMAGE includes a configuration board description file for every analog configuration board
made by Teradyne. Config boards are used on advanced linear, PATH, and advanced
mixed-signal test heads. A config board description file describes the wiring on the test head
to the IMAGE configuration software. On Catalyst, a DIB adaptor allows the tester to use an
IMAGE Solutions V8.3 4-5
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
advanced mixed-signal DIB and a test program developed for the device on an advanced
mixed-signal tester.
IMAGE also includes a confsim file for every config board description file. Each confsim
file illustrates a typical (although not the only) system configuration which might use the
corresponding config board.
These confsim files are stored in $IMAGEBIN/custom/cfg_bds and $IMAGEBIN/custom/
dib_adaptors. They are also available on a pull-right menu from the FILE menu of the
IMAGE Control window.
To select a confsim file for a config board description file:
1. Select FILE>$IMAGEBIN/CUSTOM/CFG_BDS or FILE>$IMAGEBIN/CUSTOM/DIB_ADAPTORS
and pull right. This displays the lists of config board description files. If you are working
on a tester, no files are displayed.
2. Select a confsim file and release. IMAGE is initialized with the new confsim file.
As new config boards are added, new confsim files will be added to this directory.
Writing Configuration Files
The IMAGE Control window allows you to create new configuration files that match your
tester for use with the simulator during test development. The selection WRITE CONFIG TO
FILE uses the tester configuration to create a confsim file that matches that configuration.
To write a file:
1. Select FILE>WRITE CONFIG TO FILE... The Write Configuration window is displayed (figure
4-3).
Figure 4-3. Write Configuration Window
2. Select a directory and enter a filename. The name must start with confsim to be read
by the configuration accelerators.
3. Click WRITE CONFIGURATION.
Using tconfig to Write a Configuration File
You can also create new configuration files using tconfig. The tconfig program creates
configuration files that match your tester for use with the simulator during test development.
The program can also compare the current test system configuration against a saved
configuration. This is useful to ensure that test system configurations have not changed.
IMAGE Solutions V8.3 4-6
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
The tconfig -compare command exits with nonzero status if differences are found. This
can be useful in UNIX scripts.
The syntax is:
tconfig [-create [-outfile <file>] | -compare [-infile <file>]]
where:
tconfig Writes current hardware configuration as a confsim file to the
standard output.
tconfig -create Writes the current hardware configuration to the file /image/
tester/<host>/system_config.
tconfig -create -outfile <file>
Writes the current hardware configuration as a confsim file to
<file>.
tconfig -compare Compares the current hardware configuration to the default file
in /image/tester/<host>/system_config.
tconfig -compare -infile <file>
Compares the current hardware configuration to <file>.
Writing a Configuration File Including License Information
You can write a configuration file which includes licensing information using the function
tl_dump_configuration ("filename");
The license information is placed near the top of the file in the system configuration area.
See “tl_dump_configuration” on page 26-189 for more information.
Editing confsim Files
You may need to create a new confsim file to reflect a new hardware configuration. The
easiest method is to use the command
tconfig -create -outfile <file>
This produces a confsim file that matches your configuration. If you need to edit this further,
use the IMAGE templates in $IMAGEBIN/custom as a guide to the confsim syntax for each
instrument and subsystem.
To find the board ID for a particular instrument board, press the HELP button to display
IMAGE on-line help. In the help window select BASE LANGUAGE>BOARD IDENTIFICATION
NUMBERS.
Note that in IMAGE V5.0 and later versions a confsim file must include every hardware
subsystem. If a subsystem is not mentioned, IMAGE will not know it is there. This is a
change from some older versions of IMAGE which automatically provide a default
configuration for some subsystems, such as the DC Subsystem and the Synchronized
Power Subsystem.
IMAGE Solutions V8.3 4-7
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
For example, you load a test program that loaded without error in a previous version of
IMAGE and get a warning that a crosspoint is not present behind a particular pin. If your
confsim file did not specify the DC configuration, you must edit the file to specify explicitly
the DC configuration you wish to simulate. All confsim formats are backwards-compatible
to previous versions of IMAGE.
Viewing Configuration Files and Pinmaps
Using the IMAGE Control window you can view the current configuration being simulated
(or the current hardware configuration on a tester), the current configuration board
description file, other configuration board files, or a skeleton pinmap for your current tester
and station. You can use these functions during test program development. For example,
when writing an advanced linear or advanced mixed-signal pinmap, you can view the details
of a configuration board description file to see the DIB names and the test-head
configuration to see the channel card slot setup.
The VIEW button in the IMAGE Control window allows you to view configuration files and
pinmaps. Hold down MENU on VIEW to display a pop-up menu with the following selections:
SHOW BASE CONFIGURATION...
Shows a summary of the hardware in the current configuration.
(This is the default.)
SHOW DETAILED CONFIGURATION...
Shows a detailed report of the current configuration in confsim
file format.
SHOW SKELETON PINMAP
Shows a pinmap for the current configuration and station with
entries for all available channels.
SHOW CURRENT CONFIG BOARD FILE
Shows the contents of the configuration board file corresponding
to the currently mounted configuration board.
SHOW OTHER CONFIG BOARD FILE
Shows the contents of any configuration board description file
either in your home directory or in the directory $IMAGEBIN/
custom/cfg_bds.
EXTRACT CONFIG BOARD FILE...
Specify a configuration board file to extract (see “Extracting
Config Board Files” on page 4-13).
SHOW CONFCHANGES... Shows the contents of the confchanges file if on tester
hardware.
Viewing a Base Hardware Configuration
Select VIEW>SHOW BASE CONFIGURATION to see a summary of the hardware in the current
configuration. This listing shows you what type of test head each station is assigned to, the
IMAGE Solutions V8.3 4-8
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
configuration board for each station (if any), and a list of the instrument subsystems in the
configuration. Figure 4-4 shows an example.
You can get the same listing in a station window by typing the command show_tconfig.
Figure 4-4. Base Configuration Window
You can also see the test-head type of a given station window by looking at the icon, if the
window is closed, or at the icon embedded in the button region, if the window is open.
Viewing a Detailed Configuration
Select VIEW>SHOW DETAILED CONFIGURATION, you see a detailed listing of the current
configuration in confsim file format. This is a scrollable window that allows you to view the
entire file. Figure 4-5 shows an example.
IMAGE Solutions V8.3 4-9
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
Figure 4-5. Detailed Configuration Window
Viewing a Skeleton Pinmap
The IMAGE Control window can provide a skeleton pinmap for the test system and station
that you are currently using. You can use this pinmap to help create a new test program.
To see a skeleton pinmap, select VIEW>SHOW SKELETON PINMAP. Pull right to select a
station number. (Station 1 is the default.) A scrollable text window is displayed with a pinmap
that includes entries for all available channels. You can copy and paste the contents of this
window into your test program and edit it. The skeleton pinmap will compile.
Figure 4-6 shows a portion of skeleton pinmap for station 1 of an A540ALSP tester.
IMAGE Solutions V8.3 4-10
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
Figure 4-6. Example Skeleton Pinmap
You can also display the skeleton pinmap for any station using the dump_pinmap command.
The syntax is:
dump_pinmap [-station #]
where:
station # Specifies a station. Use this parameter when outside a station
window.
Viewing Current Config Board Files
If the configuration is for advanced linear or advanced mixed-signal test systems, you can
see the contents of the current configuration board description file. On Catalyst, it allows you
to view the DIB adaptor configuration file:
1. Select VIEW>SHOW CURRENT CONFIG BOARD FILE.
IMAGE Solutions V8.3 4-11
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
2. Pull right and select STATION 1 or STATION 2. Each station will have the backplane listed
for that station (either A or B).
This displays a listing of the current configuration board description file in a scrollable
window that allows you to view the entire file (figure 4-7).
Note that only backplane A config board files are viewable. Digital config boards are all the
same and are hardwired to digital channels.
Figure 4-7. Config Board Window
Viewing Other Config Board Files
IMAGE includes configuration board description files for all current config boards made by
Teradyne. These files are stored in $IMAGEBIN/custom/cfg_bds or $IMAGEBIN/custom/
dib_adaptors. You can also create your own configuration description board files and
store them in your home directory in $HOME/cfg_bds or $HOME/dib_adaptors.
To see the contents of any of these files:
1. Select VIEW>SHOW OTHER CONFIG BOARD FILE.
IMAGE Solutions V8.3 4-12
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
2. Pull right and select $IMAGEBIN/CUSTOM/CFG_BDS or $HOME/CFG_BDS (or
$IMAGEBIN/CUSTOM/DIB_ADAPTORS or $HOME/DIB_ADAPTORS). Either selection
displays the contents of that directory.
3. Select a file and its contents are displayed. You will see a listing of the configuration
board description file similar to the one shown in figure 4-7.
Extracting Config Board Files
In IMAGE V6.4 or later, you can get the latest configuration board files available by either
specifying them on a command line or in the Extract Configuration window (figure 4-8).
To see the Extract Configuration window:
1. Select VIEW>SHOW OTHER CONFIG BOARD FILE.
2. Select EXTRACT CONFIG BOARD FILE...
Figure 4-8. Extract Configuration Window
In the Extract Configuration window, type the config board file name (excluding the .cfbd
extension) and click EXTRACT. If the config board file is not found in the standard directory
($IMAGEBIN/custom/cfg_bds or $IMAGEBIN/custom/dib_adaptors), IMAGE extracts it
from the Config Board Archive (CBA) if it exists there. Extraction is from the archive /image/
CBA/cfbd_arch.tar.
To specify a config board file from the command line, from the shell prompt (possible in a
station window), type:
extract_cfbd XXxxx
XXxxx is the config file or DIB adaptor file name (excluding the .cfbd or confsim.
extension). XX is CB (for config file) or DA (for DIB adaptor file).
If the file already exists, it is renamed with a .old extension. For example, XXxxx.cfbd
becomes XXxxx.cfbd.old.
To specify multiple files, use:
extract_cfbd XXxxx1 XXxxx2 ... XXxxxN
XXxxx# represents each file.
To extract all files, use:
extract_cfbd -all
IMAGE Solutions V8.3 4-13
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
Do this with caution because it will populate the custom/cfg_bds and dib_adaptors
directories with all the config board files in the CBA. Complete extraction takes several
minutes to complete.
The syntax for the extract_cfbd command is:
extract_cfbd [-test] [-quiet] -all
extract_cfbd [-test] [-quiet] <namelist>
extract_cfbd -ls_archname
extract_cfbd -ls_all
where:
-test Prints to the screen which action the extraction would take. No
files are extracted or renamed.
-quiet Suppresses output to the screen.
-all Extracts all *.cfbd and confsim.* files.
<namelist> Extracts each <name>.cfbd and confsim.<name> file.
-ls_archname Prints out the full pathname of the Config Board Archive.
-ls_all Prints out all possible files to extract.
NOTE
You may need to run as root when extracting files from the Config Board Archive. Also, be
sure that no test programs are running when you extract config board files.
Upon successful extraction, the file will appear under the FILE menu button in the IMAGE
Control window, in either $IMAGEBIN/custom/cfg_bds or $IMAGEBIN/custom/
dib_adaptors. Although the confsim file will not be displayed in the menu, it is also
extracted along with the config board file.
Viewing confchanges Files
A confchanges file contains hardware configuration changes. IMAGE reads these changes
during initialization on a tester as exceptions to the hardware it finds on the tester. This
allows IMAGE to function normally despite any temporary changes to the hardware
configuration (such as may occur during hardware upgrade).
NOTE
You must create confchanges files manually. They are searched for using the same search
path as confsim files (see “Location of confsim Files” on page 4-3).
To see a confchanges file, press MENU on VIEW and select SHOW CONFCHANGES. (If you
are not working on a tester, this item is grayed out.) A window with the confchanges file
IMAGE Solutions V8.3 4-14
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
appears. (See “Overriding Hardware Configuration Checking” on page 4-19 for more
information.)
Changing Configuration Properties
To change configuration properties using the IMAGE Control window:
1. Select FILE>IMAGE PROPERTIES.
2. Select CATEGORY>MISCELLANEOUS (figure 4-9).
This window allows you to set the second item in the FILE button menu. The default for this
item is $HOME, but you can use another directory to store confsim files. Enter the directory
and click APPLY. To return this value to the default directory, click RESET.
Figure 4-9. IMAGE Properties Window - Config Options
Initialize Command
The initialize command scans the tester or confsim file to determine the hardware
configuration so that IMAGE can communicate with the hardware properly. Initialization
performs the following:
• Instructs all loaded test programs to execute a power-up reset.
• Reads the confsim file for the simulator or the confchanges file for the hardware.
• Sets the tl_powerup flag to 1. This is reset to zero for each test program when that
program runs to completion the first time.
IMAGE Solutions V8.3 4-15
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
The initialize command can be important for some configurations of linear test systems
if you cycle power (that is, turn power off and on again). Testers affected are A530 and A560
testers without the following hardware:
• High Speed Digital Subsystem
• Advanced Linear Test Head
• AC Subsystem
• Synchronized Power Subsystem
Since linear testers without any of this hardware do not automatically detect power being
cycled, use the initialize command each time you cycle test system power.
Invoke initialization by selecting INITIALIZE from the IMAGE Workspace menu or by typing
initialize in a station window. Syntax for the initialize command is:
initialize [-tester <tester_name>] [-dir <path>] [-file <file>]
where:
<tester_name> Is a test system name.
<path> Is a directory name to look for the confsim or confchanges file.
<file> Is a filename to use instead of a confsim or confchanges file.
Examples of initialize commands on an IMAGE simulator workstation are as follows:
initialize
This command searches for confsim or confchanges files in the following directories
in the following order:
$HOME/confsim
/image/tester/<host>/confsim
$IMAGEBIN/custom/confsim
initialize -file fleetfoot
This command searches for confsim or confchanges files in the following directories
in the following order:
$HOME/fleetfoot
/image/tester/<host>/fleetfoot
$IMAGEBIN/custom/fleetfoot
initialize -dir /h/ferret/frisky/confsims
This command searches for confsim or confchanges files in the following directories
in the following order:
/h/ferret/frisky/confsims/confsim
/image/tester/<host>/confsim
$IMAGEBIN/custom/confsim
initialize -dir .
This command searches for confsim or confchanges files in the following directories
in the following order:
IMAGE Solutions V8.3 4-16
IMAGE Base Language: Configuring IMAGE: IMAGE Control Window
Table of Contents Index Home Master Index Search Help
<expanded cwd>/confsim
/image/tester/<host>/confsim
$IMAGEBIN/custom/confsim
initialize -dir $HOME/confsims -file bar
This command searches for confsim or confchanges files in the following directories
in the following order:
$HOME/confsims/bar
/image/tester/<host>/bar
$IMAGEBIN/custom/bar
Note that the initialize command (without the -dir or -file options) uses the standard
search path when looking for confsim files. If you read a confsim file outside that search
path and then type initialize, IMAGE reads the first file named confsim found in the
standard path and initializes using that configuration. A configuration change using the
IMAGE Control window is not retained by an ordinary initialization.
When initialization is complete, a confirmation appears informing you of this fact:
Initialization Complete
If you attempt initialization illegally (such as trying to change test-head types with a test
program loaded), you get an error in the station window:
Initialization FAILED (see console)
Errors telling you about unrecognized or missing hardware also appear in the console
window but do not cause the initialization to fail.
IMAGE Solutions V8.3 4-17
IMAGE Base Language: Configuring IMAGE: Hardware Configuration Checking
Table of Contents Index Home Master Index Search Help
Hardware Configuration Checking
Each time you load a test program, IMAGE compares the hardware requirements in the test
program’s pinmap against the tester’s hardware configuration or the simulated configuration
(and against the configuration board description file in advanced linear and advanced
mixed-signal test systems or the DIB adaptor file on Catalyst). If it finds a conflict, it displays
a warning message describing the conflict. On advanced mixed-signal testers, IMAGE also
inhibits test program execution.
Configuration conflicts occur whenever the tester’s hardware configuration or the simulated
configuration does not match the configuration defined in a pinmap (and in the configuration
board description file on advanced mixed-signal testers or in the DIB adaptor file on
Catalyst). For example, a conflict occurs if a Precision Multimeter Channel Card is in test-
head slot 6 when you load a test program that expects the High Speed Sampler Channel
Card to be in test-head slot 6.
If IMAGE still does not allow you to run your test program after you have resolved all
configuration conflicts, reinitialize before rerunning your test program. (See “Initialize
Command” on page 4-15.)
confchanges Files
At times, you may need to make hardware changes, such as removing a board. Yet you still
want the remaining hardware and IMAGE to function normally. IMAGE must be able to
make allowances for missing boards and missing instruments.
Just as a confsim file allows you to use IMAGE without a test system, a confchanges file
allows you to run the tester hardware without certain boards being present. A confchanges
file has exactly the same syntax as a confsim file. Instead of listing all the hardware in the
tester, however, it lists the slot numbers and names of boards that are missing from the
tester. IMAGE reads this file and simulates the listed boards.
NOTE
IMAGE simulates the boards for configuration purposes only. The functionality of the
instruments is not simulated.
Place a confchanges file in your home directory or in the directory /image/tester/
<host>. You can read this file using the IMAGE Control window. Hold down MENU on the
VIEW button and select SHOW CONFCHANGES.
Dual Test Head Systems
In systems with two test heads, test head 2 may not be recognized by checkers or test
programs when test head 1 is disconnected. Include an LA667 Digital Interface Board (DIB)
for test head 1 in the confchanges file to rectify this problem.
IMAGE Solutions V8.3 4-18
IMAGE Base Language: Configuring IMAGE: Hardware Configuration Checking
Table of Contents Index Home Master Index Search Help
acmapchanges Files
The LFAC Dual Channel Card includes Source and Digitizer functionality on the same
board, but you may want to hide one or the other function to save mainframe card hardware
cost. IMAGE allows you to mask either the Source or the Digitizer portion of a LFAC Dual
Channel Card. To do this, place a file called acmapchanges in your home directory or in the
/image/tester/<host> directory.
The acmpachanges file has the following format:
<test_head_index> <confsim_line> <LFAC_mapping>
where:
<test_head_index> Is the test head containing the LFAC Dual Channel Card.
<confsim_line> Is the one-based number of the line in the appropriate Test Head
section of the confsim file. Note that this is not the slot number.
<LFAC_mapping> Describes how you want the card to appear to IMAGE. A zero in
this column causes the card to appear as an LFACDIG. A one in
this column causes the card to appear as an LFACSRC.
For example, if the Test Head section of your confsim file begins with the following lines:
CATALYST_TH 1
BACKPLANE A
#Slot Type Serial # Num XptA XptB Name
2 879-858-35 0x022b48e 0 # 23 24 PLFD CC
3 879-858-25 0x022b363 0 # 21 22 REFSRC CC
4 000-000-00 0x0000000 0 # 19 20 EMPTY
5 949-658-00 0x01593bd 0 # 17 18 LFAC DUAL CC
6 949-658-00 0x02297eb 0 # 15 16 LFAC DUAL CC
and you want to mask the source portion of the LFAC Dual Channel Card in slot 5, create
an acmapchanges file that contains the following line:
1 4 0
Conf Function
IMAGE includes the function read_configuration_status that you can use in a test
program to read the results of a configuration check. This function returns 1 if the last
configuration check passed and 0 if it failed. It is useful for preventing execution of a test
program on a tester without all the instruments required to run the test. (See
“read_configuration_status” on page 26-55.)
Overriding Hardware Configuration Checking
In rare situations, you may want to run a test program with existing configuration conflicts.
If you have an advanced mixed-signal or Catalyst tester, test program execution is inhibited
IMAGE Solutions V8.3 4-19
IMAGE Base Language: Configuring IMAGE: Hardware Configuration Checking
Table of Contents Index Home Master Index Search Help
when configuration conflicts exist. You can, however, use the override_config command
in the station window. The syntax is:
override_config [-station #]
Once override_config is in effect, IMAGE ignores all configuration conflicts and executes
normally.
CAUTION
IMAGE inhibits test program execution to protect tester hardware. By overriding this
feature, you risk damaging tester hardware.
When loading a test program into the simulator, IMAGE still checks for configuration
conflicts but does not inhibit you from running the test program.
IMAGE Solutions V8.3 4-20
IMAGE Base Language: Loading and Running Test Programs
Table of Contents Index Home Master Index Search Help
5 LOADING AND RUNNING TEST PROGRAMS
This section includes the following topics:
• “Loading Test Programs” on page 5-2
• “Loading for Conditional Compiling” on page 5-18
• “Running Test Programs” on page 5-21
• “Deleting Test Programs” on page 5-30
• “Understanding Test Program Execution Times” on page 5-31
• “Understanding Tester Memory Usage in IMAGE” on page 5-37
• “Profiling a Test Program” on page 5-39
IMAGE Solutions V8.3 5-1
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
Loading Test Programs
The load command or LOAD button is used to load a test program into a station. A test
program includes at least a source file (.tl) and a binary file (.bin). The binary file is a
compiled but unlinked version of the program. A more complex test program can also
include digital pattern files, waveform files, other source and binary files, and perhaps some
specialized user libraries.
You can specify the files that constitute a test program when using the load command. For
all but the simplest test programs, however, use a .load file. A .load file allows all the files
that constitute the test program to be specified only once.
This is how load works:
• If <progname>.load or just <progname> is specified, and a .load file exists, the .load
file is used to load the test program.
• If no .load file is found or if <progname>.tl is specified, <progname>.tl and
<progname>.bin are loaded.
See “Types of Files Used With load” on page 5-9, “Using .load Files to Load Test Programs”
on page 5-11, and “Using make When Loading a Test Program” on page 5-12 for more
information.
When a test program is loaded in a station window, the program name is displayed in the
station window namestripe and at the bottom of the station icon. You can also display what
test program is loaded into a station window using the command station_info -program.
See “Displaying Station Window Information” on page 3-14 for more information on the
station_info command.
Loading Using the Load Window
Press MENU on the LOAD button to display a menu with the following items:
LOAD... Brings up the Load Test Program window (figure 5-1).
LOAD TEST PROGRAM Loads selected test program in the current directory. Pull right on
this selection to display .tl, .load, and .make files in this
directory. Whether you see only .load files or both .load and
.tl files is selectable from the IMAGE Properties window. (See
“Per-User Station Window Options” on page 3-35.)
LOAD AND ENTER DEBUGLoads the selected test program in the current directory, enters
debug mode, and brings up the source window. Pull right on this
selection to display the .tl and .load files in this directory. This
selection allows you to load a test program that has not been
compiled.
IMAGE Solutions V8.3 5-2
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
Figure 5-1. Load Test Program Window
If you select LOAD from the LOAD button menu, the Load Test Program window is displayed
(figure 5-1). This window has the following features:
DIR Specifies a directory name. You can also press MENU on the
menu button and choose a directory.
FILE Specifies a file name. You can also press MENU on the menu
button and choose a file.
OPTIONS: NEW FILE Loads the selected file as a new test program, enter debug, and
bring up the source window. If a file with the specified name and
an extension of .tl or .bin already exists, the load fails.
OPTIONS: DEBUG Loads the selected file, enter debug, and bring up the source
window.
OPTIONS: NO CD ON LOAD
Loads the test program using a rooted filename derived from the
directory and file information in the load window. IMAGE will not
change directory (cd) into the directory that the program is
located in as it does normally.
OPTIONS: AUTOCALIBRATION
Loads the selected file and turn on autocalibration.
OPTIONS: NO CAL. FILE Does not use the calibration data files for instruments which
support them. (See “Controlling Calibration at Test Program
Load” on page 5-11.)
OPTIONS: CAL. PINMAP ONLY
Calibrates only those copies used in the current pinmap. (See
“Controlling Calibration at Test Program Load” on page 5-11.)
HEAD TYPE: Loads the file into the selected test head type. The choices are
MIXSIG (mixed-signal), ADV_MIXSIG (advanced mixed-signal),
PATH_II (PATH II), and CATALYST (Catalyst and Catalyst Tiger).
This selection is only displayed when loading on an auxiliary test
station.
To load a test program using the Load Test Program window:
IMAGE Solutions V8.3 5-3
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
1. Press MENU on LOAD and select LOAD. The Load Test Program window appears.
2. Move the pointer to the window and select a directory. You can either type a directory
name or press MENU on the DIR menu button to select one.
3. Select a test program file by either entering a file name or pressing MENU on the FILE
button to select one.
4. Check any options, such as DEBUG.
5. Click LOAD TEST PROGRAM.
Note that the LOAD button and Load Test Program window lack some options of the load
command. If you need an option not on this menu, you must enter the load command with
that option in a station window. For example, defining flags for use in conditional compiling
requires the -define parameter and so cannot be loaded using the LOAD button. (You can,
however, include such commands in a .load file and use the Load window. See “Using
.load Files to Load Test Programs” on page 5-11.)
Loading Using Drag and Drop
If you are using the File Manager, you can also load test programs using the drag and drop
feature. This feature allows you to move a .tl or .load file icon from the File Manager
window to a station window to load it. The procedure is as follows:
1. Press SELECT on an icon in the File Manager window and drag it.
2. Place the icon anywhere in the control panel of a station window and release SELECT
to drop the icon. The Load Test Program window appears with the test program name
already filled in.
3. Click LOAD TEST PROGRAM. The test program is loaded.
Loading Using the load Command
You can load test programs using the load command in any station window. The load
command has the following format and parameters:
load <test_prog> <modules>] [<libraries>] [<other_files>]
[-define <flag>[=<val>]] [-localdef <flag>[=<val>]]
[-object <name>] [-debug] [-new] [-source <dir>]
[-switchvar_<n> #] [-sites # ...] [-station #][-incdir <dir>]
[-behavior version <ver>|compiled|latest]
[-behavior <option> <value>]
[-head adv_mixsig | path_II | catalyst | tiger]
[-handlerprober <name>] [-fast] [-autocal] [-ignore_cal] [-cal_after]
[-nocalfile] [-frc_calfile] [-pinmap_only] [-tl_init_debug]
[-compat_mode adv_mix_mode | config_mode]
[-debug_imagemain tba_free_on | tba_free_off]
[-halt_on_config_mismatch true | false]
[-stacksize [program_stack]]
[-thread_stacksize [thread_stack]]
[-<inst> [cal_type] noautocal] [-<inst> [cal_type] ignore_cal]
[-<inst> [cal_type] nocalfile] [-<inst> [cal_type] frc_calfile]
IMAGE Solutions V8.3 5-4
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
where:
<test_prog> Specifies test program <test_prog>. This name is required. It
appears in the station window namestripe when the program is
loaded. The test program name is usually specified with no
extension, but .tl and .load are legal extensions. (You must
load .make files without the .make extension.)
<modules> Specifies other modules that are part of the test program. These
files must have an extension of .tl or .c or no extension.
<libraries> Specifies user libraries (with .a extension).
<other_files> Specifies digital patterns (.pat files) and all other files with
extensions other than .tl, .c, or .a.
-define <flag>[=<val>]
-localdef <flag>[=<val>]
Defines the symbol <flag> as a compiler flag to be used with
conditional compile directives. If -localdef is specified, define
the symbol only for the preceding module.
-object <name> Looks for the binary file for the preceding source file under the
name <name> rather than using the source name to create the
binary file name.
-debug Enters debug after loading. If the program has incomplete or
missing binary files, this must be present or the load fails.
-new Creates a new test program and enters debug. If a file with the
specified name and an extension of .tl or .bin already exists,
the load fails.
-source <dir> Specifies a directory for program source files. Use this option to
specify an additional directory for source files not in the current
directory. You can use several -source parameters to specify
more than one directory. Directories are searched in the order
listed.
-switchvar_<n> # Sets a switch variable (switchvar_1 to switchvar_64) to a
value. This option allows you to affect program execution. (See
“Switch Variables” on page 7-46.)
-sites # ... Loads a multisite test program into the specified site or sites. For
example, to load a program into sites 1, 2, and 3, use:
-sites 1 2 3
By default a multisite test program is loaded into all sites
specified in the program. (See “Loading a Multisite Test
Program” on page 17-20.)
-station # Loads the program into the specified station.
IMAGE Solutions V8.3 5-5
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
-incdir <dir> Adds the directory specified in <dir> to the list of directories
searched to locate header files. You can use several -incdir
parameters to specify more than one directory. The header files
must be listed in angle brackets.
In IMAGE V6.3 and later, you can define an environment
variable named TL_INCLUDE_PATH that adds to the include file
search path and behaves exactly like the -incdir switch. (See
“Including a Search File Path” on page 14-5.)
-behavior version <ver>|compiled|latest
-behavior <option> <value>
Specifies IMAGE behavior for a version or option. (See “Using
the IMAGE Behavior Chooser” on page 5-12.)
-head adv_mixsig|path_II|catalyst|tiger
Specifies the type of tester head for an auxiliary station as
follows:
adv_mixsig advanced mixed-signal
path_II PATH II
catalyst Catalyst
tiger Catalyst Tiger
This option is required when loading a test program into an
auxiliary station. (See “Choosing Test-Head Type When Loading
an Auxiliary Station” on page 5-10.)
-fast Allows fast load of prelinked test programs under certain
conditions. Reserved for use by Teradyne.
-handlerprober <name>
Connects to a handler or prober and sets it up. Used with wafer
mapping software. (See “Using the load Command to Connect to
a Prober” on page 10-33.)
-autocal Activates autocalibration. The default is no autocal. (See
“Controlling Calibration at Test Program Load” on page 5-11.)
-ignore_cal Ignores calibration. Allows you to load a test program under
autocalibration but ignore calibration for this test program. The
default is not to ignore calibration. (See “Controlling Calibration
at Test Program Load” on page 5-11.)
NOTE
Using this parameter allows you to run the test system uncalibrated. This may result in
incorrect testing of some devices.
IMAGE Solutions V8.3 5-6
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
-cal_after Calibrates after test program run. The default is to run calibration
before the test program run. (See “Controlling Calibration at Test
Program Load” on page 5-11.)
-nocalfile Does not use the calibration data files for instruments which
support them. (See “Controlling Calibration at Test Program
Load” on page 5-11.)
-frc_calfile Forces use of calibration data files even if the calibration file may
not be valid. (See “Controlling Calibration at Test Program Load”
on page 5-11.)
NOTE
This parameter allows you to run the test system uncalibrated. This may result in incorrect
testing of some devices. Production testing is disabled in this mode.
-pinmap_only Calibrates only those copies used in the current pinmap. (See
“Controlling Calibration at Test Program Load” on page 5-11.)
-tl_init_debug Inhibits all calls to tl_init() until the first call to main(). You
can then set a breaktrap in tl_init(), execute runtotrap, and
step through code you may need to debug.
-compat_mode adv_mix_mode | config_mode
Used with the Catalyst test system so that the system operates
as though it were an advanced mixed-signal system (as an
A580). The config_mode parameter (default) specifies that the
hardware behaves to its full capability in Catalyst native mode.
-debug_imagemain tba_free_on | tba_free_off
Sets the TBA timer to be free-running across job runs
(tba_free_on), allowing interjob timing measurements. By
default, the TBA timer is reset between job runs
(tba_free_off).
-halt_on_config_mismatch true | false
Tells IMAGE whether to halt or continue test program loading if
it detects a configuration mismatch. The default value is false.
This performs the same function as the IMAGE property
image.load.halt_on_config_mismatch.
-stacksize [program_stack]
Allocates [program_stack] bytes of stack space for the test
program. If you omit this option, IMAGE allocates 16MB for stack
space. You can increase this number if your test program uses
large arrays or other data structures. You can append the scaling
factors K (kilobytes) and M (megabytes) to the number.
IMAGE Solutions V8.3 5-7
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
-thread_stacksize [thread_stack]
For multithreaded test programs, allocates [thread_stack]
bytes of stack space per thread. You must specify memory in
multiples of the Solaris page size; for example, if the page size
is 512 bytes, [thread_stack] must be a multiple of 512. If you
omit this option, Solaris allocates 1MB of stack space per thread.
(If you specify less than 1MB, Solaris allocates the full
megabyte.) You can append the scaling factors K (kilobytes) and
M (megabytes) to the number.
-<inst> [cal_type] noautocal
Causes autocal not to be activated for instrument inst or for
cal_type. (See “Controlling Calibration at Test Program Load”
on page 5-11.)
-<inst> [cal_type] ignore_cal
Calls for no calibration of instrument inst or cal_type. (See
“Controlling Calibration at Test Program Load” on page 5-11.)
NOTE
Using this parameter allows you to run the test system uncalibrated. This may result in
incorrect testing of some devices.
-<inst> [cal_type] nocalfile
Causes autocal not to be activated for instrument inst or for
cal_type. (See “Controlling Calibration at Test Program Load”
on page 5-11.)
-<inst> [cal_type] frc_calfile
Forces use of calibration data files even if the calibration file may
not be valid for instrument inst or for cal_type.
NOTE
This parameter allows you to run the test system uncalibrated. This may result in incorrect
testing of some devices. Production testing is disabled in this mode.
The load command accepts parameters in any order. To avoid ambiguity, however, the test
program name must precede any module names without an extension.
IMAGE Solutions V8.3 5-8
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
NOTE
You need not specify -textlimit when loading a large test program. The -textlimit
option is used in some older releases as an option to the load command or in a .load file
to specify the amount of space to allocate for the test program. This is no longer necessary.
For backwards compatibility the option is still accepted but is ignored.
Types of Files Used With load
The files specified to the load command (or in a .load file) can be grouped in three
categories:
• IMAGE Test Language (ITL) modules. These are usually specified as names with no
extension with each name representing both a source file with a .tl extension and a
binary file with a .bin extension. You can optionally specify the names with a .tl or a
.c extension.
If loading using -debug, source files are loaded to allow source-level debugging. Header
files included by these source files are also automatically loaded. Corresponding binary
files are also loaded if they exist and are up to date. If loading without -debug, source
files are not loaded and need not be available to the load command. If load can locate
the files, however, it does a consistency check to ensure the .bin files are up to date.
Up-to-date binary files must exist when loading without -debug.
Available binary files are linked and loaded first. No messages about unresolved
references are generated at this time. Messages may appear about duplicate
definitions.
• Library modules and other object modules. A standard set of library modules
(modules with .a extensions) are known to the load command. In addition, any
specified filenames with the .a extension are assumed to be library modules. The load
command generates a list of libraries to be searched from these two sets of filenames.
The search order is such that any libraries you specify are searched before the standard
libraries. If a library you specify has the same name as a standard library, it replaces the
standard library.
Object modules with a .o extension are treated like libraries, except that .o files are
linked unconditionally, whereas routines in .a files are only linked if referenced. The
linker first links in .o files and searches the libraries (.a files) for any remaining
unresolved references to routines or global variables. If all references cannot be
resolved, messages about unresolved references appear at this time.
• Other files mentioned on the command line or in the .load file. This includes digital
pattern files (.pat files), waveform files (.wav files), and files with any other extensions
not mentioned above. The existence of these files is checked and the filenames are
converted to full pathnames and stored internally. The files are not actually loaded until
the appropriate load statements are encountered during execution of the test program.
Patterns and wave files are loaded using these names, which will be relative to the
directory where the load took place. Any other user files read in the test program can
use the same mechanism by using the tl_get_load_path(<filename>) function to
get a full path name.
IMAGE Solutions V8.3 5-9
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
Choosing Test-Head Type When Loading an Auxiliary Station
When you load a test program into an auxiliary station, you must use the -head parameter
to specify a test-head type. Specify one of the following:
-head adv_mixsig Specifies advanced mixed-signal test head.
-head path_II Specifies PATH II test head.
-head catalyst Specifies Catalyst test head.
-head tiger Specifies Catalyst Tiger test head.
If you try to load without this parameter, you get the error message:
Must specify head type for auxiliary station n using '-head <type>'.
The -head parameter tells IMAGE which type of test station to bring up for the auxiliary
station and, therefore, which type of test head that station can be connected to. This is
important because auxiliary stations are not connected to any test head when they are first
brought up.
NOTE
If you try to load a test program using load -head adv_linear on a tester without an
advanced linear test head, you get an error. If, however, this tester has an advanced mixed-
signal test head, this command will load the program without an error.
Before running a test program on the tester from an auxiliary station, you must connect it to
a test head using the testhead command:
testhead {1 | 2 | 3 | 4} [-show] [-station #]
where:
{1 | 2 | 3 | 4} Specifies the test head to connect the auxiliary station to.
-show Shows the current test-head connection.
-station # Specifies the test station to connect.
Loading Binaries for SUN3 and SUN4 Computers
SUN3 and SUN4 computers cannot share binary, library, or object files. A feature of IMAGE
allows you to store these architecture-specific files separately for SUN3 and SUN4 systems.
You do this by creating subdirectories named sun3 and sun4. The load command will read
the correct file for the computer you are using from the correct subdirectory if it exists.
For example, executing load x102 mylib.a on a SPARC system reads sun4/x102.bin
and sun4/mylib.a if the sun4 subdirectory exists. (See “Managing Binaries for Different
CPU Types or Operating Systems” on page 7-27.)
IMAGE Solutions V8.3 5-10
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
NOTE
Sun3 testers are not supported by IMAGE V5.0 and later.
Controlling Calibration at Test Program Load
A number of load parameters allow you to control calibration when loading a test program.
For more information on calibration, see “Using load Command Parameters” on page 21-18.
NOTE
The pinmap_only mode is available only for instruments which support calibration by
instance (see table 21-1 on page 21-7).
Using .load Files to Load Test Programs
A list of filenames (modules) is necessary so that the load command knows what files to
load. A .load file is a file containing a list of all files that constitute a test program, in any
order or format. It is a convenience, allowing this information to be put in a file once, so that
you need not specify it each time the program is loaded. The name of the file is
<progname>.load, where <progname> is the name of the test program. Newlines are
ignored1.
The format of a .load file is exactly the same as the command line format. That is, any
parameter you can specify on a command line can be included in a .load file. When using
a .load file, typically you specify only the name of the test program (the same as the name
of the .load file) on the command line. However, you can specify additional command line
parameters. A typical example of this is:
load x102_mx.load -debug
Files that constitute the program are in the file x102_mx.load, but the -debug option is
specified on the command line. In this way the same program can be loaded with or without
the debug option without editing the .load file.
A .load file can include the following:
• Names of .tl files that constitute the test program. No extension is used on these
names; .tl is assumed for the source file and .bin for the binary file.
• Names of any user libraries to be included. These files have the extension .a. Libraries
mentioned first are searched first when resolving references.
• The names of additional files used in the test program. These files are recognized by
having an extension other than .tl, .c, .a, .load, or .make. These files are checked
1. See also “Using a .load File To Tailor a Test Program” on page G3-1.
IMAGE Solutions V8.3 5-11
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
for existence and read access. This allows a check at load time for files used in the test
program such as digital pattern files (.pat files).
• Parameters to the load command
• Shell-style environment variables
• Comments following a pound sign (#). Anything on a line following a pound sign is
ignored.
Using make When Loading a Test Program
You can use the Solaris make facility when loading a test program. This facility is useful for
keeping track of the pieces of a program. (See AnswerBook for a description of the make
function.) To use make, create a makefile but name the file <progname>.make. If a
<progname>.make file exists, it is assumed to be a makefile and make is run using this
makefile before the program is loaded. If no .make file is found, or if <progname>.load is
specified, and a .load file exists, the .load file is used to load the test program.
You can use either the load command or the LOAD button in the station window to load
makefiles. When you use the LOAD button, makefiles are displayed without the .make
extension.
Setting Load Properties
The IMAGE Properties window allows you to set which files you see when using the load
button. From the IMAGE Workspace menu, select PROPERTIES>IMAGE PROPERTIES. When
the window comes up, press MENU on CATEGORY and select PER-USER STATION WINDOW
OPTIONS.
This window includes the item LOAD FILE SELECTS. The default (LOAD_AND_TL_FILES) is to
show all .tl and .load files when you use the LOAD button. You can change this default to
show only .load files or only .tl files.
Using the IMAGE Behavior Chooser
Normally, you do not have to change IMAGE behavior for test programs. Programs run
using the behavior (the default values) for the version they were compiled under. If you
recompile a program under a different version, the default values become that of the version
you just compiled under.
You may, however, want to change IMAGE behavior for an entire version or for specific
options. You may want to run your test program using the default values for a different
version than it compiled under. You may also want to specify the behavior of one or more
IMAGE options.
The IMAGE Behavior Chooser (IBC), a feature of IMAGE V5.7 and later, allows you to
control consistency in the behavior of test programs from one release to another. Using the
IMAGE Behavior Chooser, you can:
IMAGE Solutions V8.3 5-12
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
• Customize behavior of your test programs so that new IMAGE options do not interfere
with old programs
• Copy a program or ship a program to another site and be confident that it will behave in
the same way
• Selectively turn on and off certain new behaviors in a release for a test program.
NOTE
Only selected IMAGE changes in each release are controlled by the IMAGE Behavior
Chooser. The complete list is in IMAGE Quick Help.
The IMAGE Behavior Chooser runs programs using the default value for each option for the
version the program was last compiled under, unless you specified otherwise. Therefore, a
program compiled under V5.7 uses the V5.7 default values, even if it is running under a later
version of IMAGE. A new or a recompiled program runs using the defaults for the version of
IMAGE it is running. So, for example, a test program created under V5.7 uses V5.7 defaults.
The IMAGE Behavior Chooser allows you to specify a value other than the default value for
an option. Beginning with V5.7, each release of IMAGE include options you can set. A
complete list of these options and their possible values is in IMAGE Quick Help under BASE
LANGUAGE>IMAGE BEHAVIOR CHOOSER. This selection lists the options you can customize
for this version and their default values.
Specifying Behavior for a Version
You can specify behavior for a specific IMAGE version. You do this when you load a test
program, either using the load command or by specifying the behavior in a
<progname>.load file or a hidden file named .image_behavior. (See “Specifying
Behavior Using a .image_behavior File” on page 5-14.)
To specify a version use the following option to the load command or edit a
<progname>.load file to include the following syntax:
-behavior version <version_num>|compiled|latest
where:
version_num Uses the IMAGE behavior for the specified version where
version_num is a valid IMAGE version. An example would be
V5.7. No IMAGE options introduced after this version are
enabled.
compiled Uses the IMAGE behavior for the IMAGE version the test
program was compiled under. If different files in the program
were compiled under different versions, the most recent version
used in compiling any of the program files is used. No IMAGE
options introduced after this version are enabled. (This is the
default.)
IMAGE Solutions V8.3 5-13
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
latest Uses the IMAGE behavior for the latest IMAGE version. This
sets all IMAGE options to the value for the version of IMAGE you
are running.
For example, to have all options run as they would under V5.7, use:
-behavior version V5.7
To keep the options as they were for the version the test program was compiled under use:
-behavior version compiled
To use all the latest values use:
-behavior version latest
Specifying Behavior for an Option Using the load Command
You can specify behavior for some individual IMAGE options. You do this when you load a
test program using the load command or by specifying the behavior in a <progname>.load
file or a hidden file named .image_behavior (see “Specifying Behavior Using a
.image_behavior File” on page 5-14) or by using the im_behavior command (see
“Displaying and Setting Behavior Values Using the im_behavior Command” on page 5-15).
You can specify an option value using the following option to the load command or by
editing a <progname>.load file to include the following syntax:
-behavior <option> <value>
where:
option Specifies the name of the option.
value Specifies the value you want to assign. Usually, the value is
enable or disable. See IMAGE Quick Help under BASE
LANGUAGE>IMAGE BEHAVIOR CHOOSER for the exact syntax and
the list of options controlled by this feature.
You must enter this command for each option value you wish to set. For example, to specify
the value of accept_aapu_syntax to enable, you would enter:
-behavior accept_aapu_syntax enable
Specifying Behavior Using a .image_behavior File
You can select IMAGE Behavior Chooser values by specifying them as parameters to the
load command. You must, however, reenter the same commands each time you load the
test program to get the same behavior. Therefore, editing a <progname>.load file or a
hidden file named .image_behavior to specify the behavior is recommended.
A .image_behavior file allows you to specify behavior choices for all test programs
whether they are loaded or not. This file can be in any of the following places:
• $HOME (your home directory)
• /image/tester/<hostname> (a tester-specific directory)
IMAGE Solutions V8.3 5-14
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
• $IMAGEBIN/custom (an IMAGE version-specific directory)
• /image/custom (a site-wide directory)
IMAGE locates the .image_behavior file, if one exists, using the above search paths and
reads the first file it encounters. For example, if a file exists in both $HOME and in /image/
custom, IMAGE reads the file in $HOME.
The precedence for IMAGE Behavior Chooser commands from highest to lowest is as
follows:
• -behavior <option>... in a .load file
• -behavior version ... in a .load file
• -behavior <option>... in a .image_behavior file
• -behavior version ... in a .image_behavior file
This means that choosing a value for a specific option behavior overrides choosing behavior
for a version. It also means that nothing in a .image_behavior file overrides behavior
specified in a .load file.
Displaying and Setting Behavior Values Using the im_behavior Command
The im_behavior command allows you to display and set the values of the current options
for the IMAGE Behavior Chooser. You can invoke it from the command line, but you must
have a test program loaded.
The syntax is:
im_behavior [<option_name> | -get <option_name> |
-set <option_name> <value_name>]
To display a list of all current behavior options for the test program, enter im_behavior. This
shows the version the values are for, and all options for this test program and version. Each
option includes its current value, its default value, and other possible values. An example is:
% im_behavior
Default Values are the defaults for version: V6.
OPTION NAME CURRENT VALUE DEFAULT VALUE OTHER VALUES
----------------------------------------------------------------------------
accept_aapu_syntax disable disable enable
apu_alarm_mode normal normal guard_only
variable_labels_in_repeat enable enable disable
hsd50_ppmu_pad_disabled_sites disable disable enable
meter_default_wmd on on off
dec_overflow_is_uint enable enable disable
thads_instr_indep_disconn enable enable disable
auto_dual_sequencer_control auto auto force_dual
force_single
reuse_equiv_handles disable disable enable
The command im_behavior <option_name> displays the version the values are for, and
the current, default, and other possible values for the option requested. An example would
be:
IMAGE Solutions V8.3 5-15
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
% im_behavior accept_aapu_syntax
Default Values are the defaults for version: V6.
OPTION NAME CURRENT VALUE DEFAULT VALUE OTHER VALUES
----------------------------------------------------------------------------
accept_aapu_syntax disable disable enable
im_behavior -get <option_name> displays the option name and its current value. An
example would be:
% im_behavior -get accept_aapu_syntax
accept_aapu_syntax disable
You can also use the im_behavior command to set behavior options. The command
im_behavior -set <option_name> <value_name> sets the requested option to the
requested value. To use this command, the test program must be in debug mode.
An example would be:
% im_behavior -set accept_aapu_syntax enable
% im_behavior
Default Values are the defaults for version: V6.
OPTION NAME CURRENT VALUE DEFAULT VALUE OTHER VALUES
----------------------------------------------------------------------------
accept_aapu_syntax enable disable
apu_alarm_mode normal normal guard_only
variable_labels_in_repeat enable enable disable
hsd50_ppmu_pad_disabled_sites disable disable enable
meter_default_wmd on on off
dec_overflow_is_uint enable enable disable
thads_instr_indep_disconn enable enable disable
auto_dual_sequencer_control auto auto force_dual
force_single
reuse_equiv_handles disable disable enable
Note that im_behavior -set only sets the option for this load of the test program. To set it
permanently for a test program, edit the <progname>.load file for that program. (See
“Specifying Behavior for an Option Using the load Command” on page 5-14.) To set it
permanently for all test programs, edit the hidden file named .image_behavior. (See
“Specifying Behavior Using a .image_behavior File” on page 5-14.)
Keeping a History of Behavior Changes
The default behavior for some options depends on the IMAGE version used to compile the
test program. You may want to record the effects of recompiles on the behavior of your test
programs. You can have IMAGE automatically create a .ibclog file to track such changes.
To create this file, display the IMAGE Properties window and select IMAGE BEHAVIOR
CHOOSER OPTIONS. Change the CREATE .IBCLOG FILE: option to TRUE. (Note that the default
for this property is FALSE. That is, this file is not created unless you request it.)
When you load a test program, a file called <program_name>.ibclog is created. If a
.ibclog file does not already exist for that test program, a new one is created in the
IMAGE Solutions V8.3 5-16
IMAGE Base Language: Loading and Running Test Programs: Loading Test Programs
Table of Contents Index Home Master Index Search Help
directory the test program is in. If write permissions do not exist for that directory, the file is
created in the $HOME directory.
The .ibclog file contains the last date and time the file was loaded after being compiled
under a different version of IMAGE. An example would be:
load test_prog.tl
% ls *.ibclog
test_prog.ibclog
% more test_prog.ibclog
Last loaded using a different version: V5.7 on DATE: 09/16/95 TIME: 7:54:47
Each time you load the program, a new entry is created in this file if the program was
compiled under a different version of IMAGE than the last version recorded in the .ibclog
file.
IMAGE Solutions V8.3 5-17
IMAGE Base Language: Loading and Running Test Programs: Loading for Conditional Compiling
Table of Contents Index Home Master Index Search Help
Loading for Conditional Compiling
Conditional compiling is a tool for managing a set of test programs that share a common
source file or set of source files.
For example, you use a set of programs to test a family of devices. If all the devices are
similar, one test program may differ from another by only a few lines of code. You do not
want to maintain separate test programs for each device; that involves duplication of code
(hard to maintain and costly in terms of disk storage). Instead, you want a single source file
(to allow the common code to be collected in one place) and some way of defining which
sections of the source apply to which particular device. Conditional compiling gives you this
ability.
Support for conditional compiling in the IMAGE environment comes in two parts. The first is
the ability to specify to the debugger (or the compiler) a set of flags which cause the compiler
to interpret the source file differently, in combination with compiler directives like #ifdef
and #if. The second is the ability to change the name of the object file produced from a
given source file, so that the name of a .bin file can reflect the fact that it was produced
using conditional compiling.
These features are implemented as options to the load and itlc commands. (The itlc
command controls the standalone compiler. See “Standalone IMAGE Compiler” on page
7-38.)
The load command has three optional parameters designed to support conditional
compiling: -define, -localdef, and -object. The itlc command supports the same
options. The -define and -localdef options work in the same way. They specify compiler
flags used during compiling. The -object option in this case tells the compiler to produce
an object file of a given name.
Defining a Compiler Flag for Conditional Compile
The -define option specifies a compiler flag which is used in any compilation for as long
as that program is loaded. In other words, if you specify -define GROUP1 when you load a
test program, the compilation that occurs (until you delete the program) has the symbol
GROUP1 defined to be 1, and any lines after an #ifdef GROUP1 statement are compiled. It
is as if every file compiled has the line #define GROUP1 1 before anything else in the file.
Specify the -define parameter once for each flag to be defined. Compiler flags defined this
way are global; that is, they apply to all the files being loaded. This eliminates the need to
type a flag definition N times if you are loading N source files and want to have a flag defined
in all of them.
Defining a Local Compile Flag
The -localdef option specifies a flag local to a particular file. This option applies to the
preceding source file, so order within the command line is significant when using it. If no
value is specified when a flag is set, it is set to 1. For example, the command
IMAGE Solutions V8.3 5-18
IMAGE Base Language: Loading and Running Test Programs: Loading for Conditional Compiling
Table of Contents Index Home Master Index Search Help
load -define EXPERIMENTAL
base.tl -localdef STANDARD
device.tl -localdef FAMILY_NAME="YLW456"
defines EXPERIMENTAL as a global flag equal to 1, STANDARD as a flag local to base.tl (also
equal to 1), and FAMILY_NAME as a flag local to device.tl (with the value "YLW456").
Specifying an Object File
The -object parameter specifies the name of the object (binary) file used for a particular
source file. Position in the command line is significant. The parameter -object always
refers to the previously mentioned source file. For example, the command
load car.tl -object ford.bin
computer.tl -object sun375.bin
specifies that the object file for car.tl is named ford.bin and that sun375.bin is the
name of the object file for the computer.tl source file.
The load command also checks to ensure that the set of flags recorded in the object files
being loaded is consistent with the set of flags specified on the load command line. When
a conflict occurs, the module responsible for the conflict is marked as invalid if the -debug
switch for the load command is included. Otherwise the load fails.
Listing Compiler Flags
You can use the command lsflags to list which compiler flags have been set by -define
and -localdef options. (You must be debugging a test program to use lsflags.)
This command has the following syntax:
lsflags [<source_files(s)> | <binary_file>]
If you enter lsflags without parameters, the display shows you the current source file
loaded in that station, the name of the object file, and the compiler flags. Global flags are
marked with an asterisk.
Conditional Compilation on SUN3 and SPARC Computers
SUN3’s and SUN4’s are source-level compatible. In some situations, however, the faster
execution speed of SPARC computers may force changes in wait statements. Conditional
compilation can be used to execute different code on the two architectures. This can be
done by using a macro, SUN3_4, allowing you to specify two values, one to be used on a
SUN3 and another to be used on a SUN4 (SPARC). The name sparc is also defined on
SPARC computers, but not on SUN3 computers. The following examples illustrate the use
of this feature.
IMAGE Solutions V8.3 5-19
IMAGE Base Language: Loading and Running Test Programs: Loading for Conditional Compiling
Table of Contents Index Home Master Index Search Help
NOTE
Sun3 computers are not supported by IMAGE V5.0 and later. This capability is included for
backward compatibility with IMAGE V4.4.
To use different wait times depending on the computer architecture use:
wait SUN3_4(1ms, 2ms); /* Wait 1 ms on a SUN3. Wait 2 ms on a Sun4. */
The following would give the same result:
#ifdef sparc
wait 2ms; /* Wait 2 ms on SPARC */
#else
wait 1ms; /* Wait 1 ms on SUN3 */
#endif
To execute a statement for SPARC only use:
#ifdef sparc
set meter wmd= 100us; /* Execute only on SPARC */
#endif
To execute a statement for SUN3 only use:
#ifndef sparc
wait 1ms; /* Execute only on SUN3 */
#endif
IMAGE Solutions V8.3 5-20
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
Running Test Programs
Using the Run Command
You run a test program using either the RUN button in the station window control panel or by
typing the run command in a station window. To use the RUN button, press MENU on RUN.
The following menu appears:
RUN PROGRAM> Run the test program once. (See “Choosing Multi-threaded or
Single-threaded Program Execution” on page 5-24.)
RETEST (RE-RUN SAME DEVICE)>
Retest the last device with the same device serial number.
Discard summary data from the previous run. Append new
datalog data to previous data. (See “Choosing Multi-threaded or
Single-threaded Program Execution” on page 5-24.)
SET PROGRAM TERMINATION MODE>
Specify how a program will stop. (See “Setting Program
Termination Modes” on page 5-24.)
The run command has the following format:
run [-station #] [-retest] [-nostats] [-site0 x y] [-sitemask #]
[-singlethread] [-args <argument>] [-reprobe]
where:
-station # Specifies a station number.
-retest Retests the last device with the same device serial number,
discarding summary data from the previous run and appending
new datalog data to previous data.
-nostats Suppresses printing of program statistics (including bin number
and program size) after the run.
-site0 x y Runs the test program once at coordinates (x,y) as site 0.
-sitemask <value> Runs the job once for each of the sites specified in <value>. The
value is read as a bit field, with one bit for each site (8 sites
maximum, least significant bit is site 0).
-singlethread Disables multi-threaded program execution on that loop
sequence only. IMAGE V6.3 and above supports this option
under Solaris 2.5.1 and above where multi-threaded operation is
the native mode. (See “Choosing Multi-threaded or Single-
threaded Program Execution” on page 5-24.)
-args <arguments> Passes argument(s) to main(). (See “Passing Command Line
Parameters to main()” on page 5-23.)
IMAGE Solutions V8.3 5-21
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
-reprobe Runs parts in reprobe mode indicating that they have been
previously tested. (See “Running a Test Program in Reprobe
Mode” on page 5-25.)
The run command runs the test program once.
If your pointer is anywhere in the station window, you can press the F1 function key to run
a loaded test program.
If your tester is equipped with a Start Switch, you can run a program and retest using this
switch. (See “The Start Switch” on page 9-1 in the Handler/Prober Manual.)
NOTE
To make execution of test statements repeatable, IMAGE software is run in high priority
mode under UNIX/Solaris. This technique eliminates interrupts when running a test
program. You may notice, however, that the LEDs on the back of the test computer do not
flash in sequence when you are running a test program. This does not indicate a hardware
or software problem. It is the result of the program running in high priority mode.
Reading Run Time Statistics
When the test program completes execution, the run command prints statistics about the
run. The following is an example:
Device #99 Bin #0 Test time = 6.360 sec
Test program size = 2072K. (text=896K data=944K malloc data=232K)
The first line gives the device ID number, the (software) bin number for the run, and the test
time in seconds. On a simulator workstation, test time is measured by the Solaris clock,
which is accurate to about 50 ms. On a tester, the time printed is accurate to the millisecond,
since a timer with more resolution is used. (See “Understanding Test Program Execution
Times” on page 5-31.) A test program takes longer to run the first time because it must be
loaded into physical memory.
The second line gives the size of the test program process in kilobytes. The numbers
indicate how much memory used by the program is taken up by text (instructions), data
(such as global variables and string storage), and dynamic memory allocation (malloc
data). See “Understanding Tester Memory Usage in IMAGE” on page 5-37 for information
on test program size.
For a multisite test program, binning is shown for all sites. For a two-site program, an
example would be as follows:
Site Device # Bin # Test time = 2.045 sec
0 1 1
1 2 1
Test program size = 2100K. (text=904K data=952K malloc data=244K)
Test program statistics are printed after each run, except when:
IMAGE Solutions V8.3 5-22
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
• Looping a test program using the loop command with the option NO MESSAGES selected
from the LOOP button menu
• The tester is connected to a handler or prober and the station window is not in debug
• The -nostats option is used with the run command
Passing Command Line Parameters to main()
The run -arg command allows you to pass command line parameters through to main().
All tokens after -arg are passed to the test program. The arguments appear as an array of
character strings. Strings can then be readily converted to numbers using atoi(), atof(),
and other standard UNIX library functions. Under UNIX, the first argument to main() is the
program being run. Under IMAGE, this argument will be the name of the loaded test
program.
For example:
main(argc,argv)
int argc;
char *argv[];
{
/*The name of the test program is available in argv[0]*/
printf("The test program name is %s\n", argv[0]);
/*This example expects three arguments: a string, an
int, and a float*/
/*Print the string*/
printf("the first arg (a string) is %s\n", argv[1]);
/*Convert and print the int*/
printf("the second arg (an int) is %d\n", atoi(argv[2]));
/*Convert and print the float*/
printf("the third arg (a float) is %f\n", atof(argv[3]));
}
When this test program (called test_program) is loaded and run with the command line:
run -args 'first arg' 44 8.9876
the results are:
The test program is test_program
the first arg (a string) is first arg
the second arg (an int) is 44
the third arg (a float) is 8.987600
A -arg without a following token is treated as an error by the run command. The parameter
can also be used with the runtotrap command. You cannot use it with the cont command.
When the test program is not stopped, step enters the program through main(). However,
step does not accept the -arg command line parameters. (You can set a trap at the first
line of main() and use runtotrap.)
IMAGE Solutions V8.3 5-23
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
Choosing Multi-threaded or Single-threaded Program Execution
IMAGE V6.3 and later supports the option of multi-threaded or single-threaded program
execution under Solaris 2.5.1 and above where multi-threaded operation is the native mode,
as in the Catalyst test system. Choosing single-threaded operation forces the compute
blocks to run in-line on that run, retest (re-run), or loop sequence only.
Setting Program Termination Modes
You can set the test program termination mode by pressing MENU on the RUN button,
selecting SET PROGRAM TERMINATION MODE, and pulling right. This displays a menu with the
following selections:
STOP ON FAIL Stop running the test program on fail bin, stop program on error.
(This is the default.)
CONTINUE ON FAIL Continue running the test program past fail bin, stop program on
error.
CONTINUE ON ERROR Continue running the test program past fail bin, continue
program past error.
SHOW PROGRAM TERMINATION MODE
Display the current termination mode.
You can also set the termination mode using the tmode command in a station window. This
command has the following format:
tmode [-stop_on_fail | -cont_on_fail | -cont_on_error] [-show]
[-station #]
where:
-stop_on_fail Stops running the test program on a fail bin, stop the program on
an error. (This is the default.)
-cont_on_fail Continues running the test program past any fail bin, stop the
program on an error.
-cont_on_error Continues running the test program past any fail bin, continue
the program past an error.
-show Shows current termination mode.
-station # Specifies station number.
Setting the program termination mode allows you to control the way a test program decides
when to stop.
In stop-on-fail mode, the default state, device testing stops as soon as a fail bin is reached;
no additional test functions or sequencers are called. (The program actually stops at the end
of the failing test function, not immediately after the test statement that caused the device
to be binned in the fail bin.) When a single site in a test program hits a relevant run-time
error, the site on which the error occurred is disabled and testing continues on the remaining
IMAGE Solutions V8.3 5-24
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
sites. Sites are not disabled if the test program mode is continue-on-error. The test program
is only stopped if there are no more active sites after an error.
In continue-on-fail mode the test program continues past any fail bins. The sequencer
stores the fail-bin value, and, when it completes, returns that value. This state is used to
guarantee full datalogs, despite failing tests. When a single site in a test program hits a
relevant run-time error, the site on which the error occurred is disabled and testing
continues on the remaining sites. Sites are not disabled if the test program mode is
continue-on-error. The test program is only stopped if there are no more active sites after
an error.
In continue-on-error mode the test program operates as in the continue-on-fail mode. Test
programs continue past relevant run-time errors and errors are printed on the screen. This
feature is useful in debugging. It allows you to force a program to continue past errors to a
later section of greater interest. (See “Controlling Run-Time Errors” on page 15-31.)
CAUTION
Before using continue-on-error mode evaluate the errors to be sure that continuing
will not harm the hardware or the device. Do not run test programs in the continue-
on-error state during production testing.
You can also change the program termination mode from a test program using the function
call tl_set_tmode_cod(). (See “tl_set_mode_cod” on page 26-369.)
Running a Test Program in Debug and in Production Mode
When you run a test program, IMAGE works differently in debug mode and in production
mode. The difference is in the way run-time errors are handled.
In debug mode, a running test program halts when any run-time error occurs. The idea is
that during debug you may want to perform some action when the error occurs or halt the
program. Because the program only halts at the run-time error, however, the test program
is not finished and the device is not binned.
In production mode, run-time errors are handled differently. If you get an error, the program
issues the error (usually to a log file), bins the part accordingly, and continues testing.
Running a Test Program in Reprobe Mode
The reprobe switch to the run command specifies that a set of parts run in reprobe mode.
Reprobe mode indicates that the parts to be tested have been previously tested and can be
identified by their x and y coordinates. Parts run in reprobe mode are not included in the
summary data analysis but do appear in the datalog. Reprobed parts receive the same part
ID string from when they were first tested.
Because the parts are identified by x and y coordinate pairs, the coordinates of the device
being tested must be set for the device, either from the run command or during the run of
IMAGE Solutions V8.3 5-25
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
the test program. Coordinates can be set by using the run command -site0 argument,
which specifies the x and y coordinates of site 0.
Looping a Test Program
Looping allows you to run a test program repeatedly. To start looping, press MENU on the
START LOOP button. This displays a menu with the following selections:
LOOP ON WITH MESSAGES
Start running the test program repeatedly. Display the test
program binning and statistics message after each run. (See
“Choosing Multi-threaded or Single-threaded Program
Execution” on page 5-24.)
LOOP ON, NO MESSAGES Start running the test program repeatedly. Do not display the test
program binning and statistics message. (See “Choosing Multi-
threaded or Single-threaded Program Execution” on page 5-24.)
If you click SELECT on START LOOP, you start looping with no messages. When looping is
on, the START LOOP button label changes to STOP LOOP.
By default, the device number, bin number, test time, and test program size are displayed
on each loop. You can suppress this message using LOOP ON, NO MESSAGES. You would do
this to shorten the loop if, for example, you were examining a signal with an oscilloscope.
To stop looping, press MENU on the STOP LOOP button. This displays a menu with the
following selections:
LOOP OFF AFTER NEXT RUN
Stop looping after the current run of the test program. (This is the
default.)
ABORT LOOPING IMMEDIATELY
Stop looping without waiting for the current run of the test
program to finish. This selection is equivalent to the abort
command.
You can also turn looping on and off using the loop command in a station window. This
command has the following format:
loop -on | -off [-noinfo] [-singlethread] [-station #]
where:
-on Turns looping on.
-off Turns looping off.
-noinfo Does not show device#, bin#, and other information while
looping.
-singlethread Disables multi-threaded program execution on that loop
sequence only. IMAGE V6.3 and later supports this option under
Solaris 2.5.1 and above where multi-threaded operation is the
IMAGE Solutions V8.3 5-26
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
native mode. (See “Choosing Multi-threaded or Single-threaded
Program Execution” on page 5-24.)
-station # Specifies a station number.
NOTE
CONTROL-C does not affect looping.
Forcing a Test to Pass or Fail
When running a test program, you can force tests in the program to always fail, pass, or
alarm using the command force_test. Use the following syntax in a station window:
force_test -[-pass | -fail | -alarm | -clear | -show |
-site <n> <n> ...]
{name | number | name1 number2 name3 ... | all}
where:
-pass Forces the specified tests to pass.
-fail Forces the specified tests to fail.
-alarm Forces the specified tests to alarm.
-clear Undoes the force specification.
-show Displays the setting for the specified tests. This command can be
useful in a shell script.
-sites <n> Restricts the force command to the site or sites specified. The
value of n can be any site number from 0 to 8.
{name | number | name1 number2 name3 ... | all}
Specifies a test name, test number, a combination of names and
numbers, or all tests. If you specify a test name, all the tests in
that TESTF are forced. The specified state is applied to all active
test sites.
If you issue the force_test command without parameters, the current force settings are
displayed.
For example, you want tests 1 and vout2 always to fail. You would enter the command:
% force_test -fail 1 vout2
To see which tests are set to fail, enter the force_test command, as follows:
% force_test
fail 1 vout2
IMAGE Solutions V8.3 5-27
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
The action of the force_test command is the same as using the pass and fail options to
the IMAGE test statement without a test statement value. See “Test Functions” on page
14-18.
Aborting a Test Program
To stop test program execution immediately, use the ABORT button or command. Press
MENU on the ABORT button, and the following menu selections are displayed:
ABORT TEST PROGRAM EXECUTION
Stop test program execution immediately.
HALT PROGRAM IF AT TRAP
Stop the test program if it is halted at a debug trap.
LOOP OFF AFTER NEXT RUN
Stop the loop between test program executions.
You can also enter the abort command in any station window. It has the format:
abort [-afterrun] [-station #]
abort immediately stops execution of any command to the test program. For example, it
halts a looping program, even during program execution, and turns off looping. It also stops
a normal run command. Many debug commands, such as commands for debug displays
(see “Debug Displays” on page 7-47) require execution of the test program.
If you are debugging a test program, you can use HALT PROGRAM IF AT TRAP. This means
that the program is no longer considered stopped at the trap, and the hardware is reset.
(See “Halting a Test Program” on page 7-19.)
Instead of using the LOOP OFF AFTER NEXT RUN menu item you can use the command line
option -afterrun with the abort command. The -afterrun option stops the looping-to-
trap program at the end of the test program run.
In practice, always click on the ABORT button to invoke the abort command rather than
entering abort on the command line.
Controlling User Power
The USER POWER menu button controls user power to the applications circuitry on the device
interface board (DIB) in the test head. Press MENU on the USER POWER button to display
the following menu:
SHOW USER POWER Displays the state of user power.
TURN USER POWER ON Turns user power on.
TURN USER POWER OFF Turns user power off.
You can also control user power by entering the usrpower command in any station window.
It has the following format:
IMAGE Solutions V8.3 5-28
IMAGE Base Language: Loading and Running Test Programs: Running Test Programs
Table of Contents Index Home Master Index Search Help
usrpower [-on | -off] [-show] [-station #]
where:
-on Turns user power on.
-off Turns user power off.
-show Displays the state of user power.
-station # Specifies a test station.
Loading Hardware Checkers
To load and debug hardware checkers (software programs used to verify the hardware),
use the CHECKERS button. Press MENU on CHECKERS and the following menu is displayed:
CUSTOM CHECKER RUNS>
Load custom checkers.
SYSTEM CHECK> Load and run the system checkers.
CHECKER GROUPS> Load selected checker programs in groups.
CHECKER GROUPS -FAST>
Load all available checker programs quickly.
CHECKER GROUPS -DEBUG>
Load selected checker programs in groups and enter debug.
INDIVIDUAL> Load the selected checker program.
Checkers are discussed in “Checkers” on page 19-1.
IMAGE Solutions V8.3 5-29
IMAGE Base Language: Loading and Running Test Programs: Deleting Test Programs
Table of Contents Index Home Master Index Search Help
Deleting Test Programs
Click the DELETE button to delete a test program loaded in a test station. You can also delete
a program by entering the delete command in a station window. The delete command has
the format
delete [-nosave] [-station #]
where:
-nosave Deletes the test program without saving any edits.
-station # Specifies a station window.
If you click the DELETE button, a confirmation is required before the program is deleted.
If you edit a program and try to delete it before saving the changes, you are asked to save
the changes. If you click on the DELETE button with unsaved changes, you get a warning box.
If you do not want to save any changes, click on DISCARD CHANGES AND DELETE TEST
PROGRAM. You can also exit without saving changes using the delete -nosave command.
(See “Exiting Debug” on page 7-37.)
IMAGE Solutions V8.3 5-30
IMAGE Base Language: Loading and Running Test Programs: Understanding Test Program Execution Times
Table of Contents Index Home Master Index Search Help
Understanding Test Program Execution Times
Test program execution has several phases. This section describes the timing of running a
test program in production mode. You can use this information to estimate the actual device
throughput you will receive on the test floor2.
The first phase of test execution is deciding that the test should be run. In the engineering
environment this usually means typing run in the station window. In production mode,
however, this usually means polling a handler and possibly waiting for the handler to index
the next device. This phase is part of what is known as “intertest time,” that is, time not spent
actually running the test program. Serial handler communication imposes significant
overhead. Typical serial handler communication times are 175–200 ms; parallel times are
2–3 ms.
The next phase of execution is preparing to run the test. This involves resetting all
instruments used in the test and performing other preparations for run. This phase is
counted as part of the “test time,” that is, time spent running the test program.
The length of this preparation phase depends on how many instruments you use in the test.
A good estimate of reset time is anywhere from 10 ms to 50 ms (A580 advanced mixed-
signal test using many instruments). The exception to these guidelines is the Precision
Multimeter (PMM). The PMM takes about 125 to 150 ms to complete its reset. Add this time
to the estimate if the PMM is used in the test. In addition, about 1–2 ms is required to
prepare for running the test program.
The next phase, actual test execution, varies widely. However, it should not change
significantly when moving from an engineering environment to a production environment.
(The device test time printed in the test status message on the simulator does not predict
the time on the hardware. See “Test Status Message” on page 5-33.) This phase is clearly
part of the test time.
A5xx testers have a dual computer architecture. Therefore, to send output to the station
window (from printf() and the output due to the test status messages) the tester
computer must synchronize with the user computer to send the output across. This involves
at least 100 ms for the first character. In other words, if you are trying to optimize test time,
avoid sending output through printf() and run in production mode with the test status
messages turned off. Count the time necessary to synchronize and send output as test time,
but calculate it before the printf() which actually prints the status message. Therefore,
the time necessary to pass the output is not included in the printed device test time in the
test status message.
The last phase of test execution is cleaning up from the test program execution and
preparing for the next run. This involves tasks like shutting down instruments and
distributing binning information. Again, the length of this phase depends on the instruments
used in the test and the complexity of datalog. Times range from 9–30 ms. This time is also
counted as test time.
2. See also “Test Time Reduction Techniques” on page G5-1.
IMAGE Solutions V8.3 5-31
IMAGE Base Language: Loading and Running Test Programs: Understanding Test Program Execution Times
Table of Contents Index Home Master Index Search Help
Finally, the device must be binned. This involves two stages. First, the handler must be told
to bin the part (serial/parallel communication time); then the handler must actually perform
the binning. This is counted as intertest time and the length of this phase varies depending
on the type of handler communication and the length of time the handler takes to perform
binning.
Multiplexing Tests
IMAGE can multiplex tests over more than one station. This method allows device testing
to occur on one station while the handler on another station is indexing to the next device.
The overhead involved in this process is insignificant (1–2 ms). Typically, multiplexing is
used when device test times are on the same order of magnitude as indexing times.
However, you cannot reduce handler communication time using this technique.
Datalogging Tests
The way in which you datalog test results can also affect test time. In particular, using the
Datalog Output window when datalogging large amounts of data can add to test time.
IMAGE requires extra time to send data to this display window, and the additional time can
be as much as several seconds. Outputting the data to a file or an STDF file does not cause
this problem.
Linear Instrumentation Example
The following is an example of what happens during execution of a linear test program on
an A530 using a parallel handler with an index time of 100 ms and a test program execution
time of 150 ms.
• Phase 1–Decision to run–3 ms
Presumably, a test program has just completed. IMAGE polls the handler for a start
signal. This phase may have an additional delay while IMAGE waits for the handler to
complete indexing.
• Phase 2–Preparation–19 ms
Instruments must be reset and other aspects of IMAGE must be prepared for test
program run.
• Phase 3–Execution–150 ms
Actual test execution (no status message).
• Phase 4–Clean up–16 ms
Instrument shutdown; internal closure.
• Phase 5–Binning–3 ms
The handler is told to bin the device.
• Phase 6–Binning and indexing–100 ms
The handler bins the device and indexes the next device. (This phase may overlap with
phase 1.)
IMAGE Solutions V8.3 5-32
IMAGE Base Language: Loading and Running Test Programs: Understanding Test Program Execution Times
Table of Contents Index Home Master Index Search Help
The total test time (phases 2, 3, and 4) is 185 ms. The total intertest time (phases 1, 5, and
6) is 106 ms.
Advanced Mixed-Signal Instrumentation Example
This example describes what is happening during an advanced mixed-signal test program
execution on an A580 system using a serial handler with an index time of 500 ms and a test
program execution time of 10 seconds.
• Phase 1–Decision to run–180 ms
Presumably, a test program has just completed. IMAGE polls the handler for a start
signal. This phase may have an additional delay while IMAGE waits for the handler to
complete indexing. The large amount of time in this phase is largely due to the serial
handler.
• Phase 2–Preparation–50 ms
Instruments must be reset and other aspects of IMAGE must be prepared for test
program run. (This assumes no PMM in the configuration.)
• Phase 3–Execution–10000 ms
Actual test execution (no status messages).
• Phase 4–Cleanup–27 ms
Instrument shutdown; internal closure.
• Phase 5–Binning–180 ms
The handler is told to bin the device.
• Phase 6–Binning and indexing–500 ms
The handler actually bins the device and indexes the next device. (This phase may
overlap with phase 1.)
The total test time (phases 2, 3,and 4) is 10077 ms. The total intertest time (phases 1, 5,
and 6) is 860 ms.
Test Status Message
The test status message reports the length of the test time and binning status. This time is
the sum of the test program preparation phase (including resets), test execution phase, and
cleanup phase. The time printed on the simulator does not reflect what you will see on the
actual hardware.
Since the number to be printed in the status message must be calculated before the output
is sent to the station window, the overhead of synchronizing the two computers for output is
not included. Thus, the test status message accurately reflects the test time you see in
production mode with messages turned off. However, if you try to calculate the “test cycle
time” by testing a certain number of devices and dividing the total time while messages are
turned on, you will see about 150 ms of additional time attributed to communication
overhead.
IMAGE Solutions V8.3 5-33
IMAGE Base Language: Loading and Running Test Programs: Understanding Test Program Execution Times
Table of Contents Index Home Master Index Search Help
Test In Progress (TIP) Hardware Signal
The TIP signal is often used to measure test time. TIP is an active low signal. When TIP is
low, the test is executing and when TIP is high the test is not executing. You should know,
however, what TIP signals actually measure.
In terms of the definitions given above, TIP low does not cover all phases of test time. In
fact, it covers only about 3–5 ms more than the time your test program is actually executing.
While this may seem to be a good indicator of test time, it does not cover other variable
times closely tied to the test program such as reset time and shutdown time. TIP has a much
narrower view of what is actually test time.
Using Tester Utilization Events to Measure Computer Usage
IMAGE includes a utility that allows you to measure the percentage of test computer usage
by generating tester utilization (t_tester_util) events. You start generation of these
events using a selection in the IMAGE Properties window. (See “FIRMS Interface Options”
on page 3-38.) The format of t_tester_util events is in the Standard Event Message
Format (SEMF) Specification. See this document for more information.
How Utilization is Calculated
Tester utilization is calculated by
Total time program ran during period
------------------------------------------------------------------------------------------------- × 100 (5–1)
Total time for period
The first utilization period begins when IMAGE is first started, and the last one ends when
IMAGE is exited. IMAGE tries to send a message when it exits, but this cannot be
guaranteed.
NOTE
A tester utilization event always generates 0.00% when you are using the IMAGE simulator.
Generating the Events
To generate t_tester_util events, you must change a few items in the IMAGE Properties
window. You cannot change the state of tester utilization messages while IMAGE is running.
This information is read only when IMAGE is started. The new changes are only recognized
inside IMAGE when you restart IMAGE after having chosen how you wish to run tester
utilization.
The changes you must make are under the FIRMS INTERFACE category in the IMAGE
Properties window. In this category is an item labeled SEND TESTER UTIL EVENT:. The four
choices underneath this item are:
IMAGE Solutions V8.3 5-34
IMAGE Base Language: Loading and Running Test Programs: Understanding Test Program Execution Times
Table of Contents Index Home Master Index Search Help
NEVER Tester utilization is never sent. This is the default.
JOB LOAD/UNLOAD Send an event every time a test program is loaded or unloaded.
Figure 5-2 shows an example.
IMAGE Prog 1 Prog 2 Prog 2 Prog 1 IMAGE
Start Load Load Unload Unload Exit
u1 u2 u3 u4 u5
Event Event Event Event Event
Figure 5-2. Tester Events Based on Test Program Load and Unload.
TIME BASED Send an event according to the period specified. If you choose
this option, two additional fields become active:
SEND TIME BASED TESTER UTIL:
Specifies events are to occur at the same time every day spaced
by time increments. Time increment can be every 15 minutes,
half hour, hour, 2 hours, 3 hours, 4 hours, 6 hours, 8 hours, 12
hours, or daily.
ALIGN EVENT TO OCCUR AT:
Specifies the time of the first event. Enter the time in normal
format:
hour[1-12]:minute [am/pm]
or in military format:
hour[0-23]:minute
Time is always converted to normal format in the text field
whenever you click on the APPLY button or press Return, Tab, or
linefeed. Formats without am or pm are taken to occur from 1:00
am to 12:00 pm. Figure 5-3 shows an example of setting the
utilization period to 8 hours aligned to occur at 9:00 am.
IMAGE IMAGE
START EXIT
7:00 AM 9:00 AM 5:00 PM 1:00 AM 9:00AM 12:00 PM
u1 u2 u3 u4 u5
Event Event Event Event Event
Figure 5-3. Tester Events Set to Start at 9:00 AM and Occurring Every Eight Hours.
JOB AND TIME BASED Tester utilization message is sent at both the specified times and
whenever a test program is loaded or unloaded. Note that
IMAGE Solutions V8.3 5-35
IMAGE Base Language: Loading and Running Test Programs: Understanding Test Program Execution Times
Table of Contents Index Home Master Index Search Help
messages are not independent Figure 5-4 shows an example of
an event set to occur at test program load and unload and at 9:00
am with a utilization period of 8 hours.
IMAGE Job1 Job 2 Job 1 Job 2 IMAGE
Start Load Load Unload Unload Exit
7:00 AM 8:00 AM 8:30 AM 9:00 AM 10:00 AM 4:00 PM 5:00 PM 6:00 PM
u1 u2 u3 u4 u5 u6 u7
Event Event Event Event Event Event Event
Start 7:00 AM 8:00 AM 8:30 AM 9:00 AM 10:00 AM 4:00 PM 5:00 PM
End 8:00 AM 8:30 AM 9:00 AM 10:00 AM 4:00 PM 5:00 PM 6:00 PM
Figure 5-4. Tester Events Set to Start on Program Load, at 9:00 AM, and Every Eight Hours.
IMAGE Solutions V8.3 5-36
IMAGE Base Language: Loading and Running Test Programs: Understanding Tester Memory Usage in IMAGE
Table of Contents Index Home Master Index Search Help
Understanding Tester Memory Usage in IMAGE
When upgrading a tester to a new version of IMAGE, the new software affects the amount
of test computer memory available for use by test programs. This amount can change due
to several factors, including a new version of the Sun operating system (that is, a larger
UNIX/Sun kernel) and changes to IMAGE.
Such changes may cause problems with test computer memory, especially with paging.
Programs just small enough to run under one version may begin paging when running under
a new version. This section will help you understand memory usage and provide guidelines
to help you determine the maximum size for your test programs.
Allocation of Test Computer Memory
When a test program is loaded into the test computer under IMAGE, the test computer
memory is used in several ways. In addition to the memory used by the program itself,
memory is occupied by the UNIX/Sun kernel and by an additional “daemon” program which
is part of IMAGE. These factors affect the amount of memory actually available for an
IMAGE test program.
Test program size is also determined by several factors, including the number and size of
the functions and variables defined by the program. Tester instruments used by a program
have a secondary effect. For each instrument used, IMAGE links in an instrument driver
which increases program size. Test program size is reported when using the run command.
(See “Reading Run Time Statistics” on page 5-22.)
At times, the test computer may not have enough physical memory for all the programs that
need to fit in it. In such cases, Solaris swaps portions of one program out to disk while
another program runs and then restores the swapped program when it is scheduled to run.
This is known as “paging.” As a rule, avoid test programs that page. Paging is slow, which
reduces throughput, and it impairs repeatability because Solaris interrupts the test program.
Immediately before running a test program, IMAGE executes procedures to reduce the
possibility of page faults during the run. When competition for memory on the test computer
is severe, however, these procedures begin to break down. When paging starts, the first
symptom is increased test time due to page faults happening before the start of the run. As
the situation worsens, page faults begin to happen during execution of main(). When this
happens, IMAGE records the number of page faults and adds a warning message to the
status printed after the run command:
... pages read from disk during run
Stack Space
Memory used by a test program is roughly divided into the following categories:
• Text—memory space which holds instructions for each program function.
• Data—memory space used by the program’s global variables
IMAGE Solutions V8.3 5-37
IMAGE Base Language: Loading and Running Test Programs: Understanding Tester Memory Usage in IMAGE
Table of Contents Index Home Master Index Search Help
• malloc data—dynamically allocated memory such as storage allocated using
malloc().
• Stack—memory space used to implement subroutine execution and to store local
variables.
When a program begins executing, no stack space is allotted. During execution, each time
the program descends into an additional level of subroutine nesting, local variables for that
subroutine are allocated by taking up more stack space. The total amount of stack space a
program uses is, therefore, dependent on its execution flow. This may change from run to
run depending on
• How deeply nested the subroutine calls are
• The size of the local variables the program uses in those subroutines
As a result of the way the stack works, predicting the amount of stack space a program uses
is difficult. Making an accurate estimate requires an understanding of the test program and
of how it will behave when it runs.
A test program stack size of 64K is a reasonable estimate based on an examination of a
number of test programs. Note that the 64K figure is based on test programs which use very
few large local arrays (greater than 1k bytes or so), as might be used for generating
waveform data. Using large local arrays causes a program to use more stack space,
resulting in a lower maximum test program size number.
IMAGE Solutions V8.3 5-38
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
Profiling a Test Program
The Sequencer Profiler, Custom Profiler, and Memory Profiler are IMAGE features. The
Sequencer Profiler measures the time each TESTF takes to execute. The Custom Profiler
measures the time each code section specified in the test program takes to execute. The
Memory Profiler measures the memory usage of the test program.
Sequencer Profiler and Custom Profiler
Both TESTFs in sequencer profiling and code sections in custom profiling are referred to as
bins. The Terabus timer is used for timing, giving a resolution of about 10 µs. A report is
automatically generated at the end of the program run that displays the bin messages, the
time spent in each bin, and the percentage of time in each bin to the station window.
Production of this profile report does not significantly affect test time.
The Sequencer Profiler and Custom Profiler are available on the simulator, using the UNIX
system clock. However, times reported by the profiler on the simulator will not match times
reported on a tester.
Profiling adds the following additional bins:
• Pre-Test
• Non TESTF Code (Sequencer Profiler) or Unprofiled Code (Custom Profiler)
• Post-Test
• Profile Overhead
The Pre-Test bin is the time required to prepare to run the test program before the main()
function is called. Much of this time is spent resetting test system instruments before they
are used. The length of this time depends on how many different test system instruments
are used in the test program. In addition, some instruments take a long time to reset. An
example is the Precision Multimeter (PMM), which takes about 150 ms to reset.
When using the Sequencer Profiler, Non TESTF Code is the time required to execute all
code in the test program which is not in a TESTF.
When using the Custom Profiler, Unprofiled Code is the time required to execute all code
not enclosed by tl_profile_mark() and tl_profile_end().
Post-test is the time required to shut down test system instruments and clean up from the
execution of the test program.
Profile Overhead is the time required to mark each bin into the profiling data structure.
This code executes only when profiling is enabled.
The sum of execution time of these bins with test program bins approximately equals
execution time of the entire test program. This time should agree with the time reported in
the test status message (if this message is enabled).
When using profile utilities, keep in mind the extra time required for output to station
windows. Due to the A5xx dual computer architecture, sending output (from printf() and
IMAGE Solutions V8.3 5-39
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
output due to test status messages) requires that the tester computer synchronize with the
user computer. This takes at least 100 ms for the first character.
If, therefore, you are trying to optimize test time, avoid sending output through printf()
and run in production mode with test status messages off. Count the time necessary to
synchronize and send such output as test time. Due to the fact that the device test time is
itself part of the output, however, it must be calculated before the printf(). Therefore, the
time necessary to pass the output is not included in the printed device test time in the test
status message or in profiler output.
Memory Profiler
The Memory Profiler determines memory usage of the test computer and reports page
faulting during test program run and initialization. The Solaris architecture used on the test
computer allows memory pages to be swapped out to disk when physical RAM is low.
Reading and writing pages to and from disk (page faulting) is extremely slow and affects
test program repeatability and throughput.
The Memory Profiler prints the number of page faults which occurred during the test
program run after each run. Such page faults indicate that the test program is too large to
fit into physical memory at once. Recording of page fault statistics during test program run
is enabled by default.
The Memory Profiler can also print the number of page faults which occurred during test
program initialization. This type of page fault indicates that the test program is too large to
fit into physical memory along with other components of IMAGE which must execute
between test program runs. Because recording page fault statistics during test program
initialization requires test system overhead (specifically, two system calls per run), it is
disabled by default.
Page fault statistics are never printed during the first run of a test program. This is because
the program must be read from disk for the initial run, so page fault statistics at this time
would be misleading.
Page faulting problems have two common solutions. You can reduce the size of the test
program or install more memory on the test computer. To determine how much memory is
required, the Memory Profiler can display a report of memory usage on the test computer.
This report lists memory usage for various components of IMAGE, for the operating system
software, and for each test program currently loaded. It also estimates the maximum test
program size which will not cause page faulting.
NOTE
Determining exact memory allocation is not possible due to the way UNIX memory
allocation works. Memory allocation reported by the Memory Profiler (using the profile
-meminfo command) will not exactly match the memory use reported on the test program
status message line or the output from the pstat command when run on the test computer.
IMAGE Solutions V8.3 5-40
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
Profile Command
Profiling options are controlled by the profile command. The syntax of this command is
as follows:
profile [-station #] [-on | -off] [-print #] [-sequencer | -custom]
[-bytime | -byname | -byexec] [-fixed | -scaled] [-mem_info]
[-mem_check on | off | full] [-read <file>] [-writestation]
[-nostation] [-writetext [-textfile <filename>] [-notext]
[-writeinsight [-insightfile <filename>]] [-noinsight]
[-compare <filename>]] [-nocompare]
where:
-station # Specifies a test station.
-on Turns sequencer or custom profiling on. If neither sequencer
mode nor custom mode is specified, the default sequencer mode
is used. If the profiler is turned off, then turned back on, the state
of the profiling mode is the previous profiling mode.
-off Turns sequencer or custom profiling off. The profiler does
nothing. This is the default.
-print # Limits the number of bins listed in the report. Specify a positive
number to list only that number of bins. Specify 0 to list all bins.
You cannot use a negative number. When listing a limited
number of bins, the bins listed are those at the top of the list, by
whatever sorting criterion is in effect. (The default is 0, print all
bins.)
-sequencer Sets profiling mode to sequencer mode. The profiler records the
time required to execute each TESTF each time the TESTF is
called. At the end of the test program, the profiler produces a
report including the TESTF name, its datalog number, its
execution time, and the fraction of total test time the execution
time represents. (This is the default mode of the profiler.)
-custom Sets profiling mode to custom mode. The profiler records the
time required to execute each section of the code specified by
tl_profile_mark() and tl_profile_end() in the test
program. At the end of the test program, the profiler produces a
report including the name of the section specified, its profiler bin
number, its execution time, and the fraction of total test time the
execution time represents. (See “Custom Profiler Example” on
page 5-45.)
IMAGE Solutions V8.3 5-41
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
NOTE
Some IMAGE releases before V5.6 use the function tl_profile_enable() to turn on test
program profiling. This function is not used in IMAGE V5.6 and later. Remove it from any
test programs. Use of this function may interfere with some functions of the profile
command.
-bytime Sorts the report at the end of the test program by execution time,
placing the slowest bins at the beginning. You cannot use this
option with -byname or -byexec. (This is the default.)
-byname Sorts the report by name in alphabetical order. You cannot use
this option with -bytime or -byexec.
-byexec Sorts the report by execution order, placing bins executed first at
the beginning of the report. You cannot use this option with
-byname or -bytime.
-fixed Sets the output display unit for all times to be microseconds (the
base unit).
-scaled Sets the output display unit for all times to be scaled. This option
scales all times to a base unit which can be expressed as:
xxx.yyy <unit>
where there is at least one and no more than three digits before
the decimal point. Examples are:
35.62 ms
1.04 sec
876.45 usec
(This is enabled by default.)
-mem_info Displays a report of memory usage on the test computer. Not
available on the simulator. (See “Using The Memory Profiler to
Display Memory Usage” on page 5-46.)
-mem_check on Enables recording of page fault statistics during test program
run. This is enabled by default. (See “Using The Memory Profiler
to Display Page Faults” on page 5-46.)
-mem_check off Disables recording of page fault statistics during test program
run.
-mem_check full Enables recording of page fault statistics for both test program
run and test program initialization. (This is disabled by default.)
-read <file> Reads the named text file so it can be compared to another text
file. When using this option, the profiler is limited to comparing
two files. That is, no changes to the internal state of the IMAGE
IMAGE Solutions V8.3 5-42
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
profiler are made. (See “Writing Profiler Data to a File” on page
5-47.)
-writestation Writes the profiler report to the station window. This is the
default.
-nostation Suppresses writing the profiler report to the station window.
-writetext Writes the profiler report to a text file. (See “Writing Profiler Data
to a File” on page 5-47.)
-textfile <file> Uses <file> as the name of the profiler text file. If this option is
used without -textfile, the name defaults to:
profile_<Tester>_<Station>_<Program>_<Lot>_<SubLot>_<Date>.pftxt
-notext Does not write the profiler report to a text file. This is the default.
-writeinsight Writes the profiler report to a Test Insight file.
-insightfile <file>
Uses <file> as the name of the Test Insight file. If this option is
used without -insightfile, the name defaults to:
profile_<Tester>_<Station>_<Program>_<Lot>_<SubLot>_<Date>.insight
-noinsight Does not write the profiler report to a Test Insight file. This is the
default.
-compare <file> Compares the test program runs (without -read) or the named
file (with -read) to the text file <file>.
Note that if you use this option without -read and your file is
unparsable due to formatting errors (for instance, if you have
edited your file with a text editor), then the error message:
profile: Run time error in program
may be your only notice of the formatting error. (See “Writing
Profiler Data to a File” on page 5-47.)
-nocompare Performs no comparison. This is the default.
The profile command requires some option (other than -station).
The default state of the profiler is:
-off -sequencer -bytime -print 0 -scaled -mem_check on
-writestation -notext -noinsight -nocompare
Sequencer Profiler Examples
The following is an example of using the profiler in its default mode. First, a program is
loaded and run and produces the usual run-time statistics as in:
a570% run
IMAGE Solutions V8.3 5-43
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
Device #2 Bin #1 GRADE_1 Test time = 0.117 sec
Test program size = 1440K. (text=832K data=544K malloc data=64K)
Using the profile command to turn profiling on enables the profiler in its default
configuration. After the IMAGE status line, the profiler prints a report listing all the bins
marked in decreasing order by execution time.
a570% profile -on
a570% run
Device #3 Bin #1 GRADE_1 Test time = 0.144 sec
Test program size = 1440K. (text=832K data=544K malloc data=64K)
Name # time % time
----------------------------------------------------------------------
Pre-Test 53.586 msec 37.2%
lnreg 7 10.424 msec 7.2%
ldreg 9 10.403 msec 7.2%
lnreg 8 10.289 msec 7.1%
ldreg 10 10.282 msec 7.1%
Non TESTF Code 9.408 msec 6.5%
Post-Test 7.554 msec 5.2%
vout 1 5.324 msec 3.7%
vout 4 5.314 msec 3.7%
vout 3 5.261 msec 3.7%
vout 5 5.256 msec 3.6%
vout 2 5.251 msec 3.6%
iq 6 5.042 msec 3.5%
Profile Overhead 635.000 usec 0.4%
--------------
Total test time: 144.029 msec
You can specify more than one option for profile. Here we ask for a report sorted by name
and listing only five bins:
a570% profile -byname -print 5
a570% run
Device #4 Bin #1 GRADE_1 Test time = 0.143 sec
Test program size = 1440K. (text=832K data=544K malloc data=64K)
Name # time % time
----------------------------------------------------------------------
Non TESTF Code 9.373 msec 6.6%
Post-Test 7.555 msec 5.3%
Pre-Test 52.692 msec 36.9%
iq 6 5.041 msec 3.5%
ldreg 10 10.283 msec 7.2%
--------------
Total test time: 142.806 msec
Note that turning profiling off does not reset the profiler. In fact, you can alter the profiler
configuration with profiling turned off, and the changes take effect when profiling is next
enabled. For example:
IMAGE Solutions V8.3 5-44
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
smith% profile -off
smith% run
Device #4 Bin #1 Test time = 0.156 sec
Test program size = 1400K. (text=816K data=528K malloc data=56K)
smith% profile -bytime -print 2
smith% profile -on
smith% run
Device #5 Bin #1 Test time = 0.158 sec
Test program size = 1400K. (text=816K data=528K malloc data=56K)
Name # time % time
----------------------------------------------------------------------
ldreg 10 16.945 msec 15.2%
ldreg 9 15.424 msec 13.8%
--------------
Total test time: 111.634 msec
Custom Profiler Example
The following test program example shows the use of the Custom Profiler. The
tl_profile_mark() and tl_profile_end() functions indicate where to begin and end
time measurement of code.
main()
{
tl_profile_mark(1, "First code section to test");
<code section>
tl_profile_mark(2, "Second code section to test");
<code section>
tl_profile_mark(3, "Third code section to test");
<code section>
tl_profile_mark(1, "First code section to test");
<code section>
tl_profile_end();
}
If we run this program, we get the following report:
Device #0 No binning Test time = 6.391 sec
Test program size = 1416K. (text=808K data=544K malloc data=64K)
Turning custom profiling on produces the following for this program:
Device #0 No binning Test time = 6.074 sec
Test program size = 1416K. (text=808K data=544K malloc data=64K)
Name # time % time
----------------------------------------------------------------------
Third code section to test 3 3.010 sec 49.5%
Secode code section to test 2 2.006 sec 33.0%
First code section to test 1 1.001 sec 16.5%
IMAGE Solutions V8.3 5-45
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
Pre-Test 50.562 msec 0.8%
Post-Test 6.032 msec 0.1%
Profile Overhead 492.000 usec 0.0%
Unprofiled Code 23.000 usec 0.0%
--------------
Total test time: 6.074 sec
NOTE
Some IMAGE software drivers also use profile -custom. This may cause the appearance
in the profile output of bins you did not create.
Using The Memory Profiler to Display Memory Usage
The following shows the memory usage output for profile -mem_info:
a570% profile -mem_info
Tester: a570t
Total RAM: 11080K Free RAM: 3208K
Process Size
---------------- -------------
IMAGE 640K
System 1584K
Station 1 13624K
Optimum total test program size is 8856K.
The -mem_info option is not available on the simulator.
Using The Memory Profiler to Display Page Faults
Page fault statistics during test program run are enabled by default. The following is an
example:
a570% run
Device #0 No binning Test time = 102.011 sec
Test program size = 13264K. (text=624K data=12608K malloc data=32K)
1160 page faults detected during program run
You can disable the first two lines of output using the -nostats option to the run command
or using the -noinfo option to the loop command. These commands are not controlled by
the Memory Profiler.
Using -mem_check full enables page fault statistics during test program initialization as
well. An example would be
a570% profile -mem_check full
Full memory statistics enabled.
a570% run
IMAGE Solutions V8.3 5-46
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
Device #0 No binning Test time = 88.193 sec
Test program size = 13264K. (text=624K data=12608K malloc data=32K)
1111 page faults detected during program run
907 page faults detected during program initialization
Writing Profiler Data to a File
To write a profiler report to disk as a text file, use profile -writetext. The following
example uses the custom mode on the simulator. Sequencer mode works just as well, as
will a real tester.
test% profile -on -custom -writetext
test% run
Device #0 No binning Test time = 0.013 sec
Test program size = 3144K. (text=1104K data=632K malloc data=1408K)
**** WARNING! **** Simulator times do _not_ accurately reflect hardware!
Name # time % time
--------------------------------------------------------------------
Pre-Test 6.621 msec 52.5%
Post-Test 4.685 msec 37.1%
Profile Overhead 253.000 usec 2.0%
eol 3 171.000 usec 1.4%
loop 10000 87.000 usec 0.7%
loop 10001 87.000 usec 0.7%
loop 10002 87.000 usec 0.7%
loop 10003 87.000 usec 0.7%
loop 10005 87.000 usec 0.7%
loop 10008 87.000 usec 0.7%
loop 10006 87.000 usec 0.7%
loop 10007 87.000 usec 0.7%
loop 10009 87.000 usec 0.7%
loop 10004 87.000 usec 0.7%
Unprofiled Code 11.000 usec 0.1%
startup 1 4.000 usec 0.0%
---------------
Total test time: 12.615 msec
test% ls prof*pftxt
profile_grind_1_proftest_1_jan11_14:01.pftxt
Once the file is written, you can compare the next run of the test program to that file using
profile -compare, as shown in the following:
test% profile -notext -compare profile_grind_1_proftest_1_jan11_14:01.pftxt
test% run
Device #0 No binning Test time = 0.013 sec
Test program size = 3152K. (text=1104K data=632K malloc data=1416K)
**** WARNING! **** Simulator times do _not_ accurately reflect hardware!
IMAGE Solutions V8.3 5-47
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
Name # time % time old time % change
------------------------------------------------------------------------------------
Pre-Test 6.849 msec 53.1% 6.621 msec 3.4%
Post-Test 4.737 msec 36.7% 4.685 msec 1.1%
Profile Overhead 256.000 usec 2.0% 253.000 usec 1.2%
eol 3 171.000 usec 1.3% 171.000 usec 0.0%
loop 10000 87.000 usec 0.7% 87.000 usec 0.0%
loop 10001 87.000 usec 0.7% 87.000 usec 0.0%
loop 10002 87.000 usec 0.7% 87.000 usec 0.0%
loop 10003 87.000 usec 0.7% 87.000 usec 0.0%
loop 10005 87.000 usec 0.7% 87.000 usec 0.0%
loop 10008 87.000 usec 0.7% 87.000 usec 0.0%
loop 10006 87.000 usec 0.7% 87.000 usec 0.0%
loop 10007 87.000 usec 0.7% 87.000 usec 0.0%
loop 10009 87.000 usec 0.7% 87.000 usec 0.0%
loop 10004 87.000 usec 0.7% 87.000 usec 0.0%
Unprofiled Code 11.000 usec 0.1% 11.000 usec 0.0%
startup 1 4.000 usec 0.0% 4.000 usec 0.0%
--------------- --------------- --------
Total test time: 12.898 msec 12.615 msec 2.2%
To use a different file, use a different name as in
test% profile -compare baseline.pftxt
test% run
Device #0 No binning Test time = 0.013 sec
Test program size = 3152K. (text=1104K data=632K malloc data=1416K)
**** WARNING! **** Simulator times do _not_ accurately reflect hardware!
Name # time % time old time % change
------------------------------------------------------------------------------------
Pre-Test 6.632 msec 52.5% 25.619 msec -74.1%
Post-Test 4.685 msec 37.1% 27.078 msec -82.7%
Profile Overhead 248.000 usec 2.0% 2.802 msec -91.1%
eol 3 171.000 usec 1.4% 1.073 msec -84.1%
loop 10000 87.000 usec 0.7% 31.000 usec 180.6%
loop 10001 87.000 usec 0.7% 165.963 msec -99.9%
loop 10002 87.000 usec 0.7% 313.503 msec -100.0%
loop 10003 87.000 usec 0.7% 488.115 msec -100.0%
loop 10005 87.000 usec 0.7% 862.833 msec -100.0%
loop 10008 87.000 usec 0.7% 1.304 sec -100.0%
loop 10006 87.000 usec 0.7% 948.425 msec -100.0%
loop 10007 87.000 usec 0.7% 2.264 sec -100.0%
loop 10009 87.000 usec 0.7% 1.469 sec -100.0%
loop 10004 87.000 usec 0.7% 616.329 msec -100.0%
Unprofiled Code 12.000 usec 0.1% 62.000 usec -80.6%
startup 1 4.000 usec 0.0% 24.000 usec -83.3%
--------------- --------------- --------
Total test time: 12.622 msec 8.489 sec -99.9%
IMAGE Solutions V8.3 5-48
IMAGE Base Language: Loading and Running Test Programs: Profiling a Test Program
Table of Contents Index Home Master Index Search Help
You can compare two files using -read and -compare. Note that you do not need a test
program loaded to compare two files. (In fact, you do not even need to have IMAGE
running.)
test% profile -off
test% delete
delete: Test program has been deleted
test% profile -read comparison -compare baseline
Name # time % time old time % change
------------------------------------------------------------------------------------
Pre-Test 33.846 msec 43.8% 25.619 msec 32.1%
Post-Test 26.462 msec 34.3% 27.078 msec -2.3%
eol 3 4.376 msec 5.7% 1.073 msec 307.8%
Profile Overhead 3.470 msec 4.5% 2.802 msec 23.8%
loop 10002 3.361 msec 4.4% 313.503 msec -98.9%
loop 10003 914.000 usec 1.2% 488.115 msec -99.8%
loop 10000 776.000 usec 1.0% 31.000 usec 2403.2%
loop 10007 669.000 usec 0.9% 2.264 sec -100.0%
loop 10001 554.000 usec 0.7% 165.963 msec -99.7%
loop 10008 543.000 usec 0.7% 1.304 sec -100.0%
loop 10006 542.000 usec 0.7% 948.425 msec -99.9%
loop 10009 542.000 usec 0.7% 1.469 sec -100.0%
loop 10004 541.000 usec 0.7% 616.329 msec -99.9%
loop 10005 541.000 usec 0.7% 862.833 msec -99.9%
Unprofiled Code 56.000 usec 0.1% 62.000 usec -9.7%
startup 1 24.000 usec 0.0% 24.000 usec 0.0%
--------------- --------------- --------
Total test time: 77.217 msec 8.489 sec -99.1%
IMAGE Solutions V8.3 5-49
IMAGE Base Language: Data Collection
Table of Contents Index Home Master Index Search Help
6 DATA COLLECTION
This section describes using IMAGE to organize, collect, and analyze device test results. It
includes the following topics:
• “Organizing Test Data” on page 6-3
• “Datalog Reports” on page 6-13 including:
– “Datalog Setup Using the Data Collection Setup Display” on page 6-14
– “Using the Enhanced Functional Datalog Display” on page 6-26
– “Datalog Setup Using the datalog Command” on page 6-31
– “Creating Datastreams” on page 6-48
– “Controlling Datalog From a Test Program” on page 6-57
– “Controlling Enhanced Functional Datalog (EFD) from a Test Program” on page 6-62
– “Changing Datalog Setup Information” on page 6-66
– “Changing Datalog Output” on page 6-67
– “Retrieving Datalog Setup Information” on page 6-68
– “Controlling Datalog Sampling” on page 6-75
– “Additional Methods of Controlling Datalog From a Test Program” on page 6-75
– “Additional Methods for Retrieving Datalog Setup Information in a Test Program” on
page 6-77
– “Custom Datalog Filters” on page 6-82
– “Monitoring Disk Space During Datalog” on page 6-84
• “Summary Reports” on page 6-89
• “Device Interface Board and Probe Card Information in Datalog” on page 6-107
• “Real Time Yield Trend Monitor” on page 6-112
• “Histogram Plots” on page 6-120
The main graphical tool for organizing and collecting data in IMAGE is the Data Collection
Setup display. This display allows you to specify how to collect datalog and histogram data.
It includes the following subwindows:
• Lot Setup Manager (see page 6-5)
• Enhanced Functional Datalog display (see page 6-26)
• Datastream Setup window (see page 6-48)
IMAGE Solutions V8.3 6-1
IMAGE Base Language: Data Collection:
Table of Contents Index Home Master Index Search Help
• Auto-Summary Setup window (see page 6-94)
• Station Plot window (see page 6-137)
IMAGE also includes command-line equivalents for all window functions.
IMAGE Solutions V8.3 6-2
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
Organizing Test Data
The first step in gathering test data is to set up the collection process so that data is
organized in a meaningful way. IMAGE groups data by its association with a group of
devices in a device lot. Each device lot is identified by characteristics that help interpret test
results, including:
• Lot ID
• Test program name
• Tester and station used
• Operator name
• Time and date of testing
Most of this information is set and maintained automatically. In addition, IMAGE provides
tools to help you organize and identify data, including the lot ID, operator name, and test
code. You use these tools when you set up data collection. (Some parameters can also be
set from within a test program using tl_ functions. See “Additional Methods of Controlling
Datalog From a Test Program” on page 6-75 and “Base IMAGE Functions” on page 26-1.)
Lot Identification
When testing a lot of devices, you will commonly have IMAGE record an identification
number for the lot (a lot ID) to clearly identify any datalog output, summary reports, and
STDF files produced by testing that batch of parts. Typically, when doing package testing,
each batch of parts is identified by a single number or alphanumeric string (usually called
the lot ID). In wafer-probe, however, you often have an ID for a cassette or boat of wafers
and also an ID (or wafer number) for each wafer.
Setting the Lot and Sublot
IMAGE allows you to assign two IDs to a group of parts, a lot ID and a sublot ID, to address
the needs of wafer probing and package testing. Set the lot ID and sublot ID in any of the
following ways:
• Using the Lot Setup Manager in the Data Collection Setup display (see “Using the Lot
Setup Manager to Set Up Lots” on page 6-5)
• Using the startlot command from a station window (see “Opening a Lot Using the
startlot Command” on page 6-7)
• Using the lot command from a station window (see “Setting Lot and Sublot Using the
lot Command” on page 6-9)
• Using the tl_write_lot_id() and tl_write_sblot_id() functions from a test
program
IMAGE Solutions V8.3 6-3
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
Incrementing Lots and Sublots
A new lot, with a new lot ID, is started automatically by IMAGE when you test the first device
after editing and compiling (or recompiling) a sequencer. This is done because editing a
sequencer usually changes the test list in some way.
IMAGE increments the lot ID or sublot ID at the end of each lot. This occurs when you
request a final summary report or the tester receives an ENDLOT signal from a handler or
prober or from the Start Switch.
IMAGE increments a lot ID differently depending on how the lot and sublot IDs are set. IDs
are incremented as follows:
• If the lot ID is nonnumeric, IMAGE does not change it. For example, if you set the lot ID
to abc, IMAGE cannot increment that lot ID at the end of the lot.
• If the lot ID is numeric (such as 1), IMAGE increments it. For example, if the lot ID is 33,
at end of the lot IMAGE sets the new lot ID to 34.
• If the sublot ID is set, IMAGE increments the sublot ID rather than the lot ID. For
example, if the lot ID is set to abc and the sublot ID is set to 66, at the end of the lot
IMAGE sets the new sublot ID to 67, while leaving the lot ID set to abc.
• If both the lot and sublot ID are unset, the lot ID is set to 1 when an end-of-lot occurs.
Table 6-1 shows how the lot and sublot ID number incrementing works. This will help you
decide on an identification strategy for each application.
Table 6-1. Lot and Sublot Number Incrementing
Before Endlot After Endlot
Lot ID Sublot ID Lot ID Sublot ID
1 <unset> 2 <unset>
1 1 1 2
abc <unset> abc <unset>
abc 1 abc 2
<unset> <unset> 1 <unset>
For example, in most wafer-probe applications you can set the lot ID to the ID for the entire
cassette of wafers and set the sublot ID to 1 at the beginning of the cassette. The sublot ID
then acts as the wafer number and is incremented at the end of each wafer (using the endlot
signal from the prober). For testing packaged devices, you can set the lot ID but leave the
sublot ID unset. In this case, the lot ID is incremented once the lot of packed parts is
complete.
IMAGE Solutions V8.3 6-4
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
Using the Lot Setup Manager to Set Up Lots
The Lot Setup Manager (figure 6-1) allows you to set up device lots, sublots, and lot
parameters. Display this window by clicking on the LOT button on the Data Collection Setup
display. (See “Datalog Setup Using the Data Collection Setup Display” on page 6-14.)
Figure 6-1. Lot Setup Manager
Anytime you open the Lot Setup Manager, it displays the current information for the current
lot. If lot information changes while the Lot Setup Manager is open, however, the new
information is not shown in the display. To update the Lot Setup Manager (and all other
open data windows), use the menu item SETTINGS>REFRESH DISPLAY WITH DATA
COLLECTION SETTINGS in the Data Collection Setup display. (See “Control Panel Items” on
page 6-15.)
The Lot Setup Manager includes the following items:
LOT ID: Sets the lot ID for a new lot. The default is 1. (See “Lot
Identification” on page 6-3.)
SUBLOT ID: Sets the sublot ID for a new lot. This is concatenated with the lot
ID on the command line that this window produces. The final
form of an entire lot ID is either the lot ID itself or the lot ID
followed by a colon and the sublot ID.
ENGINEERING LOT ID:
Specifies the engineering lot ID.
IMAGE Solutions V8.3 6-5
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
DEVICE ID: Sets the starting device ID number when starting a new lot. Each
device is given a unique number. The device number is
automatically incremented each time the test program runs
(testing a new device). This entry takes positive integers only.
The default is 1.
SET ID BUTTON Sets the DEVICE ID to the number specified without starting a
new lot.
PART TYPE: Text describing the part type or product ID.
PACKAGE TYPE: Text describing the package type.
DESIGN REVISION: Text describing the device design revision.
DEVICE FAMILY ID: Specifies the product family ID.
OPERATOR: Specifies the operator name or ID. This must be a string. If you
do not specify a name, the operator name is automatically set to
the name used at login when the test program is loaded.
SUPERVISOR: Specifies the supervisor name or ID.
TEST FLOOR ID: Specifies the test floor ID.
FACILITY ID: Specifies the test facility ID.
TEST CONDITION: Specifies the test condition to switch the currently loaded test
program to. You define test conditions in the test program
header (usually near the pinmap). (See “Test Conditions” on
page 15-27.) If you enter a test condition and have not specified
this condition in your program, you get an error when you run the
program.
PROCESS ID: Specifies the fabrication process ID.
RETEST CODE: Specifies the retest code.
TEST TEMP.: Specifies the test temperature. It can be stored as degrees
Celsius, Fahrenheit, Kelvin, or any scale. It also can be
expressed in terms such as HOT, ROOM, and COLD if
preferred.
BURN IN TIME: Specifies the burn-in time in minutes.
OPERATION FREQ.: Specifies the operation frequency or step.
JOB REVISION: Specifies the test program revision number.
TEST SETUP ID: Specifies the test setup ID.
TEST SPEC. NAME: Specifies the test specification name.
TEST SPEC. VERSION: Specifies the test specification version number.
TEST FLOW ID: Specifies the test flow ID.
IMAGE Solutions V8.3 6-6
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
SUMMARY? Selects whether or not to generate an automatic summary for the
lot that will close when the new lot is started. The default is YES.
FULL STATISTICS? Selects whether or not the generated summary has full statistics.
Full statistics include mean, standard deviation, (one, three, and
six) sigma values, Cp, and Cpk. The default is YES. See
“Summary Statistics” on page 6-105.
APPLY Starts a lot with the attributes specified in the Lot Setup
Manager. When you click APPLY, you must confirm that you
intend to start a new lot.
SHOW CURRENT Shows the current lot setup in effect in the station window
(similar to the showlot command).
RESET Refreshes the display with the setting information the display
had before you made any changes.
If you change the current setup of the display, the message -- MODIFIED -- appears in the
lower right hand corner of the display. To apply your changes, you must start a new lot.
To make changes in the Lot Setup Manager:
1. Enter your changes.
2. Click the APPLY button. A pop-up window appears asking
CONFIRM STARTING NEW LOT?
3. Click CONFIRM to start a new lot with the new information. If you click CANCEL, the lot
remains the same and your changes are not applied.
Using IMAGE Commands to Set Up Lots
You can use IMAGE commands to set up lots and lot parameters. The main command is
the startlot command, which you use to start a lot and set lot parameters. IMAGE also
provides several other commands to set individual lot parameters (such as testcond to set
test conditions) and the showlot command to display current lot information. These
commands are described in the following sections.
Opening a Lot Using the startlot Command
The startlot command allows you to start a lot, close the current lot, and set many lot
parameters. The syntax is:
startlot [-lotid <XX>] [-parttype <XX>] [-testcond <XX>] [-operator <XX>]
[-retestcode <XX>] [-supervisor <XX>] [-jobrev <XX>] [-processid <XX>]
[-dsgnrev <XX>] [-famlyid <XX>] [-facilid <XX>] [-floorid <XX>]
[-operfrq <XX>] [-specnam <XX>] [-specver <XX>] [-flowid <XX>]
[-setupid <XX>] [-engid <XX>] [-burn_tim <XX>] [-tsttemp <XX>]
[-pkgtyp <XX>] [-noconfirm] [-nosummary] [-show] [-station #]
[-fullstats <on/off>] [-usrtext <XX>]
where:
IMAGE Solutions V8.3 6-7
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
-lotid <XX> Specifies the lot and sublot ID number. (See “Lot Identification”
on page 6-3.) Lot ID can be any series of alphanumeric
characters that identifies the lot. The default is 1. Multiple words
must be enclosed in double quotes ("). You can also write the lot
ID as
<lot_id:sublot_id>
-parttype <XX> Text describing the part type or product ID.
-testcond <XX> Specifies a test condition for the currently loaded test program.
You define test conditions in the test program header (usually
near the pinmap). (See “Test Conditions” on page 15-27.) If you
enter a test condition and have not specified this condition in
your program, you get an error when you run the program.
-operator <XX> Specifies the operator name. This must be a string. If you do not
specify a name, the operator name is automatically set to the
name used at login when the test program is loaded.
-retestcode <XX> Specifies the retest code.
-supervisor <XX> Specifies the supervisor name or ID.
-jobrev <XX> Specifies the test program revision number.
-processid <XX> Specifies the fabrication process ID.
-dsgnrev <XX> Specifies the device design revision.
-famlyid <XX> Specifies the product family ID.
-facilid <XX> Specifies the test facility ID.
-floorid <XX> Specifies the test floor ID.
-operfrq <XX> Specifies the operation frequency or step.
-specnam <XX> Specifies the test specification name.
-specver <XX> Specifies the test specification version number.
-flowid <XX> Specifies the test flow ID.
-setupid <XX> Specifies the test setup ID.
-noconfirm Each time you issue the startlot command, you are asked if
you want to start a new lot. If you answer yes, a new lot is started.
-noconfirm bypasses this confirmation.
-nosummary Does not produce a summary report on the previous lot.
-show Shows the setup for the new lot. To show information for the
current lot use the showlot command.
-station # Starts a lot on the specified station.
IMAGE Solutions V8.3 6-8
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
-fullstats Provides mean, standard deviation, (one, three, and six) sigma
values, Cp, and Cpk. See “Summary Statistics” on page 6-105.
-usrtext <XX> Specifies the contents of the USER_TXT field of the Master
Information Record (MIR). Text should be enclosed in quotes.
Setting Lot and Sublot Using the lot Command
You can set the lot ID and sublot ID using the lot command from a station window. The
syntax for the lot command is:
lot [<lot_id>] [-station #]
where:
<lot_id> Is any series of alphanumeric characters that identifies the lot.
(See “Lot Identification” on page 6-3.) The default is 1. Multiple
words must be enclosed in double quotes ("). You can also write
the lot ID as:
<lot_id:sublot_id>
-station # Specifies the station number to be affected when the command
is issued from another station window or terminal.
For example, before you start a lot you give the command lot 4445:1. This sets the lot ID
to 4445 and the sublot ID to 1.
Type lot without arguments or parameters to display the current lot ID.
NOTE
If the sublot ID is previously set, issuing the lot <lot_id> command will not reset the
sublot ID. The sublot ID will retain its previous value. To reset the sublot ID, use the
command
lot <lot_id>:
The colon, without any following arguments, resets the sublot ID field.
Setting Operator Name Using the operator Command
You can set the operator name for each lot using the operator command. Syntax for the
operator command is:
operator [<operator_name>] [-station #]
where:
<operator_name> Specifies the name of the operator. This must be a string. If you
do not specify a name, the operator name is automatically set to
the name used at login when the test program is loaded.
-station # Specifies a station window.
IMAGE Solutions V8.3 6-9
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
Setting Test Conditions Using the testcond Command
The testcond command allows you to set a test condition for a test program from a station
window. Test conditions are used to specify conditions under which a device is being tested,
such as hot or cold. They can also be used to include special tests or to specify different test
limits.
You define test conditions in the test program header (usually near the pinmap). Any test
condition you specify can be set from a station window using the testcond command. (See
“Test Conditions” on page 15-27.)
The testcond syntax is:
testcond [<testcondition> | -default] [-show] [-during_lot]
where:
<testcondition> Specifies the test condition to switch the currently loaded test
program to.
-default Switches the test program back to the default test condition.
-show Displays the current test condition. This parameter can be
combined with setting a test condition.
-during_lot Changes the test condition during a lot.If you change test
conditions during a lot, be aware that the test_cod field in the
MIR will not be changed.
Setting a Device Number Using the device Command
Within each lot, each device is given a unique device number. Device numbers start at 1 by
default at the beginning of each lot and are automatically incremented each time the test
program runs (testing a new device).
You can change the device number using the device command. The syntax for the device
command is:
device # [-station #]
where:
# Sets the device number. You can use any number greater than
0.
-station # Specifies a station number.
At the start of each new lot, the device number resets to 1. If a run is aborted, you can retest
the current device using the RETEST option under the RUN button or the run -retest
command. This command appends new datalog information to the existing datalog file and
discards the previous summary information for that device (if datalog and summaries are
enabled).
IMAGE Solutions V8.3 6-10
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
Displaying Lot Information
You may wish to see all the lot information for a lot, either after you have changed some lot
parameters or after loading a test program. You can do this using the showlot command.
The syntax is:
showlot [-lotid | -progname] [-station #]
where:
-lotid Displays lot information for the specified lot. If you do not specify
a lot, information for the current lot is displayed.
-progname Displays lot information for the specified test program.
-station # Specifies a station number.
This command displays all current information on the specified lot. An example would be as
follows:
walter% showlot
Lot: 1
Sublot:
Started at: Mon Dec 28 10:45:02 1992
Program: dc_dual_site
Version:
Part Type:
Operator: williams
Station Number: 1
Station Mode: E
Tester Type: A540 ALSP
Node Name: walter
Executive: IMAGE V5.0 122492
Test Code:
Retest Code:
Handler or Prober:
DIB Type:
DIB ID:
Closing a Device Lot
A device lot is closed in any of the following ways:
• An automatic handler or wafer prober sends an endlot or end-of-wafer signal to the
tester.
• You end the lot by requesting a final lot summary (see “Summary Reports” on page
6-89) or by pressing the END LOT button on the Start Switch (see “The Start Switch” on
page 9-1 in the Handler/Prober Manual).
• You modify entries in the Lot Setup Manager, click APPLY, and confirm that you want to
start a new lot.
• You issue a startlot command, closing the current lot and starting a new one.
IMAGE Solutions V8.3 6-11
IMAGE Base Language: Data Collection: Organizing Test Data
Table of Contents Index Home Master Index Search Help
When you issue a startlot command and close the current lot, you get a summary report
for that lot as if you had typed summary -final. (See “Automatic Summary Reports Using
the setauto Command” on page 6-96.) You can override this default by using the SUMMARY?
option in the Lot Setup Manager or the -nosummary option to the startlot command.
IMAGE Solutions V8.3 6-12
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Datalog Reports
Datalogging allows you to monitor the results of each execution of all tests in a test program,
or tests you select, and produces a list of the values returned by those tests. In addition to
the test value, a datalog report contains other information about the execution of a test, such
as the test limits and whether tests failed or alarmed. Figure 6-2 shows a sample datalog
report.
Lot: 445 Tester: walter Program: dc_dual_site
Device: 1 Station: 1 Site: 0 Date: Tue Dec 8 14:18:56 1992
Sequencer: seq1
1 vout1 4.86 v 2 vout2 4.93 v
3 vout3 4.80 v 4 vout4 4.85 v
5 vout5 4.96 v 6 iq 3.70 ma
7 linereg1 10 mv 8 linereg2 17 mv
9 loadreg1 -7 mv 10 loadreg2 27 mv
Bin: 1
Lot: 445 Tester: walter Program: dc_dual_site
Device: 2 Station: 1 Site: 1 Date: Tue Dec 8 14:18:57 1992
Sequencer: seq1
1 vout1 4.87 v 2 vout2 4.97 v
3 vout3 4.90 v 4 vout4 4.97 v
5 vout5 4.99 v 6 iq 4.00 ma
7 linereg1 -10 mv 8 linereg2 18 mv
9 loadreg1 -8 mv 10 loadreg2 -28 mv
Bin: 1
Figure 6-2. Sample Datalog Report, Brief Format
The sequence for datalogging is:
• Load a test program.
• Set up datalog—turn datalog on and specify datalog parameters.
• Run the test program to produce test results.
When you set up datalogging, you specify:
• Output destination—where datalog results will go
• Test selection criteria—which test results to datalog
• Datalog format—how the datalog report should be organized and which information
should be shown
You can set up datalog either using the Data Collection Setup display (available by clicking
SELECT on the DATA button) or using the datalog command (see “Datalog Setup Using the
datalog Command” on page 6-31).
IMAGE Solutions V8.3 6-13
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Datalog Setup Using the Data Collection Setup Display
The Data Collection Setup display (figure 6-3) allows you to interactively examine and
modify setups for datalog and histogramming functions within IMAGE. Each active station
(each station with a test program loaded) has a separate data collection display. This
display shows the current setup for datalog and histogramming and allows you to modify
this setup. Datalogs created from this display show vectors and cycle numbers when the
pattern halts, which might not be the failing vectors and cycle numbers.
Control Panel
Histogram
items
Datalog
output
items
Datalog
criteria Datalog
items format
items
Datalog
options
items
Message Area
Figure 6-3. Data Collection Setup Display
Bringing Up the Display
To bring up the Data Collection Setup display:
1. Load a test program into a station window.
2. Press MENU on the DATA button in the station window and select DATA COLLECTION
SETUP DISPLAY from the menu.
IMAGE Solutions V8.3 6-14
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
You can also bring up the window by typing the command dacldisp in a station window. If
for some reason the display does not come up (for example, you did not load a test
program), a message appears in the station window.
You can close the Data Collection Setup display to an icon. When you iconify this display,
all subwindows disappear with it.
The Data Collection Setup display closes when the station window closes because you
must monitor the commands in the station window to be sure that your command went
through. This display also opens the station window whenever you open (deiconify) the
Data Collection Setup display.
Regions in the Display
The Data Collection Setup display has the following regions:
• A control panel is at the top of the display.
• Datalog Output items on the upper left side of the terminal pane specify where datalog
data should go.
• Datalog Criteria items on the lower left side of the terminal pane specify which tests to
datalog.
• Histogramming items at the upper right side of the terminal pane are related to the
setup of the histogramming functions.
• Datalog Format items on the lower right side of the terminal pane specify the format of
the datalog output on the report.
• Datalog Options items on the lower left side of the terminal pane specify pin leakage
values for digital leakage datalogging. This option is only available for HSD50 leakage
tests.
• The message area at the bottom of the window displays messages, such as when an
error occurs.
Control Panel Items
The Data Collection Setup display control panel includes the following items:
LOT... Displays the Lot Setup Manager, which allows you to start a lot
and change lot information. (See “Using the Lot Setup Manager
to Set Up Lots” on page 6-5.)
PLOT Creates a histogram plot using the currently selected list of tests
for histogramming. The plot is displayed in a station window
(ASCII plot) or in the Histogram Tool (histodisp) window. (See
“Histogram Tool” on page 6-124.)
SUMMARY Provides a test summary. Click SELECT for a summary. Press
MENU to select one of the following options:
PARTIAL SUMMARY TO STATION WINDOW (see “Generating
Summary Reports” on page 6-89)
IMAGE Solutions V8.3 6-15
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
FINAL SUMMARY TO STATION WINDOW (see “Generating Summary
Reports” on page 6-89)
PARTIAL SUMMARY TO TEXT FILE (see “Generating Summary
Reports” on page 6-89)
FINAL SUMMARY TO TEXT FILE (see “Generating Summary
Reports” on page 6-89)
SUMMARY FROM PREVIOUS LOT (see “Generating Summary
Reports” on page 6-89)
SET SUMMARY CHECKPOINT FREQUENCY... brings up the
Summary checkpoint setup window (see “Setting Summary
Checkpoint Frequency” on page 6-104)
AUTO-SUMMARY SETUP brings up the Auto-Summary Setup
window (see “Auto-Summary Setup Window” on page 6-94)
ACCUMULATE SUMMARIES displays a menu that allows you to
enable, clear, or disable counters for accumulated summaries
(see “Setting Up Accumulated Summary Reports” on page
6-100)
SUMMARY SITE DATA MODE... brings up the Summary Site Data
mode window (see “Setting Up the Summary Site Data Mode” on
page 6-102)
SETTINGS Press MENU on this button to display the following selections:
REFRESH DISPLAY WITH DATA COLLECTION SETTINGS
Replaces the currently displayed setup information for all data
collection windows with the actual current datalog settings. For
example, if you modify some items on the display and select
REFRESH, the items return to their original settings since you
never clicked on APPLY to save those settings.
PAUSE ALL DATA COLLECTION TEMPORARILY
Temporarily halts all data collection. You can only select this
item if data collection is enabled.
RESUME DATA COLLECTION
Resumes data collection using the current setup.
WRITE COMMAND FILE WITH CURRENT DATA COLLECTION
SETTINGS
Writes a <program>.dlg file containing commands which, when
executed, duplicate the data collection setup currently shown on
the display. (See “Saving and Loading the Display” on page
6-17.)
LOAD DATA COLLECTION SETUP FROM FILE
Loads a <program>.dlg file containing commands which, when
IMAGE Solutions V8.3 6-16
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
executed, duplicate the data collection setup in the file. (See
“Saving and Loading the Display” on page 6-17.)
DATASTREAM... Displays the Datastream Setup window. (See “Setting Up a
Datastream Using the Datastream Setup Window” on page
6-48.)
FUNCTIONAL (EFD)...
Press SELECT on this button to bring up the Enhanced
Functional Datalog display. This display allows you to display
more information in the datalog about failing vectors. (See
“Using the Enhanced Functional Datalog Display” on page 6-26.)
APPLY Applies the currently displayed setup to the data server. You
must click SELECT on this button to make any data collection
changes take effect.
RESET Resets the display to its last-saved values (the values in the
display when you last clicked APPLY).
Saving and Loading the Display
Two items in the SETTINGS menu of the Data Collection Setup display allow you to save the
display to a file and to reload the file to recreate the display.
Use the item WRITE COMMAND FILE WITH CURRENT DATA COLLECTION SETTINGS item to write
the display setting to a file. This item has two choices. The first choice, SAVE USING LAST
SETUP PARAMETERS (the default), writes whatever data collection parameters you have
specified to a file called <progr_name>.dlg. If you have not specified any parameters, this
choice writes the setups from the Data Collection Setup display and the Histogram Tool.
The second choice, SETUP SAVE PARAMETERS, allows you to specify which data collection
window setups to save. If you select this item, the Data Collection Setup Save window is
displayed (figure 6-4). Use this window to select setups from any data collection windows,
including the EFD Datalog, Automatic Summary, Lot Information, and Datastream displays.
You can select as many windows as you wish. You must select at least one.
IMAGE Solutions V8.3 6-17
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Figure 6-4. Data Collection Setup Save Window
You can also select a directory and filename for the setup file. The default is the current
directory and <program_name>.dlg. Click on SAVE SETUP(S) to finish your selection.
The SETTINGS menu also includes an item to allow you to load a setup you have saved. If
you choose LOAD DATA COLLECTION SETUP FROM FILE, the Data Collection Setup Load
window is displayed (figure 6-5). This window allows you to load any .dlg file to restore
datalog setups. You may also run .dlg files as scripts.
Figure 6-5. Data Collection Setup Load Window
Selecting Datalog Output
The Datalog Output section of the Data Collection Setup display (figure 6-3 on page 6-14)
includes the following items:
DATALOG TO: DATALOG WINDOW
Sends datalog output to the Datalog Output window (figure 6-8).
DATALOG TO: STDF FILE
Sends datalog output to an STDF file.
DATALOG TO: TEXT FILE Sends datalog output to a text file.
DATALOG TO: PRINTER Sends datalog output to a printer.
IMAGE Solutions V8.3 6-18
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
DATALOG WINDOW DISPLAY HOST:
Selects the name of the host to display the Datalog Output
window. This item is grayed out (inactive) if DATALOG
TO:DATALOG WINDOW is not selected.
STDF FILE: Selects the name of the STDF file to receive datalog data. This
item shows the current STDF filename if you have assigned one.
It is grayed out (inactive) if DATALOG TO:STDF FILE is not
selected. If you leave this item blank, IMAGE generates a
filename. (This name does not appear in the display.)
TEXT FILE: Selects the name of the text file to receive datalog data. This item
shows the current text filename if you have assigned one. It is
grayed out (inactive) if DATALOG TO:TEXT FILE is not selected. If
you leave this item blank, IMAGE generates a filename. (This
name does not appear in the display.)
PRINTER: Selects the name of the printer to print the datalog data. This
item shows the default printer name if you have assigned one.
The default printer name is assigned using IMAGE Properties
(see “Datalog/Summary Options” on page 3-38). It is grayed out
(inactive) if DATALOG TO: PRINTER is not selected. When
datalogging to a printer, a separate file with the extension
.printtmp is created. This file is spooled at the end of the lot or
when datalogging is turned off. The .printtmp file is deleted
after printing.
If you omit a filename, datalog to a standard test data format (STDF) file creates a default
name based on the test program name and station number. The format of the default
filename is:
node_station#_<test_program>_<lot_id>_timestamp.stdf
An example would be:
constance_1_volt_reg2_23_Feb16_09:57.stdf
If you omit a filename, datalog to a text file creates a default name with the format:
node_station#_<test_program>_<lot_id>_timestamp.data
When enabling datalog to a text or STDF file, if the filename exists it is moved to a backup
file called <filename>% and a new file is started.
Naming STDF Files
STDF filenames should follow standard file naming conventions to be processed by FIRMS.
(See “Standard Test Data Format” on page 24-1.) The IMAGE property
image.datalog.stdf_filename_check allows you to turn on strict STDF file name
checking. You can set this property to TRUE (on) or FALSE (off) in the IMAGE Properties
window using the STRICT CONFORMANCE OF STDF FILENAMES property in the
IMAGE Solutions V8.3 6-19
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
DATALOG/SUMMARY OPTIONS category (see figure 6-6) or specify the value in your
.Xdefaults file.
If you set this property to TRUE, the datalog and datastream commands return an error if
the STDF filename does not conform to STDF V4 specifications. This property also affects
STDF filenames specified in the Data Setup window and the tl_set_datalog() command.
If you set this property to FALSE, or if you do not specify it in your .Xdefaults file, all
programs retain their default behavior (off).
Figure 6-6. IMAGE Properties Datalog/Summary Options
Selecting Datalog Criteria
The Datalog Criteria section of the Data Collection Setup display (figure 6-3 on page 6-14)
includes the following items when you select STANDARD INTERFACE:
CRITERIA Determines which tests are selected for datalog.
CRITERIA>ALL TESTS Datalogs all tests. (This is the default.)
CRITERIA>PASSED TESTS
Datalogs all passing tests.
CRITERIA>FAILED TESTSDatalogs all failing tests.
IMAGE Solutions V8.3 6-20
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
CRITERIA>ALL ANALOG TESTS
Datalogs all analog tests.
CRITERIA>PASSED ANALOG TESTS
Datalogs all passing analog tests.
CRITERIA>FAILED ANALOG TESTS
Datalogs all failing analog tests.
CRITERIA>ALL DIGITAL TESTS
Datalogs all digital tests.
CRITERIA>PASSED DIGITAL TESTS
Datalogs all passing digital tests.
CRITERIA>FAILED DIGITAL TESTS
Datalogs all failing digital tests.
CRITERIA>LIST OF TESTS
Datalogs the specified list of tests. The LIST menu includes the
following items:
LIST OF TESTS Datalogs only tests entered in LIST: item.
(This is the default list.)
PASSED TESTS + FAILED ON LIST Datalogs all passing tests
and any failing tests entered in LIST: item.
FAILED TESTS + PASSED ON LIST Datalogs all failing tests
and any passing tests entered in LIST: item.
ANALOG: FROM LIST Datalogs only analog tests entered in
LIST: item.
ANALOG: PASSED + LIST Datalogs all passing analog tests
and analog tests entered in LIST: item.
ANALOG: FAILED + LIST Datalogs all failing analog tests
and analog tests entered in LIST: item.
DIGITAL: FROM LIST Datalogs only digital tests
entered in LIST: item.
DIGITAL: PASSED + LIST Datalogs all passing digital tests
and digital tests entered in LIST: item.
DIGITAL: FAILED + LIST Datalogs all failing digital tests
and digital tests entered in LIST: item.
LIST Specifies a list of tests to datalog. This is the LIST OF TESTS
referred to in the CRITERIA item. You can use test names, test
numbers, ranges of test numbers, and sequencer names. See
“Test Selection” on page 6-38 for more information.
EXTENDED INTERFACE Brings up the Extended Datalog Test Selection window (figure 6-
7).
IMAGE Solutions V8.3 6-21
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Figure 6-7. Extended Datalog Test Selection Window
Current test criteria settings for the data stream are loaded into the TESTS TO DATALOG
scrolling list. You can edit the list with the following setting controls:
ADD Adds a test set to the list. Define test sets with the following
INCLUDE options:
TEST NUMBERS: ALL or TESTS ON LIST
TEST TYPES: ANALOG, DIGITAL, or BOTH
TEST RESULTS: ANALOG, DIGITAL, or BOTH
Only active when there are fewer than nine test sets defined.
CHANGE Changes a selected test set’s settings to those you specify in the
INCLUDE options. Only active when a test set is selected.
DELETE Removes a selected test set from the list. Only active when a test
set is selected.
Commit changes to datalog test selection by clicking APPLY in the Data Collection Setup
(dacldisp) main display window (figure 6-3).
SAMPLE RATE Specifies a sampling rate for datalog—how often devices are
datalogged. The default is 1, every device datalogged. (See
“Sampled Datalog” on page 6-47.)
INCL. WAFER MAP INFO Specifies collection of all information relevant to wafer mapping.
(See “Generating Wafer Map Information” on page 6-47.)
SAMPLE LIMIT Specifies a sampling limit for datalog—the total number of
devices to be datalogged. The default is no limit. (See “Sampled
Datalog” on page 6-47.)
Datalog Format Items
The Datalog Format section of the Data Collection Setup display (figure 6-3 on page 6-14)
includes the following items:
IMAGE Solutions V8.3 6-22
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
FORMAT Controls the format of the datalog output as it appears in a text
file or in the station window. Choices are:
LABEL ONLY, NO LIMITS (brief format)
LABEL, LIMITS AND TESTNAME (full format)
LABEL ONLY, ONE LINE EFD (EFD format)
CUSTOM FORMATTER
You can change the default datalog format. For more
information, see “Datalog/Summary Options” on page 3-38.
Format does not apply when data is being sent only to an STDF
file. See “Leakage Output Format” on page 6-43 and “Wafer
Output Format” on page 6-43.
CUSTOM FORMATTER Specifies the name for a custom formatter. This item is grayed
out (inactive) if FORMAT>CUSTOM FORMATTER is not selected.
IMAGE searches along the path specified by your $PATH
environment variable for the program to run. See “Custom
Datalog Filters” on page 6-82.
OUTPUT WIDTH Specifies either 80 column or 132 column output. Not all datalog
output is printed to 132 column output if you choose 132 column
output. This option is most useful when used with enhanced
functional datalog. The default is 80 columns.
SHOW Press MENU on the button to choose PIN NAMES or PIN NUMBERS.
PINS PER LINE Specifies the number of pins or channels on each line of the
datalog. Corresponds to the -pins_per_line filter command
line option.
CHANNELS Specifies whether channel numbers are displayed in the datalog.
A setting of ON corresponds to the -channels_on filter
command line option; a setting of OFF corresponds to the
-channels_off filter command line option.
SPACE BETWEEN PINS OFF minimizes the space between pins in a pin list. If you are
using enhanced functional datalog, space between pins is
eliminated. The default is ON. A setting of OFF corresponds to
the -no_pin_space filter command line option.
TRUNCATE PIN NAMES ON restricts pin names in datalog output to six characters
(default). OFF shows full pin names and corresponds to the
-full_pin_names filter command line option.
WRAP OUTPUT ON (default) displays output as specified in OUTPUT WIDTH
(either 80 or 132 columns). OFF displays output on one line and
corresponds to the -no_wrap filter command line option.
When you modify an item in the display, the display records the fact by displaying the
message MODIFIED at the bottom of the window. This indicates that changes were made
to the setup, but they have not yet been saved. You must click the APPLY button for any
changes to take effect.
IMAGE Solutions V8.3 6-23
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
For more information on the command line filters, see “Command Line Filter Syntax” on
page 6-83.
Datalog Options Items
The Datalog Options section of the Data Collection Setup display (figure 6-3 on page 6-14)
allows you to datalog leakage values for HSD50 pins. The leakage datalog is output in a
special format. (See “Leakage Output Format” on page 6-43.) This section includes the
following items:
LEAKAGE DATALOG Enables pin leakage datalogging. Choices are:
OFF Leakage tests are included in normal datalog output.
ALL LEAKAGE TESTS All leakage tests are datalogged with
the values for pins specified by the LEAKAGE PINS option.
FAILING LEAKAGE TESTSOnly failing leakage tests are datalogged
with the values for pins specified by the LEAKAGE PINS option.
Passing tests are included in normal datalog output.
LEAKAGE PINS Specifies which pin leakage values to datalog. This option is
active only when leakage datalogging is turned on. Choices are
ALL PINS Values for all pins are included in the datalog output.
FAILING PINS ONLYOnly values for those pins that failed the
leakage limits are included in the leakage datalog output.
STDF MODE Specifies the type of datalogged results. Choices are:
HEAVY Specifies that each test result record (PTR, MPR, or FTR)
will contain all the information about the test, including the test
number, the test name and label, the test limits, and the test
result.
LIGHT Specifies that much of the static data for each test,
including the limits, is only contained in the first result record for
each test. This is the default.
EXTRA-LIGHT(XLIGHT) Specifies that the test name and label
(test_txt) is also only contained in the first result record for
each test.
Lighter modes create smaller STDF files.
See “tl_set_test_condition_during_lot” on page 26-382 for the
side effects of changing the test conditions during the run of a lot.
Datalog Output Window
The Datalog Output window (figure 6-8) is the first output option on the Data Collection
Setup display. When this option is selected and applied, a datalog -on -datawin...
IMAGE Solutions V8.3 6-24
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
command is generated, which brings up the Datalog Output window. All datalog data is then
sent to that window.
Figure 6-8. Datalog Output Window, Motif-style running in CDE
The Datalog Output window includes the following commands:
FILE menu Allows saving the displayed data and closing the display.
EDIT menu Allows locating and copying data within the display.
VIEW menu Controls what part of the data is shown.
NEXT DEVICE, PREVIOUS DEVICE
Scroll through the datalog output by device.
CLEAR Removes data from the display.
To support the capabilities of the OpenWindows and Common Desktop Environment
window managers, IMAGE includes versions of the Datalog Output window tuned for each
system. Both versions operate in both window managers, and you can choose the version
you prefer.
To choose the version of the Datalog Output window for the current session only:
1. In the Data Collection Setup display, choose DATALOG WINDOW as a DATALOG OUTPUT
destination. A DATAWIN VERSION item appears above the Datalog Criteria section.
IMAGE Solutions V8.3 6-25
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
2. In the DATAWIN VERSION item, click the version of the Datalog Output window you want
to use. Choose XVIEW for an OpenWindows-style display; choose MOTIF for a CDE-style
display.
3. When you are finished configuring the collection parameters, click APPLY.
To set the version of the Datalog Output window that IMAGE uses as its default, set the
DATALOG/SUMMARY OPTIONS>DEFAULT DATAWIN VERSION option in IMAGE Properties to
XVIEW (for OpenWindows-style) or MOTIF (for CDE-style). (For more information on how to
set IMAGE properties, see “Changing IMAGE” on page 3-33). You can also change the
default Datalog Output window version by including the following line in your .Xdefaults
file:
image.datawin.version:
After the property name, add xview (for OpenWindows-style) or motif (for CDE-style). If
you do not include this line in your .Xdefaults file, IMAGE uses the XView version.
The Motif version of the Datalog Output window supports wide displays, making it easier to
read lengthy output from programs with large numbers of pins.
In order for the Motif version of the Datalog Output window to scroll automatically as new
data appears, the cursor must be at the end of the existing data. You can position the cursor
in the appropriate place by selecting VIEW>END OF LOG or pressing CONTROL+E.
The Motif version of the Datalog Output window can be divided into no more than two
viewable text areas, and the view areas are not writable.
The Datalog Output window disappears if datalog to the window is disabled with the
datalog -off command. You can also disable datalog to this window by selecting QUIT
from its window menu, or FILE>EXIT.
Using the Enhanced Functional Datalog Display
The Enhanced Functional Datalog (EFD) display (figure 6-9) allows you to specify more
failure information than is available on the Data Collection Setup display. The EFD is
available for Advanced Mixed-Signal, Catalyst, and Catalyst Tiger test systems.
IMAGE Solutions V8.3 6-26
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Figure 6-9. Enhanced Functional Datalog Display
Datalogs of digital data made from the Data Collection Setup display show the vector and
cycle number after the pattern halts, which may not be the failing vector and cycle number.
In the EFD, however, the additional failure information is read from the History RAM.
Datalogs produced by the EFD, therefore, show the failing vector and its cycle number. Also
the vector and cycle number at the beginning of datalogs set up by the EFD display are the
vector and cycle numbers after the pattern halted. (See “EFD Output Format” on page 6-44.)
However, reading additional data from History RAM uses test time. Use this EFD display
only when you want more failure information. (See “Pattern Execution History RAM” on
page 37-52 in the Catalyst Instrumentation Manual.)
In the EFD display, you can:
• Specify different datalog setups for different tests or groups of tests
• Select all vectors in HRAM or only the failing vectors
• Put the HRAM into multiple failures mode (advanced mixed-signal only)
• Specify the number of vectors to datalog before a failing vector
• Specify the number of vectors to datalog after a failing vector
• Specify the number of failing vectors to datalog, and if multiple failures occur, specify all
vectors
• Include programmed channel data when a vector is datalogged
• Include tset and loop count information when a vector is datalogged
• Specify the pins, list of pins, failing pins, or all pins to be datalogged. If datalogging a list
of pins, you can datalog only the failing pins in the list or all pins in the list.
• Specify the grouping of vector data: pattern column groups or pattern column order
• Specify the radix of the vector data when pattern column groups are used
IMAGE Solutions V8.3 6-27
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
All these features (except the advanced mixed-signal HRAM multiple failure mode) can be
specified on a per-test basis. Datalog setups can have different EFD setups for different
tests or groups of tests.
When you open the Enhanced Functional Datalog display, it displays the current datalog
information. If datalog information changes while the EFD display is open, however, the new
information is not shown in the display. To update this display (and all other open data
windows), use the menu item SETTINGS>REFRESH DISPLAY WITH DATA COLLECTION
SETTINGS in the Data Collection Setup display. (See “Control Panel Items” on page 6-15.)
EFD Display Control Panel Items
The EFD display control panel includes the following items:
ADD Displays the Add EFD setup window (figure 6-10) that allows you
to assign a name to the EFD setup or to enter the name of the
setup to be displayed. If no EFD setups exist, you must click
SELECT on this button to add an EFD setup before you can use
EFD. This window automatically generates a name for each
setup of the form efd_setup_<n>. You can replace this with your
own setup name.
Figure 6-10. Add EFD Setup Window
REMOVE Selects the EFD setup to remove. Choices are CURRENT EFD
SETUP or ALL EFD SETUPS.
SHOW Displays all EFD setups and allows you to select one to be
displayed.
HRAM FAIL MODE Specifies A580 or Catalyst HRAM failure mode as on or off. ON
puts the HRAM in multiple failure mode, allowing the HRAM to
capture up to 63 failing vectors. The failure mode can be
specified only for all EFD setups, not for individual EFD setups.
Setting HRAM fail mode ON is the same as the following
statements:
set hsd50 hram_failmode:on;
set hsd50 ignore_halt_on_fail:always;
set hsd50 hram_stop_on_full:on;
This setting appears only with advanced mixed-signal, Catalyst,
or Catalyst Tiger test systems.
IMAGE Solutions V8.3 6-28
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Setting the HRAM Fail Mode
Setting the HRAM fail mode from the EFD can conflict with HRAM set statements in your
test program. For example, a program may include the statement:
set hsd50 hram_failmode:off;
If you use set HRAM FAIL MODE:ON in the EFD display and run the program, you get an error
such as the following:
[3092] EFD hram_failmode_off conflicts with hram_failmode: on
Enhanced Functional Datalog hram_failmode_off has been specified, but
'hram_failmode : on' has just been specified.
In such a case you may want to use a set error ignore statement to ignore these errors.
See “Changing the Default Action for an Error” on page 15-31 and “Pattern Debugging From
a Test Program” on page 37-20 in the Catalyst Instrumentation Manual.
EFD Display Items
The EFD display includes the following items:
CRITERIA Specifies which tests to datalog. Can be ALL FAILED TESTS or LIST
OF TESTS. Only one criteria can be active at a time. Default is ALL
FAILED TESTS. Applying a criteria overwrites the previous criteria.
LIST Specifies the test or list of tests to be displayed in the datalog.
DATALOG Datalogs only failing vectors in HRAM or datalog all vectors. Can
be FAILING VECTORS or ALL VECTORS. Default is FAILING VECTORS.
VECTORS BEFORE FAIL Specifies the number of vectors before the failing vector to
datalog. The default is 0.
VECTORS AFTER FAIL Specifies the number of vectors after the failing vector to datalog.
The default is 0.
PROG. CHANNEL DATA Displays the programmed channel data along with the failing
data. The default is ON, meaning display the programmed
channel data.
NUMBER OF FAILED VECTORS
Specifies the number of failed vectors captured in HRAM to
datalog. To datalog multiple failures, the number can equal the
total number of vectors. The default is 1.
PINS Datalogs a list of pins, only the failing pins, or all pins used by the
pattern. The choices are FAILING PINS, ALL PINS, FAILING PINS IN
LIST, or LIST OF PINS. If you also specify a list of pins in the text
field next to LIST, only failing pins in the list of pins are
datalogged. The default is FAILING PINS.
LIST Specifies the pins or list of pins to be displayed in the datalog.
The pins or list of pins can be pin numbers or pin names.
IMAGE Solutions V8.3 6-29
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
DISPLAY Groups the vector data in the datalog by PIN ORDER, PATTERN
COLUMN GROUPS, or PATTERN COLUMN ORDER. PIN ORDER
displays the information by numerical pin order (pin 1 to pin N).
PATTERN COLUMN ORDER displays the pins in the order they
appear in the pattern with no groups. PATTERN COLUMN GROUPS
displays the pin groups. The default is PIN ORDER.
RADIX Shows the datalog in OCTAL, HEX (hexadecimal), DECIMAL,
BINARY, or SYMBOLIC. You can change the radix only if you select
PATTERN COLUMN GROUPS from the DISPLAY menu above. This
item is grayed out (inactive) unless PATTERN COLUMN GROUPS
are selected. The default is the radix used in the pattern file. If
groups are not used, the vector data is shown in symbolic.
LOOP COUNT Specifies whether the loop count is shown with the vector data in
the datalog. The default is ON.
TIMING SETS Specifies whether the timing set is shown with the vector in the
datalog. The default is ON.
APPLY Applies the currently displayed setup to the data server.
Generates a datalog statement in the station window. You must
click SELECT on this button to make any EFD changes take
effect.
RESET Resets the display to its last-saved values (the values in the
display when you last clicked APPLY).
Setting Up the EFD Display
To bring up the Enhanced Functional Datalog display (figure 6-9 on page 6-27) from the
Data Collection Setup display proceed as follows:
1. Load a test program.
2. In the Data Collection Setup window, enable datalog output to the Datalog Output
window, an STDF file, or a text file.
3. Click SELECT on the FUNCTIONAL (EFD) button in the control panel of the Data
Collection Setup display. The Enhanced Functional Datalog display appears. All items
in the display except the ADD button are grayed out (inactive).
4. Click ADD. The Add EFD Setup window appears. The setup name should read:
efd_setup_1
5. Click on ADD in the Add EFD Setup window. All items in the EFD display should become
active.
EFD Restrictions
Observe the following restrictions when using enhanced functional datalog:
• The -channels and -add_efd pat_col_grp options are incompatible. If both are
selected, the datalog or datastream commands or both fail.
IMAGE Solutions V8.3 6-30
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
• To display information by pin groups, the pin group names in the pattern file must match
the pin groups in the pin map. Otherwise, individual pins are displayed.
• The test program must have a pinmap.
• EFD cannot datalog passing tests.
• You can have only one EFD setup per test.
• EFD cannot be programmed using the datalog test program statement.
• EFD can be paused and resumed from the display or the command line and enabled or
disabled using the tl_set_dlg_enable() function.
• EFD reads back the HRAM. Reading and reconstructing HRAM on advanced mixed-
signal testers (A570 and A580) takes about 700 ms per SCM. HRAM need only be read
once for each failing test for which EFD is on; it does not need to be read again for each
failing vector.
• For a failing vector to be datalogged, both the failing vector itself and the vector where
the fail flag is set (60 or 62 cycles later on advanced mixed-signal test systems, 34
cycles later on mixed-signal test systems) must be captured in HRAM.
• The number of vectors datalogged before and after a failing vector may not always be
the number you requested; it is limited by how many vectors before and after the failing
vector were captured in HRAM. For instance, with A580 fail mode, only three vectors
before the failing vector and 60 vectors after the failing vector are generally available. If
the longer pipeline depth is used, one vector before the failing vector and 62 vectors
after the failing vector are available.
• Setting up HRAM to capture logic rather than fail may result in an incorrect list of failing
pins for datalogged vectors. The list of failing pins printed at the beginning of the datalog
output for each test is still correct, but the failing pins listed for individual vectors could
be incorrect.
• EFD setups apply to all datalogs and datastreams. You cannot associate an EFD setup
with any single datastream or datalog output.
Datalog Setup Using the datalog Command
Most functions in the Data Collection Setup display and Enhanced Functional Datalog
display have parameters and switches in the datalog command. The syntax for using the
datalog command is:
datalog [-on (outputs) (format) [(includes) | (tests) | (notests)]
(samples) (mode) (leakage)]
[-off] [-show] [-pause] [-resume]
[-change [(includes) | (tests) | (notests)] (samples) (mode)
(leakage)]
[-add_output (outputs)] [-remove_output (outputs)]
[-add_efd <efd_setup_name> (efd_info)]
[-remove_efd <efd_setup_name>] [-efd_off] [-station #]
[-wafer_map] [-smy_checkpoint #]
where:
IMAGE Solutions V8.3 6-31
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
-on Turns datalog on.
(outputs) = Specifies where to send the data (the output stream). This is
required. Specify one or more of the following:
[-stdf] [-stdf_file <stdf filename>]
[-statwin] [-datawin] [-datawin_display <host>]
[-file <filename>] [-printer [<printername>]] [-pmc]
See “Output Selection” on page 6-37.
(format) = [-pin names | numbers] [-channels on | off]
[-pins_per_line #] [-format <program_name>]
[-no_wrap] [-full_pin_names]
-pin names | numbers
Specifies datalog of pin names or pin numbers.
-channels on | off Specifies whether channel numbers are datalogged.
-pins_per_line # Specifies the number of pins or channels on each line of the
datalog.
-format Specifies the datalog format as full (fulldlgfmt) or brief
(dlgfmt) by calling the appropriate datalog filter. See “Output
Format” on page 6-41. You can also specify the name of a
custom datalog filter, and IMAGE searches along the path
specified by your $PATH environment variable for the program to
run. See “Custom Datalog Filters” on page 6-82. Format does
not apply when data is being sent only to an STDF file.
-no_wrap Specifies displaying output on one line.
-full_pin_names Shows full pin names (number of characters not restricted).
(includes) = Use the -include switch multiple times (up to nine) to specify
sets of tests to datalog.
[-include [all | (lists)] [pass | fail]
[analog | digital]
See “Test Selection” on page 6-38.
(tests) = Specifies tests to datalog. (This switch is obsolete but functions
as before. Use -include to specify tests.) You can specify one
of the following:
[-test [all | pass | fail] [digital | analog] (lists)]
-notests
(lists) Specifies a list of tests.
[list_file <filename>]
[list [#] [# to #] [<test_name>]
[SEQUENCER <seqname>]]
Types of list elements are shown in table 6-2.
IMAGE Solutions V8.3 6-32
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Table 6-2. Datalog list Parameters
Parameter Definition Example
# Test number list 10
# # .. # List of test numbers list 10 20 30
# to # Range of test list 10 to 40
numbers
test_name Test name or names list leak_test
test_name test_name List of test names list vout1 vout2 vout3
SEQUENCER seq_name1 Sequencer name list SEQUENCER tp_seq_1
SEQUENCER name SEQUENCER Sequencer list list SEQUENCER seq1 SEQUENCER
name seq2
1. The SEQUENCER prefix must be written exactly as shown.
(samples) = [-samprate #] [-samplimit #]
-samprate # Specifies sampling rate for datalog, how often devices are
datalogged. Default is 1, datalog every device. (See “Sampled
Datalog” on page 6-47.)
-samplimit # Specifies a sampling limit for datalog, the total number of devices
to be datalogged. The default is no limit. (See “Sampled Datalog”
on page 6-47.)
(mode) = [-mode <heavy/light/xlight>]
(Affects STDF file only)
Specifies the type of datalogged results. heavy specifies that
each test result record (PTR, MPR, or FTR) will contain all
information about the test, including test number, test name and
label, test limits, and test result. In light mode, much of the
static data for each test, including the limits, is only contained in
the first result record for each test. In extra-light (xlight) mode,
the test name and label (test_txt) is also only contained in the
first result record for each test. The lighter the mode, the smaller
the STDF file will be. The STDF mode for an STDF file is user
selectable. The STDF mode for all other outputs is heavy. (See
“tl_set_test_condition_during_lot” on page 26-382 for the side
effects of changing the test conditions during the run of a lot.)
(leakage) = Enables leakage datalogging of HSD50 pins. This is an HSD50
option only. Leakage datalog is output in a special format. (See
“Leakage Output Format” on page 6-43.)
IMAGE Solutions V8.3 6-33
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
[-lkg [off | all | fail]
[all_pins | fail_pins]]
[off | all | fail]
Either no leakage tests are datalogged, all leakage tests are
datalogged, or only failing leakage tests are datalogged. Leaving
the -lkg switch out of the datalog command also turns datalog
leakage off. You can combine the all and fail keywords with
all_pins and fail_pins.
[all_pins | fail_pins]
Specifies that all pin values or only failing pin values are included
in the datalog output. (See “Leakage Selection” on page 6-40.)
-off Turns datalog off. This closes all output streams, deletes all
setup information, and turns off all EFD setups.
-show Displays the current datalog setup in the station window. This
includes the outputs selected, the format (brief or full), what tests
are enabled for datalog, and the sample rate. If data collection is
paused, the output includes the line:
Data Collection is PAUSED
-pause Pauses all data collection temporarily.
-resume Resumes data collection.
-change [(includes) | (tests) | -notests]
(samples) (mode) (leakage)
Allows you to modify parts of the datalog setup without turning
off datalog or respecifying the entire datalog setup.
-add_output (outputs)
Allows you to add an output (for example, -stdf) without
respecifying the entire datalog setup.
-remove_output (outputs)
Allows you to remove an output without turning off datalog or
respecifying the entire datalog setup.
-add_efd <efd_setup_name> (efd_info)
Add EFD setups. You can specify multiple EFD setups by
repeating this statement. If two setups conflict, the latest
specification overrides.
You cannot use this option when datalogging passing tests. If
passing tests are selected, the datalog command fails and an
error message is displayed. As with other datalog setups, you
must use the -test option.
You cannot use this option without specifying an output on a
command line. If no outputs are specified in a datalog
command, the EFD setup is incrementally added to any
previously opened outputs. If no outputs are open, the setup is
IMAGE Solutions V8.3 6-34
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
rejected and you are warned by an error message. Specifying an
output with an EFD setup either opens an output, if none exists,
or closes existing outputs and opens the latest output
specification.
EFD setups apply to all datalogs and datastreams. You cannot
associate an EFD setup with any single datastream or datalog
output.
For more information on EFD, see “Using the Enhanced
Functional Datalog Display” on page 6-26 and “Wafer Output
Format” on page 6-43.
efd_setup_name Is a unique identifier assigned to a particular EFD setup.
(efd_info) = [fail_vect | all_vect] [num_fail_vect #]
[loop_cnt_on | loop_cnt_off]
[vect_before_fail #] [vect_after_fail #]
[hram_failmode_on | hram_failmode_off]
[all_pins | fail_pins]
[pin_list [<pin> | <pin> to <pin>]]
[prog_data_on | prog_data_off] [tset_on | tset_off]
[pat_col_grp | pat_col_ord | pin_ord]
[display_radix [octal hex dec bin sym]]
[fail_vect | all_vect]
Specifies whether failing vectors or all vectors captured in HRAM
should be datalogged. (The default is fail_vect.)
[num_fail_vect #]
Specifies how many failed vectors to datalog when datalogging
failing vectors. You can specify a specific number or use all to
datalog all failing vectors captured in HRAM.
[loop_cnt_on | loop_cnt_off]
Shows the loop count along with the vector data in the datalog.
(The default is loop_cnt_on.)
[vect_before_fail #]
Specifies the number of vectors before the failing vector to
datalog. (The default is 0.)
[vect_after_fail #]
Specifies the number of vectors after the failing vector to datalog.
(The default is 0.)
[hram_failmode_on | hram_failmode_off]
Specifies A580 or Catalyst HRAM failure mode as on or off.
When on, the HRAM is in multiple failure mode and allows the
HRAM to capture up to 63 failing vectors. You can specify HRAM
failure mode only for all EFD setups, not for each EFD setup.
IMAGE Solutions V8.3 6-35
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Setting HRAM fail mode on is equivalent to the following Catalyst
statements:
set hsd50 hram_failmode:on;
set hsd50 ignore_halt_on_fail:always;
set hsd50 hram_stop_on_full:on;
This setting applies only to advanced mixed-signal test systems.
Note that this parameter can affect settings in a test program.
See “Setting the HRAM Fail Mode” on page 6-29.
[all_pins | fail_pins]
Datalogs all pins or only the failing pins. (The default is
fail_pins.)
[pin_list [<pin> | <pin> to <pin>]]
Datalogs a pin or list of pins. Can also be written as pin1
pin2...pinn
[prog_data_on | prog_data_off]
prog_data_on displays the programmed channel data with the
failing data. (The default is prog_data_on.)
[tset_on | tset_off]
Shows the timing set along with the vector in the datalog. (The
default is tset_on.)
[pat_col_grp | pat_col_ord | pin_ord]
Groups the vector data in the datalog by pattern column groups
or pattern column order. Pin order displays the information by
numerical pin order (pin 1 to pin N). Pattern column order
displays the pins in the order they appear in the pattern with no
groups. Pattern column groups displays the pin groups. (The
default is pin_ord.)
[display_radix [octal hex dec bin sym]]
Shows the datalog in octal, hexadecimal, decimal, binary, or
symbolic. The default is the radix used in the pattern file. If
groups are not used, the vector data is shown in symbolic.
-remove_efd <efd_setup_name>
Deactivates the named EFD setup. It is analogous to datalog
-off. The -remove_efd and -efd_off options need not be
used with any other option, such as -test or -stdf. If
deactivating a specific EFD setup, you must provide the setup
name.
This option removes EFD setups from all datalog and
datastream output setups.
-efd_off Deactivates EFD and all EFD setups. This option removes EFD
setups from all datalog and datastream output setups.
-station # Specifies a station number to collect datalog data.
IMAGE Solutions V8.3 6-36
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
-wafer_map Collects all information relevant to wafer mapping. Use this
option with the -samprate # option. (See “Generating Wafer
Map Information” on page 6-47.)
-smy_checkpoint # Specifies the number of devices to test before writing datalog
information to a backup file.
The datalog command will fail if you datalog passing tests, passing digital tests, or any
analog tests and any EFD setup.
For non-EFD options, the latest option specified in a command overrides all previous
specifications. The current default is not changed. If a pinmap is found, fail information is
displayed by pin. Otherwise channel data is printed.
Examples of datalog commands are as follows:
• Display the current datalog setup for station 2:
datalog -show -station 2
• Datalog failed tests to the named text file:
datalog -on -file <file_name> -test fail
• Datalog test numbers 4–12 to an STDF file and Datalog Output window:
datalog -on -stdf -datawin -test list 4 to 12
• Create the default EFD setup. The default EFD setup datalogs failing vectors and no
vectors before or after the failing vector. Vector data is displayed in pin order and only
failing vectors are datalogged. The following command turns on datalogging, sets up the
EFD file efd_example, and sends the results to an STDF file:
datalog -on -test fail -add_efd efd_example1 -stdf
See “Wafer Output Format” on page 6-43.
Output Selection
Possible output selections for the datalog command are:
-stdf Write output in STDF (binary) format to a disk file.
-stdf_file <stdf filename>
Write output in STDF format to a file you specify.
-statwin Display output in the station window.
-datawin Display output in the Datalog Output window. Can be
abbreviated -dwin.
-datawin_display <host>
Display output in the Datalog Output window on the specified
host.
-file <filename> Write output as ASCII text to a disk file.
-printer [<printername>]
Write output to a separate file with the extension .printtmp.
IMAGE Solutions V8.3 6-37
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
This file is spooled at the end of lot or when datalogging is turned
off. The .printtmp file is deleted after printing.
-pmc Display output to the Production Menu Control.
For example, to datalog all failing tests to the Datalog Output window use
datalog -on -datawin -test fail
You can use output selection switches individually or in combination with one another, but
at least one must be active for any data to be logged.
NOTE
Each time you modify the datalog setup using the datalog command you must respecify
output selections. Omitted selections are automatically turned off.
Datalog to a standard test data format (STDF) file sends data to a file called
<node>_<station#>_<test_program>_<lot_id>_<timestamp>.stdf
For example:
constance_1_volt_reg2_23_Feb16_09:57.stdf
The -stdf_file option allows you to set your own file name for an STDF file. (For
information on STDF filenames, see “Naming STDF Files” on page 6-19.) For example, to
turn on STDF datalog for all tests and collect the STDF data into the file myfile.stdf, use
the following command:
datalog -test all -stdf_file myfile.stdf
Datalog to an STDF file lets you maintain large amounts of data that consume less disk
space. Files can also be transferred to a FIRMS host for storage.
When setting up datalog to a text file, the <filename> specification is optional. If you omit
it, a default filename is created based on the test program name and station number. The
format of the default filename is
<node>_<station#>_<test_program>_<lot_id>_<timestamp>.data
When enabling datalog to a text or STDF file, if the filename exists it is moved to a backup
file called <filename>% and a new file is started.
Test Selection
Use the -include switch of the datalog command to select tests to be datalogged. The
-test switch works as before, but -include is preferred and provides extended
functionality for specifying sets of tests to datalog.
You can specify analog or digital tests using the analog and digital keywords. You can
use either of these keywords with existing keywords, such as pass, fail, or all. For
example, to datalog all digital tests, use the command
IMAGE Solutions V8.3 6-38
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
datalog -include digital all
Each of the pairs of keywords, analog and digital, pass and fail, and all and list, are
exclusive. Use only one from each pair with the -include switch. The subswitches are
restrictive: using the keyword analog restricts the set to only analog tests, fail restricts the
set to only failing tests, and list restricts the set to only tests on the list. The all keyword
is only required when there are no other subswitches specified (as in -include all).
You can use the -include switch up to nine times to specify multiple sets of tests to
datalog. A test is included only once even if it falls into more than one include set.
Options to -include can be in any order. Therefore, both the following commands are legal:
datalog -include pass digital
datalog -include digital pass
To specify a list of tests, use -include list. Next, specify the list elements separated by
spaces. A list element can be a test name, a test number, a range of numbers, or a
sequencer name. (See table 6-2 on page 6-33.) For example, the following command will
datalog four single tests and one range of tests:
datalog -include list aa bb 42 3 to 7 cc
If the list is long, you can continue it on the next line by ending the current line with a
backslash (\), or you can use a list_file.
Table 6-3 contains some example datalog switches and their meanings.
Table 6-3. Datalog Switches
Switch Definition
-include all All Tests
-include pass Passing Tests
-include list <...> Tests on List
-include analog Analog Tests
-include analog pass Analog Passing Tests
-include analog list <...> Analog Tests on List
-include analog pass list <...> Analog Passing Tests on List
-include fail list <...> Failing Tests on List
-include analog pass Analog Passing Tests and Digital Failing Tests
-include digital fail
-include analog list <A> Analog Tests on List A and Digital Tests on List
-include digital list <B> B
IMAGE Solutions V8.3 6-39
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
The -include switch and the -test switch cannot be used together on a datalog command
line. When turning data streams on (using the -on switch), either -include or -test can
be used to define the test criteria. When changing the setup for a data stream (using the
-change switch), test criteria defined with -test or -include replaces the current test
criteria for that data stream. If neither -test nor -include is specified with the -change
switch, the test criteria for that data stream remains unchanged.
Using a List of Tests in a File
You can keep a list of tests in a text file and use it by specifying:
-include list_file <filename>
An example would be:
datalog -on -stdf -include list_file <filename>
The format of the list_file is a series list of elements, one element per line. You can
embed comments in the list file by preceding them with a # in column 1. Figure 6-11 shows
a sample datalog test list file.
# THIS IS A SAMPLE DATALOG LIST_FILE
#
# Any line containing a "#" is treated as a comment from that
# point on. (These are comments.)
10 # Datalog test 10
100 to 200 # and tests in the range 100 to 200
beta # also log test beta
SEQUENCER main_seq # and anything in this sequencer
# THIS IS THE END
Figure 6-11. Sample Datalog Test List File
Leakage Selection
The -lkg switch takes up to two arguments:
-lkg [<testspec>] [<pinspec>]
where <testspec> can be off, all (default), or fail, and <pinspec> can be all_pins
(default) or fail_pins.
Take care when using the defaults. The default action when turning a data-stream on is to
use the default values for any values not specified. The default action when changing an
existing datastream is to leave the value unchanged if it is not specified. However, if neither
value (<testspec> or <pinspec>) is specified when changing an existing datastream, both
default values are used.
For example:
-on -lkg -on -lkg all all_pins
IMAGE Solutions V8.3 6-40
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
-on -lkg <testspec> <pinspec>
Set both as specified.
-on -lkg <testspec>
-on -lkg <testspec> all_pins
-on -lkg <pinspec>
-on -lkg all <pinspec>
-change -lkg -change -lkg all all_pins
-change -lkg <testspec> <pinspec>
Changes both as specified.
-change -lkg <testspec>
Changes only the test spec.
-change -lkg <pinspec>
Changes only the pin spec.
Output Format
The format of a datalog report is controlled by the format test program. You can change the
report format by selecting the following test format programs:
• Brief format (dlgfmt) displays the test number, label, and result (see figure 6-2 on page
6-13).
• Full format (fulldlgfmt) displays the test name, number, label, result, and limits (see
figure 6-12).
• EFD one-line format (efddlgfmt) displays the test number, label, result, and additional
EFD information in a one-line format (see “Wafer Output Format” on page 6-43).
Specify the format test program for the text output streams using one of the following
switches with the datalog command:
-format dlgfmt
-format fulldlgfmt
-format efddlgfmt
The default format test program is dlgfmt. The -format switch applies to all output streams
created by a single datalog command, including output to the station window, the Datalog
Output window, and an STDF file, and a text file.
IMAGE Solutions V8.3 6-41
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Lot: xyz111 Tester: topaz Program: cd1711
Device: 1 Station: 1 Site: 0 Date: Mon May 16 13:22:03 1988
Sequencer: first_level_tests
10 leak_vcc leak_vcc 10 volts < 54 volts (F) < 50 volts
20 lcap_vcc lcap_vcc 24.9 uf (F) < 20.0 uf
30 ac_rip ac_rip 20 Khz < 30 Khz (F) < 30 Khz
40 sig_amp sig_amp -1.25
50 saturate saturate 500 ma < 495 ma (F)
Sequencer: second_level_tests
100 leak_vcc leak_vcc 5 volts < 60 volts (F) < 55 volts
200 lcap_vcc lcap_vcc 17.9 uf < 30.0 uf
300 ac_rip ac_rip 15 Khz < 28 Khz < 40 Khz
400 sig_amp sig_amp -8.52
500 saturate saturate 400 ma < 288 ma (F)
Bin: 20
Lot: xyz111 Tester: topaz Program: cd1711
Device: 2 Station: 1 Site: 0 Date: Mon May 16 13:22:07 1988
Sequencer: first_level_tests
10 leak_vcc leak_vcc 10 volts < 40 volts < 50 volts
20 lcap_vcc lcap_vcc 22.4 uf (F) < 20.0 uf
30 ac_rip ac_rip 20 Khz < 18 Khz (F) < 30 Khz
40 sig_amp sig_amp -2.65
50 saturate saturate 500 ma < 500 ma (F)
Sequencer: second_level_tests
100 leak_vcc leak_vcc 5 volts < 61 volts (F) < 55 volts
200 lcap_vcc lcap_vcc 10.0 uf < 30.0 uf
300 ac_rip ac_rip 15 Khz < 15 Khz < 40 Khz
400 sig_amp sig_amp 6.95
500 saturate saturate 400 ma < 308 ma (F)
Bin: 20
Lot: xyz111 Tester: topaz Program: cd1711
Device: 3 Station: 1 Site: 0 Date: Mon May 16 13:22:11 1988
Sequencer: first_level_tests
10 leak_vcc leak_vcc 10 volts < 31 volts < 50 volts
20 lcap_vcc lcap_vcc -3.9 uf < 20.0 uf
30 ac_rip ac_rip 20 Khz < 33 Khz (F) < 30 Khz
40 sig_amp sig_amp -4.66
50 saturate saturate 500 ma < -33 ma (F)
Sequencer: second_level_tests
100 leak_vcc leak_vcc 5 volts < 61 volts (F) < 55 volts
200 lcap_vcc lcap_vcc 17.9 uf < 30.0 uf
300 ac_rip ac_rip 15 Khz < 29 Khz < 40 Khz
400 sig_amp sig_amp 10.87
500 saturate saturate 400 ma < 283 ma (F)
Figure 6-12. Full Format Datalog Report
IMAGE Solutions V8.3 6-42
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Leakage Output Format
You can use the datalog full and brief format for HSD50 leakage results if you choose
LEAKAGE DATALOG in the Data Collection Setup display or use the -lkg switch with the
datalog command. The output includes limits for the test and values for each of the pins
depending on how you have setup the leakage datalog.
In the examples below, (F) denotes failed high limit and (f) denotes failed low limit. If the
pin name is shown as C#XX, the number is the channel number. This happens for channels
that are not in the pin map.
The following is an example of the full format. The output shows labels, limits and test name.
13 fail leakage test_leakag 20.00 ua < Xi < 250.00 ua
C#1: 100.00 ua C#2: 113.00 ua PIN1: 126.00 ua
PIN2: 139.00 ua PIN3: 152.00 ua PIN4: 165.00 ua
PIN5: 178.00 ua PIN6: 191.00 ua C#9: 204.00 ua
C#10: 217.00 ua C#11: 230.00 ua C#12: 243.00 ua
C#13: 256.00 ua(F) C#14: 269.00 ua(F) C#15: 282.00 ua(F)
C#16: 295.00 ua(F)
14 fail leakage high re test_leakag 200.00 ua < Xi < 400.00 ua
C#1: 100.00 ua(f) C#2: 113.00 ua(f) PIN1: 126.00 ua(f)
PIN2: 139.00 ua(f) PIN3: 152.00 ua(f) PIN4: 165.00 ua(f)
PIN5: 178.00 ua(f) PIN6: 191.00 ua(f) C#9: 204.00 ua
C#10: 217.00 ua C#11: 230.00 ua C#12: 243.00 ua
C#13: 256.00 ua C#14: 269.00 ua C#15: 282.00 ua
C#16: 295.00 ua
The following is an example of the brief format. The output shows labels only.
13 fail leakage
C#1: 100.00 ua C#2: 113.00 ua PIN1: 126.00 ua
PIN2: 139.00 ua PIN3: 152.00 ua PIN4: 165.00 ua
PIN5: 178.00 ua PIN6: 191.00 ua C#9: 204.00 ua
C#10: 217.00 ua C#11: 230.00 ua C#12: 243.00 ua
C#13: 256.00 ua(F) C#14: 269.00 ua(F) C#15: 282.00 ua(F)
C#16: 295.00 ua(F)
14 fail leakage hig
C#1: 100.00 ua(f) C#2: 113.00 ua(f) PIN1: 126.00 ua(f)
PIN2: 139.00 ua(f) PIN3: 152.00 ua(f) PIN4: 165.00 ua(f)
PIN5: 178.00 ua(f) PIN6: 191.00 ua(f) C#9: 204.00 ua
C#10: 217.00 ua C#11: 230.00 ua C#12: 243.00 ua
C#13: 256.00 ua C#14: 269.00 ua C#15: 282.00 ua
C#16: 295.00 ua
Wafer Output Format
When you use datalog at wafer probe, the start and end of wafer are added to the output
format. For example:
Wafer: <waferid> Start Time: <wafer start time>
End of Wafer: <waferid> Part Count: <n>
Finish Time: <wafer finish time>
IMAGE Solutions V8.3 6-43
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
EFD Output Format
EFD datalogs provide additional information on failing vectors and pins. You can specify
one-line or two-line formats.
One-Line EFD Format. The one-line EFD output format places results for each vector on
one line. Any pin that fails anywhere in the pattern is marked with a pound sign (#) under
the pin name, even if the failure is outside the selected range of vectors. For example:
Lot: 1 Tester: hudson Program: my
Device: 1 Station: 1 Site: 0
Sequencer: flow_1
100 Functional Pattern Halt Vector: 268 Halt Cycle: 269 Failing Pins: 8 (F)
Pattern: 16PinPat_ro
Failed Pins:
PIN001 : 1 PIN003 : 3 PIN005 : 5 PIN007 : 7
PIN009 : 9 PIN011 : 11 PIN013 : 13 PIN015 : 15
P P P P P P P P
I I I I I I I I
N N N N N N N N
0 0 0 0 0 0 0 0
0 0 0 0 0 1 1 1
1 3 5 7 9 1 3 5
Vector Tset Cycle # # # # # # # #
2 ro_ts 3 L L L L L L L L
3 ro_ts 4 F H / / H H H H H
4 ro_ts 5 L L L L L L L L
6 ro_ts 7 L L L L L L L L
7 ro_ts 8 F H H / / / / H H
8 ro_ts 9 L L L L L L L L
9 ro_ts 10 F H H H H H H / /
10 ro_ts 11 L L L L L L L L
Bin: 2
Note that pin 1 is marked as failing although the displayed vectors show no failure data.
Failures are listed on each vector line using a code for the expected value (table 6-4). The
default value is F.
Table 6-4. EFD One-Line Format Symbols
Expected Data Printed Symbol
H or 1 /
L or 0 .
M -
V @
IMAGE Solutions V8.3 6-44
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
To specify the one-line EFD format, click MENU on the FORMAT list in the Data Collection
Setup Window and select. (You must also have the EFD enabled and have defined a setup.)
You can enable one-line EFD output on the command line by specifying the -add_efd and
-format efddlgfmt parameters on the same command line.
Two-Line EFD Format. For passing vectors, the two-line EFD format output is the same
as the one-line EFD format shown above. For failing vectors, the expected value is shown
on the first line and the actual received value appears on the second line under each failed
pin. (“Actual mode” is available only on testers that support this feature, such as the Catalyst
and Catalyst Tiger test systems. Earlier systems that do not support actual mode display an
F under the failed pin.) Any pin that fails anywhere in the pattern is marked with a pound
sign (#) under the pin name, even if the failure is outside the selected range of vectors. For
example:
Lot: 1 Tester: hudson Program: my
Device: 4 Station: 1 Site: 0
Sequencer: flow_1
100 Functional Pattern Halt Vector: 268 Halt Cycle: 269 Failing Pins: 7 (F)
Pattern: 16PinPat_ro
Failed Pins:
PIN009 : 1 PIN003 : 3 PIN005 : 5 PIN007 : 7
PIN009 : 9 PIN011 : 11 PIN013 : 13 PIN015 : 15
P P P P P P P P P P P P P P P P
I I I I I I I I I I I I I I I I
N N N N N N N N N N N N N N N N
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1
1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
Vector Tset Cycle # # # # # # # #
2 ro_ts 3 L 0 L 0 L 0 L 0 L 0 L 0 L 0 L 0
3 ro_ts 4 F H 1 H 1 H 1 H 1 H 1 H 1 H 1 H 1
L L
4 ro_ts 5 L 0 L 0 L 0 L 0 L
0 L 0 L 0 L 0
6 ro_ts 7 L 0 L 0 L 0 L 0 L
0 L 0 L 0 L 0
7 ro_ts 8 F H 1 H 1 H 1 H 1 H
1 H 1 H 1 H 1
L L L L
8 ro_ts 9 L 0 L 0 L 0 L 0 L
0 L 0 L 0 L 0
9 ro_ts 10 F H 1 H 1 H 1 H 1 H
1 H 1 H 1 H 1
L L
10 ro_ts 11 L 0 L 0 L 0 L 0 L 0 L 0 L 0 L 0
Bin: 2
Note that pin 1 is marked as failing although the displayed vectors show no failure data.
To specify the two-line EFD format, click MENU on the FORMAT list in the Data Collection
Setup Window and select LABEL, LIMITS AND TESTNAME (you must also have the EFD
enabled and have defined a setup). You can enable two-line EFD output on the command
line by specifying the -add_efd and -format fulldlgfmt parameters on the same
command line.
IMAGE Solutions V8.3 6-45
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Dumping Datalog Information During Debug
tl_dump_data() is a test program function that allows you to display a partial datalog result
in the station window while stopped at a breaktrap during debug. (See “tl_dump_data” on
page 26-190.)
Specifying a Test Data Directory
Datalog files go to the directory (local or remote) specified by DATALOGGING TO FILE OPTIONS
in the PRODUCTION SETUP category of IMAGE Properties. (This option also sends data
collection, datalog, STDF, histogram, datastream, summary, and summary STDF files to
the same directory. See “Production Setup Options” on page 3-37.) You can specify only a
single directory for storing datalog data files. If you do not set this default directory, files go
to the directory from which the test program was loaded.
You can use environment variables when specifying directory names or parts of directories.
For example, specifying TEST DATA DIRS as $HOME/data would place all datalog files in the
subdirectory data of the user’s home directory.
To override writing datalog files to the test data directories, specify the full path name for
datalog files. For example the following command will write file.data to
/u/other_directory, regardless of whether test data directories have been specified:
datalog -on -test all -file /u/other_directory/file.data
Displaying the Current Data Directory
To display the current data collection directory, use the command:
dacldir [-station #]
Field Limitations in Datalog Reports
IMAGE allows up to 256 characters for test names and labels in datalog reports. Long
names are truncated depending on which output format is used. Two results per line is brief
format, and one result per line is full format. Field widths used for all the datalog fields are
listed in table 6-5.
Table 6-5. Datalog Field Widths
Number of Field Width Characters
Datalog Field
Brief Format Full Format
Test number 6 6
Test label 16 18
Test name – 11
Lower test limit (includes scale factor and units) – 9
IMAGE Solutions V8.3 6-46
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Table 6-5. Datalog Field Widths (Continued)
Number of Field Width Characters
Datalog Field
Brief Format Full Format
Test result (includes scale factor and units) 11 11
Upper test limit (includes scale factor and units) – 9
Sampled Datalog
When datalogging, you can select a datalog sample rate and sample limit. This allows you
to adequately characterize a lot or wafer, while limiting the disk space for data files. Use the
-samprate # and -samplimit # switches to specify that only 1 in every N devices is to be
datalogged, up to a maximum of L logged devices.
For example, to datalog 1 in 10 devices include the following on the datalog command line:
-samprate 10
If the rate and the limit are not specified, the rate defaults to 1 (every device is logged), and
the limit defaults to “no limit.” You can use sample rate and sample limit independently. The
maximum value for rate and limit is 232; the minimum value for rate is 1.
When the sample rate is changed, the sample index count (the number of devices tested
since the last datalog) is reset to 1. The sample index is incremented following each run of
the test program. When the index count reaches the sample rate, a datalog record for that
device is created. Then the sample index is reset to 1 and the count begins again. When
the sample limit is reached, no more datalog data is sent to the output streams. To reset the
“no limit” condition, set the limit to 0.
Generating Wafer Map Information
When using sample datalog, the only information collected is for parts that are sampled. All
other information is discarded, including X/Y coordinate information that can be used for
creating wafer maps.
You can use the -wafer_map option to the datalog and datastream commands to collect
such information. This option indicates that all information relevant to wafer mapping is to
be collected regardless of sample rate and limit.
The Data Collection Setup display also includes a check box located beneath the SAMPLE
RATE:item and labelled INCL. WAFER MAP INFO.
When used, this option results in test data being collected for sampled parts, but a Part
Information Record (PIR) and Part Results Record (PRR) is collected for every part. The
PRR contains X/Y coordinate and binning information and the PIR is required for
compliance with the STDF specification.
The -wafer_map option is relevant only when used with the -samprate # option.
IMAGE Solutions V8.3 6-47
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Creating Datastreams
The datalog command and the Data Collection Setup display allow you to create data
streams. These data streams, however, must include the same test criteria or same
sampling information, and you can send the stream to only a limited number of outputs.
The datastream command and the Datastream Setup window allow you to simultaneously
create multiple data collection streams with different characteristics, such as test criteria,
sampling rates, and limits. You can also send the datastreams to different output
destinations. (See “Controlling Data Collection From a Test Program” on page G8-1 for
more on the differences between streams set up using the datalog and datastream
commands.)
Setting Up a Datastream Using the Datastream Setup Window
The Datastream Setup window (figure 6-13) allows you to generate data-stream commands
in the station window to manage datastream setups. Bring up this window by clicking on the
DATASTREAM... button on the control panel of the Data Collection Setup display.
Figure 6-13. Datastream Setup Window
This window has a scrollable list of all currently active datastream setups at the top (if any
are set up). Only streams set up using the datastream command are listed. (See also
“Showing Current Datastreams” on page 6-56.) This list displays each datastream's output
mode and ID. Datastreams outputting to STDF files have:
STDF:<filename>
IMAGE Solutions V8.3 6-48
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
listed on the right side of the list. Datastreams outputting to external programs have:
PGM:<filename>
listed on the right side of the list. If the datastream uses the default (system) filename, it has
DEFAULT FILE NAME as the filename. To perform operations on a particular setup, select
the setup from the list.
Anytime you open the Datastream Setup window, it displays the current datalog information.
If datalog information changes while the Datastream Setup window is open, however, the
new information is not shown in the display. To update the Datastream Setup window (and
all other open data windows), you must use the menu item SETTINGS>REFRESH DISPLAY
WITH DATA COLLECTION SETTINGS in the Data Collection Setup display. (See “Control Panel
Items” on page 6-15.)
The Datastream Setup window has the following controls:
DATASTREAM ID Identifies a particular datastream. Note that this identifier is not
created or modified in the active datastream setups until you
click on ADD, CHANGE, or DELETE. If you delete a setup from the
list of active setups, you delete the setup whose datastream ID
is currently modified. You are warned if you try to add a stream
when another stream with the same ID exists or try to change a
datastream’s ID to an ID already in use. Changing the
datastream ID of a stream requires that the stream be restarted.
DESTINATION Selects either an STDF file or a program as the destination of the
datastream.
FILE/PROGRAM NAME Specifies the name of the STDF file or program name. If you
specify STDF FILE, you can fill in this line with the name of the
destination file (see “Naming STDF Files” on page 6-19) or leave
it blank to have IMAGE choose the filename. System-generated
filenames do not appear in this field. If you specify PROGRAM as
the destination, fill in this field with the name of the program to
send the datastream data to. If you leave this blank, you get a
default datalog filter, datalogging to a file whose name is based
on the current test program and stream name. IMAGE searches
along the path specified by your $PATH environment variable for
the program to run. You also specify all command-line
arguments to run the program on this line. Fill in the program
name as you would when running the program from the
command line of a shell. Changing the output destination
requires that the stream be restarted for your changes to take
effect.
TEST CRITERIA INTERFACE
Determines which tests are selected for datalog. Standard
options include:
TEST CRITERIA>ALL TESTS
Datalogs all tests. (This is the default.)
IMAGE Solutions V8.3 6-49
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
TEST CRITERIA>PASSED TESTS
Datalogs all passing tests.
TEST CRITERIA>FAILED TESTS
Datalogs all failing tests.
TEST CRITERIA>ALL ANALOG TESTS
Datalog all analog tests.
TEST CRITERIA>PASSED ANALOG TESTS
Datalog all passing analog tests.
TEST CRITERIA>FAILED ANALOG TESTS
Datalog all failing analog tests.
TEST CRITERIA>ALL DIGITAL TESTS
Datalog all digital tests.
TEST CRITERIA>PASSED DIGITAL TESTS
Datalog all passing digital tests.
TEST CRITERIA>FAILED DIGITAL TESTS
Datalog all failing digital tests.
TEST CRITERIA>LIST OF TESTS
Datalog the specified list of tests. The LIST menu includes the
following items:
LIST OF TESTS Datalog only tests entered in LIST: item. (This
is the default list.)
PASSED TESTS + FAILED ON LIST Datalog all passing tests
and any failing tests entered in LIST: item.
FAILED TESTS + PASSED ON LIST Datalog all failing tests
and any passing tests entered in LIST: item.
ANALOG: FROM LIST Datalog only analog tests entered in
LIST: item.
ANALOG: PASSED + LIST Datalog all passing analog tests
and analog tests entered in LIST: item.
ANALOG: FAILED + LIST Datalog all failing analog tests
and analog tests entered in LIST: item.
DIGITAL: FROM LIST Datalog only digital tests entered in
LIST: item.
DIGITAL: PASSED + LIST Datalog all passing digital tests
and digital tests entered in LIST: item.
DIGITAL: FAILED + LIST Datalog all failing digital tests
and digital tests entered in LIST: item.
IMAGE Solutions V8.3 6-50
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
TEST LIST Specifies a list of tests to datalog. This is the LIST OF TESTS
referred to in the CRITERIA item. You can use test names, test
numbers, ranges of test numbers, and sequencer names. See
“Test Selection” on page 6-38 for more information.
EXTENDED TEST CRITERIA INTERFACE
Brings up the Extended Datastream Test Selection window
(Figure 6-14).
Figure 6-14. Extended Datastream Test Selection Window
Current test criteria settings for the data stream are loaded into the TESTS TO DATALOG
scrolling list. You can edit the list with the following setting controls:
ADD Adds a test set to the list. Define test sets with the following
INCLUDE options:
TEST NUMBERS: ALL or TESTS ON LIST
TEST TYPES: ANALOG, DIGITAL, or BOTH
TEST RESULTS: ANALOG, DIGITAL, or BOTH
Only active when there are less than nine test sets defined.
CHANGE Changes a selected test set’s settings to those you’ve specified
in the INCLUDE options. Only active when a test set is selected.
DELETE Removes a selected test set from the list. Only active when a test
set is selected.
Commit changes to datastream test selection by clicking ADD or CHANGE in the Datastream
Setup display (figure 6-13).
SAMPLE RATE Specifies a sampling rate for datalog, how often devices are
datalogged. The default is 1, every device datalogged. (See
“Sampled Datalog” on page 6-47.)
IMAGE Solutions V8.3 6-51
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
SAMPLE LIMIT Specifies a sampling limit for datalog, the total number of devices
to be datalogged. The default is no limit. (See “Sampled Datalog”
on page 6-47.)
MODE Specifies the STDF mode of the datastream. HEAVY specifies
that each test result record (PTR, MPR, or FTR) will contain all
information about a test, including test number, test name and
label, test limits, and test result. In LIGHT mode, much of the
static data for each test, including the limits, is only contained in
the first result record for each test. In Extra-Light (XLIGHT) mode,
the test name and label (test_txt) is also only contained in the
first result record for each test. The lighter the mode, the smaller
the STDF file will be. The default is LIGHT. (See
“tl_set_test_condition_during_lot” on page 26-382 for the side
effects of changing the test conditions during the run of a lot.)
LEAKAGE DATALOG Enables datalogging for HSD50 pin leakage values. Leakage
datalog is output in a special format. (See “Leakage Output
Format” on page 6-43.) Choices are
OFF Leakage tests are included in normal datalog
output.
ALL LEAKAGE TESTS All leakage tests are datalogged with
the values for pins specified by the LEAKAGE PINS option.
FAILING LEAKAGE TESTS Only failing leakage tests are
datalogged with the values for pins specified by the LEAKAGE
PINS option. Passing tests are included in normal datalog output.
LEAKAGE PINS Specifies which pin leakage values to datalog. This option is
active only when leakage datalogging is turned on. Choices are
ALL PINS Values for all pins are included in the datalog
output.
FAILING PINS ONLY Only values for those pins that failed the
leakage limits are included in the datalog output.
ADD Adds a new stream to the list of active datastreams. Change the
current setup (including datastream ID) using the window control
items, then click ADD.
CHANGE Changes the currently selected streams attributes to be the
attributes selected using the previously described controls. To
change a stream, select it and modify the desired items on the
display. Click on CHANGE. Some changes require that the stream
be restarted. You are notified when this is the case and given an
opportunity to go back.
IMAGE Solutions V8.3 6-52
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
NOTE
Be careful when restarting a stream that is outputting to a file. The file may be overwritten
when the stream is restarted.
DELETE Removes a setup from the list of currently active datastream
setups.
NOTE
When using the DELETE button, the setup you select in the list of currently active setups is
removed. If you have modified the datastream ID, the stream ID selected in the list of
currently active setups is be removed, not the modified datastream ID.
RESET Returns information on the controls to be the state of the
currently selected setup before you changed any information on
the display.
To add a new setup:
1. Change the datastream ID to the name of the new setup.
2. Set the other items on the display up to match your output criteria.
3. Click ADD.
You are warned if you try to add a stream when another stream with the same ID exists or
try to change a datastream’s ID to an ID already in use. Changing the datastream ID of a
stream requires that the stream be restarted.
If you change the current setup, the message -- MODIFIED -- appears in the lower right
hand corner of the display.
Setting Up a Datastream Using the datastream Command
The syntax for the datastream command is as follows:
datastream [-on <sid> (outputs) (tests) (samples) (mode) (leakage)]
[-off <sid>] [-show]
[-change <sid> (tests) (samples) (mode) (leakage)]
[-station #] [-wafer_map]
(outputs)= [-stdf] [-stdf_file <stdf filename>]
[-program_name <"program_name arg1 ... argn">]
(includes)= [-include [all | list_file <filename>] [pass | fail]
[analog | digital]]
(tests)= [-test [all | pass | fail] [digital | analog]
[list_file <filename>] [list [#] [# to #]
[<test_name>] [SEQUENCER <seqname>]]]
(samples)= [-samprate #] [-samplimit #]
IMAGE Solutions V8.3 6-53
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
(mode)= [-mode <heavy/light/xlight>]
(leakage)= [-lkg [ off | all | fail] [all_pins | fail_pins]]
where:
on Starts the datastream command processor.
<sid> Is the stream identification (up to 10 alphanumeric characters).
(outputs) Is the stream destination. Can be an STDF file with a default
name or an STDF file that you name (see “Naming STDF Files”
on page 6-19) or the name of a program and its arguments.
(includes) Specifies which test criteria to use.
-include all all tests
-include list <...>
a specific test, or a range of test numbers
-include list_file <filename>
a file containing a list of tests
-include pass passing tests
-include fail failing tests
-include analog analog tests
-include digital digital tests
The digital and analog keywords can be combined with pass,
fail, all, and list. A subset of digital and analog tests will be
datalogged if combined with any of these (except all). You can
use this switch multiple times (up to nine) to specify sets of
criteria.
(tests) Is the test criteria and is required. It can be:
-test all all tests
-test pass passing tests
-test fail failing tests
-test digital digital tests
-test analog analog tests
-test list_file <filename>
tests from a file
-test list # a specific test number
-test list # to # a range of test numbers
-test <test_name> a named test
-test SEQUENCER <seqname>
tests from a specific sequencer
The digital and analog keywords can be combined with pass,
fail, all, and list. A subset of digital and analog tests will be
datalogged if combined with any of these (except all).
The -test switch is obsolete, but it is still supported. Use the
-include switch to specify criteria.
(samples) Is the sampling information. samprate is the sample rate.
samplimit is the sample limit.
IMAGE Solutions V8.3 6-54
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
(mode) Specifies the STDF mode of the datastream. Heavy specifies
that each test result record (PTR, MPR, or FTR) will contain all
the information about a test, including test number, test name
and label, test limits, and test result. In Light mode, much of the
static data for each test, including the limits, is only contained in
the first result record for each test. In Extra-Light (Xlight) mode,
the test name and label (test_txt) is also only contained in the
first result record for each test. The lighter the mode, the smaller
the STDF file will be. (See “tl_set_test_condition_during_lot” on
page 26-382 for the side effects of changing the test conditions
during the run of a lot.)
(leakage) Enables leakage datalogging of HSD50 pins. This is an HSD50
option only. Leakage datalog is output in a special format. (See
“Leakage Output Format” on page 6-43.) The following keywords
can be used:
[off | all | fail]
Either no leakage tests are datalogged, all leakage tests are
datalogged, or only failing leakage tests are datalogged. Leaving
the -lkg switch out of the datalog command also turns datalog
leakage off. The all and fail keywords can be combined with
all_pins and fail_pins.
[all_pins | fail_pins]
Specifies all pin values or only failing pin values are included in
the datalog output. See “Leakage Selection” on page 6-40.
-off Stops the datastream command processor for the specified
datastream or test station.
-show Displays the datastream setup in a station window. See
“Showing Current Datastreams” on page 6-56.
-change <sid> (tests) (samples) (mode) (leakage)
Allows you to modify parts of the datastream setup without
turning off datalog or respecifying the entire datalog setup.
(-change_mode is considered obsolete, but still works to change
modes: Heavy>Light, Light>Heavy, XLight>Heavy.)
-station # Specifies a station number.
-wafer_map Collect X/Y coordinate and binning information for every device
(used in wafer mapping). Use this option with the -samprate #
option. See “Generating Wafer Map Information” on page 6-47.
You can perform the following stream operations:
• Create a stream with a particular set of characteristics
• Change the characteristics of a stream (except the output program which receives the
data)
• Delete a stream
IMAGE Solutions V8.3 6-55
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
When you create a new datastream, you must specify one output selection:
-stdf Output goes to an STDF file with a default system name.
-stdf_file Output goes to an STDF file you name (see “Naming STDF
Files” on page 6-19).
-program_name Output goes to a particular process.
Specifying a Test Data Directory
When the TEST DATA DIRS option (in the PRODUCTION section of the IMAGE Properties
window) is set to some directory, all datastream files are written to this directory. (See
“Production Setup Options” on page 3-37.)
Showing Current Datastreams
The command datastream -show displays all current datastreams in the station window.
This listing shows you all datastream streams set using the datastream command (or the
Datastream Setup window). It also includes all current datastreams set using the datalog
command (or the Data Collection Setup window), the histodisp command, and other data
collection commands. An example is as follows:
smith% datastream -show
Currently Enabled Datastreams
Stream ID: DATALOG (stdf) STDF Output - No PID
Test Criteria: ALL tests
----------------------------------------------------------------------------
Stream ID: dlg_datawin Output Mode: Heavy Process ID: 3903
Name/args: "dlgfmt"
Test Criteria: ALL tests
----------------------------------------------------------------------------
Stream ID: DATALOG (file) Process ID: 3904
Test Criteria: ALL tests
----------------------------------------------------------------------------
Stream ID: HISTOGRAM STDF Output - No PID
Test Criteria: ALL tests
----------------------------------------------------------------------------
Stream ID: new_stream Output Mode: Light STDF Output - No PID
Test Criteria: ALL tests
----------------------------------------------------------------------------
Only the last stream listed here was created using the datastream command. Only this
stream would be shown in the Datastream Setup window.
Controlling Datastreams from a Test Program
IMAGE allows you to control datastreams from within a test program. For more information,
see “tl_add_datastream” on page 26-143, “tl_change_datatastream” on page 26-169,
“tl_get_datastream” on page 26-204, and “tl_remove_datastream” on page 26-340.
IMAGE Solutions V8.3 6-56
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Controlling Datalog From a Test Program
IMAGE includes test program syntax which allows you to control data collection from within
a test program.1 Using this syntax, you can control datalog setups from within a program
using the following test functions:
• tl_set_datalog sets the state of data collection
• tl_change_datalog changes the state of data collection (see “Changing Datalog Setup
Information” on page 6-66)
• tl_add_datalog_output allows you to add an output to data collection (see “Changing
Datalog Output” on page 6-67)
• tl_remove_datalog_output allows you to remove an output from data collection (see
“Changing Datalog Output” on page 6-67)
• tl_get_datalog gets information on the state of data collection (see “Retrieving
Datalog Setup Information” on page 6-68)
These functions take a variable number of arguments. The arguments consist of a list of
flags (represented by macros) which may or may not be followed by values. Some
arguments like TL_DLG_ON and TL_DLG_OFF do not accept values. Others, such as
TL_DLG_TEST, accept an argument, in this case a bit flag containing the test criteria. Any
flag which accepts arguments will accept at most one.
The order in which the macros and values are passed to the function is irrelevant. However,
if a flag requires a value, it must immediately follow the flag. Some of the values can be set
using macros which can be OR’ed together.
Each function reads through the argument list, making sure that each flag requiring a value
has an appropriate value (for example, you did not specify datalog test criteria for
TL_DLG_O_STATWIN). The arguments are then processed to verify that all the necessary
information is present and no conflicting arguments are included (for example, TL_DLG_ON
and TL_DLG_OFF).
tl_set_datalog Syntax
The function tl_set_datalog() sets the state of data collection. You must call
tl_set_datalog() before any tests for the current device are executed. Use this function
in your program before calling the first sequencer.
tl_set_datalog() returns one of three values when called:
0 Error connecting to IMAGE or IMAGE could not process
command.
1 IMAGE acknowledged command and command was successful.
-1 Command failed due to a syntax error.
1. See also “Controlling Data Collection From a Test Program” on page G8-1
IMAGE Solutions V8.3 6-57
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
When the program successfully invokes tl_set_datalog(), the datalog buffer is dumped,
the command is processed, and the datalog command is sent to IMAGE. This ensures no
data is lost.
The syntax is:
err = tl_set_datalog(<macro_parameter_list>, NULL);
Table 6-6 shows the relationship between datalog command parameters and
tl_set_datalog() syntax.
Table 6-6. datalog Command Options and Equivalent tl_set_datalog() Syntax
tl_set_datalog() Syntax
datalog Command
Notes
Parameter Argument
Test Program Macro
Data Type
-on TL_DLG_ON
-off TL_DLG_OFF
<output> TL_DLG_OUTPUT unsigned int Arguments to
bit flag TL_DLG_OUTPUT can be
OR’ed together for multiple
outputs.
-stdf TL_DLG_O_STDF
-stdf_file TL_DLG_STDF_NAME char * Used with or without
TL_DLG_O_STDF.
-statwin TL_DLG_O_STATWIN
-datawin TL_DLG_O_DWIN
-datawin_display TL_DLG_DWIN_DIS char * Used with or without
TL_DLG_O_DWIN. If not used, it
defaults to host and monitor
used by dataserv.
-file TL_DLG_O_FILE
-file <filename> TL_DLG_FILE_NAME char * Used with or without
TL_DLG_O_FILE.
-printer TL_DLG_O_PRINTER Turns on datalogging to the
default printer.
-printer TL_DLG_PRINTER_NAME char * Used with or without
<printername> TL_DLG_O_PRINTER to specify
a printer name.
-pmc TL_DLG_O_PMC
IMAGE Solutions V8.3 6-58
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Table 6-6. datalog Command Options and Equivalent tl_set_datalog() Syntax (Continued)
tl_set_datalog() Syntax
datalog Command
Notes
Parameter Argument
Test Program Macro
Data Type
-pin names TL_DLG_PIN_OUTPUT unsigned int
-pin numbers bit flag
TL_DLG_PIN_NAMES
TL_DLG_PIN_NUMBERS
-format TL_DLG_OUTPUT_FMT char *
-test TL_DLG_TEST unsigned int
bit flag
all TL_DLG_ALL_TEST Arguments can be OR’ed
together to pass one
pass TL_DLG_PASS_TEST
argument, if analog and
fail TL_DLG_FAIL_TEST digital are added.
digital TL_DLG_DIGITAL_TEST
analog TL_DLG_ANALOG_TEST
list TL_DLG_TEST_LIST unsigned Terminated by element
int[n] whose value is 0.
list_file TL_DLG_TEST_FILE char *
list # to # TL_DLG_TEST_RNG int[2n+1] A list of begin/end range value
pairs specifying a set of test
ranges, terminated by test
number 0.
list <name> TL_DLG_TEST_NAME char *
SEQUENCER TL_DLG_SEQ_NAME char *
<name>
-samprate # TL_DLG_SAMP_RATE unsigned int
-samplimit TL_DLG_SAMP_LIMIT unsigned int
IMAGE Solutions V8.3 6-59
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Table 6-6. datalog Command Options and Equivalent tl_set_datalog() Syntax (Continued)
tl_set_datalog() Syntax
datalog Command
Notes
Parameter Argument
Test Program Macro
Data Type
-lkg TL_DLG_LKG_STATE Leakage is off unless
<leakage info> specified.
off TL_DLG_LKG_OFF
all TL_DLG_LKG_ALL This is the default if leakage is
specified.
fail TL_DLG_LKG_FAIL
all_pins TL_DLG_LKG_ALL_PINS This is the default.
fail_pins TL_DLG_LKG_FAIL_PINS
-station No macro.
tl_set_datalog() can be
used only for the station in
which the test program is
loaded.
-wafer_map TL_DLG_WAFER_MAP
Differences Between the datalog Command and tl_set_datalog
The datalog command allows you to specify a filename following the -file flag. When
using the test program function you can specify datalog to a file using the TL_DLG_TEST
followed by TL_DLG_O_FILE argument (which can be OR’ed together when specifying
multiple outputs). The data file name is specified using the macro TL_DLG_FILE_NAM
followed by character string containing the file name.
If you specify TL_DLG_FILE_NAM, specifying DLG_O_FILE for DLG_TEST is optional. That is,
specifying TL_DLG_FILE_NAM automatically enables datalog to a file. This is also true when
specifying the name of the STDF file using TL_DLG_STDF_NAME. This option automatically
enables datalog to STDF without requiring you to specify TL_DLG_O_STDF with DLG_TEST.
Specifying both is acceptable. Also if you specify the Data Window host using
TL_DLG_DWIN_DISP, datalog to the Datalog Output window is automatically selected.
The datalog command allows you to specify several tests or test ranges following the
keyword list. The command has separate macros to deal with test lists and test ranges.
Test lists consist of an array of test numbers terminated by a zero-valued element (test
number 0 is illegal). The input for test ranges is an array of unsigned integer pairs specifying
the start and ending test number for a range. This array is terminated by an element whose
value is zero. However, several ranges can be specified during one invocation of
tl_set_datalog().
IMAGE Solutions V8.3 6-60
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
tl_set_datalog Examples
The following examples compare datalog commands to tl_set_datalog() statements.
The definition of NULL is taken from stdio.h, which is assumed to be included.
• The following outputs all passing tests to the station window and a text file. datalog
command syntax would be:
datalog -on -test all -statwin -file
tl_set_datalog function syntax would be:
tl_set_datalog(TL_DLG_ON, TL_DLG_TEST, TL_DLG_ALL_TEST,
TL_DLG_OUTPUT, TL_DLG_O_STATWIN | TL_DLG_O_FILE, NULL);
• The following outputs test results for tests 1 to 8 to the STDF file Wafer_test_results,
a text file, and the Datalog Output window, where the test both passes and is an analog
test. datalog command syntax would be:
datalog -on -test pass analog list 1 to 8
-stdf_file Wafer_test_results -file -datawin
tl_set_datalog function syntax would be:
tl_set_datalog(TL_DLG_ON, TL_DLG_TEST,
TL_DLG_PASS_TEST | TL_DLG_ANALOG_TEST, TL_DLG_TEST_RNG,
tlist, TL_DLG_OUTPUT, TL_DLG_O_DWIN | TL_DLG_O_FILE,
TL_DLG_STDF_NAME, stdf_filename, NULL)
where:
unsigned int tlist[3] = {1, 8, 0}
char *stdf_filename = "Wafer_test_results"
• The following outputs test results (whether passing or failing) for tests 1 through 5 and
8 through 9 to the station window. Nothing is output to STDF, the Datalog Output
window, or a text file. datalog command syntax would be:
datalog -on -test list 1 to 5 8 to 9 -statwin
tl_set_datalog function syntax would be:
tl_set_datalog(TL_DLG_ON, TL_DLG_TEST_RNG, tlist, TL_DLG_OUTPUT,
TL_DLG_O_STATWIN, NULL);
where:
unsigned int tlist[5] = {1, 5, 8, 9, 0}
• The following outputs test results (whether passing or failing) for tests 1, 5, 9, 11, and
14 to the station window. datalog command syntax would be:
datalog -on -test list 1, 5, 9, 11, 14 -statwin
tl_set_datalog function syntax would be:
tl_set_datalog(TL_DLG_ON, TL_DLG_TEST_LIST, tlist, TL_DLG_OUTPUT,
TL_DLG_O_STATWIN, NULL);
where:
unsigned int tlist[6] = {1, 5, 9, 11, 14, 0}
IMAGE Solutions V8.3 6-61
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Controlling Enhanced Functional Datalog (EFD) from a Test Program
The function tl_set_efd_datalog allows you to set or disable the enhanced functional
datalog from within a test program. It provides the functionality of the datalog command with
the -add_efd, -remove_efd, or -efd_off options.
tl_set_efd_datalog Syntax
tl_set_efd_datalog() returns one of three values:
0 Error connecting to IMAGE or IMAGE could not process
command.
1 IMAGE acknowledged command and command was successful.
-1 Command failed due to a syntax error.
When the program successfully invokes tl_set_efd_datalog(), the datalog buffer is
dumped, the command is processed, and the datalog command is sent to IMAGE. This
ensures no data is lost.
The syntax is:
err = tl_set_efd_datalog(<action>, “<efd_setup_name>“, <macro_parameter_list>,
NULL);
where:
action Specifies the action to take. Legal values are TL_DLG_EFD_ADD
(equivalent to the datalog command’s -add_efd option),
TL_DLG_EFD_REMOVE (equivalent to the -remove_efd option),
and TL_DLG_EFD_OFF (equivalent to the -efd_off option); you
can specify one action at a time.
efd_setup_name Names the EFD setup you want to add or remove. This must be
of type char *.
macro_parameter_list
Specifies the EFD settings you want to implement. The list is in
the format <option>, <argument>, ... (or <option>,
<option>, ... if you specify an option that does not take any
arguments).
To set EFD datalogging options, specify the TL_DLG_EFD_ADD action and set datalogging
options in the macro_parameter_list. You must also specify a name for the EFD setup.
This turns on enhanced functional datalogging. If EFD was enabled, this replaces the
existing EFD setup with the options you specify in the macro_parameter_list.
To remove a setup from the active list, specify the TL_DLG_EFD_REMOVE action. You must
specify a name for the EFD setup you want to remove; do not specify any options for the
macro_parameter_list. Because test programs use only one setup at a time, this has the
effect of turning off enhanced functional datalogging.
IMAGE Solutions V8.3 6-62
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
TL_DLG_EFD_REMOVE removes the EFD setup you name from the list that the EFD Setup
dialog maintains; it has the same functionality as the dialog’s REMOVE button. You can use
this function, either in a test program or in the Immediate Window, to remove a setup from
the EFD dialog. Removing an inactive setup does not affect the current setup.
To turn off enhanced functional datalogging entirely, specify TL_DLG_EFD_OFF and omit the
setup name and all values for the macro_parameter_list. This removes all setups from
the EFD dialog.
Table 6-7 lists EFD-related datalog command parameters and the equivalent
tl_set_efd_datalog() macros.
Table 6-7. EFD Command Options and Equivalent tl_set_efd_datalog() Syntax
tl_set_efd_datalog() Syntax
datalog Command Argument
Test Program Macro Notes
Parameter Data Type
fail_vect TL_DLG_EFD_FAIL_VECT Datalogs failing vectors only
(fail_v)
all_vect (all_v) TL_DLG_EFD_ALL_VECT Datalogs all vectors
num_fail_vect TL_DLG_EFD_NUM_FAIL_VECT unsigned Number of failed vectors to
(num_fv) int capture; default is 1 vector
vect_before_fail TL_DLG_EFD_VECT_BEF_FAIL unsigned Number of vectors to capture
(v_bef_f) int before each failing vector;
default is zero (0) vectors
before failing vector
vect_after_fail TL_DLG_EFD_VECT_AFT_FAIL unsigned Number of vectors to capture
(v_aft_f) int after each failing vector;
default is zero (0) vectors after
failing vector
hram_failmode_on TL_DLG_EFD_HRAM_FM_ON
(hr_fm_on)
hram_failmode_off TL_DLG_EFD_HRAM_FM_OFF
(hr_fm_off)
prog_data_on TL_DLG_EFD_PROG_DATA_ON
(pd_on)
prog_data_off TL_DLG_EFD_PROG_DATA_OFF
(pd_off)
tset_on (ts_on) TL_DLG_EFD_TSET_ON
tset_off (ts_off) TL_DLG_EFD_TSET_OFF
IMAGE Solutions V8.3 6-63
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Table 6-7. EFD Command Options and Equivalent tl_set_efd_datalog() Syntax (Continued)
tl_set_efd_datalog() Syntax
datalog Command Argument
Test Program Macro Notes
Parameter Data Type
fail_pins TL_DLG_EFD_FAIL_PINS Datalogs failing pins only
(fail_p)
all_pins (all_p) TL_DLG_EFD_ALL_PINS Datalogs all pins
pin_list # # # … TL_DLG_EFD_PIN_LIST unsigned Terminated by element whose
int[n] value is 0
pin_list # to # TL_DLG_EFD_PIN_RNG unsigned Terminated by element whose
to int[n] value is 0
-test all TL_DLG_EFD_ALL_FAIL_TEST
-test list # # … TL_DLG_EFD_TEST_LIST unsigned Terminated by element whose
int[n] value is 0
-test list # to # TL_DLG_EFD_TEST_RNG unsigned Terminated by element whose
int[n] value is 0
pin_ord TL_DLG_EFD_PIN_ORD
pat_col_ord TL_DLG_EFD_PAT_COL_ORD
(pc_ord)
pat_col_grp TL_DLG_EFD_PAT_COL_GRP
(pc_grp)
display_radix TL_DLG_EFD_DISP_RADIX Sets the display radix to the
(radix) default
TL_DLG_EFD_RADIX_OCT Sets the display radix to octal
TL_DLG_EFD_RADIX_HEX Sets the display radix to hex
TL_DLG_EFD_RADIX_DEC Sets the display radix to
decimal
TL_DLG_EFD_RADIX_BIN Sets the display radix to binary
TL_DLG_EFD_RADIX_SYM Sets the display radix to
symbolic
The tl_set_efd_datalog function uses the same default settings as the datalog
command. To use a default setting, omit the appropriate macro from the function call. For
example, you can invoke the default EFD setup:
IMAGE Solutions V8.3 6-64
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
datalog -add_efd efd_setup_1 hr_fm_off fail_v fail_p pd_on lpc_on ts_on num_fv
1 v_aft_f 0 v_bef_f 0 in_ord -test all
by specifying an empty parameter list:
tl_set_efd_datalog(TL_DLG_EFD_ADD, “efd_setup_1”, NULL);
Differences Between the datalog Command and tl_set_efd_datalog
The datalog command allows you to specify pin names or pin numbers. For example, the
following two lists are identical:
pin_list RCV22 RCV24 RCV30 RCV40
and
pin_list 22 24 30 40
The tl_set_efd_datalog function accepts only pin numbers in enumerated lists. To
specify this list in the function, you would use the following macro and argument:
err = tl_set_efd_datalog(TL_DLG_EFD_ADD, “efd_setup_1”, TL_DLG_EFD_PIN_LIST,
22, 24, 30, 40, 0, NULL);
The tl_set_efd_datalog function does not support loop counts.
tl_set_efd_datalog Examples
The following examples compare datalog commands to tl_set_datalog() statements.
The definition of NULL is taken from stdio.h, which is assumed to be included.
• To enable enhanced functional datalogging with the default settings and a specific list
of pins, you can use the command:
datalog -add_efd efd_setup_1 hr_fm_off fail_v fail_p pd_on lpc_on ts_on
num_fv 1 v_aft_f 0 v_bef_f 0 pin_ord -test list 2000 to 2003
2006 to 2009
or the function:
tl_set_efd_datalog(TL_DLG_EFD_ADD, “efd_setup_1”, TL_DLG_EFD_TEST_RNG,
tlist, NULL);
where:
unsigned int tlist[5] = { 2000, 2003, 2006, 2009, 0 };
• To run a specific list of tests and capture four failing vectors from any pin, with two
vectors before and one vector after each failure, you can use the command:
datalog -add_efd efd_setup_8 hr_fm_off fail_v all_p pd_on lpc_on ts_on
num_fv 4 v_aft_f 1 v_bef_f 2 pin_ord -test list 200 300 400 500
or the function:
tl_set_efd_datalog(TL_DLG_EFD_ADD, "efd_setup_8", TL_DLG_EFD_FAIL_VECT,
TL_DLG_EFD_NUM_FAIL_VECT, 4, TL_DLG_EFD_VECT_BEF_FAIL,
2, TL_DLG_EFD_VECT_AFT_FAIL, 1, TL_DLG_EFD_TEST_LIST,
tlist, NULL );
where:
IMAGE Solutions V8.3 6-65
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
unsigned int tlist[5] = { 200, 300, 400, 500, 0 };
• To remove a setup named efd_setup_8, you can use the command line:
datalog –remove_efd efd_setup_8
or the function call:
tl_set_efd_datalog(TL_DLG_EFD_REMOVE, “efd_setup_8”, NULL);
• To turn off enhanced functional datalogging, you can use the command line:
datalog –efd_off
or the function call:
tl_set_efd_datalog(TL_DLG_EFD_OFF, NULL);
Changing Datalog Setup Information
The function tl_change_datalog() allows you to modify parts of the datalog setup without
respecifying the entire datalog setup. This function uses some of the same macros used by
tl_set_datalog(), specifically those that specify the setup variables.
tl_change_datalog Syntax
Parameters for tl_change_datalog() are listed in table 6-8.
Table 6-8. tl_change_datalog Parameters
tl_change_datalog() Syntax
Notes
Argument Data
Test Program Macro
Type
TL_DLG_TEST unsigned int bit
flag
TL_DLG_ALL_TEST Arguments can be OR’ed together to pass one
argument, if analog and digital are added.
TL_DLG_PASS_TEST
TL_DLG_FAIL_TEST
TL_DLG_DIGITAL_TEST
TL_DLG_ANALOG_TEST
TL_DLG_TEST_LIST unsigned int[n] Terminated by element whose value is 0.
TL_DLG_TEST_FILE char *
TL_DLG_TEST_RNG int[2n+1] A list of begin/end range value pairs specifying
a set of test ranges, terminated by test number
0.
TL_DLG_TEST_NAME char *
IMAGE Solutions V8.3 6-66
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Table 6-8. tl_change_datalog Parameters (Continued)
tl_change_datalog() Syntax
Notes
Argument Data
Test Program Macro
Type
TL_DLG_SEQ_NAME char *
TL_DLG_SAMP_RATE unsigned int
TL_DLG_SAMP_LIMIT unsigned int
TL_DLG_LKG_STATE Leakage is off unless specified.
TL_DLG_LKG_OFF
TL_DLG_LKG_ALL This is the default if leakage is specified.
TL_DLG_LKG_FAIL
TL_DLG_LKG_ALL_PINS This is the default.
TL_DLG_LKG_FAIL_PINS
No macro. tl_set_datalog() can be used
only for the station in which the test program is
loaded.
TL_DLG_WAFER_MAP
Changing Datalog Output
The functions tl_add_datalog_output() and tl_remove_datalog_output() allow you
to add or remove datalog outputs without respecifying the entire datalog setup. These
functions also use some of the same macros used by tl_set_datalog(), specifically those
that specify the output variables.
tl_add_datalog_output and tl_remove_datalog_output Syntax
Parameters for tl_change_datalog() are listed in table 6-9.
Table 6-9. tl_add and tl_remove_datalog Parameters
tl_add and tl_remove_datalog() Syntax
Notes
Argument Data
Test Program Macro
Type
TL_DLG_OUTPUT unsigned int bit Arguments to TL_DLG_OUTPUT can be OR’ed
flag together for multiple outputs.
IMAGE Solutions V8.3 6-67
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Table 6-9. tl_add and tl_remove_datalog Parameters (Continued)
tl_add and tl_remove_datalog() Syntax
Notes
Argument Data
Test Program Macro
Type
TL_DLG_O_STDF
TL_DLG_STDF_NAME char * Used with or without TL_DLG_O_STDF.
TL_DLG_O_STATWIN
TL_DLG_O_DWIN
TL_DLG_DWIN_DIS char * Used with or without TL_DLG_O_DWIN. If not
used, it defaults to host and monitor used by
dataserv.
TL_DLG_O_FILE
TL_DLG_FILE_NAME char * Used with or without TL_DLG_O_FILE
TL_DLG_O_PRINTER Turns on datalogging to the default printer.
TL_DLG_PRINTER_NAME char * Used with or without TL_DLG_O_PRINTER to
specify a printer name.
TL_DLG_O_PMC
Retrieving Datalog Setup Information
The function tl_get_datalog() reinitializes information on the state of data collection and
can be queried about the program’s datalog state. It uses the same macros used by
tl_set_datalog and provides additional flags. This allows the function to perform many
tasks, including:
• Determining if datalog was set using a test list or range of test numbers
• Determining sequencer names
• Determining if sampled datalog is enabled
• Determining if wafer mapping is selected
tl_get_datalog Syntax
Macros used by tl_get_datalog() are, for the most part, the same as those used by
tl_set_datalog(), with some additions. If you request the test criteria, you can determine
if the criteria includes a test list or range of test numbers, sequencer names, if sample
datalog is enabled, or if wafer mapping is selected. A set of macros is provided to test the
big flag returned. If you determine that a test range or test list was used, you can retrieve
the exact information by a subsequent call of tl_get_datalog() and passing the
IMAGE Solutions V8.3 6-68
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
TL_DLG_TEST_RNG or TL_DLG_TEST_LIST flags with an address of a pointer to unsigned
int.
There are two differences in function argument usage between tl_get_datalog() and
tl_set_datalog() flags. The flag for TL_DLG_TEST can contain more information than was
used to set datalog test criteria. You receive all information used to set datalog but can also
test the flag returned to determine if a test list was being used (this includes a test range),
test names, sequencer names, sampled datalog, and if wafer mapping was used.
If more information is needed (like the exact test list, test names, or sampling criteria) it can
be retrieved by a subsequent function call.
Parameters for tl_get_datalog are listed in table 6-10. Note that TL_DLG_ON and
TL_DLG_OFF are actually return values for TL_DLG_STATE. When these macros are used in
tl_set_datalog(), they can be used alone for brevity. tl_get_datalog() must be
passed pointers to the variable which will store the data.
Table 6-10. tl_get_datalog Parameters
Keyword Data Type Declaration Macros to access
TL_DLG_STATE unsigned int TL_DLG_ON
TL_DLG_OFF
TL_DLG_TEST unsigned int TL_DLG_PASS_TEST
TL_DLG_FAIL_TEST
TL_DLG_ALL_TEST
TL_DLG_ANALOG_TEST
TL_DLG_DIGITAL_TEST
TL_DLG_TEST_LIST_SEL
TL_DLG_TEST_FILE_SEL
TL_DLG_TEST_RNG_SEL
TL_DLG_TEST_NAME_SEL
TL_DLG_SEQ_NAME_SEL
TL_DLG_SAMP_RATE_SEL
TL_DLG_SAMP_LIMIT_SEL
TL_DLG_WAFER_MAP_SEL
IMAGE Solutions V8.3 6-69
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Table 6-10. tl_get_datalog Parameters (Continued)
Keyword Data Type Declaration Macros to access
TL_DLG_OUTPUT unsigned int TL_DLG_O_STATWIN
TL_DLG_O_DWIN
TL_DLG_O_STDF
TL_DLG_O_FILE
TL_DLG_O_HISTO
TL_DLG_O_PRINTER
TL_DLG_O_PMC
TL_DLG_PIN_OUTPUT unsigned int TL_DLG_PIN_NAMES
TL_DLG_PIN_NUMBERS
TL_DLG_TEST_RNG unsigned int *
TL_DLG_TEST_LIST unsigned int *
TL_DLG_TEST_NAME char **
TL_DLG_SEQ_NAME char **
TL_DLG_STDF_NAME char *
TL_DLG_FILE_NAME char *
TL_DLG_SAMP_RATE unsigned int
TL_DLG_SAMP_LIMIT unsigned int
TL_DLG_OUTPUT_FMT char *
tl_get_datalog Examples
The following examples illustrate use of each individual get option. The ... before and after
each option illustrate that more than one option can be requested with every call to
tl_get_datalog().
• TL_DLG_STATE
unsigned int state;
error = tl_get_datalog(TL_DLG_STATE, &state, ...)
if (state & TL_DLG_ON)
printf("Datalog enabled.\n");
else
printf("Datalog disabled.\n");
• TL_DLG_TEST
unsigned int test_crit;
error = tl_get_datalog(...,
IMAGE Solutions V8.3 6-70
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
TL_DLG_TEST, &test_crit,
...,
NULL);
if (!error) {
/* Error Processing */
}
else {
if (test_crit & TL_DLG_ALL_TEST)
printf("Datalog all tests.\n");
else if (test_crit & TL_DLG_FAIL_TEST)
printf("Datalog Failing tests\n");
else if (test_crit & TL_DLG_PASS_TEST)
printf("Datalog Passing tests\n");
if (test_crit & TL_DLG_WAFER_MAP_SEL)
printf("X/Y coords collected for all parts\n");
if (test_crit & TL_DLG_TEST_LIST_SEL)
printf("Datalog test list being used.\n");
if (test_crit & TL_DLG_SAMP_RATE_SEL)
printf("Sample rate has been set.\n");
• TL_DLG_OUTPUT
unsigned int dlg_output;
error = tl_get_datalog(...,
TL_DLG_OUTPUT, &dlg_output,
...,
NULL);
if (!error) {
/* Error Processing */
}
else {
if (dlg_output & TL_DLG_O_STATWIN)
printf("Datalog to station window.\n");
if (dlg_output & TL_DLG_O_DWIN)
printf("Datalog to datalog window.\n");
.
.
.
}
• TL_DLG_TEST_RNG
unsigned int *rngPtr = (unsigned int *) NULL;
error = tl_get_datalog(...,
TL_DLG_TEST_RNG, &rngPtr,
...,
NULL);
if (!error) {
/* Error Processing */
}
else {
while (rngPtr[i]) {
printf("Range start %d Range End %d\n", rngPtr[i++],
IMAGE Solutions V8.3 6-71
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
rngPtr[i++]);
}
}
• TL_DLG_TEST_LIST
unsigned int *listPtr = (unsigned int *) NULL;
error = tl_get_datalog(...,
TL_DLG_TEST_LIST, &listPtr,
...,
NULL);
if (!error) {
/* Error Processing */
}
else {
while (*listPtr) {
printf("Test number is %d\n", *listptr);
listptr++;
}
}
• TL_DLG_TEST_NAME
char ** testNames = (char **) NULL;
error = tl_get_datalog(...,
TL_DLG_TEST_NAME, &testNames,
...,
NULL)
if (!error) {
/* Error Processing */
}
else {
while (testNames[i]) {
printf("Test name is %s.\n", testNames[i]);
.
.
.
i++;
}
}
• TL_DLG_SEQ_NAME
char **seqNames
error = tl_get_datalog(...,
TL_DLG_SEQ_NAME, &seqNames,
...,
NULL);
if (!error) {
/* Error Processing */
}
else {
while (seqNames[i]) {
printf("Sequencer name is %s.\n", seqNames[i]);
.
.
IMAGE Solutions V8.3 6-72
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
.
i++;
}
}
• TL_DLG_STDF_NAME
char *stdf_file = (char *) NULL;
error = tl_get_datalog(...,
TL_DLG_STDF_NAME, &stdf_file,
...,
NULL);
printf("STDF file name %s.\n", stdf_file);
• TL_DLG_FILE_NAME
char *text_file = (char *) NULL
error = tl_get_datalog(...,
TL_DLG_FILE_NAME, &text_file,
...,
NULL);
if (!error) {
/* Error Processing */
}
else
printf("Datalog file name %s.\n", text_file);
Alternatively, you can also first determine if datalog to a file was enabled before
processing the datalog file name.
char *text_file = (char *) NULL
error = tl_get_datalog(...,
TL_DLG_OUTPUT, &dlg_output,
TL_DLG_FILE_NAME, &text_file,
...,
NULL);
if (!error) {
/* Error Processing */
}
else if (dlg_output & TL_DLG_O_FILE)
printf("Datalog file name %s.\n", text_file);
• TL_DLG_SAMP_RATE
unsigned int sample_rate;
error = tl_get_datalog(...,
TL_DLG_SAMP_RATE, &sample_rate,
...,
NULL);
if (!error) {
/* Error Processing */
}
else
printf("Sample rate %d.\n", sample_rate);
Alternatively, you can execute only the sample rate code if the sample rate was set:
IMAGE Solutions V8.3 6-73
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
unsigned int sample_rate;
error = tl_get_datalog(...,
TL_DLG_TEST, &test_crit,
TL_DLG_SAMP_RATE, &sample_rate,
...,
NULL);
if (!error) {
/* Error Processing */
}
else if (test_crit & TL_DLG_SAMP_RATE_SEL) {
printf("Sample rate %d \n", sample_rate);
• TL_DLG_SAMP_LIMIT
unsigned int samp_lim;
error = tl_get_datalog(...,
TL_DLG_SAMP_LIMIT, &samp_lim,
...,
NULL);
if (!error) {
/* Error Processing */
}
else
printf("Sample Limit %d.\n", samp_lim);
• TL_DLG_PIN_OUTPUT
error = tl_get_datalog(...,
TL_DLG_PIN_OUTPUT, &fmt,
...,
NULL);
if (!error) {
/* Error Processing */
}
else
if (fmt & TL_DLG_PIN_NAMES)
printf("Datalog output has pin names.\n");
else
printf("Datalog output has pin numbers.\n");
• TL_DLG_OUTPUT_FMT
char *output_fmt = (char *) NULL;
error = tl_get_datalog(...,
TL_DLG_OUTPUT_FMT, &output_fmt,
...,
NULL);
if (!error) {
/* Error Processing */
}
else
printf("Datalog format used is %s.\n", output_fmt)
IMAGE Solutions V8.3 6-74
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Displaying Datalog information
Once you have set datalog criteria, rather than having to parse through all the information
for a setup, you may only want to display the datalog setup information in the station
window. The function which prints out datalog information for the datalog command can
display information from the test program. The function is called with no arguments and
displays the latest state of datalog information in the test program, as if you had typed
datalog -show from the test program.
Controlling Datalog Sampling
The following functions make it possible for the test program to know if a part will be
datalogged and provide the ability to control when a part will be datalogged. For more
information on how each function works, see “Base IMAGE Functions” on page 26-1.
• tl_get_part_datalogged returns if the current part will be datalogged in the standard
datalog outputs.
• tl_set_part_datalogged sets whether the current part will be datalogged in the
standard datalog streams and must be called before any sequencers are executed.
Additional Methods of Controlling Datalog From a Test Program
In addition to the test program syntax described in“Controlling Datalog From a Test
Program” on page 6-57, several datalog parameters can be controlled from a test program
by other methods. This section describes these methods.
Datalog Format
Use the <datalog format> field of a sequencer line to specify the format for the datalog
output line and the units associated with the test value. (See “Datalogging Program Variable
Values” on page 14-24.) The datalog format string (figure 6-15) is enclosed in double quotes
and has two components:
• A field specification, starting with %, that includes a field width specifier, a precision
modifier, and a conversion character
• A six-character units string. The first character of the units string can be a multiplier
such as u for micro (E-06).
field width specifier (total number of characters printed)
%10.11f sec units string
conversion character
precision modifier
(digits after the decimal point)
Figure 6-15. Datalog Format String
IMAGE Solutions V8.3 6-75
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Here are some sample datalog formats:
"%6.2f mvolts" Units of volts, scale factor of milli
"%5.2f kHz" Units of hertz, scale factor of kilo
"%10.2f sec" Units of seconds, scale factor of unity (factor unspecified)
The field specification used in the first example ("%6.2f") specifies the test result format.
The field-width specifier (6) describes the total number of characters of the result to be
printed. The precision modifier (.2) describes how many decimal places of the result should
be printed. The conversion character (f) specifies conversion of a float or double variable
to decimal.
If no datalog format string is specified on the sequencer line, the compiler uses a fixed-point
format with two digits to the right of the decimal point.
For a discussion of conversion specifications, see “printf()” on page 16-4. Scale multipliers
are discussed under “Units” on page 13-17.
Datalogging Program Variables
You can use datalog reports to maintain a record of test program variable values. Write
these variable values to the datalog stream with a datalog statement such as:
datalog foo $702;
(See “Datalogging Program Variable Values” on page 14-24.)
The appearance of program variables on a datalog report is controlled by the test selection
mechanism in the following way:
• When a datalog statement appears inside a test, the value appears on the report if that
test is datalogged.
• When a datalog statement appears outside a test function, the value appears on the
report only if all tests are being datalogged.
• If it is specifically requested by number, the result appears.
Datalogging Text Strings
You can send text messages of up to 256 characters to the datalog stream using the
lprintf() function in a test program. (See “Writing Text to a Datalog Report” on page
14-24.) An example using the lprintf() function is:
lprintf("ISOURCE: over value at %d\n",isrcov);
The text string is printed on the datalog report if the test in which it is generated is
datalogged. If the lprintf() call is not in a test, a string for that test only appears on the
report if all tests are selected to be datalogged.
Two additional functions allow you to write a formatted string of characters to a datalog
report. They are:
Lprintf() Print a formatted string to the datalog report regardless of
datalog mode.
IMAGE Solutions V8.3 6-76
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Mprintf() Print a formatted string to the datalog report regardless of
datalog mode or binning status.
Writing an EPS Record for Failing Tests
In versions of IMAGE before V5.6, if a test fails or a run-time error occurs, an End Program
Section Record (EPS) is not generated for the failing sequencer. In V5.6 and later, you can
optionally modify this behavior and have an EPS record written to the datalog stream.
To datalog an EPS record, call the function tl_datalog_endseq_on_fail() and pass it a
nonzero value. To turn this feature off, call the same function with an argument whose value
is zero. (See “tl_datalog_endseq_on_fail” on page 26-175.)
By default IMAGE will not datalog an EPS record when a test fails or encounters a run-time
error.
Integer Overflow Format
The overflow value of integers when using decimal or hexadecimal format is represented in
datalog output as unsigned. This allows datalogging to values between 2,147,483,647 and
4,294,967,295.
An option in the IMAGE Behavior Chooser, dec_overflow_is_uint, allows you to change
integer overflow output to signed. Setting this option to disable reports all values greater
than INT_MAX as INT_MAX. This is the behavior before V6.0.
Setting dec_overflow_is_uint to enable reports results in the range of INT_MAX to
UINT_MAX as the actual value. Results greater than UINT_MAX are reported as UINT_MAX.
This is the default behavior.
Note that this applies only to values not scaled when stored in the datalog. Scaled values
such as 2.147483647+e9 are stored differently than straight integer values and do not reach
the integer overflow limit.
Additional Methods for Retrieving Datalog Setup Information in a Test
Program
In addition to using tl_get_datalog() (see “Retrieving Datalog Setup Information” on
page 6-68), you can use other methods to make specific data collection setup information
available to the test program. A set of functions, described in this section, allows you to
retrieve information regarding the specific setup of a particular data collection stream,
datalog or datastream, the directory a specific file is being written to, or the default datalog
directory. These functions complement other data collection query functions in the test
program.
The key function is tl_update_data_collection_state(), which retrieves the current
data collection setup information from the dataserv process on the user computer. Once
this function is called and the datalog state updated, information can be retrieved using
query functions which access this state information. The set of functions is listed below with
IMAGE Solutions V8.3 6-77
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
a brief explanation of what each function does. For more information, see “Base IMAGE
Functions” on page 26-1.
Retrieving Data Collection Information
Retrieve the current data collection setup using the function:
int tl_update_data_collection_state(void)
None of the other functions described in this section operate properly unless this function is
called first. If streams are changed after calling this function, it must be called again,
otherwise the setup information will be obsolete.
The function returns 0 if the setup information could not be obtained. This may indicate that
the process which stores the data collection information was busy. If the function returns 0,
try waiting several seconds and call the function again.
Retrieving Data Collection Stream Names
Retrieve an array of names of data collection streams enabled using the function:
char **tl_get_data_collection_streams(void)
Each element of the returned array will be a pointer to a character string containing the
name of a datalog stream.
Standard datalog streams can be identified using the following macros:
TL_DATALOG_STATWIN Datalog output to station window.
TL_DATALOG_DATAWIN Datalog output to Datalog Output window.
TL_DATALOG_STDF Datalog output to STDF file.
TL_DATALOG_FILE Datalog output to text file.
TL_HISTOGRAMMING Datalog output to .histo (histogram) file.
These macros represent strings, so strcmp() must be used to identify the streams. See the
example below for the exact syntax.
There are no predefined macros for datastream stream IDs, as there are no predefined
streams for them. If a stream does not match any of the above macros, it can be assumed
to be a datastream.
To use this function you must declare a variable to be of type pointer to pointer of type char
(for example, char **some_variable_name;) and use it in the following fashion:
char **dataCollectionStreams = (char **) NULL;
dataCollectionStreams = tl_get_data_collection_streams();
You need not manage the memory used returned by the function; it is managed by the
function itself. Do not free this memory.
IMAGE Solutions V8.3 6-78
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Retrieving Data Collection Stream Setup State
Retrieve data collection stream setup criteria using the function:
int tl_get_stream_criteria(char *streamName,
struct tl_tlist_element **list, int *numListElements)
This function returns the data collection setup state (such as pass, fail, or all), for the stream
streamName, by function return and any test list information through the second argument.
The test criteria for all datalog streams must be the same. Retrieving the test criteria for one
datalog stream retrieves the test criteria for all datalog streams.
Datastream streams, on the other hand, can have different criteria and each stream may be
different. Criteria for datastreams must be retrieved individually by stream.
The following macros can be used to determine the test criteria being used:
TL_NOTEXIST No data collection streams.
TL_PASS Stream datalogging passing tests.
TL_FAIL Stream datalogging failing tests.
TL_ALL Stream datalogging all tests.
TL_PASSANALOG Stream datalogging passing analog tests.
TL_FAILANALOG Stream datalogging failing analog tests.
TL_PASSDIGITAL Stream datalogging passing digital tests.
TL_FAILDIGITAL Stream datalogging failing digital tests.
If test lists are enabled for a particular data collection stream, the number of streams is
returned through the argument list in numListElements.
If numListElements is nonzero (that is, a test list has been used), an array of test list
elements is returned. This array can be examined to determine which tests have been
selected in the list. A test list element looks like:
enum tl_setup_type {TL_TEST_NUM, TL_TEST_RANGE, TL_TEST_NAME,
TL_SEQ_NAME};
struct tl_tlist_element {
enum tl_setup_type type;
unsigned int test_num, last_test;
char name[TL_MAXNAME+1];
};
If the type field is set to TL_TEST_NUM, the test_num field is set to the test number.
Retrieving Data Collection Stream Sample Information
Retrieve data collection stream sample information using the function:
int tl_get_stream_sample_info(char *streamName, int *sampleRate,
int *sampleLimit)
IMAGE Solutions V8.3 6-79
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
This function returns the sample rate and limit for the stream identified by streamName.
Retrieving Data Collection Stream Filename
Retrieve data collection stream filename using the function:
char *tl_get_stream_filename(char *streamName)
This function returns the name of the file that stream streamName is writing. If the filename
returned is not a full path, it is being written to the default datalog directory.
Retrieving Datalog Directory
Retrieve datalog directory using the function:
char *tl_get_datalog_directory(int update)
This function returns the name of the directory where datalog files are written by default. It
automatically checks to see if the directory was previously set. If it was not set, the function
sends a command to dataserv to get the directory. Otherwise, it returns the cached
directory name. If the value of the argument is nonzero, it forces the directory name to be
updated.
Retrieving Data Collection Stream Directory
Retrieve data collection stream directory using the function:
char *tl_get_datalog_directory_for_stream(char *streamName)
This function returns the name of the directory where data collection stream streamName is
writing its data. If the stream is not writing a file, it returns NULL.
Programming Example
The following program excerpt shows a possible use of the datalog functions.
main()
{
int sampRate = 0,
sampLimit = 0,
tlistCount = 0;
char *sname = (char *) NULL,
**stream = (char **) NULL,
*streamFileName = (char *) NULL,
*streamDLdir = (char *) NULL;
/* Get the current data collection state from the dataserv process.
If there is some error in retrieving this information the function
will return 0. */
if (!tl_update_data_collection_state()) {
printf("Error updating data collection state.\n");
IMAGE Solutions V8.3 6-80
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
exit(1);
}
/* Retrieve an array of pointers to the names of each datalog stream
currently enabled. The data collection functions take care of
managing all of the memory used for the list so it isn't necessary
to allocate or free any memory. */
stream = tl_get_data_collection_streams();
printf("Default Datalog Directory: '%s'\n", tl_get_datalog_directory(1));
while (*stream) {
switch (tl_get_stream_criteria(*stream, &lptr, &tlistCount)) {
case TL_NOTEXIST: printf("Existing stream %s doesn't exist.\n",
*stream);
break;
case TL_PASS: printf("'%s' enabled for Passing tests.\n", *stream);
break;
case TL_FAIL: printf("'%s' enabled for Failing tests.\n", *stream);
break;
case TL_ALL: printf("'%s' enabled for All tests.\n", *stream);
break;
case TL_PASSANALOG:
printf("'%s' enabled for passing analogtests.\n", *stream);
break;
case TL_FAILANALOG:
printf("'%s' enabled for failing analog tests.\n", *stream);
break;
case TL_PASSDIGITAL:
printf("'%s' enabled passing digital tests.\n", *stream);
break;
case TL_FAILDIGITAL:
printf("'%s' enabled passing digital tests.\n", *stream);
break;
}; /* end switch */
/* * Print the test list information, if it exists. */
while (tlistCount--) {
switch (lptr->type) {
case TL_TEST_NUM:
printf("Test Number: '%d'\n", lptr->test_num);
break;
case TL_TEST_RANGE:
printf("Test Range: '%d' to '%d'\n",
lptr->test_num, lptr->last_test);
break;
IMAGE Solutions V8.3 6-81
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
case TL_TEST_NAME:
printf("Test Name: '%s'\n", lptr->name);
break;
case TL_SEQ_NAME:
printf("Sequencer: '%s'\n", lptr->name);
}
lptr++;
}
if (tl_get_stream_sample_info(*stream, &sampRate, &sampLimit)) {
printf("Sample rate: %d\n", sampRate);
printf("Sample limit: %d\n", sampLimit);
}
else
printf("'%s' does not exist.\n", *stream);
if (streamFileName = tl_get_stream_filename(*stream))
printf("'%s' writing file: '%s'\n", *stream, streamFileName);
else
printf("'%s' NOT writing a file\n", *stream);
if (streamDLdir = tl_get_datalog_directory_for_stream(*stream))
printf("'%s' datalogging to: '%s'\n", *stream, streamDLdir);
else
printf("'%s' Not datalogging to any directory.\n", *stream);
stream++;
} /* end while */
seq1();
sort bin;
}
Custom Datalog Filters
You can make custom datalog filters for writing customized datalog text files. See
$IMAGEBIN/custom/dl_filters for information on creating custom datalog filters for your
use. (You can also create custom summary filters. See “Setting Summary Checkpoint
Frequency” on page 6-104.)
IMAGE provides several filter programs for writing datalog text files using existing STDF
files as input. You can run any of these filters as a standalone program to create datalog
text files from STDF files and display the datalog in the window or send it to a text file. The
filters in $IMAGEBIN are as follows:
• dlgfmt generates a datalog file with the test number, label, and result
• fulldlgfmt generates a datalog file displaying the test name, number, label, results,
and limits; also used as two-line format for EFD
• efddlgfmt generates a one-line format for EFD
IMAGE Solutions V8.3 6-82
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Command Line Filter Syntax
The general syntax for these filters is as follows:
<filter> [ -file <filename> ] [ -pins_per_line # ]
[ -no_pin_space ] [ -full_pin_names ]
[ -no_wrap ] [ -channels_on ] [ -channels_off ]
[ -usage ] < <stdf_file_name>
where:
<filter> Is the filter you want to use (dlgfmt, fulldlgfmt, or
efddlgfmt).
-file Specifies the path and file name of the output file.
-pins_per_line Specifies the number of pins or channels on each line of the
datalog. Corresponds to the PINS PER LINE field in the EFD
graphical setup.
-no_pin_space Minimizes the space between pins in a pin list. Corresponds to
the SPACE BETWEEN PINS field in the EFD graphical setup.
-full_pin_names Shows full pin names (which are normally truncated at six
characters). Corresponds to a value of OFF in the TRUNCATE PIN
NAMES field in the EFD graphical setup.
-no_wrap Displays output on one line. Corresponds to a value of OFF in the
WRAP OUTPUT field in the EFD graphical setup.
-channels_on | -channels_off
Specifies whether channel numbers are displayed in the datalog.
Corresponds to the CHANNELS field in the EFD graphical setup.
-usage Displays a summary of the filter command line options.
<stdf_file_name> Is the path and file name of the input STDF file.
For more information on the options in the EFD graphical setup, see “Datalog Format Items”
on page 6-22.
Command Line Filter Examples
To generate a datalog report from an STDF file showing only test labels, enter the following
command in the window:
dlgfmt [-file <filename>] < some_stdf_file
For example, to generate a datalog report from an STDF file named test.stdf and send
it to a station window, type the following in the window:
dlgfmt < test.stdf
To generate a full datalog report from an STDF file, type the following command in the
window that you want the datalog report to appear:
IMAGE Solutions V8.3 6-83
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
fulldlgfmt [-file <filename>] < some_stdf_file
For example, the following command generates a full datalog report from an STDF file
named test.stdf and sends it to the station window:
fulldlgfmt < test.stdf
The following command generates the same full datalog report from an STDF file named
test.stdf and sends it to a text file named datalog_file.data:
fulldlgfmt -file datalog_file.data < test.stdf
Monitoring Disk Space During Datalog
Datalog over long periods can fill up a storage disk. This can easily happen if you are using
an automatic handler or prober or automatic looping commands, all of which can produce
large amounts of data. If testing continues when the datalog disk is full, you lose data and
must retest your devices.
To help you manage datalog data, IMAGE includes a disk monitor feature. When you turn
this feature on, IMAGE checks all disks that test stations are datalogging to, stops the
stations when the disks are almost full, and displays a window with a warning message that
you must dismiss before you can continue (figure 6-16). A header in the window tells you
which station is affected.
When the amount of available space on a disk a test station is datalogging to reaches a
preset level or a level you specify in a setup file, the disk monitor tries to stop looping and
handler polls for any test station datalogging to that disk. When disk space reaches this limit
the disk monitor window appears with this status message:
ATTEMPTING TO STOP AUTOMATIC RUNNING
The disk monitor continues to try to stop the test station until it is successful. If you try to
dismiss the window while the disk monitor is trying to stop the test station, IMAGE issues a
warning.
After the disk monitor stops the test station, the warning message in the window displays
this status:
AUTOMATIC RUNNING STOPPED
IMAGE Solutions V8.3 6-84
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Figure 6-16. Disk Monitor Window
The message area of the window displays suggestions on what you should do. (You can
change this text. See “Changing Disk Monitor Window Text” on page 6-88.) The window
footer displays error messages with handler status on the left and looping status on the right.
While the warning window is displayed, you can still type commands in the test station
window, and you can restart the test program. However, the disk monitor will stop the test
station if the amount of free space on the disk is at or below the limit.
NOTE
After the disk monitor stops a test window and you have cleared enough disk space to
continue, you must dismiss the warning window before using the test station. The disk
monitor will not allow further test program runs unless you dismiss this window.
You can specify the amount of disk space remaining and the frequency that disks are
checked before the disk monitor stops a test station by changing or creating the contents of
the diskmon_config file (see “Specifying the Disk Space Limit and Sampling Rate” on page
6-86). You can also change the warning message that appears in the window by editing or
creating the file image_disk_warning (see “Changing Disk Monitor Window Text” on page
6-88).
Using the Disk Monitor
To use the disk monitor, type the diskmon command in any window. The syntax is:
diskmon [-on] [-off] [-show] [-usage] [-reinit]
where:
IMAGE Solutions V8.3 6-85
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
-on Turns the disk monitor on. You will see a message that the
monitor has started.
-off Turns the disk monitor off. You will see a message that the
monitor has stopped.
-show Displays all the active files and the current limits for disk
checking.
-usage Prints a usage message showing all parameters.
-reinit Reinitializes the disk monitor checking parameters (the limit and
sampling information). You will see a message that the monitor
has started. (See “Reinitializing the Disk Monitor” on page 6-87.)
The command diskmon -show displays whether the disk monitor is active and a list of all
active stations and their active file. The following is an example:
Total # of Active Files: 0 Total # of Active File Systems: 0
Checking Against Limit of 5120 KB remaining disk space
Checking Period Range: 5 Seconds to 40 Seconds
Specifying the Disk Space Limit and Sampling Rate
The diskmon_config file specifies the disk space limit and the sampling rate for the disk
monitor. When you start the disk monitor, it reads this file to determine how often it should
check active disks and when it should stop a test station. You can use the default file in
$IMAGEBIN/custom or create your own file and put it in the directory from which the disk
monitor is started. The default file specifies a disk limit of 10 megabytes or 5 percent of the
total disk space and a sampling rate of 5 to 40 seconds.
The disk monitor searches for the file in the following order and uses the first file found:
• The directory from which the disk monitor is started
• /image/<tester_name> directory
• $IMAGEBIN/custom directory
A diskmon_config file contains two lines:
limit: <disk_limit> [KB | MB | PERCENT | %]
sample: <lower_limit> <upper_limit>
where:
disk_limit Is an integer and is the minimum amount of free disk space that
must remain on the disk before the disk monitor stops the test
station. Specify this value in kilobytes (KB), megabytes (MB), or
percentage of the total disk space (PERCENT or %). It must be
greater than 10 megabytes or 5%. The default is 10 megabytes
or 5%.
sample Is the sampling rate, the rate at which the disk monitor checks all
disks being datalogged to. It can vary between the lower_limit
and upper_limit. The disk monitor checks disks more often
IMAGE Solutions V8.3 6-86
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
(lower_limit) when the disk is closer to the limit (disk_limit).
Use higher sample rates for devices with longer test times.
lower_limit Is an integer and is the lower bound of the time between
samples. This is the shortest time (in seconds) between disk
checks. Minimum is 3 seconds, maximum is 20 seconds, and the
default is 5 seconds.
upper_limit Is an integer and is the upper bound of the time between
samples. This is the longest time (in seconds) between disk
checks. Minimum is 30 seconds, maximum is 60 seconds, and
the default is 40 seconds.
Some sample diskmon_config files are shown below. Upper case or lower case letters are
accepted.
limit: 5 Mb /* set limit to 5120KB remaining disk space */
Sample: 5 20 /* set sample rate to vary from 5 to 20 sec */
LIMIT 5000KB /* set limit to 5120KB remaining disk space */
sample: 10 40 /* set sample rate to vary from 10 to 40 sec*/
Limit: 20% /* set limit to 20% remaining disk space */
SAMPLE: 3 60 /* set sample rate to vary from 3 to 60 sec*/
The disk monitor works more efficiently if you pass a worst-case estimate of the amount of
datalog to it by using the function:
tl_set_datalog_disk_usage(<integer number of KB/second>)
Put this function in the tl_init section of your test program. The worst-case estimate is a
quantity expressed as the number of kilobytes per second the test station will datalog to a
disk. Compute the worst case by setting up the datalog for the maximum amount of output
and running the test program with the device, then dividing the size of the datalog by the
runtime. Supplying the worst-case estimate is optional since the disk monitor normally uses
the default values in the diskmon_config file.
Reinitializing the Disk Monitor
Once you start the disk monitor, it runs in the background and monitors all datalog to any
disks. It continues to run using the disk space limit and sampling rate you have set until you
turn it off or exit IMAGE.
After you start the disk monitor, you may decide to change the disk space limit, the sampling
rate, or both. To change these parameters you must edit the diskmon_config file and
reinitialize the disk monitor to use the new checking parameters. Otherwise, the disk
monitor continues to use the old parameters.
To reinitialize the disk monitor to use new checking parameters, use:
diskmon -reinit
IMAGE Solutions V8.3 6-87
IMAGE Base Language: Data Collection: Datalog Reports
Table of Contents Index Home Master Index Search Help
Changing Disk Monitor Window Text
You can change the warning message in the disk monitor window using the file
image_disk_warning. This file contains the text displayed when the disk monitor stops a
test station. The file can contain anything you wish, but only the first 1000 characters are
displayed in the warning message. The default file is in the $IMAGEBIN/custom directory.
IMAGE searches for the file in the same order as it does for the configuration file and uses
the first file found:
• The directory from which the disk monitor is started
• /image/<tester_name> directory
• $IMAGEBIN/custom directory
IMAGE Solutions V8.3 6-88
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Summary Reports
A summary report provides a summary of the status of a device lot during or after testing. It
includes information on the number of devices tested, the number of devices sorted into
each bin, the number of executions for each test, and the failing percentage for each test.
IMAGE provides three types of summary reports:
• A partial summary is a report of a device lot before the completion of testing the lot.
• A final summary (figure 6-17) shows information for an entire lot of devices after testing
is complete.
• An accumulated summary shows summary information for two or more lots.
The basic summary mechanism in IMAGE is always active while a test program is loaded.
Unlike datalog, you need not turn it on.
Parts of a Summary
A summary report is composed of several parts:
• The summary header at the top of the report lists the lot, the operator, the time of
testing and other details. You can set some of these items using IMAGE commands.
(See “Organizing Test Data” on page 6-3.)
• The bin totals show the number of devices placed in the bins you have defined and the
percentage in each bin. Hardware bins (also called handler bins) are bins that
correspond to physical bins in a handler. Software bins are additional bins that you set
up that do not exist on the handler or prober you are using. (See “Assigning Bin
Numbers” on page 15-6.)
• The test summary shows the number of times each test in the test program was
executed and the number and percentage of failures.
Summary bin and fail counts are cleared when a test program is first loaded and at the
beginning of each lot. They are updated after each device is tested.
A device lot is closed when a device handler or prober or the Start Switch sends an endlot
signal to the tester, or when you a request a final summary report. Requesting a final
summary clears the bin and failure counters, resets the device number, and increments the
lot number.
Generating Summary Reports
You can generate summary reports using the SUMMARY button on the Data Collection Setup
display or using the summary and setauto commands in a station window or by pressing
the END LOT button on the Start Switch. You can also accumulate summary results over
several lots using the accsum command.
IMAGE Solutions V8.3 6-89
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Final SUMMARY Mon Jan 29 14:20:23 1990
Lot: xyz111
Sublot:
Started at: Mon Jan 29 14:19:56 1990
Program: cd1711
Version:
Part Type:
Operator: casper
Station Number: 1
Station Mode: E
Tester Type: A500
Node Name: mom5
Executive: IMAGE V3.0 012990
Test Code: R7J
Retest Code:
Handler or Prober:
DIB Type:
DIB ID: 0
SOFTWARE BIN TOTALS
Bin Total % Bin Total % Bin Total %
--- ----- ----- --- ----- ----- --- ----- -----
0 57 58.2 2 19 19.4 3 10 10.2
6 1 1.0 20 6 6.1 60 5 5.1
HARDWARE BIN TOTALS
Bin Total % Bin Total % Bin Total %
--- ----- ----- --- ----- ----- --- ----- -----
0 57 58.2 2 19 19.4 3 10 10.2
6 1 1.0 20 6 6.1 60 5 5.1
Total number of devices binned = 98
------ Test ------ Total ---- Failures ----
Number Name Execs. Total %/Part %/Exe
---------------------------------------------------------------
10 leak_vcc 98 67 68.37 68.37
Mean: 0.0000 Std. Dev: 0.0000
Sigma 1s: 0.0000 3s: 0.0000 6s: 0.0000
20 lcap_vcc 41 19 19.39 46.34
Mean: 0.0000 Std. Dev: 0.0000
Sigma 1s: 0.0000 3s: 0.0000 6s: 0.0000
30 ac_rip 29 24 24.49 82.76
Mean: 0.0000 Std. Dev: 0.0000
Sigma 1s: 0.0000 3s: 0.0000 6s: 0.0000
40 sig_amp 19 0 0.00 0.00
Mean: 0.0000 Std. Dev: 0.0000
Sigma 1s: 0.0000 3s: 0.0000 6s: 0.0000
Cp/CPK 1s: 7 Sigma 1s: 0.0101 3s: 0.0303 6s: 0.0607
Figure 6-17. Final Summary Report
IMAGE Solutions V8.3 6-90
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Using the Data Collection Setup Display
The SUMMARY button in the control region of the Data Collection Setup display (see figure
6-3 on page 6-14) sends a partial device test summary of the current (or previous) lot to the
station window when you click SELECT on it. (Click SELECT on the DATA button to display
this window.) Press MENU on SUMMARY to display a menu with the following choices:
PARTIAL SUMMARY TO STATION WINDOW
Sends a summary of datalog results to this point to the station
window. (This is the default.)
FINAL SUMMARY TO STATION WINDOW
Sends a final summary to the station window.
PARTIAL SUMMARY TO TEXT FILE
Sends a partial summary to a test file.
FINAL SUMMARY TO TEXT FILE
Sends a final summary to a test file.
SUMMARY FROM PREVIOUS LOT
Sends a final summary from the previous lot to the station
window.
SET SUMMARY CHECKPOINT FREQUENCY...
Specifies the number of devices to test before writing summary
information to a backup file. When you select this item, the
Summary checkpoint setup window appears. Enter a number in
the CHECKPOINT FREQUENCY field and click SELECT on APPLY.
See “Setting Summary Checkpoint Frequency” on page 6-104.
If you choose to send a partial or final summary to a text file, a file of the following form is
created:
node_station#_<test_program>_<lot_id>_timestamp.summary
Using the summary Command
You can also generate and display a summary of the current lot using the summary
command. The syntax for using the summary command is:
summary [-station #] [-filter <filter_name>] [-file]
[-smy_checkpoint #] [-smry_fname <file_name>] [-stdf_on | -stdf_off]
[-sites | -merged] [-site_recs | -no_site_recs] [-fail_tests_only]
[-all_tests] [-accum | -auto | -final | -partial | -prev] [-no_lot_incr]
where:
-station # Specifies a station number to display the summary.
-filter <filter_name>
Formats the summary report using a filter. Use dlgfmt for a
partial summary and fulldlgfmt for a final summary.
IMAGE Solutions V8.3 6-91
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
-file Sends any summary, except a final summary, to a file. For
example, partial summaries are sent to a file using this option.
-smy_checkpoint # Specifies the number of devices to test before writing summary
information to a backup file. (See “Setting Summary Checkpoint
Frequency” on page 6-104.)
-smry_fname <file_name>
Specifies the summary file name for accumulated or previous
summary. Not usable for final summaries.
-stdf_on Reverses the action of -stdf_off and allows IMAGE to create
summary STDF files.
-stdf_off Disables creation of an STDF file for summary records only.
Summary records are still written to any open STDF files. This
option disables summary STDF file creation for all summaries,
including automatic summaries, until re-enabled using
-stdf_on.
-sites Generates a site-specific summary, plus a combined summary
for all the sites. (The combined summary is the standard merged
summary.)
-merged Generates only the merged summary, the default unless
modified in the IMAGE Properties window under Datalog/
Summary Options (see “Setting IMAGE Properties” on page
3-34).
-site_recs Generates site-specific summary records plus the combined site
records. (See “Setting Up the Summary Site Data Mode” on
page 6-102.)
-no_site_recs Generates only the combined site records. Site-specific
summary records are not generated. Do not use this switch with
other summary commands. For example, if -no_site_recs is
chosen, you cannot generate site specific summaries with the
-sites switch because none of the records required for site-
specific summaries will be in the information stream. (See
“Setting Up the Summary Site Data Mode” on page 6-102.)
-fail_tests_only Includes only failed tests in a summary report. You can also set
IMAGE to include only failed tests using the Datalog/summary
options in IMAGE Properties window. (See “Datalog/Summary
Options” on page 3-38.) You can use this parameter to override
the setting in the Properties window. This option does not affect
how data is collected.
-all_tests Includes all tests in a summary report. You can set IMAGE to
include only failed tests using the Datalog/summary options in
IMAGE Properties window. (See “Datalog/Summary Options” on
page 3-38.) You can use this parameter to override the setting in
IMAGE Solutions V8.3 6-92
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
the Properties window. This option does not affect how data is
collected.
-accum Generates and displays an accumulated summary for all full
device lots tested since the accumulation counters were
enabled. (See “Setting Up Accumulated Summary Reports” on
page 6-100.)
-auto Sends an auto endlot and generates a .summary file. Cannot be
used with -prev or -accum switches. (See “Automatic Summary
Reports Using the setauto Command” on page 6-96)
-final Generates and displays a final summary report. This switch also
closes the device lot, clears all counters, resets the device
number, and increments the lot number.
-partial Generates and displays a partial summary report.
-prev Displays the final summary of the last full lot tested. This is useful
if the last final summary report is lost after beginning to test the
next device lot.
-no_lot_incr Disables automatic increment of lot or sublot number at the end
of a lot when you specify -final. Can be used only with -final
or -auto.
Summary reports generated using the summary command are sent to a station window
(except for summary -auto, which is sent to a file). To send reports elsewhere, use Solaris
redirection operators (> and |). For example, to send a final summary report to a line printer
use:
summary -final | lpr
Controlling Summary From a Test Program Using tl_summary
You can generate a summary report from a test program by using the tl_summary()
function. This function can be used in place of a tl_system() call to invoke the summary
command.
tl_summary Syntax
The tl_summary controls the summary from a test program. Arguments used by
tl_summary can be unsigned integer flags or character strings. Terminate the entire
argument list by NULL. The syntax is:
int tl_summary (unsigned int key …)
tl_summary() returns one of two values when called:
0 Failure: An error occurred because of conflicting parameters or
connection to the data server was not possible
1 Success: Summary set up
IMAGE Solutions V8.3 6-93
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Arguments and parameters accepted by this function correspond to some of the parameters
and values accepted by the summary command. For example, the ACCUM argument
corresponds to the –accum parameter for the summary command.
This function is designed to accept a variable number of arguments (listed in table 6-11).
The two types of arguments are:
flags Indicate an on or off state for a particular parameter or that value
is being provided as the next argument. These correspond to
flag values for the summary command.
values These arguments are values for a particular parameter and must
immediately follow the parameter (flag) being used.
Table 6-11. tl_summary Parameters
summary command
Parameter Argument Data Type
equivalent
ACCUM flag summary –accum
SMRY_FNAME char * summary –smry_fname
tl_summary Example
The following is an example of the tl_summary command. To print an accumulated
summary to a file, use the following syntax:
err = tl_summary(ACCUM, SMRY_FNAME, “my_accum_summary”, NULL);
Generating Automatic Summary Reports
Because device lots can be ended automatically by an endlot signal from a handler or
prober, IMAGE has an automatic summary feature which lets you preselect a destination
for the final summary report when a lot is automatically ended, usually by a handler or
prober.
You can set up automatic summaries either from the Data Collection Setup display using
the Auto-Summary Setup window or using the setauto command.
Auto-Summary Setup Window
The Auto-Summary Setup window (figure 6-18) allows you to set up the outputs for
automatic summaries generated when a lot ends. Bring up this window by choosing AUTO-
SUMMARY SETUP... from the SUMMARY menu in the Data Collection Setup display.
IMAGE Solutions V8.3 6-94
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Figure 6-18. Auto-Summary Setup Window
Anytime you open the Auto-Summary Setup window, it displays the current datalog
information. If datalog information changes while the Auto-Summary Setup window is open,
however, the new information is not shown in the display. To update the Auto-Summary
Setup window (and all other open data windows), you must use the menu item
SETTINGS>REFRESH DISPLAY WITH DATA COLLECTION SETTINGS in the Data Collection Setup
display. (See “Control Panel Items” on page 6-15.)
The Auto-Summary Setup window includes the following items:
AUTO SUMMARY TO: STATION WINDOW
Sends the auto-summary to the station window.
AUTO SUMMARY TO: STDF FILE
Sends the auto-summary to an STDF file.
AUTO SUMMARY TO: TEXT FILE
Sends the auto-summary to a text file.
AUTO SUMMARY TO: LINE PRINTER
Sends the auto-summary to a printer. This is the default output.
NEW STDF FILE You cannot specify an STDF file name as IMAGE will try to
attach the summary information to the current STDF file output.
If you select an STDF as an output, you can set this control to
YES, and IMAGE tries to create a new STDF file if none exists. If
a current STDF file exists and you select YES, you end up with
two identical files. The default is YES. This item is grayed out
(inactive) if STDF is not selected as an output.
IMAGE Solutions V8.3 6-95
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
TEXT FILE NAME Specifies the name of a text file for output. Leaving this blank
causes IMAGE to select a default file name. This item is grayed
out (inactive) if a text file is not selected as an output.
PRINTER NAME Specifies a printer name for output. Leaving this blank causes
IMAGE to select the default printer.
TESTS Specifies ALL TESTS or FAILED TESTS ONLY. Selecting FAILED
TESTS ONLY produces a summary that only contains information
on devices that failed. The default is ALL TESTS.
SITE SPECIFIC SUMMARYSpecifies whether or not to generate a site-specific summary in
addition to the standard combined (merged) summary. (See
“Setting Up the Summary Site Data Mode” on page 6-102.)
FORMATTER Specifies STANDARD FORMATTER (SUMFMT) or CUSTOM
FORMATTER. The default is SUMFMT.
CUSTOM FORMATTER Specifies the name of a custom formatter. IMAGE searches for
this formatter using your current $PATH environment variable.
(See “Custom Summary Filters” on page 6-103.)
APPLY This button puts the current setup into effect.
RESET This button reverts to the previous setup (the setup before you
made any changes).
If you change the current setup, the message -- MODIFIED -- appears in the lower right
hand corner of the display.
To turn off automatic summaries, make sure no outputs are selected.
Automatic Summary Reports Using the setauto Command
You can set up automatic summaries from a station window using the setauto command.
The syntax for setauto is:
setauto [-statwin] [-stdf] [-file [<file_name>]] [-lpr] [all_tests]
[-fail_tests_only] [-sites | -merged] [-stdf_on | -stdf_off]
[-autosum_off] [-show] [-format <program_name>] [-station #]
[-printer <printer_name>]
where:
-statwin Generates a final summary and sends it to a station window.
-stdf Generates a summary and send sit an STDF file. (See “Standard
Test Data Format” on page 24-1.)
-file [<file_name>]
Generates a final summary and sends it to the specified file. If
you omit the filename, IMAGE generates a file name.
-lpr Generates a final summary and sends it to the standard printer.
IMAGE Solutions V8.3 6-96
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
-all_tests Includes all tests in a summary report. You can set IMAGE to
include only failed tests using the Datalog/summary options in
IMAGE Properties window. (See “Datalog/Summary Options” on
page 3-38.) You can use this parameter to override the setting in
the Properties window. This option does not affect how data is
collected.
-fail_tests_only Includes only failed tests in a summary report. You can also set
IMAGE to include only failed tests using the Datalog/Summary
Options in IMAGE Properties window. (See “Datalog/Summary
Options” on page 3-38.) You can use this parameter to override
the setting in the Properties window. This option does not affect
how data is collected.
-sites Generates a site-specific summary, plus a combined summary
for all the sites. (The combined summary is the standard merged
summary.)
-merged Generates only the merged summary, the default unless
modified in the Auto-Summary Setup window (see figure 6-18 on
page 6-95).
-stdf_on Reverses the action of -stdf_off and allows IMAGE to create
summary STDF files.
-stdf_off Disables creation of an STDF file for summary records only.
Summary records are still written to open STDF files. This option
disables summary STDF file creation for all summaries,
including those created using the summary command
processor, until re-enabled using -stdf_on.
-autosum_off Completely disables generation of automatic summaries. Most
useful if many summaries are being generated during
engineering or debugging and if the summaries are not useful.
-show Displays the current destination and format for automatic
summaries in a station window. The default destination is the
standard printer and an STDF file. The default format program is
sumfmt.
-format <program_name>
Formats the summary report using a filter. The standard IMAGE
format name is sumfmt. You can also enter a custom formatter
name, and IMAGE searches for this name in $PATH. This option
requires that you specify a destination. If you do not, you get an
error message. (See “Custom Summary Filters” on page 6-103.)
-printer <printer_name>
Specifies an alternate printer to send the summary to.
-station # Specifies a station number to display the summary.
IMAGE Solutions V8.3 6-97
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
A final summary has four possible destinations: the station window, an STDF file, a text file,
and a printer. You can select any or all of these options.
When using the -lpr option, you can select an alternate printer for the summary sheet
using the -printer option. For example, the following command sends a summary report
to the station window and a laser writer (printer lw):
setauto -statwin -lpr -printer lw
The automatic summary feature is also useful for generating multiple final summary reports
when a lot is ended by an operator. To do this, you can use the command summary -auto
to generate an endlot report from the keyboard. When you issue this command, the display
shows:
Auto Endlot Occurred on station #<n> at <date and time>
Controlling Summary From a Test Program Using tl_set_autosummary
You can use the function tl_set_autosummary() to control setup of autosummaries from
a test program. You can use this function to control automatic summaries rather than using
a tl_system() call to invoke the setauto command.
If IMAGE is busy this function waits until IMAGE is free to accept commands. This is usually
due to IMAGE processing data from the previous test program run or the command
processor having established a connection.
tl_set_autosummary Syntax
The tl_set_autosummary controls the summary from a test program. You can use a
variable number of arguments, generally in pairs of the form:
<flag, argument>
Arguments can be unsigned integer flags or character strings. Terminate the entire
argument list by NULL. The syntax is:
int tl_set_autosummary (unsigned int key ...)
tl_set_autosummary() returns one of two values when called:
0 Failure—An error occurred because of conflicting parameters or
connection to the data server was not possible.
1 Success—Auto-summary set up.
Arguments and parameters accepted by this function correspond to the parameters and
values accepted by the setauto command. For example the FILE argument corresponds
to the -file parameter for setauto.
This function is designed to accept a variable number of arguments (listed in table 6-12).
The two types of arguments are:
IMAGE Solutions V8.3 6-98
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
flags Indicate an on or off state for a particular parameter or that a
value is being provided as the next argument. These correspond
to flag values for the setauto command.
values These arguments are values for a particular parameter and must
immediately follow the parameter (flag) being used.
Table 6-12. tl_set_autosummary Parameters
Parameter Argument Data Type setauto Command Equivalent
SETAUTO_STATWIN flag setauto -statwin
SETAUTO_STDF flag setauto -stdf
SETAUTO_STDF_OFF flag setauto -stdf_off
SETAUTO_FILE flag setauto -file
SETAUTO_FILE_NAME char * setauto -file <name>
SETAUTO_PRINTER flag setauto -lpr
SETAUTO_PRINTER_NAME char * setauto -printer <name>
SETAUTO_SMY_FORMATTER char * setauto -format <fmt>
SETAUTO_AUTOSUM_OFF flag setauto -autosum_off
SETAUTO_FAIL_TESTS_ONLY flag setauto -fail_tests_only
SETAUTO_ALL_TESTS flag setauto -all_tests
Like the setauto command, whenever this function is called it sets the auto-summary setup
to whatever criteria was used in the most recent call of the function. The AUTOSUM_OFF flag
cannot be used with any other parameter. It must be used alone. Example:
tl_set_autosummary(AUTOSUM_OFF, NULL);
The FAIL_TESTS_ONLY and ALL_TESTS flags cannot be used at the same time, that is, in
the same invocation of tl_set_autosummary.
Beyond these two exceptions there are no restrictions on the use of arguments. The
SMY_FORMATTER applies to formatted (ASCII) outputs (these are FILE, STATWIN, and
PRINTER).
tl_set_autosummary Examples
The following are examples of the tl_set_autosummary command.
To turn autosummary to the station window, file, and printer using printer speedy and
summary formatting process, my_formatter use:
IMAGE Solutions V8.3 6-99
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
err = tl_set_autosummary(SETAUTO_FILE,SETAUTO_STATWIN,
SETAUTO_PRINTER_NAME, "speedy",
SETAUTO_SMY_FORMATTER, "my_formatter", NULL);
Note that since the printer name for the summary is being specified, it is unnecessary to use
the SETAUTO_LPR argument.
To enable autosummary to an ASCII file called my_ascii_file and to the default line
printer, for failing tests only use:
err = tl_set_autosummary(SETAUTO_FILE_NAME, "my_ascii_file", SETAUTO_LPR,
SETAUTO_FAIL_TESTS_ONLY,NULL);
Again, note that since the name of the ASCII file for the summary is being specified, there
is no need to also use the SETAUTO_FILE parameter.
Setting Up Accumulated Summary Reports
You can accumulate summary information over two or more device lots by activating the
summary accumulation counters. You can do this either from the Data Collection Setup
display or using the accsum command.
The SUMMARY button menu in the Data Collection Setup display includes the menu item
ACCUMULATE SUMMARIES. Pull right on this item to display the following submenu:
ENABLE COUNTERS Enables summary accumulation counters.
CLEAR COUNTERS Clears summary accumulation counters.
CLEAR & DISABLE COUNTERS
Clears the summary accumulation counters, stops accumulated
summary collection, and reports the current accumulated
summary.
You can use the accsum command in a station window. It has the following syntax:
accsum [-enable | -disable | -clear] [-station #]
where:
-enable | -disable enable enables summary accumulation counters. disable
stops accumulated summary collection and reports the current
accumulated summary.
-clear Clears summary accumulation counters.
-station # Specifies a station number to display the summary.
Once enabled, summary data is updated and saved each time a device lot ends. The first
update of the counters occurs on the first final summary following the accsum -enable
command.
IMAGE Solutions V8.3 6-100
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Controlling Accumulated Summary From a Test Program Using
tl_set_accsum
Use the function tl_set_accsum() to control the setup of accumulated summaries from a
test program. You can use it to control accumulated summaries rather than using a
tl_system() call to invoke the accsum command.
tl_set_accsum Syntax
The tl_set_accsum controls the accumulated summary report from a test program. You
can use the following arguments of type unsigned integer. The argument does not need to
be terminated by NULL. The syntax is:
int tl_set_accsum (unsigned int key)
tl_set_accsum() returns one of two values:
0 Failure: An error occurred because of conflicting parameters or
connection to the data server was not possible
1 Success: Summary set up
Arguments and parameters accepted by this function correspond to some of the parameters
and values accepted by the accsum command. For example, the SMY_ASUME argument
corresponds to the -enable parameter for the summary command.
This function is designed to accept a variable number of arguments (listed in table 6-13).
The two types of arguments are:
flags Indicate an on or off state for a particular parameter or that value
is being provided as the next argument. These correspond to
flag values for the summary command.
values These arguments are values for a particular parameter and must
immediately follow the parameter (flag) being used.
Table 6-13. tl_set_accsum Parameters
Parameter Argument Data Type summary command equivalent
SMY_ASUME flag accsum -enable
SMY_ASUMD flag accsum -disable
SMY_ASUMC flag accsum -clear
tl_set_accsum Example
The following is an example of the tl_set_accsum command. To enable the accumulated
summary counters, use the following syntax:
err = tl_set_accsum(SMY_ASUME);
IMAGE Solutions V8.3 6-101
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Setting Up the Summary Site Data Mode
IMAGE supports a summary datalogging mode in which individual statistics for each site
can be reported. You can determine whether or not site-specific summary records appear
in the datalog and summary streams by using the switches -site_recs or -no_site_recs
to the summary command or by pressing MENU on the SUMMARY button in the Data
Collection Setup display and selecting SUMMARY SITE DATA MODE... (see figure 6-19).
Figure 6-19. Summary Site Data Mode Window
INCLUDE MULTI-SITE RECORDS, like the -site_recs switch, generates site-specific summary
records in addition to the IMAGE standard combined site records.
MERGED DATA RECORDS ONLY, like the -no_site_recs switch, generates only the
combined site records. Once set, all future summary generation will be affected by which
mode has been chosen.
For example, if MERGED DATA RECORDS ONLY is chosen, you cannot generate site-specific
summaries by using the -sites switch to the summary or setauto commands because
none of the records required for site-specific summaries will be in the information stream.
Specifying a Test Data Directory
Summary and summary STDF files go to the directory (local or remote) specified by
DATALOGGING TO FILE OPTIONS in the PRODUCTION SETUP category of IMAGE Properties.
(This option also sends all datalog, data collection, datalog, STDF, histogram, and
datastream files to the same directory. See “Production Setup Options” on page 3-37.) You
can specify only a single directory for storing summary files. If you do not set this default
directory, files go to the directory from which the test program was loaded.
You can use environment variables when specifying the names of directories or portions of
directories. For example, specifying TEST DATA DIRS as $HOME/data would place all datalog
files in the subdirectory data of the user’s home directory.
You can override writing files to TEST DATA DIRS by specifying the full path name when
turning on each form of data collection. For example, to override the default for summary
files, you can use:
setauto -file /u/other_directory/file.summary
IMAGE Solutions V8.3 6-102
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
This writes file.summary to the directory /u/other_directory, regardless of whether
test data directories have been specified or not.
Summary Report Format
Summary reports are formatted by a program that reads STDF summary records and
formats and prints the actual summary text. The -filter switch for the summary command
and the -format switch for the setauto command allow you to specify an alternative
program to use in formatting the report. You can use the Teradyne-supplied default format
sumfmt to produce the report (except in the case of automatic summaries to STDF files).
Custom Summary Filters for STDF Data
You can make custom summary filters for writing summary text files using a filter program
that takes existing STDF files as input. You can run this filter as a stand-alone program to
create summary text files from STDF files and display the summary in the window or to a
text file. The filter is named sumfmt and is in the $IMAGEBIN directory. See
$IMAGEBIN/custom/sum_filters/README for information on creating custom summary
filters.
To generate a summary from an STDF file named test.stdf, type the following command
in a window:
sumfmt [-file <filename>] < test.stdf
For example, the following command generates a summary and sends it to the window:
sumfmt < test.stdf
The following command generates a summary and sends it to a file named summary.data:
sumfmt -file summary.data < test.stdf
The summary filter also accepts a flag and integer value, which acts as a Boolean, called
-fail_tests_only. You can display only failing tests using the command:
sumfmt -fail_tests_only 1 < some_stdf_file.stdf
Custom Summary Filters
You can change the format of the summary reports printed at the end of the test program
by editing the file $IMAGEBIN/custom/sum_filters/summary_format.c. After editing this
file, save it under a different name, such as summary_custom, in the sum_filters directory.
Then compile and link the file by typing:
make summary_custom
To test the custom summary report, load a test program in a test station, run the test
program, and type the following command in the station window:
summary -station # -filter $IMAGEBIN/custom/sum_filters/summary_custom
IMAGE Solutions V8.3 6-103
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
where # is the number of the station window in which the test program was run. See
$IMAGEBIN/custom/sum_filters/README for more information on creating custom
summary filters.
Setting Summary Checkpoint Frequency
IMAGE allows you to save all summary information for a current lot under test as well as
any STDF files being written to in the event of a power failure. This feature lets you
determine a frequency of backing up to a disk file the summary information stored in
$IMAGEBIN/dataserv. The frequency specifies the number of devices to test before writing
summary information to the backup file.
After the “nth” part is tested, IMAGE creates a summary backup file if none exists, or moves
the previous backup file to a save file (overwriting any previous save file with the same
name) and then writes the stored summary information to the backup file. Therefore, you
will always have two copies of saved summary information, one more recent than the other.
The summary file is an STDF file with a .summary_stdf file extension. Older saved
summary files have a .summary_stdf% extension. You can create summaries by
redirecting the saved summary file into the summary filter, sumfmt, using the following
command:
sumfmt < savedfilename.summary_stdf
You can back up summary information at any time. More frequent backups, however,
degrade the performance of data collection, and possibly the tester, due to the increased
overhead of manipulating summary data.
To set the frequency, bring up the Data Collection Setup display and press MENU on the
SUMMARY button. Choose SET SUMMARY CHECKPOINT FREQUENCY from the menu and the
Summary checkpoint setup window appears (figure 6-20). Insert the frequency number you
want and click on OK. In figure 6-20, summary information is backed up after every 100
devices is tested.
Figure 6-20. Summary Checkpoint Setup Window
You can also set checkpoint frequency from a station window using the command summary
-smy_checkpoint #. (See “Using the summary Command” on page 6-91.)
IMAGE Solutions V8.3 6-104
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Merging STDF Files
Since you can create more than one STDF file for a particular lot of devices, you may wish
to merge STDF files into one file representing the entire lot, in a way that reflects the final
file if the lot were tested in its entirety. Use the following command to do this:
stdf_merge <stdffile> [stdffile2] -o <output_file>
where:
stdffile Specifies the first STDF file to merge. If you do not specify a
second file, this file is repaired. The repair process removes any
incomplete device information.
stdffile2 Specifies the second file to merge. Used to merge two STDF
files.
output_file Specifies the name of the output file. This is required.
When invoked, this utility preprocesses each STDF file provided, looking for test description
records (a Parametric Test Result Record or Functional Test Result Record) in each file. If
it finds a test number that is parametric in one STDF file and functional in the other, a
warning is displayed and no merging occurs. In this preprocess step, appropriate records
(such as the hardware and software bin records and test synopsis records) are merged. If
limits change or statistical information (mean or standard deviation) changes for respective
tests from one STDF file to the other, they are marked as invalid in the merged STDF file.
This command does not attempt to merge the Master Information Records (MIRs) from
each of the STDF files. It uses the MIR from the first input file. The two STDF files are
assumed to represent two halves of a lot and, as such, the MIR from the first half is used.
When two STDF files are being merged, the utility renumbers devices from the second file
to sequentially follow the first.
For information on STDF files, see “Standard Test Data Format” on page 24-1.
Writing Text From a Test Program to a Summary Report
A test program can send a text string to summary output. You can use this text string to
highlight special conditions. Send the text string to the summary using the smprintf()
function. (See “Writing to a Summary Report” on page 14-25.) The string cannot exceed 256
characters. If multiple strings are written, only the last one received appears on the report.
Summary Statistics
Summaries can include statistical information about each test, including the mean, standard
deviation, (one, three, and six) sigma values, Cp, and Cpk. This option can be used with
datalog enabled or disabled.
Cp and Cpk are indices used to measure process capability.
IMAGE Solutions V8.3 6-105
IMAGE Base Language: Data Collection: Summary Reports
Table of Contents Index Home Master Index Search Help
Cp is the specification width divided by the process width. For example, if Cp = 1.0, the
process width equals the specification width. If Cp = 2, the process specification width is
twice the process width. Cp does not take into account any noncentering of process relative
to the specification limits.
Cpk includes noncentering of process relative to specification limits. For example, a process
may have a Cp = 2, but if the center of this distribution (the mean) is not centered on the
target value (or the center of distribution), Cpk is < Cp. If the process is perfectly centered,
Cp = Cpk.
Calculation for Cp or Cpk requires that both upper and lower test program limits be present
and remain constant during execution of the program. If either limit is not specified, Cp or
Cpk is not calculated. If the program changes either limit during a particular lot, the
calculation for Cp or Cpk is invalidated and not printed. No message is printed on the
summary sheet informing you of this, and Cp or Cpk simply vanishes.
Statistical information can be calculated and displayed on the summary sheet at the
beginning of a lot using the startlot -fullstats on command. This command enables
statistics at the start of a particular lot. Use the command startlot -fullstats off to
disable statistics at the start of a particular lot.
If a test has one result or no result, no statistics are printed because the statistics are
meaningless. No warning message is printed.
IMAGE Solutions V8.3 6-106
IMAGE Base Language: Data Collection: Device Interface Board and Probe Card Information in Datalog
Table of Contents Index Home Master Index Search Help
Device Interface Board and Probe Card Information in
Datalog
Prior to IMAGE V6.4, device interface board (DIB) and probe card information was reported
and stored in IMAGE in an inconsistent manner. V6.4 and later provides a more accurate
method for handling DIB and probe card information. In some cases, particularly where
external software is dependent on having the DIB and probe card information stored in the
STDF file in the older, previous location and format, you may want to disable this new
feature.
To do this, use the IMAGE Behavior Chooser to disable accurate_eeprom_strings. Do
one of the following:
• Add the string -behavior accurate_eeprom_strings disable to your .load file
• Add the string -behavior accurate_eeprom_strings disable to the load
command:
load <file>.tl -behavior accurate_eeprom_strings disable
• Add the string -behavior accurate_eeprom_strings disable to the file
.image_behavior in your home directory ($HOME), the tester-specific directory
(/image/tester/<hostname>), or the site directory ($IMAGEBIN/custom).
Only do this in rare cases where it is necessary, as a temporary patch until the third-party
software can be modified to match this newer method of information storage.
accurate_eeprom_strings
The two possible values for accurate_eeprom_strings are enable and disable. In
IMAGE V6.4 and later, the default value is enable. This option allows you to choose
whether to use the older, previous definitions for certain datalog fields in IMAGE or the
newer, more accurate and consistent definitions now available.
Regardless of how this option is set, you can use the functions
tl_read_and_set_dib_info() and tl_read_and_set_prb_info() to get the new
behavior. The IMAGE Behavior Chooser option setting (enable or disable) only affects the
behavior of the older functions tl_write_dib_id_to_stdf() and
tl_read_probe_card(), which you should no longer use unless you want the older
behavior.
When accurate_eeprom_strings is enabled, the following fields can be set:
Table 6-14. V6.4 STDF Fields
Internal Field Name STDF Field Name Labeled As (in Reports)
dib_typ SDR.dib_typ DIB Type
dib_id SDR.dib_id DIB ID
prb_typ SDR.card_typ Probe Card Type
IMAGE Solutions V8.3 6-107
IMAGE Base Language: Data Collection: Device Interface Board and Probe Card Information in Datalog
Table of Contents Index Home Master Index Search Help
Table 6-14. V6.4 STDF Fields (Continued)
Internal Field Name STDF Field Name Labeled As (in Reports)
prb_card SDR.card_id Probe Card ID
The functions set the following variables:
Table 6-15. Variables Set by New Functions
Sets These
This Function From This Format
Variables
tl_read_and_set_dib_info() dib_typ DIB Type Formatted ASCII
dib_id DIB ID ASCII string
tl_read_and_set_prb_info() prb_typ Probe Card Type Formatted ASCII
prb_card Probe Card ID ASCII string
Formatted ASCII for the dib_typ and prb_typ fields can be selected by using one of two
parameters in the call to tl_read_and_set_dib_info() or
tl_read_and_set_prb_info():
Parameter Format
EEPROM_LONG_STRING 876-543-21 (5445 [TE]) 9701-B.P1
EEPROM_SHORT_STRING 87654321
In this example, the Board Type is 876-543-21, the Company ID is 5445, which is ASCII for
TE (Teradyne’s company ID), the Revision Code date is 9701, and the Artwork Revision
Code is B.P1.
For compatibility, the following functions work as described below:
Function Will Call
tl_write_dib_id_to_stdf() tl_read_and_set_dib_info(EEPROM_LONG_STRING)
tl_read_probe_card() tl_read_and_set_prb_info(EEPROM_LONG_STRING)
All four variables, dib_typ, dib_id, prb_typ, and prb_card, are available for display in
showlot, the Station Monitor (statmon), and summary reports.
When accurate_eeprom_strings is disabled, the fields are set as in IMAGE versions
before V6.4:
Table 6-16. Previous STDF Fields
Internal Field Name STDF Field Name Labelled As (in Reports)
dib_typ SDR.dib_typ DIB ID
IMAGE Solutions V8.3 6-108
IMAGE Base Language: Data Collection: Device Interface Board and Probe Card Information in Datalog
Table of Contents Index Home Master Index Search Help
Table 6-16. Previous STDF Fields (Continued)
Internal Field Name STDF Field Name Labelled As (in Reports)
prb_typ SDR.card_typ Probe Card Type
prb_card SDR.card_id Probe Card ID
Table 6-17. Variables Set by Previous Functions
Sets This
This Function From This Format
Variable
tl_write_dib_id_to_stdf() dib_typ DIB ID decimal
tl_read_probe_card() prb_card DIB ID decimal
In addition, the functions tl_set_dib_id() and tl_get_dib_id() return an error code
when accurate_eeprom_strings is disabled.
Only DIB ID is available for display in showlot, the Station Monitor, and summary reports,
and, in some cases, may be displayed as DIB Type.
Handling Global Variables
In IMAGE V6.4 and later, the following four IMAGE variables are not changed in name, only
in use:
tl_dib_typ[]
tl_dib_id[]
tl_prb_typ[]
tl_prb_card[]
The following four STDF Site Description Record (SDR) fields are still called:
dib_typ[] /* DIB board type */
dib_id[] /* DIB board ID */
card_typ[] /* Probe card type */
card_id[] /* Probe card ID */
The jobplan_status_info structure now includes the following character strings:
dib_id[]
dib_typ[] (V6.4 and later)
card_typ[] (V6.4 and later)
card_id[] (V6.4 and later)
IMAGE Solutions V8.3 6-109
IMAGE Base Language: Data Collection: Device Interface Board and Probe Card Information in Datalog
Table of Contents Index Home Master Index Search Help
Setting Global Variables
Each of the four global variables has a tl_set function that you can use to set the variables
directly:
tl_set_dib_typ()
tl_set_dib_id()
tl_set_prb_typ()
tl_set_prb_card()
NOTE
These functions can only be called before the first sequencer starts. If called after, no set is
done, an error is returned, and an error message is generated.
The function tl_read_and_set_dib_info() sets tl_dib_typ[] and tl_dib_id[]
together, and the function tl_read_and_set_prb_info() sets tl_prb_typ[] and
tl_prb_card[] together. These functions set the global variables from the hardware and
return a status code. Each takes an input argument of SHORT_FORM_DIB_TYP or
LONG_FORM_DIB_TYP (the default). They function differently for different test-head types.
Table 6-18. Variables Settings According to Test-Head Type
Test Head
tl_dib_typ[ ] / tl_prb_typ[ ] tl_dib_id[ ] / tl_prb_card[ ]
Type
ADV_LINEAR, 876-543-21 (5445[TE]) YYWW-R.A SSSSSSS
ADV_MIXSIG, (Board Type; Company ID1;Revision
(Serial number from
CATALYST, Code;
EEPROM or NULL String (“”)
TIGER Artwork Revision Code, from
if it can’t be read)
EEPROM)
[or 87654321 if SHORT_FORM_DIB_TYP
specified or 0 if it can’t be read]
MIXSIG DIB Type: 0 - 511 (from jumpers): NULL String (“”)
Teradyne’s ID >= 256
Probe Card Type: 0
LINEAR 0 NULL String (“”)
On a simulator, or on a tester if testing has already begun, the functions will do nothing
and return an error status.
1. The Company Code is stored (and published) as four hex bytes, and Teradyne’s code is 5445.
(This also represents the ASCII code for TE.)
Reading and Storing Global Variables
Four functions are available to read the variables directly:
IMAGE Solutions V8.3 6-110
IMAGE Base Language: Data Collection: Device Interface Board and Probe Card Information in Datalog
Table of Contents Index Home Master Index Search Help
tl_get_dib_typ()
tl_get_dib_id()
tl_get_prb_typ()
tl_get_prb_card()
Each of the four global variables is stored in the Site Description Record (SDR) in the
following location:
tl_dib_typ[] --> SDR.dib_typ[]
tl_dib_id[] --> SDR.dib_id[]
tl_prb_typ[] --> SDR.card_typ[]
tl_prb_card[] --> SDR.card_id[]
Displaying Global Variables
The showlot command (see “Displaying Lot Information” on page 6-11) and the standard
IMAGE format (sumfmt) program now have four fields. The values are read from:
DIB Type: SDR.dib_typ[] <==NEW
DIB ID: SDR.dib_id[]
Probe Card Type: SDR.card_typ[] <==NEW
Probe Card ID: SDR.card_id[] <==NEW
The Station Monitor can display the following information:
DIB Type: <==NEW
DIB ID:
Probe Card Type: <==NEW
Probe Card ID: <==NEW
IMAGE Solutions V8.3 6-111
IMAGE Base Language: Data Collection: Real Time Yield Trend Monitor
Table of Contents Index Home Master Index Search Help
Real Time Yield Trend Monitor
The Real Time Yield Trend Monitor (figure 6-21) provides a graphical indicator showing test
yield. Two axes make up the yield chart. The X axis represents the number of devices,
wafers, or lots tested, and the Y axis represents the percentage yield. The percentage yield
is shown as device, bin, or test yield.
Figure 6-21. Yield Trend Monitor
You can connect up to two Real Time Yield Trend Monitors to a single station window and
have up to eight yield charts displayed on each monitor. Each chart is individually set up
with respect to the data shown on the X and Y axes. You control the layout of the chart by
indicating what you want displayed horizontally and vertically.
IMAGE Solutions V8.3 6-112
IMAGE Base Language: Data Collection: Real Time Yield Trend Monitor
Table of Contents Index Home Master Index Search Help
Opening the Yield Trend Monitor Window
Open the Yield Trend Monitor by selecting REAL TIME YIELD MONITOR... from the DATA menu
or by entering the yielddisp command in a station window. This command has the
following syntax:
yielddisp [-load <filename>] [-station #] [-devices #]
[-xaxis [device | wafer | lot]] [-cells #]
[-yaxis [device | [hbin | sbin] | test] [-ymax #] [-ymin #]
[-bin [# # #]] [-test [# # #]]
where:
-load <filename> Specifies the setup file to load.
-station Selects the station number to which the Yield Trend Monitor is
connected.
-devices Specifies the number of devices per cell.
-xaxis Selects the item to use on the X axis. Choices are
device, wafer, and lot.
-cells Specifies the number of cells to display on the X axis.
-yaxis Selects the yield to show on the Y axis. Choices are
device, hbin (hard bin), sbin (soft bin), and test.
-ymax Specifies the Y axis high limit.
-ymin Specifies the Y axis low limit.
-bin Specifies the bin list to use with -yaxis bin.
-test Specifies the test list to use with -yaxis test.
Control Panel Items
The Yield Trend Monitor window control panel includes the following items:
FILE Loads a setup file. Click SELECT to load a file. Press MENU to
select one of the following options:
LOAD SETUP... Brings up the Yield Display Load Setup
Window. (See “Yield Display Load Setup Window” on page
6-115.)
SAVE SETUP... Brings up the Yield Display Save Setup
Window. (See “Yield Display Save Setup Window” on page
6-115.)
PROPERTIES... Brings up the Yield Display Properties
window. (See “Yield Display Properties Window” on page 6-115.)
IMAGE Solutions V8.3 6-113
IMAGE Base Language: Data Collection: Real Time Yield Trend Monitor
Table of Contents Index Home Master Index Search Help
ADD Allows you to add charts to your display. Click SELECT to add
the first chart listed. Press MENU to select one of the following
chart options:
DEVICE YIELD BY DEVICES
DEVICE YIELD BY WAFER
DEVICE YIELD BY LOT
BIN YIELD BY DEVICES
BIN YIELD BY WAFER
BIN YIELD BY LOT
TEST YIELD BY DEVICES
TEST YIELD BY WAFER
TEST YIELD BY LOT
Device yield is calculated by taking the number of devices that
pass and dividing by the number of devices tested.
Bin yield is calculated by taking the number of devices in
specified bins that pass and dividing by the total number of
devices in all bins.
Test yield is calculated by taking the number of devices that pass
specified tests and dividing by the total number of devices for all
tests.
After you select a chart option, the Yield Chart Properties
window is displayed (see “Yield Chart Properties Window” on
page 6-118). This window allows you to modify the chart
properties before adding the chart to the display.
EDIT Edits the properties using the Yield Chart Properties window.
Click SELECT to edit the properties of CHART A, or press MENU
and choose a different chart.
DELETE Removes charts from the display. Click SELECT to delete Chart
A, or press MENU to select a different chart. Display is redrawn
when a chart is deleted.
QUIT Quits the Real Time Yield Monitor display.
Yield Display Load Setup
The Yield Display Load Setup window (figure 6-22) allows you to load a previously saved
setup file to configure the charts. A setup file defines all the charts, including their individual
chart properties, that the yield monitor program uses. Select FILE>LOAD SETUP... to display
the Yield Display Load Setup window.
IMAGE Solutions V8.3 6-114
IMAGE Base Language: Data Collection: Real Time Yield Trend Monitor
Table of Contents Index Home Master Index Search Help
Figure 6-22. Yield Display Load Setup Window
NOTE
Loading a setup file deletes all the currently displayed charts.
Setup files have a .yld filename extension. These files are ASCII files. Editing them directly
(using a text editor) is not recommended.
Yield Display Save Setup
The Yield Display Save Setup window (figure 6-23) allows you to save the currently defined
charts to a setup file. The setup file can then be used in another session to display the
desired charts. Select FILE>SAVE SETUP... to display the Yield Display Save Setup window.
Figure 6-23. Yield Display Save Setup Window
This window allows you to easily set up the Yield Monitor program to display the desired
charts, without needing to add new charts and set up their individual chart properties.
Yield Display Properties Window
The Yield Display Properties window (figure 6-24) is used to adjust the devices per cell or
the orientation of the charts. Select FILE>PROPERTIES... to display the Yield Display
Properties window.
IMAGE Solutions V8.3 6-115
IMAGE Base Language: Data Collection: Real Time Yield Trend Monitor
Table of Contents Index Home Master Index Search Help
The Display Properties panel allows you to adjust the number of devices per cell and the
orientation of the charts. It has the following controls:
DEVICES PER CELL Changes the number of devices shown on the X axis. If you are
using more than one chart, the number of devices is changed on
all charts.
CHART LAYOUT Allows you to display charts either horizontally or vertically when
using multiple charts. HORIZONTAL displays the charts side by
side. VERTICAL displays the charts one on top of the other.
Figure 6-24. Yield Display Properties Window Showing the Display Properties Panel
The Default Chart Properties panel in the Yield Display Properties window (figure 6-25)
allows you to specify default values for all charts. Changing default chart properties does
not affect the current charts being displayed. However, it does affect the default values used
the next time the program is run. This panel has the following controls:
# OF CELLS Specifies the number of cells to show on the X axis.
GRAPH STYLE Allows you to show individual bars or a cumulative graph or both.
Y AXIS HIGH LIMIT Specifies the highest value displayed on the Y axis.
Y AXIS LOW LIMIT Specifies the lowest value displayed on the Y axis.
YIELD UPPER CONTROL LIMIT
Specifies upper control limit used to identify a yield problem.
YIELD LOWER CONTROL LIMIT
Specifies lower control limit used to identify a yield problem.
IMAGE Solutions V8.3 6-116
IMAGE Base Language: Data Collection: Real Time Yield Trend Monitor
Table of Contents Index Home Master Index Search Help
Figure 6-25. Yield Display Properties Window Showing the Default Chart Properties Panel
Yield Chart Properties Window
The Yield Chart Properties window (figure 6-26) is used to add a chart or edit the properties
of a chart. Click the EDIT or ADD menu to display this window.
Properties you can change for every chart include the high and low limit for the Y axis, the
bin and test lists, the number of cells to show on the X axis, the graph styles which are
INDIVIDUAL (BAR) or CUMULATIVE (LINE), the sites to include, and the yield upper and lower
control limit.
The yield upper and lower control limits are used to identify yield problems. When the yield
goes above or below the control limit values or goes below the low limit, the bar and line
graphs are drawn in red to indicate a problem.
IMAGE Solutions V8.3 6-117
IMAGE Base Language: Data Collection: Real Time Yield Trend Monitor
Table of Contents Index Home Master Index Search Help
Figure 6-26. Yield Chart Properties Window
Using the Yield Trend Monitor to Show Test Yield
Follow the steps listed below to use the Yield Trend Monitor to show test yield:
1. Load a test program in a station window.
2. At the prompt type the yielddisp command with no option switches.
This starts a chart yield display showing device yield on the Y axis and devices (10 per
cell) on the X axis. This chart is labeled Chart A (figure 6-27).
3. Use the EDIT menu item to modify the Y axis limits for Chart A. Click the EDIT menu to
display the Yield Chart Properties (figure 6-26). Change the Y axis high and low limits
to a range value of 50 to 100.
4. With the Yield Chart Properties still displayed, modify the control limits to 80 and 100.
Figure 6-27. Yield Trend Monitor Showing Chart A
IMAGE Solutions V8.3 6-118
IMAGE Base Language: Data Collection: Real Time Yield Trend Monitor
Table of Contents Index Home Master Index Search Help
5. Add a second chart to your display by clicking MENU on the ADD menu item and
dragging to DEVICE YIELD BY LOT.
This adds a second chart to the display that shows device yield as each lot completes.
The second chart is labeled Chart B. It inherits the Y axis limits and the control limits
from Chart A, see figure 6-28.
Figure 6-28. Yield Trend Monitor Showing Charts A and B
6. Begin testing devices and observe the yield in the display. As each lot ends another bar
is added to Chart B indicating the yield for that lot.
7. Save the chart setup to a .yld file. Select FILE>SAVE SETUP.... In the Yield Display Save
Setup window enter a file name and location and click SAVE.
To use the saved chart setup to configure other charts, select FILE>LOAD SETUP... . The
Yield Display Load Setup window appears. From the DIRECTORY and FILE menu buttons,
select the .yld file with the desired setup and click LOAD. The setup file defines the
individual chart properties that the yield monitor program uses.
IMAGE Solutions V8.3 6-119
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
Histogram Plots
IMAGE includes a histogramming package as a standard data analysis tool. This tool allows
you to collect test results in a standard test data format (STDF) disk file and later plot the
distribution of these results as a histogram. You can print histogram plots as high-definition
plots in a Histogram Tool window (see “Histogram Tool” on page 6-124). You can also print
them as ASCII plots in any station window (see“Generating ASCII Histograms” on page
6-135). A histogram plot also produces statistics about the results, such as the mean and
standard deviation.
To produce a histogram use the following steps:
1. Set up histogramming to collect results from the desired tests.
2. Run the test program to generate and collect data.
3. Process the data and generate the histogram plots.
The histogram capability comprises setting up the data collection for a histogram (step 1)
and generating the plots (step 3). You can perform each of these steps using either a
window-based method or a command line method. The window-based utilities are the Data
Collection Setup display and the Histogram Tool. Their command line counterparts are the
histoset and histoplot commands. (See also “Two General-Purpose Histogram
Functions” on page G10-1 for another histogramming technique.)
Collecting Histogram Data
As with datalog, histogram plots require setting up selection criteria for collecting test data.
Histograms, however, use a different setup than datalog. This method provides the flexibility
of not having to datalog tests that are to be histogrammed and the ability to histogram
datalogged tests.
To set criteria for collecting test result data use either the Data Collection Setup display or
the histoset command to:
• Specify a list of tests whose results will be collected into the histogram data file. The list
can be a single test or every test in the program. Selecting a test list is the same as for
the datalog command. The list can also be kept in (and set up from) a disk file.
• Specify that data is to be collected on a sampled basis. That is, collect the specified test
results for every Nth device until results for M devices have been collected.
• Specify the name of the file into which test result data will be collected (or the name of
an existing file to append data to).
• Display the current histogram data collection setup.
• Turn off histogram data collection.
Setting Histogram Parameters Using the Data Collection Setup Display
The Data Collection Setup display (figure 6-29) allows you to interactively set up, modify,
and examine histogram data collection. The procedure is similar to setting up datalog
parameters. The display shows whether histogramming is on and allows you to turn it on or
IMAGE Solutions V8.3 6-120
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
off. (See “Control Panel Items” on page 6-15 for a listing of control panel buttons in this
display.)
Histogram
items
Figure 6-29. Data Collection Setup Display Showing Histogram Items
The Data Collection Setup display includes the following histogram items:
HISTOGRAM: OFF/ON Shows whether histogramming is enabled or disabled. Press
MENU and select from the menu to change.
NOTE
The option ON, APPEND TO FILE and the FILE field do not appear in the Data Collection Setup
display in IMAGE V5.7 and later.
CRITERIA Selects tests for histogramming. Press MENU to select one of
the following items:
IMAGE Solutions V8.3 6-121
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
ALL TESTS Datalog all tests (the default)
LIST OF TESTS Datalog the specified list of tests
LIST Allows you to enter a list of tests to histogram (the list referred to
in the CRITERIA item). You can use test names, test numbers,
and ranges of test numbers. This item is grayed out (inactive) if
LIST OF TESTS is not selected.
SAMPLE RATE Controls how often device data is sampled for histogramming.
(The default is 1.)
SAMPLE LIMIT Controls the total number of devices sampled. (The default is no
limit.)
Using the histoset Command
To set up histogramming with a command line, use the histoset command. The syntax is:
histoset [-off | -on <test_selection(s)>] [-samprate #] [-samplimit #]
[-show] [-station #]
where:
<test_selection> = -test [all] [list_file <filename>]
[list [#] [# to #] [<test_name>] [SEQUENCER seq_name]]
-test selects which tests to histogram. It can be:
-test all all tests
-test list_file <filename>
tests from a file
-test list # a specific test number
-test list # to # a range of test numbers
-test <test_name> a named test
-test SEQUENCER <seqname>
tests from a specific sequencer
Table 6-19 shows histogram list parameters.
Table 6-19. Histogram list Parameters
Parameter Definition Example
# Test number list 10
# # .. # List of test numbers list 10 20 30
# to # Range of test numbers list 10 to 40
test_name Test name list leak_test
SEQUENCER seq_name1 Sequencer name list SEQUENCER tp_seq_1
1. The SEQUENCER prefix must be written exactly as shown.
IMAGE Solutions V8.3 6-122
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
-samprate # Set the sampling rate for histogram data. (The default is 1—
every device sampled.)
-samplimit # Set the sampling limit for histogram data. (The default is no limit.)
-show Display the current histogram setup in the station window.
-station # Specifies a station number to collect histogram data.
-off Turns histogramming off.
The following examples show examples of histoset commands:
• Collect test results for test ALPHA on every device:
histoset -on -test list ALPHA
• Collect test results for all tests at every fifth device until data on 1000 devices has been
collected (that is, until 5000 devices have been tested):
histoset -on -test all -samprate 5 -samplimit 1000
NOTE
Each time histogram data collection is enabled (or the test selection is changed), the data
file is reset to begin collecting data for the specified setup, unless the setup was specified
as ON, APPEND TO FILE. The previous data file (if any) is renamed <filename>% (note the %).
Data Output
When histogramming is turned on (test result data is being collected), the test results
collected are by default sent to a disk file called:
node_station#_<test_program>_<lot_id>_timestamp.histo
An example file for lot #23 for the program volt_reg2 run on node constance would be:
constance_1_volt_reg2_23_feb16_09:57.histo
These histogram files conform to the Teradyne STDF format and are created in the directory
where the test program was loaded.
The histogram tool stores one part’s worth of data in a buffer so that it can detect retests.
Each time you test a part, the tool compares the current data with the previous part’s data
in the buffer. If the current part is a retest, the previous data is discarded.
Specifying a Test Data Directory
When the TEST DATA DIRS option (in the PRODUCTION section of the IMAGE Properties
window) is set to a directory, all histogram data is written to this directory. (See “Production
Setup Options” on page 3-37.)
IMAGE Solutions V8.3 6-123
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
Generating Histograms
Once you have turned histogramming on and collected data in an STDF file (by running a
test program), you can plot a histogram. IMAGE has two utilities to analyze data and
construct histogram plots: the Histogram Tool (histodisp) and the histoplot command
for ASCII displays. These utilities allow you to specify:
• A single test for a histogram plot (for any test for which data was, or is, being collected)
• The number of histogram cells to be plotted
• Whether the Y axis should display percent or absolute counts
• That the first N results for a test are to be ignored (used for ignoring devices at the edge
of a wafer)
• Plot limits to limit the baseline axis of the plotted histogram (control the visible range of
the data plotted)
• Population limits to determine the statistical significance of a result (whether or not it will
be included in the mean and standard deviation calculations)
• The full-scale percentage for the Y axis of the plot
• A cumulative percentage line for the plot
• An STDF file to be processed
These utilities automatically look for an STDF file when invoked under IMAGE. Histograms
can be plotted while data is being appended to the file. You can use this to examine a
snapshot of the data distribution at any point during testing.
Real-Time Histogram
In addition to plotting from a file, you can use the histodisp utility to connect to a station
while running a test program and analyze the data in real time (while parts are being tested).
When running histodisp in real-time mode, the tool collects all test data while parts are
being tested. This includes all tests in the test program (not only the test being viewed). You
can change the test number to view different distributions. You can also view test results
specific to a particular site or bin or both.
In real time mode, you must specify:
• Tests using test numbers (rather than test names)
• A station number to connect
• The frequency at which the display should be refreshed
Histogram Tool
The Histogram Tool (histodisp) is a window-based interface to the histogramming
function (figure 6-30). Features of this window utility include:
• High-resolution graphics
• The ability to send a “snapshot” of the plot to a file
• The ability to specify that the test limits be used to limit the baseline axis of a plot
IMAGE Solutions V8.3 6-124
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
• The ability to zoom in on part of a plot
Control Panel
Statistical area
Display area
Message area
Figure 6-30. Histogram Tool Window
The Histogram Tool window is divided into several areas:
• Control Panel at the top of the window includes controls for loading histogram files,
connecting to and disconnecting from stations, and specifying plot parameters.
• Statistical area located above the display area displays statistical information about the
collected data and the plot. Information includes
– A header that includes the test number, name, label, and units
– Distribution statistics calculated from the population in the plot
– Plot statistics calculated from the plot limits and that give the characteristics of the
cells that make up the plot
• Display area is where plots are displayed. (If no test results are collected in the data
file, the display tells you that it cannot display a plot.) The plot is scaled to fit this region
of the window.
• Message area at the bottom of the window displays IMAGE messages.
IMAGE Solutions V8.3 6-125
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
Invoking the Histogram Tool
When you have run a test program and collected test results, you can invoke the Histogram
Tool in either of the following ways:
• Press MENU on the DATA button in the station window and select HISTOGRAM TOOL or
REAL TIME HISTOGRAM from the menu.
• Press MENU on the PLOT button in the Data Collection Setup display and select BRING
UP HISTODISP WINDOW (FOR GRAPHICS PLOT) from the pull-right menu.
The Histogram Tool window appears with statistical and display regions unfilled. (You can
also start the histogram tool using the histodisp command in a station window. See “Using
the histodisp Command” on page 6-134.)
Using the Histogram Control Panel
The Histogram Tool control panel (figure 6-30) is used to set up histogram parameters and
to plot the histogram. It has the following controls:
FILE Press MENU on this menu button to see a menu for file
operations. The menu allows you to load histogram files or to
send plots to a file. (See “Manipulating Histogram Files” on page
6-127.) When the histogram tool is in real-time mode this button
is grayed out (inactive).
VIEW Press MENU on this button to see a menu for changing the plot
display. Menu items allow you to change the plot’s data setup
and display setting. (See “Changing Histogram Data Setup” on
page 6-128.)
CONNECT Press MENU on this button to connect to a station (from 1 to 8)
in real-time mode. If the display is connected to a different
station, a pop-up window is displayed to confirm that you want to
disconnect from the current station.
NOTE
Disconnecting from a station causes all data collected by the histogram tool to be lost.
DISCONNECT Click SELECT on this button to disconnect from a station.
Disconnecting from a station causes all data collected by the
histogram tool to be lost. If you re-connect to the same station,
the histogram tool will only display the results for parts tested
from that point forward.
TEST Enter the test name or test number you wish to plot in this field.
When the tool is in real-time mode, you must specify tests by
entering the test number, not the test name.
IMAGE Solutions V8.3 6-126
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
PLOT Click SELECT on this button to plot the current test. Press
MENU to display the Plot file history menu. This is a list of the
histogram files that have been loaded in the display. If you select
a file from this menu, it is loaded in the display and plotted. When
the histogram tool is in real-time mode this button is grayed out
(inactive).
Plotting a Histogram
To plot a histogram:
1. Load a histogram file into the Histogram Tool window. Do this in any of the following
ways:
a. Select FILE>LOAD. This displays the Load window (figure 6-31) and allows you to
load a file from any directory.
b. Select FILE>READ FILE, then pull right. This displays a menu of all the .histo and
.stdf files in the current directory and allows you to load one of these files.
c. Press MENU on the PLOT button. This displays a history menu of all files that have
been loaded into the display and allows you to select one, load it, and plot it.
2. Enter a test name or test number in the TEST field. If you do not specify a test and try to
plot, an error is displayed.
3. Enter or change any of the optional histogram parameters using selections in the VIEW
button menu.
4. Click PLOT. IMAGE retrieves test results for the test you specified and plots a histogram.
Plotting a Histogram in Real Time
To plot a histogram in real time:
1. Press MENU on the DATA button and select REAL TIME HISTOGRAM... from the menu or
type histodisp -rt in a station window.
This brings up the histogram tool connected to the station from which it was invoked.
2. Enter a test number (not a test name) in the TEST field.
If a test number is not specified in the TEST field, the tool displays the results for the first
test encountered in the test program.
3. Enter or change any of the optional histogram parameters using selections in the VIEW
button menu.
By default, the display does not refresh until at least five parts are tested. To change the
default, select VIEW>DISPLAY. In the Display Settings window, change the REFRESH
AFTER setting to the desired value.
Manipulating Histogram Files
The FILE button on the Histogram Tool control panel is used to load and store files. Press
MENU on FILE to display the following menu:
IMAGE Solutions V8.3 6-127
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
LOAD... Load the specified file into the histogram window. When you
select this option, the Load window is displayed (figure 6-31).
Select a directory and a file and click LOAD FILE.
Figure 6-31. Histogram Load Window
READ FILE Read the specified file from the current directory into the
histogram display. Pull right on the selection to display the list of
available .histo files in the current directory.
SEND PLOT TO FILE... Send the current plot on the display to a file you specify. The plot
must first have been generated before it can be sent to a file. The
output is the same as the histoplot output, an ASCII plot.
When you select this option the Save window appears (figure 6-
32). Select a directory and click SELECT on SAVE FILE.
Figure 6-32. Histogram Save Window
Changing Histogram Data Setup
Select VIEW>DATA... to change histogram data parameters. The Data Setup window
appears (figure 6-33).
Figure 6-33. Histogram Data Setup Window
IMAGE Solutions V8.3 6-128
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
The window has the following features:
SITE Sets the site to plot in a program with more than one site (a
multisite test program). (Default is not selected.)
CELLS Sets the number of cells in the plot. The minimum is 2 and the
maximum is 100. (Default is 15.)
FULL SCALE % Specifies the maximum value of the Y axis, percent if in
PERCENTAGES mode or count if in COUNTS mode. (Default is not
selected.)
RESULTS TO SKIP Specifies the number of results to skip (ignore) at the beginning
of the data file. This function is useful if a data file was created
while testing a wafer which may have bad devices along its
edge. (Default is 0.)
NUMBER OF SIGMAS Selects the number of sigmas (1 to 20) to plot around the mean.
(Default is 3.)
BIN RESULTS Selects results from all bins or only from one bin to plot. You can
select any bin number, and you can select whether this is a
hardware or software bin. See “Assigning Bin Numbers” on page
15-6. (Default is all.)
POPULATION LIMIT Sets the low or high population limits or both for data used in
calculating the plot. See “Setting Population Limits and Plot
Boundaries” on page 6-130.) (Default is not selected.)
PLOT LIMIT Sets the low and high boundaries for the plot. See “Setting
Population Limits and Plot Boundaries” on page 6-130. (Default
is not selected.)
Changing Histogram Display Characteristics
Select VIEW>DISPLAY to change display settings of the histogram. The Display Settings
window appears (figure 6-34). The window has the following features:
PLOT USING: TEST LIMITS
Plot the histogram using the test limits. If selected, the plot is
redrawn to include the test limits, overriding any plot limits which
may have been set. (Default is not selected.)
SHOW: PERCENTAGES Display the percentage of results in each cell on the Y axis (as in
figure 6-34). If this option is not selected, the plot shows the
absolute number (count) of values in each cell. (Default is show
percentages.)
IMAGE Solutions V8.3 6-129
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
Figure 6-34. Histogram Display Settings Window
SHOW: TEST LIMITS Display the test limits. If selected, lines representing the test
limits are drawn on the plot. The plot is not resized to show test
limits outside the plot limits. (Default is not selected.)
SHOW: CUMULATIVE% Display the cumulative percentage curve on top of the
histogram. If displayed, the corresponding axis is displayed on
the right side of the plot and is always labelled in percentages
from 0% to 100%. (Default is not selected.)
NOTE
The cumulative percentage always represents the displayed data, not all data within the
population limits.
BAR: SHADED/STRIPED/HOLLOW/SOLID
Display the bars of the histogram as shaded (gray, as in figure 6-
34), striped, hollow (unfilled), or solid (black). (The default is
shaded.)
GRID: ON Display display horizontal grid lines. (The default is not selected.)
REFRESH AFTER...RESULTS
This setting specifies the number of parts that will be tested
before the tool updates the display. The default value is 5.
Setting this to a smaller value results in the display being
updated more frequently. This field only affects real time mode.
Setting Population Limits and Plot Boundaries
On a histogram plot, population limits limit the results used in the distribution statistics (that
is, mean and standard deviation). Any results falling outside the population limits are
included in the overflow and underflow counts.
Plot boundaries (limits) are used to limit the X axis of the display. They do not affect the
distribution statistics. Using test limits to plot the results has the same effect as setting the
plot limits to the test limits.
Limit and boundary defaults work as follows:
IMAGE Solutions V8.3 6-130
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
• Test limits are used if you choose the PLOT USING: TEST LIMITS option from the Display
settings window.
• If a test limit is not set, the corresponding plot boundary (plot high or low limit) is used.
• If a plot boundary is not set, the corresponding population limit is used.
• If the population limit is not set, the minimum (or maximum, whichever is appropriate)
test result value is used.
In theory, a limit that is not set implies that the limit is infinity (which is what is shown in the
statistics region), but this is not a plottable value.
Using the Zoom Feature
The histogram display window includes a feature that allows you zoom in on a portion of a
plot by changing the plot limits. Since each test result is stored in the data file, you can zoom
in to find the value of a single result. The zoom feature works with the PLOT LIMIT fields in
the Data Setup window. Note that zoom will not work if you have test limits turned on.
To zoom in on an area (figure 6-35), do the following:
1. Display a plot.
2. Select VIEW>DATA. The Data Setup window appears.
3. Place the pointer in the plot area and click SELECT. A vertical zoom bar appears to
mark the high limit. You can also press SELECT and move the bar left or right. When
the bar appears, its position on the X axis is automatically recorded in the PLOT LIMIT:
HIGH field of the Data Setup window.
4. Place the pointer where you want the lower limit and click SELECT. A second zoom bar
appears. When the bar appears, its position on the X axis is automatically recorded in
the PLOT LIMIT: LOW field of the Data Setup window. Figure 6-35 shows a plot at the left
with two zoom bars.
5. Place the pointer on either zoom bar and press SELECT to move it to a position on the
X axis of the plot where you want the high or low limit and release. You can also move
the pointer close to a bar and click on MENU to move the bar. As you move the bar, the
values in the PLOT LIMIT field change.
6. Click PLOT. This generates a new plot using the high and low limits set by the zoom bars.
The zoom bars disappear from the new plot, the plot limits are shown in the histogram
setup region, and the plot statistics are changed to reflect the new limits. The histogram
on the right in figure 6-35 shows a new histogram after using zoom.
IMAGE Solutions V8.3 6-131
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
Zoom Bars
Figure 6-35. Placing Zoom Bars on Histogram Plot (top) to Generate New Plot of Selected Area (bottom)
If you use only one bar, the plot zooms in on the area to the left of the bar.
You can also place plot limits by entering values into the PLOT LIMIT fields and clicking PLOT.
IMAGE Solutions V8.3 6-132
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
You cannot drag the left zoom bar over the right one (or the right one over the left) since
one bar is automatically dropped as the other is picked up. This preserves the right and left
handedness of the bars.
To remove a bar, place the pointer on it and press SELECT. Move the bar left or right out
of the display. The bar disappears.
To display the full plot again, unselect the high and low plot limits in the PLOT LIMIT fields
and click PLOT.
Using the Display Area Menu
The display area has a pop-up menu that includes selections for altering plot display
characteristics. These selections are also in the Display Settings window under the VIEW
button, but you may find using this menu more convenient. To use the menu, place the
pointer in the plot area and press MENU. A menu with the following selections is displayed:
PLOT USING>AUTO LIMITS/TEST LIMITS
Plot the histogram using the data limits (AUTO LIMITS) or the test
limits. (Default is AUTO LIMITS.)
SHOW>PERCENTAGES Display the percentage of results in each cell on the Y axis. If this
option is not selected, the plot shows the absolute number
(count) of values in each cell. (Default is show percentages.)
SHOW>TEST LIMITS Display the test limits. If selected, lines representing the test
limits are drawn on the plot. The plot is not resized to show test
limits outside the plot limits. (Default is not selected.)
SHOW>CUMULATIVE% Display the cumulative percentage curve on top of the
histogram. If displayed, the corresponding axis is displayed on
the right side of the plot and is always labelled in percentages
from 0% to 100%. (Default is not selected.)
NOTE
The cumulative percentage always represents the displayed data, not all data within the
population limits.
BAR>SHADED/STRIPED/HOLLOW/SOLID
Display the bars of the histogram as shaded (gray, as in figure 6-
34 on page 6-130), striped, hollow (unfilled), or solid (black).
(Default is shaded.)
GRID>ON/OFF Display display horizontal grid lines. (Default is OFF.)
REFRESH AFTER...RESULTS
This setting specifies the number of parts that will be tested
before the tool updates the display. The default value is 5.
IMAGE Solutions V8.3 6-133
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
Setting this to a smaller value results in the display being
updated more frequently. This field only affects real-time mode.
Using the histodisp Command
You can also display the Histogram Tool by typing the histodisp command in a station
window. Options to this command allow you to change the default setup of the display. The
syntax is:
histodisp [<test_number> | <test_name>] [-file <filename> | -rt]
[-station <integer>] [-fullscale <value>] [-cells <integer>] [-count]
[-cumu] [-grid] [-hard_bin <integer>] [-soft_bin <integer>]
[-pop LOW HI] [-plot LOW HI] [-skip <integer>] [-testlimits]
[-site <integer>] [-sigmas <integer>]
where:
test_number | test_name
Specifies a test number or test name.
-file <filename> Uses the named file for the plot. If you do not use this option, the
plot defaults to the current data file.
-rt Brings up histodisp in real time mode. If invoked from a station
window, the histogram tool connects to that station.
-station <integer> Specifies a station number to display the plot.
-fullscale <value> Specifies the maximum value of the Y axis as a percentage or
count.
-cells <integer> Sets the number of cells in the plot, where N is an integer. The
minimum is 2 and the maximum is 100. (Default is 15.)
-count Sets the Y axis to display the absolute number (counts) in a cell
rather than percentage of results.
-cumu Displays the cumulative percentage curve for the cells. If
displayed, the corresponding axis is displayed on the right side
of the plot and is always labelled in percentages from 0% to
100%.
NOTE
The cumulative percentage always represents the displayed data, not all data within the
population limits.
-grid Displays horizontal grid lines.
-hard_bin Displays the hardware bin to be displayed. See “Assigning Bin
Numbers” on page 15-6.
IMAGE Solutions V8.3 6-134
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
-soft_bin Specifies the software bin to be displayed. See “Assigning Bin
Numbers” on page 15-6.
-pop[ulation] <LOW> <HI>
Sets low and high limits for data used in calculating the plot.
Limits can be specified as two floating point values or as X for
none. Both low and high limits are expected. (Default is plus and
minus infinity.)
-plot <LOW> <HI> Sets low and high limits for data used to display the plot. Limits
can be specified as two floating point values or as X for none.
Both low and high limits are expected. (Default is plus and minus
infinity.)
-skip <integer> Skips the specified number of results at the beginning of the data
file.
-testlimits Uses the test limits to limit the X axis. This overrides any plot
limits you may also have specified.
-site <integer> Selects the site in a multisite test program.
-sigmas <integer> Selects the number of sigmas (from 1 to 20) to plot around the
mean. (Default is 3.)
Generating ASCII Histograms
The histoplot (character plot) command generates an ASCII histogram in any station
window (figure 6-36). You can also start a plot from the Station Plot window in the Data
Collection Setup display.
Although this ASCII plot lacks some graphics features of the Histogram Tool, it is versatile.
It can be sent to a file or redirected to a line printer using Solaris redirection commands (see
“Redirection Operator” on page 2-22).
IMAGE Solutions V8.3 6-135
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
.................................................................
. H I S T O G R A M R E P O R T .
.................................................................
Test No Test Function Name Test Label Units
-----------------------------------------------------------------
3 Normal Dist. test3 t3
Lower Test Limit= 30 Upper Test Limit= 35
- DISTRIBUTION STATISTICS -
Lower Pop Limit= -Infinity Upper Pop Limit= +Infinity
Total Results= 24 Results Accepted= 24
Underflows= 0 Overflows= 0
Mean= 32.5 Std Deviation= 1.03799
Minimum Value= 30.3 Maximum Value= 33.82
- PLOT STATISTICS -
Lower Plot Limit= 30.3 Upper Plot Limit= 33.82
Cells= 15 Cell Width= 0.234667
Full Scale Percent= 33.33% Full Scale Count= 8
Cell Value Percent Cell Cumul
each '*' = 0.6536% (0.1569 results) % %
+-----------------------------------------------------------------
30.3 |************* 8.3 8.3
30.53 | 0.0 8.3
30.77 | 0.0 8.3
31 |************* 8.3 16.7
31.24 | 0.0 16.7
31.47 | 0.0 16.7
31.71 | 0.0 16.7
31.94 |********************************************* 29.2 45.8
32.18 | 0.0 45.8
32.41 | 0.0 45.8
32.65 | 0.0 45.8
32.88 |*************************************************** 33.3 79.2
33.12 | 0.0 79.2
33.35 | 0.0 79.2
33.59 |******************************** 20.8 100.0
33.82 +-----------------------------------------------------------------
Figure 6-36. Sample ASCII Histogram Report
The histoset and histoplot commands work independently. Therefore, you can be
running a test program and collecting data and still generate “intermediate” (snapshot)
histogram plots using histoplot.
IMAGE Solutions V8.3 6-136
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
Using the Data Collection Setup Window
To plot ASCII histograms in the text window, you can use the Station Plot window (figure 6-
37). Bring up the Station Plot window (click the PLOT menu or choosing PLOT HISTOGRAM IN
STATION WINDOW (ASCII PLOT) from the PLOT menu in the Data Collection Setup display).
Figure 6-37. Station Plot Window
The Station Plot window automatically fills in the FILENAME field on the window if the
histogramming is activated. It also copies the first test listed in the histogram criteria test if
it is filled in. You can change either of these items.
You can only specify one test to display in the station window.
Once you choose the filename to plot from and the test you wish to plot, click the PLOT
button. This creates the ASCII plot in the station window.
Using the histoplot Command
You can also generate an ASCII plot from a station window using the histoplot command.
This command includes most options used with the histodisp command. The differences
are:
• A test number or test name is required.
• The -cumu option produces a cumulative percentages column.
• The -grid option is not available.
The syntax of the histoplot command is as follows:
histoplot {test_number | test_name}
[-cells <integer>] [-count][-cumu] [-file <filename>]
[-fullscale <value>] [-hard_bin <integer>] [-soft_bin <integer>]
[-pop LOW HI] [-plot LOW HI] [-skip <integer>]
[-station <integer>] [-testlimits] [-site <integer>]
[-sigmas <integer>]
where:
test_number | test_name
Specifies a test number or test name (required).
-cells <integer> Specifies the number of cells in the plot. (Default is 15.)
-count Displays the absolute value of each cell on the Y axis. (Default is
to display the percentage on the Y axis.)
IMAGE Solutions V8.3 6-137
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
-cumu Displays the cumulative percentage for the cells.
-file <filename> Plots the named file.
-fullscale <value> Specifies the maximum value of the Y axis, percent if in
Percentages mode or count if in Counts mode.
-hard_bin <integer>
Specifies a hardware bin. (See “Assigning Bin Numbers” on
page 15-6.)
-soft_bin <integer>
Specifies a software bin to be displayed. (See “Assigning Bin
Numbers” on page 15-6.)
-pop <LOW> <HI> Specifies low and high limits for data used in calculating the plot.
LOW and HIGH can be specified as two floating point values or as
X for none. (Default is minus and plus infinity.)
-plot <LOW> <HI> Specifies low and high boundaries for the plot. LOW and HIGH can
be specified as two floating point values or as X for none. (Default
is minus and plus infinity.)
-skip <integer> Skip the specified number of results at the beginning of the data
file.
-station <integer> Specifies a station number to display the plot.
-testlimits Use the test limits to limit the X axis. This overrides any plot limits
you may also have specified.
-site <integer> Selects the site in a multisite test program.
-sigmas <integer> Selects the number of sigmas (from 1 to 20) to plot around the
mean. (Default is 3.)
To send a plot to a file or to a line printer (or anywhere but the station window), include
Solaris redirection operators in the command.
The following are examples of histoplot commands:
• Plot a histogram of test 25:
histoplot 25
• Plot a histogram of test 25 and limit the highest result plotted (not the statistical values)
to 5.25:
histoplot 25 -plot X 5.25
• Print a histogram of test 25 on the line printer:
histoplot 25 | lpr
• Plot a histogram of test 25 with 30 cells:
histoplot 25 -cells 30
IMAGE Solutions V8.3 6-138
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
Histogram File Merging Program
IMAGE includes a stand-alone program, merge_histo, which merges two or more
histogram files into a single file. This allows you to make plots of a test for multiple lots. The
syntax for this program is:
merge_histo <input_files> -output <output_file> [-silent] [-ignore]
where:
input_files Specifies the names of the files to be merged.
-output Specifies the name of the output file.
-silent Causes the program not to print out status messages indicating
the progress of the merge (such as ...beginning merge).
-ignore Forces the program to try to merge the files even if they were
created by different test programs or testers. Take care when
using this option, since you can easily merge incompatible files
when using it and create a merged file containing meaningless
data.
For example, you have three histogram files in a directory named a.histo, b.histo, and
c.histo. Merge them into a single file called alpha.histo as follows:
% merge_histo a.histo b.histo c.histo -output alpha.histo
...checking files for consistency
...beginning merge
...file a.histo complete
...file b.histo complete
...file c.histo complete
...merge complete
As with the APPEND TO FILE option of Data Collection Setup display (see “Setting Histogram
Parameters Using the Data Collection Setup Display” on page 6-120), merge_histo has
several restrictions and things to be careful about:
• When you merge two histogram files, merge_histo opens the files to compare certain
data items within the files to ensure that it makes sense to merge them. Specifically, it
checks that the test program name, tester name, station number, and IMAGE software
version match. If these items do not match, the files are not merged (unless you include
the -ignore option in the command).
• merge_histo cannot determine if a test program was modified (for example, test
functions added, changed, or deleted) between the time the two .histo files were
created. For example, you may merge two histogram files, one created by a version of
a test program with 100 tests and one created by a later revision with 110 tests. You
may be unable to plot all the tests in the histogram display when using this merged file.
• merge_histo cannot determine that two files were created using identical “test criteria”
selections before merging them. For example, you can create a .histo file with data for
all test functions, and then merge it with a file created with only test function “x” selected.
IMAGE Solutions V8.3 6-139
IMAGE Base Language: Data Collection: Histogram Plots
Table of Contents Index Home Master Index Search Help
This would result in a merged file containing more occurrences of one test than certain
other tests.
IMAGE Solutions V8.3 6-140
IMAGE Base Language: Debugging Test Programs
Table of Contents Index Home Master Index Search Help
7 DEBUGGING TEST PROGRAMS
IMAGE includes a debugger for developing, debugging, and modifying test programs. The
debugger supports incremental edit and recompile, setting breaktraps, and immediate
commands. When you enter debug:
• A source window (figure 7-1) appears. This window is where the test program you
loaded in the station is displayed and edited.
• The station window displays a third row of buttons in its control panel. These buttons are
used to control debug functions.
• The DISPLAY button on the station window control panel is activated. This provides
access to a variety of debug displays covering test system functions and instruments
and functions.
This section discusses editing, debugging, and recompiling test programs. It includes the
following topics:
• “Entering Debug” on page 7-2
• “Using the Source Window” on page 7-5
• “Viewing Test Programs” on page 7-7
• “Breaktraps” on page 7-11
• “Editing and Compiling Functions” on page 7-23
• “Manipulating Test Program Files” on page 7-31
• “Exiting Debug” on page 7-37
• “Standalone IMAGE Compiler” on page 7-38
• “Libraries” on page 7-45
• “Switch Variables” on page 7-46
• “Debug Displays” on page 7-47
• “Interactive Debug Displays” on page 7-49
• “Variables Display” on page 7-56
• “Immediate Commands” on page 7-64
IMAGE Solutions V8.3 7-1
IMAGE Base Language: Debugging Test Programs: Entering Debug
Table of Contents Index Home Master Index Search Help
Entering Debug
You can enter debug in several ways:
• When creating a new test program:
– Check NEW FILE in the Load test program window. (See “Loading Using the Load
Window” on page 5-2.)
– Enter the command load -new. (See “Loading Using the load Command” on page
5-4.)
• When loading an existing test program:
– Check DEBUG in the Load test program window. (See “Loading Using the Load
Window” on page 5-2.)
– Use the LOAD AND ENTER DEBUG option in the LOAD button pull-right menu. (See
“Loading Using the Load Window” on page 5-2.)
– Enter the load -debug command. (See“Loading Test Programs” on page 5-2.)
– Enter the load -tl_init_debug command to debug the optional test-program
function, tl_init(). (See“Loading Using the load Command” on page 5-4.)
• After loading a test program:
– Enter the debug command in a station window.
– Click the DEBUG button.
The debug command has the following syntax:
debug [-source <dir>] [-station #]
where:
-source <dir> Specifies the location of the source files.
-station # Specifies the test station to use for debug.
IMAGE Solutions V8.3 7-2
IMAGE Base Language: Debugging Test Programs: Entering Debug
Table of Contents Index Home Master Index Search Help
Namestripe
Control Panel
Text pane
Source
window
Message area
Source
window
icon
Figure 7-1. Station Window and Source Window in Debug
You must have a program loaded to enter debug. The debug command fails if source files
for a loaded program cannot be located or if source files have changed since the binary was
loaded. Source files from a test program are assumed to be in the same directory as the
binary files.
If source files are in a different directory, you must specify that directory to the debugger.
Do this using the command debug -source <dir> or, when loading the program, you can
use the -source option of the load command. Use multiple -source parameters if all the
source files that make up a test program are not in the same directory. Source directories
are searched in the order listed.
You can determine if a station window is in debug using the command:
station_info -debugmode
IMAGE Solutions V8.3 7-3
IMAGE Base Language: Debugging Test Programs: Entering Debug
Table of Contents Index Home Master Index Search Help
See “Displaying Station Window Information” on page 3-14 for more information on the
station_info command.
IMAGE Solutions V8.3 7-4
IMAGE Base Language: Debugging Test Programs: Using the Source Window
Table of Contents Index Home Master Index Search Help
Using the Source Window
When you enter debug, the source window (figure 7-1) appears. This window is similar to a
Textedit window and allows you to display and edit the text of the test program loaded in the
station. It is initially placed above the station window.
The source window can be moved and resized and has its own control panel. The
advantage of this separate source window is that you can edit a test program in this window
while keeping the station window closed. (You would have the station window open when
debugging the program.)
When you first enter debug, the source window is in debug mode. This mode allows you to
run the test program, set and unset breaktraps, and watch the text as you step through the
program. The third row of buttons in the station window control panel includes these debug
functions.
Parts of the Window
The source window has the following features:
• The namestripe includes the station number where the program is loaded, the name of
the test program, and the name of the current source file displayed in the window. If you
have edited the test program, the namestripe displays (EDITED).
• The control panel includes buttons for editing and compiling test programs.
• The text pane displays the text of the test program. It includes scrolling. It also has a
background menu that you can display by pressing MENU in the pane. It includes similar
controls to those on the control panel.
• The message area at the bottom of the window displays any messages and warnings.
For example, when you enter edit mode, the EDIT MODE message is displayed in this
area.
• The icon for the source window (figure 7-1) displays the name of the file in the source
window. If the file has edits, the file name is preceded with a greater-than sign (>).
Opening and Closing the Source Window
The station and source windows are linked to open and close in relation to one another.
They open and close in the following ways:
• If you open or close the station window, the source window opens or closes.
• If you open or close the source window, only the source window opens and closes.
This arrangement allows you to have any combination of windows open but also makes it
easy to open or close both windows at once.
You can change this behavior using IMAGE Properties. From the IMAGE Workspace menu,
select PROPERTIES>IMAGE PROPERTIES. Select the category PER-USER STATION WINDOW
OPTIONS. The option ICONIFY BEHAVIOR allows you to specify how the station window (CMD
REGION) and the source window (SOURCE REGION) open and close in relation to one another.
IMAGE Solutions V8.3 7-5
IMAGE Base Language: Debugging Test Programs: Using the Source Window
Table of Contents Index Home Master Index Search Help
Editing Program Text
The source window control panel includes the following menu buttons:
FILE> Commands to load and save files and to create new versions.
These commands are only available when debugging. If you are
editing, they are grayed out (inactive). (See “Manipulating Test
Program Files” on page 7-31.)
VIEW> Commands to see various parts of the test program. (See
“Viewing Test Programs” on page 7-7.)
EDIT> Commands to enter the editor and to perform editing functions
such as cut and paste. (See “Editing a Test Program” on page
7-23.)
FIND> Commands to search for text.
COMPILE> Commands to compile the test program. (See “Compiling Using
the compile Command” on page 7-26.)
IMMEDIATE> Command to immediately execute a portion of the code in a test
program. (See “Using the Immediate Command From the
Source Window” on page 7-66.)
To edit in the source window, you should be familiar with Sun’s Text Editor (textedit). The
IMAGE debug editor and textedit operate in the same way and have similar buttons and
menus. For an introduction to textedit, select HELP from the IMAGE Workspace menu
and select ABOUT TEXT EDITOR from Sun’s on-line Help Viewer.
IMAGE Solutions V8.3 7-6
IMAGE Base Language: Debugging Test Programs: Viewing Test Programs
Table of Contents Index Home Master Index Search Help
Viewing Test Programs
The IMAGE debugger sees a test program as a list of functions, possibly grouped into files.
You can use this organization to find out the state of a program and to examine other parts
of the program.
The VIEW menu button on the source window control panel includes functions for viewing
parts of the test program. The menu includes the following:
CHANGE FUNCTION... Find and display the selected function.
CHANGE FILE Display the selected source file in the source window.
LIST FUNCTIONS> List functions and global variables in the test program.
SELECT LINE AT NUMBER...
Display the selected line number. (This is the default for the VIEW
button.)
WHAT LINE NUMBER Display the line number of the selected line.
TRAP ARROW TO TOP
SHOW CARET AT TOP Change the source window display to place the trap arrow at the
top of the window. If you are in edit mode, this item changes to
SHOW CARET AT TOP.
CHANGE LINE WRAP> Wrap long lines at a word or a character or clip them. The default
is to wrap them at a word.
Changing Test Program Functions
The VIEW>CHANGE FUNCTION selection allows you to find and display a selected function in
a large program. To change functions:
1. Select VIEW>CHANGE FUNCTION. The Change function window appears (figure 7-2).
2. Enter the name of the function and click CHANGE FUNCTION.
You can also change functions by typing:
chfunc <new_current_function>
in a station window. If you are working with multiple source files and the function is in a file
other than the one currently being displayed, chfunc automatically moves to the file
containing the function.
Figure 7-2. Change Function Window
IMAGE Solutions V8.3 7-7
IMAGE Base Language: Debugging Test Programs: Viewing Test Programs
Table of Contents Index Home Master Index Search Help
Changing Test Program Files
The VIEW>CHANGE FILE selection and the chfile command allow you to display different
files in the source window. Use this when your test program has multiple source files. (If the
test program does not have multiple files, this selection on the source menu is grayed out.)
To invoke the command, select CHANGE FILE from the source window menu, then select the
file you want from the pull-right menu. You can also type the following in the station window:
chfile <new_current_filename>
The CHANGE FILE menu displays files in the following order:
• IMAGE Test Language files (.tl)
• C language files (.c)
• Header files (.h)
• Other files
Viewing Header Files
You can use CHANGE FILE to view or edit header files included in a program using the
#include statement. Only header files included with double quotes (" ") can be edited;
header files included with angle brackets (<>) cannot be changed.
Adding a New File to a Test Program
You can use the chfile command to add a new file to a test program. If the file specified
is not a part of the loaded program, a check is made to see if the file already exists in your
directory or the directory you specify.
If the file you specify does not exist, you are asked if this is a new file that you wish to add.
Answer yes to add a new file. The new file can be a header (.h) file or a source (.tl or .c)
file. The default is a source file (.tl).
New source files consist of only a few #include statements to include the standard header
files; new header files are empty except for a comment. New files are copies of the files
newfileinit.tl (standard header file) and newhdrinit.h (empty header file) in the
directory $IMAGEBIN/custom.
To change the contents of a newly created program file, put a modified version of the new
source files in the directory you load from. To change them on a system-wide basis, you
must make new versions of both $IMAGEBIN/custom/newfileinit.tl and
newhdrinit.h.
Changing files can affect immediate commands, since the header section of the current file
is used by the compiler when executing these commands. (See “Immediate Commands” on
page 7-64.)
IMAGE Solutions V8.3 7-8
IMAGE Base Language: Debugging Test Programs: Viewing Test Programs
Table of Contents Index Home Master Index Search Help
Listing Test Program Functions
When starting to debug a test program, you may need to organize the various parts of the
program. The VIEW>LIST FUNCTIONS selection has a pull-right menu with options to allow you
to do this by listing the functions and global variables the program contains. LIST FUNCTIONS
has the following menu options:
LIST FUNCTIONS List all functions in the test program. Functions not compiled or
linked correctly are marked with an asterisk (*). The following is
an example of LIST FUNCTIONS output:
FILES FUNCTIONS (* -not compiled, S -sequencer, T -testf)
myprogram.tl HEADER *main
multi1.tl HEADER (s)myseq
multi2.tl HEADER (T)test1 (T)test2 (T)test3 (T)test4
myfile3.tl HEADER func1 func2 func3 func4
CREATE CROSS-REFERENCE
Display a cross-reference listing all global variables and
functions in the test program. The list includes the type of each
variable and function and the names of all functions which
reference each variable and function. The following is an
example cross-reference listing:
CROSS REFERENCE
VARIABLE NAME TYPE WHERE REFERENCED
------------- ---- ----------------
once int freq_tms
FUNCTION NAME TYPE WHERE REFERENCED
------------- ---- ----------------
freq_tms() TESTF seq1
main() int
seq1() SEQUENCER main
WRITE CROSS-REFERENCE TO FILE
Write a cross-reference listing of all global variables and
functions in the test program to a file. The listing is written to
<program_name>.xref in the current working directory.
You can also list function by typing the list command in a station window. The list
command has the following syntax:
list [-xref | -files | -sort | <filename>]
where:
-xref Displays a cross-reference listing all global variables and
functions in the test program.
-files Lists all the files that constitute a program but not the functions
in those files.
IMAGE Solutions V8.3 7-9
IMAGE Base Language: Debugging Test Programs: Viewing Test Programs
Table of Contents Index Home Master Index Search Help
-sort Lists of functions sorted by the function name.
<filename> Lists only the functions in the file <filename>.
You can also write a cross-reference to a file using the syntax:
list -xref > <file_name>
Selecting and Determining Line Numbers
You can select a line in a test program using the VIEW>SELECT LINE AT NUMBER selection.
When you select this option, the Line Number window appears (figure 7-3). Enter a line
number and click SELECT LINE AT NUMBER.
Figure 7-3. Line Number Window
You can also determine the number of a test program line using the VIEW>WHAT LINE
NUMBER?. To determine a line number, click on a line (or click SELECT and ADJUST to
select several lines). Then select VIEW>WHAT LINE NUMBER?. You see a box with a
message similar to this:
Selection begins in line 24.
Press "Continue" to proceed.
Finding Trap Arrows
You can set breaktraps in a test program to stop execution at some point. (See “Breaktraps”
on page 7-11.) When you run the program to a trap, the program stops, and an arrow
appears at the trap point. If you scroll through the program, you may need to find the trap
arrow and display it in the source window. Use the VIEW>TRAP ARROW TO TOP selection.
When you choose this selection, the test program line with the trap arrow is placed at the
top of the source window text pane.
Changing Line Wrap
You can set the way long program lines are handled using the VIEW>CHANGE LINE WRAP
selection. The default is to wrap the line to the next line when a word does not fit. You can
also wrap lines at a character or clip long lines without wrapping them at all.
IMAGE Solutions V8.3 7-10
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
Breaktraps
You can request that a test program stop at specified lines in a program or under certain
program conditions. Such stop points are called breaktraps. When a program has stopped
for a breaktrap, you can examine variables or hardware or execute immediate commands.
If a program is stopped for a program fault or user interrupt by CONTROL-C, you can execute
immediate commands or print commands. But if the program is stopped for a fault, it cannot
be continued. You can distinguish between these states by the shading of the breaktrap
arrow. (See “Stepping Through a Test Program” on page 7-16.)
Setting and Listing Breaktraps
You can set traps on a specified line or function of the file (line number trap) or when a
specified program condition is met (ATE breaktrap). You can also list traps you have set.
Setting a Breaktrap
You set traps using the SET menu button in the station window control panel. This button
has the following menu:
TRAP ON SELECTED LINE
Stop the test program at the selected line. (This is the default.)
TRAP IN FUNCTION Stop the test program at the selected function.
TRAP ON TEST Stop the test program at the selected test.
TRAP ON FAILED TEST Stop the test program at the first failing test.
TRAP ON PASSED TEST Stop the test program at the first passing test.
TRAP ON PATTERN START
Stop the test program at the beginning of a digital pattern. (Used
to debug a digital pattern.)
TRAP ON ALARM Stop the test program at an alarm.
TRAP ON READ METER Stop the test program at a read meter statement.
TRAP ON RUN TIME ERROR
Stop the test program at a run-time error. (See “Setting
Breaktraps on Run-Time Errors” on page 7-13.)
TRAP ON TEST NUMBER Stop the test program at the selected test number.
LIST TRAPS List all traps set in the test program.
To set a line number trap using the mouse:
1. Make the test program line you want visible in the source window.
2. Select (highlight) any character in the line by clicking SELECT at the beginning and
ADJUST at the end of the selection.
IMAGE Solutions V8.3 7-11
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
3. Select SET>TRAP ON SELECTED LINE from the menu.
Each trap you set is given a number in the order that you set it, starting at 1. When a trap is
set on a line, a stopsign icon appears to the left of its text (figure 7-4). If you run a program
to trap, an arrow at the left margin indicates the trap at which the program is stopped.
Figure 7-4. Breaktrap Stopsign and Arrow
You can also set traps by typing the settrap command in the station window. This
command has the following syntax:
settrap [-function <func>] [-line <line>] [-test] [-failedtest] [-passedtest]
[-patternstart] [-alarm] [-readmeter] [-error] [-test <number>]
where:
-function <func> Stops the test program at function <func>.
-line <number> Stops the test program at line <number>.
-test Stops the test program at the selected test.
-failedtest Stops the test program at the first failing test.
-passedtest Stops the test program at the first passing test.
-patternstart Stops the test program at the beginning of a digital pattern.
-alarm Stops the test program at an alarm.
-readmeter Stops the test program at a read meter statement.
-error Stops the test program at a run-time error.
-test <number> Stops the test program at the specified test number.
IMAGE Solutions V8.3 7-12
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
Sometimes the trap does not appear on the line you specify. This is because not all source
lines have executable code. Exactly which source lines are trappable is not always obvious.
(See “Breaktrap Placement” on page 7-21.) If the line specified cannot be trapped on,
IMAGE selects the next trappable line and sets the trap there. If the program contains no
further trappable lines, it is an error.
Setting Breaktraps on Run-Time Errors
When you run a test program in debug and get a run-time error, the test program halts at
the error and does not bin the device, You can also set a trap on a run-time error using the
TRAP ON RUN TIME ERROR menu selection or the settrap -error command.
Setting a trap on a run-time error causes the test program to trap in the IMAGE run-time
error handler. If the program stops at a FORCE_BIN, it places the trap arrow on the error.
The program traps after the error message has been given but before IMAGE takes any
action. The hardware remains in the same state it was in when the error was detected.
When you continue from the trap, IMAGE will do exactly what it would have done otherwise.
The test mode (such as continue-on-error or stop-on-fail) will not affect whether the
program traps, and whether the program traps will not affect what the program does on
continue. Any changes you make to the handling of that error when at the trap (using
immediate commands) will not take effect for that instance of the error.
For safety reasons, you cannot trap on errors that take the FORCE_HALT action. The
program will not trap on errors with action IGNORE.
The IMAGE debugger also allows you to step to a run-time error.
Listing Breaktraps
List the current traps set, including the trap numbers, using the SET>LIST TRAPS selection.
When you issue this command, a list of current traps and the current state of the program
similar to the following is displayed in the station window:
Program is stopped in function vout1() at line 97
->trap 1: function vout1 line 97: "set meter input:pin = vout src:v;"
You can also list traps using the listtrap command. The syntax is:
listtrap [-current]
where:
-current Changes the output format of the trap list to a form that can be
executed as a command file.
You can use the listtrap -current command to save breaktraps by first listing and
directing the output to a scratch file. Then you can restore them by executing that scratch
file. For example, to save your breaktraps to the test program file saved_traps use:
listtrap -current > saved_traps
You can then log off and leave your station. When you return, reload using:
IMAGE Solutions V8.3 7-13
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
load <progname> -debug; source saved_traps
This reloads your test program with all the traps you set.
Deleting Breaktraps
To delete breaktraps, use the UNSET button in the station window control panel. Press
MENU on UNSET to display the following menu:
UNSET AT SELECTED LINE
Delete the trap at the selected line. (This is the default for the
UNSET button.)
UNSET TRAP ON TEST Delete the trap at the selected test.
UNSET TRAP ON FAILED TEST
Delete the trap at the failing test.
UNSET TRAP ON PASSED TEST
Delete the trap at the passing test.
UNSET TRAP ON PATTERN START
Delete the trap at the beginning of the digital pattern.
UNSET TRAP ON ALARM Delete the trap at the alarm.
UNSET TRAP ON READ METER
Delete the trap at the read meter statement.
UNSET TRAP ON RUN TIME ERROR
Delete the run-time error trap. (See “Setting Breaktraps on Run-
Time Errors” on page 7-13.)
UNSET TRAP ON TEST NUMBER
Delete the trap at the selected test number.
UNSET ALL TRAPS Delete all traps set in the test program.
To delete a line-number trap, select any character in the line and click SELECT on UNSET.
When a trap is removed, the debugger removes the stopsign. If the line has no executable
code, the next line in the function with executable code is used. If the line you specify has
no trap, you get an error.
You can also delete traps by typing the unsettrap command in the station window. This
command has the following syntax:
unsettrap [<trapnumber>] [-all] [-line <number>] [-test] [-failedtest]
[-passedtest] [-alarm] [-patternstart] [-readmeter] [-error]
[-test <number>]
where:
<trapnumber> Specifies the number of the trap to delete. Display the number
using the listtrap command.
IMAGE Solutions V8.3 7-14
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
-all Deletes all traps set in the test program.
-line <number> Deletes the trap at line <number>.
-test Deletes the trap at the selected test.
-failedtest Deletes the trap at the failing test.
-passedtest Deletes the trap at the passing test.
-patternstart Deletes the trap at the beginning of the digital pattern.
-alarm Deletes the trap at the alarm.
-readmeter Deletes the trap at the read meter statement.
-error Deletes the run-time error trap.
-test <number> Deletes the trap at the specified test number.
Using Breaktraps During Program Execution
To use a breaktrap, click TO TRAP or enter the runtotrap command. The debugger runs the
program up to the first trap and stops. (To execute a program without stopping at any traps,
use the RUN button or run command.) The debugger checks that the line the program
stopped at is on the screen, changing files or scrolling if necessary. An arrow appears to the
left of the trapped line.
NOTE
The IMAGE debugger does not support running to breaktraps during multi-threaded
execution. The debugger runs programs single-threaded if you use one or more breaktraps
and run to trap.
Figure 7-4 on page 7-12 shows the source window stopped at a trap with the arrow next to
the stop sign. When you singlestep with step or next commands, the arrow follows the path
of execution.
This section describes commands you can use to run a test program with breaktraps.
Running a Test Program to a Trap
To run a test program to a trap, use the TO TRAP button in the station window. Press MENU
on the TO TRAP button to display the following menu:
RUN TO TRAP Run the test program to the trap. (This is the default.)
LOOP TO TRAP Rerun the test program until either a breaktrap is encountered or
the program experiences an exception of some sort (such as a
run-time error or a SEGV). A CONTROL-C in the station window
IMAGE Solutions V8.3 7-15
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
or the station ABORT button will stop the test program right where
it is.
You can also enter the runtotrap command in the station window. This command has the
following syntax:
runtotrap [-station #] [-retest] [-nostats] [-loop] [-args ...]
where:
-station <#> Specifies the station number to run the test program.
-retest Retests the device using the same serial number.
-nostats Suppresses printing run-time statistics for the test program after
the run.
-loop Reruns the test program until either a breaktrap is encountered
or the program experiences an exception of some sort (such as
a run-time error or a SEGV). This parameter works with other
runtotrap command options. A CONTROL-C in the station
window or the station ABORT button stops the test program right
where it is.
-args ... Pass one or more parameters to main(). (See “Passing
Command Line Parameters to main()” on page 5-23.)
Stepping Through a Test Program
The step command allows you to step through a test program. You can step to any
trappable ATE condition, or you can select a line and step to it. To use step, press MENU
on the STEP menu button in the station window control panel. The following menu is
displayed:
SINGLESTEP, STOPPING IN CALLED FUNCTIONS
Run the test program to the next trappable function.
STEP TO SELECTED LINE Run the test program to the selected line.
STEP TO TEST Run the test program to the selected test.
STEP TO FAILED TEST Run the test program to the first failing test.
STEP TO PASSED TEST Run the test program to the first passing test.
STEP TO PATTERN START
Run the test program to the beginning of a digital pattern. Used
to start debugging a digital pattern.
STEP TO ALARM Run the test program to an alarm.
STEP TO READ METER Run the test program to a read meter statement.
IMAGE Solutions V8.3 7-16
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
STEP TO RUN TIME ERROR
Run the test program to a run-time error. (See “Setting
Breaktraps on Run-Time Errors” on page 7-13.)
STEP TO TEST NUMBER Run the test program to the selected test number.
You can also type the step command in the station window. The command has the
following syntax:
step [<n>] [-line <number>] [-test] [-failedtest] [-passedtest]
[-patternstart] [-alarm] [-readmeter] [-error] [-test <number>]
where:
<n> Specifies the number of steps. For example, step 4 executes
four steps.
-line <number> Runs the test program to line <number>.
-test Runs the test program to the selected test.
-failedtest Runs the test program to the first failing test.
-passedtest Runs the test program to the first passing test.
-patternstart Runs the test program to the beginning of a digital pattern.
-alarm Runs the test program to an alarm.
-readmeter Runs the test program to a read meter statement.
-error Runs the test program to a run-time error. (See “Setting
Breaktraps on Run-Time Errors” on page 7-13.)
-test <number> Runs the test program to the specified test number.
The step command descends into called subroutines. If the program is not stopped at a
breaktrap and you execute step, you step into the first line of main(). An exception is that
you cannot SINGLESTEP once stopped at trap-on-alarm for an alarm due to a floating-point
exception. You can use the STEP TO SELECTED LINE menu item (step -line <n> command
line) or the cont (continue) command.
NOTE
The function tl_read_char_nowait can cause a problem during debugging. If you are
stopped in a trap and step into this function, you will lose IMAGE and have to reboot.
Whenever a program stops at a breaktrap, the source window changes to display the trap
and an arrow appears next to the trap. If a program stops because it has run to trap or
because you have used the step or next commands, the arrow is hollow with a white
outline. If it stops from using CONTROL-C, a program fault, or a run-time error, the arrow is
solid and grey.
IMAGE Solutions V8.3 7-17
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
Thus, the arrow tells you whether the program is active or not. If the arrow is white it is
active, and you can use the cont, step, or next commands or examine hardware or look
at local variables. If the arrow is gray, it is inactive and you cannot use cont, step, or next;
power is turned off to the DUT. (This may indicate a run-time error.)
Continuing to the Next Breaktrap
Click SELECT on the CONT button to continue to the next breaktrap after a program stops
for a trap or after a step or next command. You can also type cont in the station window.
It has the following syntax:
cont [-station #] [-repeat <n>] [-nostats] [-toend]
where:
-station <#> Specifies a station number.
-repeat <n> Continues <n> times without refreshing between commands.
Use CTRL-C if you need to interrupt the test program.
-nostats Continues without printing out the test program run-time
statistics.
-toend Continues to the end of the program unless stopped by an error
in the program or a CTRL-C. This option cannot be combined
with the -repeat option.
Stepping to the Next Executable Line
Click SELECT on the NEXT button to step to the next executable line in the current function.
You can also type next in a station window. This command has the following syntax:
next [<n>]
where:
<n> Specifies the number of steps. For example, next 4 executes
four steps.
The next command goes to the next line in the current function. Like the step command,
next includes an option that allows you to execute the command a number of times.
Another command you can use to change the display is VIEW>TRAP ARROW TO TOP in the
source window. If you are stopped at a trap, this command changes the display to put the
trap arrow to the top of the window, changing files if necessary.
Moving Within a Function Calling Sequence
Each function in an IMAGE test program has a calling sequence. This sequence is the
succession of statements within the program that calls a function. For example, in one
calling sequence main() may call function aa() which calls function bb(). You can see this
calling sequence using the where command.
IMAGE Solutions V8.3 7-18
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
Each function in a function calling sequence is called a “frame.” For instance, main() calls
aa(), which calls bb(), and the program stops in bb(). In this case there are active frames
for main, aa, and bb. Each time a test program stops, at a trap or for some other reason
(such as a CONTROL-C or a SEGV), IMAGE sets the “current frame” to the stopped frame.
The IMAGE debugger includes commands that allow you to move within a function-calling
sequence in a test program. The up command allows you to move up in the sequence. The
down command allows you to move down. You must type these commands. They are not
available as buttons.
Each up command resets the current frame to the previous calling frame which is a user
function and highlights the source line for that frame. The next up command moves the
current frame one more user frame and highlights that source. The where command shows
a > at the start of the where output line which is the current frame.
The down command works in reverse. Each down command moves the frame toward the
stopped function.
If you use up at the top frame (main()) or down at the bottom frame, the current frame text
is highlighted again without error.
Halting a Test Program
When a program is stopped at a trap, commands on other stations are locked out. The halt
command tells IMAGE that the program is no longer stopped at a trap. The halt command
also reverts the hardware to the hardware reset state and turns power off to the DUT. After
a halt, local variables cannot be printed.
Press MENU on the HALT button in the station window to display a menu with the following
choices:
HALT PROGRAM IF AT TRAP
Stop the test program running if it is at a trap. The trap arrow is
removed from the source window. (This is the default.)
HALT AND SNAPSHOT DISPLAYS
Stop the test program running if it is at a trap but do not reset the
debug displays. This command does not cause the displays to
revert to the hardware reset state. The trap arrow is removed
from the source window.
PRINT CALLING HISTORY FROM CURRENT TRAP (WHERE)
Print the list of called functions starting with the current function.
You can also halt a test program by typing the halt command in the station window. It has
the following syntax:
halt [-snapshot]
where:
-snapshot Stop the test program running if it is at a trap but do not reset the
debug displays.
IMAGE Solutions V8.3 7-19
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
Printing a Function-Calling History
When a program is trapped, use the PRINT CALLING HISTORY option or type where in the
station window to list the function calls that got the program there. The list starts with the
function the program is currently in, then lists the function that called it, and so on, back to
main(). This is useful when a program stops for a fault in that program, such as a
segmentation fault or from a CONTROL-C.
For example, a test program is stopped at a trap at a read_meter statement. The where
command would display something like the following:
smith% where
tl_trap at 0x197b8
tl_sim_read_meter at 0x48080
tl_read_meter_m601 at 0x6e868
read_meter at 0x817bc
> vout1(), line 98 "vout1[x] = read_meter();"
seq1(), line 53 "seq vout1() $1 > 4.50v < 5."
main(), line 41 "bin_number = seq1();"
The where command shows a > at the start of the current function. The current function is
explained in “Moving Within a Function Calling Sequence” on page 7-18.
Using Function Keys
You can also execute trap commands using the OpenWindows function keys feature. This
feature allows you to use the F# keys at the top of the keyboard to execute the following
functions:
F1 Run a program.
F2 Halt a program.
F3 Continue a program.
F4 Step through a program.
F5 Next executable line.
To see which keys execute which functions, select UTILITIES>FUNCTION KEYS from the
IMAGE Workspace menu. This displays a window (figure 7-5) showing the function
assigned to each key. (If your pointer is not in the station window, the keys are blank.)
IMAGE Solutions V8.3 7-20
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
Figure 7-5. Station Window and Function Keys Window Showing Key Functions
You can disable these key functions if you wish to use the keys in other ways. Select GLOBAL
STATION WINDOW OPTIONS from the IMAGE Properties window and set ENABLE FUNCTION
KEYS to FALSE. (See “Global Station Window Options” on page 3-34.)
Breaktrap Placement
Where can you place a breaktrap? Generally, the ending semicolon of an ITL statement is
the trappable symbolic line number for that statement. When a statement extends over
several source lines, the trap point is on the line containing the semicolon of the statement.
You can trap on the “return” statement of a function or the closing curly brace of a function
which does not return a value. If the function returns a value, a breaktrap on the closing curly
brace will not be hit.
You can also set traps on an initialized automatic variable declaration. (The act of assigning
a value to the variable is executable and so trappable.)
SEQUENCER functions have a line of “invisible” executable code (code not displayed in the
source window) on the same line as the opening brace of the function. If you step into the
function, you will stop at that invisible line before stepping to your own visible line.
When you set a trap on a for() statement, the program traps on the initialization part (the
first part) of the statement.
You cannot set a breaktrap at an end brace with a return(val) statement. If you place a
breaktrap on the closing brace of a function, it will not be hit if an explicit return statement is
executed.
IMAGE Solutions V8.3 7-21
IMAGE Base Language: Debugging Test Programs: Breaktraps
Table of Contents Index Home Master Index Search Help
When a program is edited, traps do not “move.” That is, IMAGE tries to associate each trap
with the text of the line on which the trap originally appeared. (However, always check the
locations of breaktraps after editing.)
If a function is deleted, all traps in it are deleted.
IMAGE Solutions V8.3 7-22
IMAGE Base Language: Debugging Test Programs: Editing and Compiling Functions
Table of Contents Index Home Master Index Search Help
Editing and Compiling Functions
You edit a test program in the source window using commands in the EDIT button menu and
other commands in the source window control panel. All source window commands are also
contained in a source window pop-up menu (figure 7-6). (Place the pointer anywhere in the
text pane of the source window and press MENU.) You can also use most debugger and
tester commands and all Solaris Text Editor commands while editing. Commands you
cannot use are: edit, compile, save, library, revert, chfile, newversion, and
load_file.
Figure 7-6. Source Window Pop-up Menu
As you edit, IMAGE can compile your changes incrementally, reducing the time needed to
edit and compile files. The debugger also keeps an edit history of your changes, allowing
you to undo changes. For instance, you can command the debugger to revert to an older
version of a program. You can also save the current state of a test program on disk at any
time while in debug.
When you finish editing and exit the editor, the new source is compiled and linked into the
test program. You must save (or discard) changes when exiting debug. (See “Exiting
Debug” on page 7-37.)
Editing a Test Program
To use editing commands, press MENU on the EDIT button in the source window control
panel and select EDIT FILE from the menu. The following menu is displayed:
EDIT FILE>EDIT Enter the editor to edit the current file in the source window. The
file must not be write-protected.
EDIT FILE>EDIT -NOSAVE
Enter the editor to edit the current file in the source window but
do not save any changes.
IMAGE Solutions V8.3 7-23
IMAGE Base Language: Debugging Test Programs: Editing and Compiling Functions
Table of Contents Index Home Master Index Search Help
AGAIN Repeat the last editing action.
UNDO> Undo the last editing action or all editing actions.
COPY Store a copy of the selected text on the clipboard.
PASTE Insert contents of the clipboard at the insertion point.
CUT Remove the selected text and store it on the clipboard.
You can also enter the editor by typing the edit command in the station window. This
command has the following syntax:
edit [-nosave]
where:
-nosave Enters the editor but does not save any changes.
When you enter the editor, the message EDIT MODE is displayed in the message region,
and all breaktrap indicators (stopsigns and arrows) disappear. Edit commands are
described in the on-line Help handbook and in the Sun manuals OpenWindows Version 3
User’s Guide and CDE 1.0 User's Guide.
If you have moved the pointer into the source window, the point at which text is inserted into
your file (the insertion point) is denoted by a blinking triangular caret. When you are not in
the source window, the pointer becomes a grey diamond. When you enter the editor, the
insertion point is at the end of any selection in the window. If you make no selection, the
insertion point is where it was when you last edited the file. If you have never edited the file,
the insertion point is at the top of the file.
Make sure you know where new text will be inserted before you start typing, since the
insertion point is not always on the screen. To find the current insertion point, select
VIEW>SHOW CARET AT TOP from the source window menu.
You can enter the editor when stopped at a breaktrap. As soon as you compile, however,
the debugger halts the test program.
Compiling Changes
Test programs, either new programs or edited programs, must be compiled before they can
be run. Use the COMPILE menu button in the source window control panel to compile test
programs. You can also type the compile command in the station window.
Compiling in Debug Mode
You can compile a test program at any time while you are in debug mode. Press MENU on
COMPILE to display the following menu items:
COMPILE ALL, ENABLE AUTO-COMPILE
Compile the test program. If errors exist, they are listed and the
program does not compile. Compiles all functions that need
compiling and links all functions that need linking. Also turns
IMAGE Solutions V8.3 7-24
IMAGE Base Language: Debugging Test Programs: Editing and Compiling Functions
Table of Contents Index Home Master Index Search Help
automatic compiling back on if auto-compilation is off. (This is
the default.)
DISABLE AUTO-COMPILE Turn off auto-compilation (the feature that automatically
compiles and links all the functions after editing).
FORCE RECOMPILE OF CURRENT FILE
Recompile the entire current file. Typically, this command is not
needed.
Compiling in Edit Mode
If you enter edit mode and edit a test program, the sections of the program you changed
must be compiled before you can run it. In fact, compiling the program is the normal way of
exiting the editor. If you are in edit mode, press MENU on COMPILE to display the following
menu items:
EXIT AND COMPILE Exit the editor and compile the test program. If errors exist, the
program does not exit from the editor. This option compiles all
functions that need compiling and links all functions that need
linking. It also turns automatic compiling back on if auto-
compilation is off. The first compiler error is displayed and
highlighted in reverse video. It becomes the selection. (This is
the default for the COMPILE button in edit mode.)
EXIT, DON’T COMPILE Save the edits made to the test program and exit the editor
without compiling.
NOTE
A test program must be compiled (or recompiled if it has been edited) before it can be run.
QUIT (IGNORE EDITS) Exit the editor and do not save any edits made to the test
program.
The file header (the top of the file containing macro definitions, declarations, and so on)
must compile correctly before file functions can compile. Therefore, you may see the
following message when compiling if the header has errors:
Cannot compile. Bad header section.
You must correct the errors before other functions in the file can be compiled.
Header files should not contain definitions of variables, only declarations. That is, a header
file can contain extern int i; but should not contain int i;. Loading a header file
containing variable definitions gives a warning.
If you exit the editor without compiling and the file contains certain errors, functions with
these errors cannot be compiled. If you try to compile, the following message appears:
Errors after line #. Cannot compile.
IMAGE Solutions V8.3 7-25
IMAGE Base Language: Debugging Test Programs: Editing and Compiling Functions
Table of Contents Index Home Master Index Search Help
You must correct these errors before the functions will compile.
Compiling Using the compile Command
You can also compile by typing the compile command in the station window. (You cannot
use this command if you are in edit mode.) This command has the following syntax:
compile [-force] [-off] [<function(s)>]
where:
-force Recompiles the entire current file. Typically, this command is not
needed except when IMAGE header files have changed after a
release.
-off Turns off auto-compilation (the feature that automatically
compiles and links functions after editing).
<functions> Compiles and link only the specified function and only if
necessary.
Incremental Recompiling
IMAGE includes an incremental recompile feature. With this feature, you make edits to a
program loaded in the station window. Then, when you edit a program, only those functions
you changed are recompiled. This speeds up the edit/recompile/run cycle.
In general, you recompile each function as you edit it. Editing comments between two
functions does not cause the functions to be recompiled, but editing comments within a
function does. When recompiling a function, any static variables declared in the function are
reinitialized to the initial value following the equal sign or to zero if no initial value is
specified.
Editing global variables in the header causes all global variables to be recompiled. When
recompiled, initialized variables (variables followed by an equal sign) are reinitialized to the
specified initial value, but uninitialized variables (variables not followed by an equal sign)
retain their current value.
NOTE
Uninitialized variables always start with a value of zero. They are initialized to zero when the
test program is loaded or when a new variable is created while editing.
Some changes made while editing cannot be handled incrementally because they cause
global changes. These changes include edits to:
• A pinmap
• A header file
• A macro definition (#define)
IMAGE Solutions V8.3 7-26
IMAGE Base Language: Debugging Test Programs: Editing and Compiling Functions
Table of Contents Index Home Master Index Search Help
• The list of include files (#include)
• A typedef or the definition of a struct, union, or enum
• An extern declaration
If one of these is changed, the entire file is recompiled. Note that changing only a comment
associated with one of these does not cause recompiling. If you change a header file that is
included by multiple source files, all the dependent source files are recompiled.
Duplicate Compiling
At times, the compiler may behave as if it is compiling a function more than once. The
standalone compiler (itlc) only compiles each function once. (See “Standalone IMAGE
Compiler” on page 7-38.) The compiler used during edit/recompile, however, occasionally
compiles a function more than once. The following example functions show why this may
happen:
int func1()
{
double d;
d = func2();
}
double func2()
{
return 2.0;
}
If both functions in this example are not compiled, func1 is compiled first and then func2 is
compiled as a result of either the compile or exitedit command. When func1 is compiled
the compiler does not know the type of the return value of func2 and, therefore, assumes
that it returns an integer. When func2 is compiled, the compiler learns that func2 returns a
double. Since func1 references func2, it must be recompiled. IMAGE, therefore,
invalidates the first compile of func1 and compiles it again.
This recompile results from not declaring functions before referencing them. In standard C
when this situation occurs, func2 must be declared at the top of the file using extern
double func2();. IMAGE does not require this.
Managing Binaries for Different CPU Types or Operating Systems
Binary files cannot be shared between SUN3 and SUN4 (SPARC) computers. You must
compile source files separately for the two architectures. Binary files for the OS 4.1 and
Solaris 2 operating systems are different and must be compiled separately for each
operating system. IMAGE includes a feature useful for maintaining one set of source files
but compiling the sources separately for use on different CPU types or on different operating
systems.
NOTE
IMAGE V5.0 and later does not support Sun3 test systems.
IMAGE Solutions V8.3 7-27
IMAGE Base Language: Debugging Test Programs: Editing and Compiling Functions
Table of Contents Index Home Master Index Search Help
To use this feature, keep the different binaries in separate subdirectories below the test
program directory. Name the subdirectories sun3, sun4, and/or sun4V. Commands that
read or write test program files (load, itlc, load_file, chfile, save, and store)
automatically read or write binary files from or to these subdirectories.
Architecture and operating system specific files are kept in the sun3, sun4, and sun4V
subdirectories. Architecture- and operating-system-specific files are files with these
extensions:
.bin Binary test program files.
.a Library files (created with the ar command or itlc -archive).
.o Object files (created with the cc command or itlc -ofile).
.exec Special binary files used for test system checkers only.
Other files, such as .tl, .load, .pat, .wav, and .h, are independent of the computer
architecture and operating system. Their location is not affected by the machine type or
operating system, so they are kept in the main test program directory. In general, whenever
a filename is specified, the name is changed if the following criteria are met:
• The name ends in .bin, .o, .a, or .exec
• A sun3 subdirectory exists if running on a SUN3
• A sun4 subdirectory exists if running on a SUN4 (SPARC) under OS 4.1
• A sun4V subdirectory exists if running on a SUN4 (SPARC) under Solaris 2
• A sun3, sun4, or sun4V subdirectory is not already specified in the filename
Examples:
• If using itlc to compile x102.tl on a SUN3 system, the binary is written to sun3/
x102.bin if the sun3 subdirectory exists.
• Executing load x102 mylib.a on a SPARC system running OS 4.1 reads sun4/
x102.bin and sun4/mylib.a if the sun4 subdirectory exists.
• Executing load x102 on a SPARC system running Solaris 2 reads sun4V/x102.bin if
the sun4V subdirectory exists.
• Executing either load /h/green/harry/job/x102 or load /h/green/harry/job/
sun4/x102 results in the file /h/green/harry/job/sun4/x102.bin being read,
assuming the command is executed on a SPARC computer running OS 4.1 and the
sun4 subdirectory exits. Note, however, that in the first case the source file is assumed
to be in /h/green/harry/job, but in the second case it is assumed to be in /h/green/
harry/job/sun4.
In a debug session, after making source-level changes, the changes are usually compiled
and the binary saved. This only updates binaries for the architecture or operating system of
the machine used during the debug session. To update binaries for another architecture or
operating system, log in to a machine of the other architecture or operating system and use
itlc to compile. You can specify the name of a .load file to itlc to simplify compiling all
files in a test program.
Use the rlogin command to log in to another machine without leaving your workstation.
IMAGE Solutions V8.3 7-28
IMAGE Base Language: Debugging Test Programs: Editing and Compiling Functions
Table of Contents Index Home Master Index Search Help
You cannot accidentally use an out-of-date binary file. The load command checks that the
binaries being read are up to date and rejects any that are out of date with respect to the
source files.
In one case, however, this consistency check does not take place. This is if you load a test
program in production (not using the -debug switch), and the source files are not available
to the load command. The source files are not available if the load command cannot find
them in the directories used to load the test program and you do not use the -source option
to specify the location of the sources. The -source option, in a .load file, allows you to
specify additional directories in which to look for source files. (See “Loading Using the load
Command” on page 5-4.)
Exiting the Editor
The normal way to exit the editor is to click SELECT on the COMPILE button. This exits the
editor and compiles the program. If you press MENU on COMPILE, the following menu is
displayed:
EXIT AND COMPILE Exit the editor and compile the test program. If errors exist, the
program does not exit from the editor. The first compiler error is
displayed and highlighted in reverse video. It becomes the
selection. (This is the default for the COMPILE button in edit
mode.)
EXIT, DON’T COMPILE Exit the editor regardless of errors and do not compile the test
program.
NOTE
A test program must be compiled (or recompiled if it has been edited) before it can be run.
QUIT (IGNORE EDITS) Exit the editor and ignore all changes made to the test program.
The test program remains as it was before entering the editor.
You can also display this menu using the EXIT EDITOR command in the source window pop-
up menu. Place the pointer in the text pane of the source window and press MENU. Select
EXIT EDITOR and pull right to display the menu.
You can also exit the editor by typing the exitedit command in the station window. This
command has the following syntax:
exitedit [-quit] [-nocomp]
where:
-quit Exits the editor and ignores all changes made to the test
program. The test program remains as it was before entering the
editor.
IMAGE Solutions V8.3 7-29
IMAGE Base Language: Debugging Test Programs: Editing and Compiling Functions
Table of Contents Index Home Master Index Search Help
-nocomp Exits the editor regardless of errors and does not compile the
test program.
IMAGE Solutions V8.3 7-30
IMAGE Base Language: Debugging Test Programs: Manipulating Test Program Files
Table of Contents Index Home Master Index Search Help
Manipulating Test Program Files
The source window includes commands that allow you to load test programs and to save
ones you have edited. The FILE button in the control panel has the following menu items:
SAVE TEST PROGRAM Saves the edited test program. (This is the default.)
STORE AS NEW FILE... Creates a new test program file.
VERSIONS> Creates a new version of the test program, recalls another
version, or lists the versions. (See “Edit History—New Version,
Versions, Revert” on page 7-33.)
LOAD FILE... Loads another source file.
Saving Test Programs
When you finish editing a program, or if you must exit debug, you can save your edits to disk
using FILE>SAVE TEST PROGRAM or by entering the save command in a station window. This
saves all modified sources and binaries on disk. Before saving source files, any existing
source files are preserved by appending a percent sign (%) to their names. This provides a
single level of backup.
SAVE writes binaries to separate SUN3 and SUN4 (SPARC) OS 4.1 and SUN4 Solaris 2
directories if they exist. (See “Managing Binaries for Different CPU Types or Operating
Systems” on page 7-27.)
Storing a Test Program in a File
Instead of saving the existing test program to the same file when you finish editing, you can
store the test program as a new file. To store a file under a new name:
1. Select FILE>STORE AS NEW FILE. The Store Test Program as New File window (figure 7-
7) is displayed.
2. Select the directory where you want to store the file.
3. Enter the new filename in the FILE field.
4. To change the name of the current file and save it, check the option USE NEW FILENAME
FOR SAVE.
Figure 7-7. Store as New File Window
IMAGE Solutions V8.3 7-31
IMAGE Base Language: Debugging Test Programs: Manipulating Test Program Files
Table of Contents Index Home Master Index Search Help
5. Click STORE AS NEW FILE.
You can also store a file by typing the store command in the station window. This command
has the following syntax:
store <filename> [-change_name]
where:
<filename> Writes a copy of the source and binary of the test program to
<filename>.
-change_name Saves the source and binary of the test program to a new file
called <filename>.
Storing a test program writes a copy of the source and binary of the test program file to a
filename different from the filename used when loading the program. You can use this to
save a temporary copy of a file on disk without changing the original program files or to put
a file in a different directory. If the specified filename contains an extension (.h, .tl, .c, or
.bin), only the source or binary is written, but not both. If you do not specify an extension,
the source is written to <filename>.tl and the binary is written to <filename>.bin. To
store a header file, you must use the .h extension.
Use the STORE>USE NEW FILENAME FOR SAVE option or the command store -change_name
to change the name of a currently loaded file as well as saving it. When you use this option,
the file is written to the specified filename, and in addition the file is now known by this new
name in the loaded test program. If you made no edits to other files in the test program, the
(EDITED) message in the station window header stripe is removed because all changes are
now saved to disk. You can now delete the test program without using the -nosave option
since all edits are saved. If you make additional edits and use save, the new changes are
saved to the new filename.
When using this option, do not specify an extension unless you are saving a header file.
Both the source and binary files will be written (.tl and .bin). If saving a header file, use
the .h extension.
This option is especially useful when working with released test programs whose files are
write-protected. You can make a change and save it as a new version of the program in one
of two ways:
• Use the EDIT -NOSAVE menu item or command and edit the write protected file. Then use
the CHANGE NAME OF CURRENT FILE AND SAVE menu item or the store -change_name
command to save the changed file to a new name.
• Use the USE NEW FILENAME FOR SAVE option in the Store window or the store
-change_name command to create a copy of the write-protected file. Edit the file. Then
use SAVE to save your changes.
With either method, you now have both the original version of the program and the modified
version on disk. Note that if you use a .load file, you must copy this and edit it by hand.
STORE writes binaries to separate SUN3 and SUN4 (SPARC) OS 4.1 and SUN4 Solaris 2
directories if they exist. (See “Managing Binaries for Different CPU Types or Operating
Systems” on page 7-27.)
IMAGE Solutions V8.3 7-32
IMAGE Base Language: Debugging Test Programs: Manipulating Test Program Files
Table of Contents Index Home Master Index Search Help
Edit History—New Version, Versions, Revert
The debugger maintains an edit history of a test program. A new version is created when a
test program is first loaded, when it is saved to disk, and when you create a new version.
You can return to earlier versions at any time during debug. To use different versions of a
test program, select FILE>VERSIONS and pull right. This displays a menu with the following
selections:
CREATE NEW VERSION Creates a new version of the test program file.
LIST VERSIONS Displays a list of all edit history versions of the test program.
REVERT TO SELECTED VERSION
Returns to an old version of the test program.
Creating a New Version
Use VERSIONS>CREATE NEW VERSION to create a new version of the program in the edit
history list. You can also create a new version by typing the command newversion in the
station window. A comment is requested when using this command. You can use this
comment later to help identify the version.
Listing Versions
Edit history versions are numbered starting at 1. Use the VERSIONS>LIST VERSIONS to
display a list of all edit history versions. An example would be as follows:
EDIT HISTORY ( ==> - Current version D - Saved on disk)
D 1 09:42 (Original program.)
2 12:25 (Prior to loading 'pinmap.h'.)
==> 3 12:25 (After loading 'pinmap.h'.)
...Changes have been made to version 3.
You can also type the versions command in the station window. This command has the
following syntax:
versions [<from> [<to>]] [-fdiff | -diff [-context]]
where:
<from> Specifies the starting version of the list.
<to> Specifies the ending version of the list.
-fdiff Lists all test program functions that have changed.
-diff Lists any differences between two versions.
-context Puts context lines around changed lines. (Used with -diff.)
If the history list is large, you can use the command:
versions [<from> [<to>]]
IMAGE Solutions V8.3 7-33
IMAGE Base Language: Debugging Test Programs: Manipulating Test Program Files
Table of Contents Index Home Master Index Search Help
to specify a starting and ending version to display a part of the list. The list of versions
indicates which version is current, whether changes have been made to that version, and
which version is stored on disk.
The command versions -fdiff lists the names of all functions in the program that have
changed between the versions, as in:
FUNCTIONS CHANGED FROM VERSION 3 TO CURRENT VERSION.
File: pinmap.h
HEADER
The command versions -diff runs the Solaris diff program on two versions of the
current file (the file displayed in the source window) and displays any lines that have
changed. This output can be redirected to a file.
The command versions -diff -context changes the format of the output and puts lines
of context around the changed lines.
By default, the differences shown are the changes made to the program since the last
version. If no changes were made since the last version, the differences shown are the
differences between the last two versions. To see differences between two other versions,
you can specify one or two version numbers. If you specify one number, the difference is
between that version and the current state of the program. If you specify two numbers, the
difference is between those two versions.
Reverting to an Older Version of a Test Program
The VERSIONS>REVERT TO SELECTED VERSION item returns you to an old version of the test
program. To revert to an old version:
1. List the versions in the station window using VERSIONS>LIST VERSIONS.
2. Select a version number from the list by highlighting it.
3. Press MENU on the FILE button and select VERSIONS>REVERT TO SELECTED VERSION.
If changes were made to the current version of the program, you are asked if you want to
create a new version with those changes before reverting.
You can also revert by typing the revert command in the station window. This command
has the following syntax:
revert <version>
Version 1 is the version originally loaded. Therefore, revert 1 restores a program to its
original version. revert 0 restores the program to the version currently saved on disk.
Loading a File
While in debug, you can load a file that exists on disk but is currently not a part of the loaded
test program. (This is similar to using the chfile command with the name of a file that exists
on disk but is not currently a part of the loaded test program.)
To load a file:
IMAGE Solutions V8.3 7-34
IMAGE Base Language: Debugging Test Programs: Manipulating Test Program Files
Table of Contents Index Home Master Index Search Help
1. Select FILE>LOAD FILE. The Load File window (figure 7-8) appears.
2. Select the directory and filename.
3. Click on a check box to select options: NEW loads a new file; RELOAD loads a file that was
already loaded; FORCE reloads the file, discarding any edits.
4. Click LOAD FILE.
Figure 7-8. Load File Window
The NEW option allows you to start a new file not currently on disk. If the file exists, an error
message is issued.
The RELOAD option reloads a file already loaded. This command fails if edits were made to
the file in the station window.
The FORCE option forces reload of a file, discarding any edits and overwriting the file using
the file on disk. This option is most useful when using a tool external to the station window
that modifies the source files, such as an automatic program generation tool that writes
source files.
You can load a file by typing the load_file command in the station window. This command
has the following syntax:
load_file <filename> [-reload [-force] | -new]
where:
<filename> Specifies the file to load.
-reload Reloads a file already loaded.
-force Reloads a file, discarding any edits and overwriting the file on the
disk.
-new Loads a new file.
This command also loads the appropriate binary for separate SUN3 and SUN4 (SPARC)
OS 4.1 and SUN4 Solaris 2 directories if they exist. (See “Managing Binaries for Different
CPU Types or Operating Systems” on page 7-27.)
IMAGE Solutions V8.3 7-35
IMAGE Base Language: Debugging Test Programs: Manipulating Test Program Files
Table of Contents Index Home Master Index Search Help
Recovering Edits After a System Crash
While in debug, each time you execute the save command, any changed files are written to
the disk. One level of backup is automatically maintained for source files (.tl and .h files).
Each time you do a save, the old version of the file is copied to a file with the same name
but with a percent sign (%) appended.
To protect against losing work in case of a test system problem, use the save command
often, so that the disk copy of the program is always up to date. This, however, is often
undesirable. You often want to verify that all changes work correctly before replacing the
disk copy of a program with a new copy.
A checkpointing feature allows you to maintain intermediate, nearly up-to-date copies on
disk automatically. If you enable this feature and the test system crashes after you make
many changes, you can recover most of your changes.
To enable checkpointing, use the .Xdefaults file, the file in your home directory containing
defaults for the windowing system. Using an editor, add the following line to your
.Xdefaults file:
Text.CheckpointFrequency: <value>
where <value> is how often (after how many characters) the checkpoint file should be
updated. A value between 50 and 200 is usually appropriate. If you set the value at 100, for
example, a new file is written every 100 edits. Every character typed is an edit. A cut and
paste counts as one edit.
The checkpoint file name is the name of the file you are editing with two percent signs (%%)
appended. It is usually in the same directory as the file you are editing. Rarely, these files
may appear instead as:
/image/tester/<hostname>/tmp/<filename>.tmp%%
where <hostname> is the name of your machine and <filename> is the name of the file you
are editing.
IMAGE Solutions V8.3 7-36
IMAGE Base Language: Debugging Test Programs: Exiting Debug
Table of Contents Index Home Master Index Search Help
Exiting Debug
Once you are in debug, the DEBUG button in the station window changes to EXIT DEBUG. To
exit debug, click this button. If you have unsaved changes, you are warned. At this point,
you can either save your edits or exit without saving.
You can also exit debug using the exitdebug command. The syntax is:
exitdebug [-nosave] [-station #]
where:
-nosave Exits debug without saving any edits.
-station # Specifies a test station to use for exiting debug.
You cannot exit debug if you are editing a test program. You must exit the editor first. (See
“Exiting the Editor” on page 7-29.)
When a station is not in debug, the loaded program must be identical to the one on disk.
Therefore, if you edited the test program but have not saved the edits, typing the exitdebug
command in a station window fails. (Clicking on the EXITEDIT button prompts you to save or
not save your edits.) At this point you can do one of the following:
• Save your changes using the SAVE command in the editor.
• Return to the version last saved using the revert command.
• Type exitdebug -nosave or click on EXIT DEBUG and select to ignore any changes at
the prompt. This discards the changes and reverts the program to match the version
already on disk.
• Stay in debug.
Some IMAGE commands take a station out of debug: DELETE (command or station window
button) and the imageexit command or EXIT on the IMAGE Workspace menu. If a loaded
program has unsaved edits, you are prompted to save the edits or to exit without saving.
IMAGE Solutions V8.3 7-37
IMAGE Base Language: Debugging Test Programs: Standalone IMAGE Compiler
Table of Contents Index Home Master Index Search Help
Standalone IMAGE Compiler
IMAGE includes the IMAGE Test Language Compiler, a stand-alone compiler you can use
on a Sun workstation. You need not be running OpenWindows to use it.
Using the itlc Command
Use the command itlc to compile ITL programs and produce unlinked object files that can
later be loaded into a test station with the load command. The syntax for the stand-alone
compiler is:
itlc [-force][-make][-define <flag>[=value]]<filename(s)>
[-incdir <pathname>][-localdef <flag>[=value]]
‘ [-object <object_name>] [-ofile] [-archive <library name>]
[-O] [-lxh <lxh_file>] [-source <directory>][-localobj]
[-lint][-lintflags <flags>]
where:
-force Forces compile even if source and binary are consistent.
filenames Are the names of source files to be compiled. Filenames must
have a .tl, .c, or .load extension. If a filename has no
extension, it is assumed to be a .tl file. The object file produced
for a file has the same name. Thus, compiling test.tl gives
test.bin.
-incdir <pathname> Adds the directory specified in <pathname> to the list of
directories searched to locate header files. You can use several
-incdir parameters to specify more than one directory. The
header files must be listed in angle brackets.
In IMAGE V6.3 and later, you can define an environment
variable named TL_INCLUDE_PATH that adds to the include file
search path and behaves exactly like the -incdir switch. (See
“Including a Search File Path” on page 14-5.)
-define/-localdef/-object
Used in conditional compile. (See “Loading for Conditional
Compiling” on page 5-18.)
-ofile/-archive/-O
Used when compiling into standard Solaris object (.o) files. (See
“Compiling Into Standard Solaris Object Files” on page 7-42.)
-lxh <lxh_file> Used to specify compilation of ProGen files. One of the files
produced using ProGen has the extension .lxh.
-localobj Unconditionally places the compiled file in the local directory
(that is, the directory containing the source code being
compiled). This switch overrides placing files in sun3, sun4, or
sun4V directories. It can be useful when compiling ProGen files.
IMAGE Solutions V8.3 7-38
IMAGE Base Language: Debugging Test Programs: Standalone IMAGE Compiler
Table of Contents Index Home Master Index Search Help
-lint Used to check IMAGE test programs for bugs and nonportable,
wasteful code. You can also define -lintflags to modify the
parameters of the -lint switch. (See “Using Lint” on page 7-40.)
Important differences between compiling files in the debugger and compiling them with itlc
are:
• Both itlc and the compiler used in the debugger allow forward references of functions
and global variables, both within files and between files, without explicitly declaring
these as extern. However, itlc can only handle references to other files mentioned to
the itlc command.
• When itlc is compiling a file and an error is detected, it continues to compile the file,
except for certain classes of errors. (The debugger aborts the compile at the end of the
function with the error.) This allows you to produce a partial object file (one containing
binary code for a subset of a file’s functions). You can load partial object files into the
debugger using the -debug switch of the load command.
Using .load Files
The itlc command allows you to specify a .load file and compiles all the source files listed
in the .load file. (See “Using .load Files to Load Test Programs” on page 5-11) To use this
feature, enter:
itlc <prog_name>.load
where prog_name is the name of the test program.
An advantage of compiling all source files with itlc is that references between files are
handled correctly without using extern declarations. For example, if a function is defined
as double abc(), abc can be called in another file and will be known by the compiler to
return a double value. If the files are compiled independently, you must declare the function
as extern double abc() to get correct results.
Forcing Compilation
The -force option causes itlc to compile all files listed regardless of whether binary files
exist for them or whether those binary files are up to date. Without -force, itlc does a
consistency check for each file having a binary file. If the binary file is consistent (matches
its source file), itlc prints a message to that effect and does not compile the file.
Diagnostic Messages
Unlike the Solaris C compiler and similar to the interactive debugger compiler, itlc
produces diagnostic output for each file it compiles, even if no errors are found. Diagnostic
output for a successful compile looks like this:
...reading file myprog.tl
...compiling file myprog.tl
...compiling HEADER
...compiling main
IMAGE Solutions V8.3 7-39
IMAGE Base Language: Debugging Test Programs: Standalone IMAGE Compiler
Table of Contents Index Home Master Index Search Help
.
.
These messages indicate how far the compilation has proceeded and also help in
determining where errors occur. Errors look like:
<stage>: "<filename>", line <number>: <message>
where:
<stage> Indicates the part of the compile that encountered the error.
Possible stages include: splitfmt, cpp, tlp, and ccom
(Solaris1) or acomp (Solaris2).
<filename>/<number>
Is the name of the file with the error and the line it appears on.
<message> Is the explanation of the error.
An example is as follows:
tlp:"tms_demo.tl", line 120: comma operator in expression
Loading Binaries for SUN3 and SUN4 Computers
SUN3 computers, SUN4 computers, and SUN4 computers running Solaris 2 cannot share
binary, library, or object files. A feature of IMAGE allows you to store these architecture- and
operating-system-specific files separately. You do this by creating subdirectories named
sun3, sun4, and sun4V. The itlc command reads the correct file for the computer you are
using from the correct subdirectory if it exists.
For example, using itlc to compile x102.tl on a SUN3 system, the binary is written to
sun3/x102.bin if the sun3 subdirectory exists. For more information, see “Managing
Binaries for Different CPU Types or Operating Systems” on page 7-27.
NOTE
The Sun3 is not supported in IMAGE V5.0 and later.
Using Lint
You can use lint to check IMAGE test programs for bugs and nonportable, wasteful code.
lint issues an error or warning if it finds any of these conditions in a test program. You can
use lint if you are running the Solaris 1 or 2 operating system. For more information on
lint, see its man page in the Solaris environment.
To run lint on a test program, use the itlc command followed by the -lint switch, as in:
itlc -lint file1.tl file2.tl file3.c
itlc outputs the following:
IMAGE Solutions V8.3 7-40
IMAGE Base Language: Debugging Test Programs: Standalone IMAGE Compiler
Table of Contents Index Home Master Index Search Help
...reading file file1.tl
...reading file file2.tl
...reading file file3.c
...compiling file file1.tl
...compiling HEADER
...compiling main
...compiling func1
...compiling func2
...compiling func3
If any cpp/tlp errors occur, they appear associated with the correct function. itlc runs
lint on all files simultaneously, outputs any lint messages, and exits. No permanent files
are created or modified. If .bin or .o files exist for the .tl files, they remain untouched.
You can specify -lintflags that are used during the lint execution. For example:
itlc -lint -lintflags humx file1.tl file2.tl file3.c
The flags you specify are used in place of the default lint flags. You can also specify
-lintflags "" to indicate that no flags should be passed to lint.
The default lint flags are the lint flags itlc uses if you do not specify the -lintflag
switch. These flags are described below for both the Solaris 1 and 2 operating systems.
Solaris 2 operating system flags are as follows:
-h Do not apply heuristic tests that try to intuit bugs, improve style,
and reduce waste.
-m Suppress complaints about external symbols that could be
declared static.
-u Suppress complaints about functions and external variables
used and not defined or defined and not used. This option is for
running lint on a subset of files of a larger program.
-x Do not report variables referred by external declarations but
never used.
Solaris 1 operating system flags are:
-u Do not complain about functions and external variables used and
not defined or defined and not used. This is for running lint on
a subset of files comprising part of a larger program.
-v Suppress complaints about unused arguments in functions.
-z Do not complain about structures that are never defined (for
example, using a structure pointer without knowing its contents).
IMAGE Solutions V8.3 7-41
IMAGE Base Language: Debugging Test Programs: Standalone IMAGE Compiler
Table of Contents Index Home Master Index Search Help
Compiling Into Standard Solaris Object Files
The IMAGE itlc compiler allows compilation into standard Solaris object (.o) files. You
can also have itlc archive the object files into a library file. In this way you can create
libraries of files that are shared among programs and users.
Compiling into .o or .a files makes symbolic debugging of these files impossible. When
compiling into .o or .a files, the Solaris compiler optimizer can be used. (The optimizer
cannot be used with the usual itlc mode because the optimizer conflicts with preparing the
modules for debugging.)
Unlike the usual itlc mode, the files are always compiled, but they are not checked for
consistency between source and binary.
The flag -ofile requests that all source files on the command line be compiled into .o files.
The flag -O requests that compilations use the Solaris optimizer. The flag -archive
<library_name> requests that all objects produced by the compilation be archived into the
file <library name>. This file should have the .a extension.
Note that itlc creates the library file if it does not already exist or replaces the object file in
the library if the library file already exists. (See ar(1) in the Solaris documentation for more
information on managing library files.)
NOTE
When Teradyne forces all files to be recompiled, both itlc and the IMAGE load
mechanism enforce this. If, however, files are compiled into .o or .a files, this cannot be
enforced, and it is your responsibility to recompile the files.
Examples of compile commands:
%itlc -ofile file.tl
Compiles file.tl into file.o.
%itlc -ofile -O file.tl
Compiles file.tl into file.o and runs the Solaris optimizer.
%itlc -archive mylib.a file1.tl file2.tl
Compiles file1.tl into file1.o, file2.tl into file2.o, and archives them both into
mylib.a.
If a subroutine aa() exists in file1.tl, and this file has been compiled into mylib.a as in
the above command, and there is a test program prog.tl which calls aa(), then file.tl
will be linked and aa() resolved with the load command line:
%load prog.tl mylib.a
If mylib.a is being shared among many users or among many work directories, use a full
file specification.
IMAGE Solutions V8.3 7-42
IMAGE Base Language: Debugging Test Programs: Standalone IMAGE Compiler
Table of Contents Index Home Master Index Search Help
If you try to compile a SEQUENCER function into a .o or .a file, you get incorrect results when
running a test program. Therefore, if you try to use itlc to compile a SEQUENCER function
into a .o or .a file you get an error message.
Determining IMAGE Binary File Type
Depending on how it was created, an IMAGE binary file can be one of several types. For
example, compiling the same source (.tl) file with the itlc command on a Sun3
workstation will produce a different binary file than compiling the same file on a Sun4
workstation. Compiling under the Solaris 2 operating system produces a different binary file
than compiling under OS 4.1.
The IMAGE command binfile allows you to determine the type of a binary file. The syntax
for using the command is as follows:
binfile [-verbose] {files}
where:
-verbose Adds additional information to the listing, including the version of
IMAGE used to compile the file.
When run, the program prints the name of the file and additional file information, such as
the CPU architecture of the machine used to compile it. For example:
% binfile program.bin
program.bin: sun4 Image binary file
If the program is written for one testing environment (such as a mixed-signal test head), this
is included in the information summary. Note that some programs are not specific to a given
testing environment (example: the program main() {}), and thus no tester identifier is
included. For example:
% binfile a500job.bin nonspecific.bin
a500job.bin: sun4 mixsig Image binary file
nonspecific.bin: sun4 Image binary file
Older IMAGE binary files (such as those produced by prior releases of IMAGE) are labeled
as old. For example:
% binfile oldfile.bin
oldfile.bin: old Image binary file
An example of the output using -verbose would be:
% binfile -verbose dc_dual_site.bin
dc_dual_site.bin: sun4 (sparc) mixsig Image binary
file bin_version=1018 image_version="V5.0 112092"
If the argument to binfile is not an IMAGE binary file, it will invoke the Solaris program
file to attempt to identify the type of the file. For example:
% ls
a500job.bin a500job.tl mydir stuff.data
% binfile *
IMAGE Solutions V8.3 7-43
IMAGE Base Language: Debugging Test Programs: Standalone IMAGE Compiler
Table of Contents Index Home Master Index Search Help
a500job.bin: sun4 mixsig Image binary file
a500job.tl: c program text
mydir: directory
stuff.data: ascii text
For more information on the file command, see the Sun’s AnswerBook or use the Sun on-
line manual by typing the command man file.
IMAGE Solutions V8.3 7-44
IMAGE Base Language: Debugging Test Programs: Libraries
Table of Contents Index Home Master Index Search Help
Libraries
The library command allows you to list the libraries IMAGE searches to resolve
unresolved references for the currently loaded test program. The command has the
following syntax:
library [<filename> ...]
This command without parameters lists current libraries. (If no test program is loaded, you
get an error message.) The following is a sample list:
smith% library
Library 1: /image/bin.5.0/libdummy.a
Library 2: /image/bin.5.0/libitldrivers.a
Library 3: /image/bin.5.0/liba5drivers.a
Library 4: /image/bin.5.0/libdrivers.a
Library 5: /image/bin.5.0/libsimdummy.a
Library 6: /image/bin.5.0/libsim.a
Library 7: /image/bin.5.0/libutil.a
Library 8: /image/bin.5.0/libshmoo.a
Library 9: /image/bin.5.0/libmathadv.a
Library 10: /image/bin.5.0/librs232.a
Library 11: /image/bin.5.0/libhandler.a
Library 12: /image/bin.5.0a/m218/libs/handler/libm218handler.a
Library 13: /image/bin.5.0/libmter.a
Library 14: /image/bin.5.0/libcter.a
Library object file: /image/bin.5.0/link_always_a500.o
Library object file: /image/bin.5.0/imagemain.o
You can add a new library to the list of libraries searched while in debug by using the
library command followed by the name of the library.
IMAGE Solutions V8.3 7-45
IMAGE Base Language: Debugging Test Programs: Switch Variables
Table of Contents Index Home Master Index Search Help
Switch Variables
Switch variables are variables with preset names that are always linked to a test program.
Unlike other variables, their values can be displayed and set using debug commands. Sixty-
four switch variables are available, all of type int. They are named switchvar_1 through
switchvar_64. To use them, you must declare the ones you use as extern in the header
section of your file. The command to display or set switch variables is:
switchvar [<variable #>[=<value>]] [-station <#>]
where:
<variable #> Specifies a switch variable number from 1 to 64.
<value> Specifies a value for the switch variable.
-station <#> Specifies a station window.
With no arguments, this command prints out the values of all switch variables. If you specify
one or more variable numbers, the contents of the specified variables are printed. For
example switchvar 2 prints out the current setting of the variable switchvar_2.
To set a switch variable, use the syntax:
switchvar <variable #>=<value>
For example, switchvar 4=100 sets the variable switchvar_4 to the value 100 in the test
program. Multiple settings and readings are possible with one command. For example,
switchvar 1 2 3 4=5 prints out the settings for variables 1, 2, and 3, and also sets variable
4 to the value 5.
Switch variables can be used outside the debugger. They are often used to set the “mode”
a test program runs in, or as a way of turning on and off some special test-program function.
For example, you could include code in a test program which checks the value of a switch
variable and uses this to determine whether to write out test data files for the run.
You can also set switch variables to a particular value when loading a test program using
the command load -switchvar_<i> #. See “Loading Using the load Command” on page
5-4.
IMAGE Solutions V8.3 7-46
IMAGE Base Language: Debugging Test Programs: Debug Displays
Table of Contents Index Home Master Index Search Help
Debug Displays
Debug displays are programs that display, and can sometimes change, the current state of
a test program and tester hardware. They receive new data from the tester after every
immediate, run, cont, step, or next command.
You can invoke debug displays only when a station is in debug. To invoke a display, press
MENU on the DISPLAY button in the station window and select a display from the following
menu:
PROGRAM DEBUG> Brings up general displays used in debugging including the
Immediate, Variables, Sync Pulse, and Simulator Database
displays. (See “Immediate Commands” on page 7-64, “Variables
Display” on page 7-56, and “Simulator” on page 12-1.)
INSTRUMENTS> Brings up instrument debug displays.
DIGITAL TOOL EXEC... Brings up the Digital Tool Executive. (See “Digital Tool
Executive” on page 12-1 in the IMAGE Software Tools Manual.)
PATTERN TOOLS> Brings up digital pattern displays.
DIBVIEW... Brings up the DIBView tool. (See “DIBView” on page 2-1 in the
IMAGE Software Tools Manual.)
SHMOO... Brings up the Shmoo tool. (See “Shmoo Plots” on page 9-1 in the
IMAGE Software Tools Manual.)
MARGIN... Brings up the Margin display. (See “Margin Testing” on page 8-1
in the IMAGE Software Tools Manual.)
SMITH DISPLAY... Brings up the Smith display. (See “Using the Smith Display Tool”
on page 20-38 in the Catalyst Instrumentation Manual.)
CALIBRATION TOOLS... Brings up the RF Calibration tools. (See “Calibrate Fixture Tool”
on page 23-25 in the Catalyst Instrumentation Manual.)
DATASHEET> Brings up the Datasheet windows. (See “Datasheet Tool” on
page 7-1 in the IMAGE Software Tools Manual.)
TEMPLATES... Brings up the Templates Tool window. (See “Digital Templates”
on page 6-1 and “Wireless Templates” on page 5-1 in the IMAGE
Software Tools Manual.)
TEST ANALYZER... Brings up the IMAGE Expert Test Analyzer. (See “IMAGE Expert
Test Analyzer” on page 16-1 in the IMAGE Software Tools
Manual.)
WAVEFORM... Brings up the Wave display. (See “Wave Display” on page 10-1
in the IMAGE Software Tools Manual.)
WAVEFORM ANALYZER...Brings up the Waveform Analyzer. (See “Waveform Analyzer” on
page 11-1 in the IMAGE Software Tools Manual.)
IMAGE Solutions V8.3 7-47
IMAGE Base Language: Debugging Test Programs: Debug Displays
Table of Contents Index Home Master Index Search Help
Note that some of these menu choices only appear only if you have a compiled test program
loaded.
You can also bring up a debug display by typing its program name in a station window.
Instrument Displays
Catalyst and Catalyst Tiger station windows have separate debug display menus. The
menu for each type of tester includes the appropriate instrument and digital pattern tools for
that tester. Instrument displays, pattern tools, the Sync Pulse display, and Tester Setup
display are described in the instrumentation and test-head manuals for each type of test
system.
Defining Which Displays Come Up Automatically
You can bring up certain debug displays automatically when a test program is loaded into
the debugger by creating a .enterdebug file and inserting a list of displays. IMAGE
automatically brings up any displays listed in this file. In much the same way, the image
command automatically brings up any program listed in the .image-init file in your home
directory.
You can have more than one .enterdebug file and customize each for a different test
program. When a station enters debug, it first checks the local directory and then your home
directory for a .enterdebug file. Failing to find it in either place, it stops looking. To
customize .enterdebug files to test programs you must have a local copy of the
.enterdebug file in the directory in which debug was executed.
Create an .enterdebug file using the debugplaces utility. This program examines the
contents of the screen and prints out a listing of the debug displays currently running, with
their positions. To create your own .enterdebug file:
1. Load a test program into the debugger.
2. Bring up any debug displays you want.
3. Type the command debugplaces. This prints out the information that must go in the
.enterbug file.
4. cd to your home directory.
5. Type debugplaces > .enterdebug.
For example, you may have the tester setup, variables, and waveform displays in iconic
form on the screen. If you type debugplaces, you might see:
setupdisp -Wp 18 190 -Ws 577 285 -WP 256 0 -Wi
vardisp -Wp 36 72 -Ws 577 285 -WP 136 0 -Wi
wave -Wp 108 100 -Ws 423 437 -WP 0 0 -Wi
If you put this list into your .enterdebug file, the next time you enter debug the same
displays will appear in the same sizes and in the same positions.
IMAGE Solutions V8.3 7-48
IMAGE Base Language: Debugging Test Programs: Interactive Debug Displays
Table of Contents Index Home Master Index Search Help
Interactive Debug Displays
IMAGE supports interactive debug displays for many instruments. Each display shows the
state of the instrument in real time during program debugging. It also allows you to change
the setup of any instrument interactively using the mouse and keyboard. Interactive displays
also allow you to change setups by typing directly on the debug display window. This is
provided in addition to the standard use of the Immediate window for even faster program
debugging.
IMAGE ExPress is an optional extension of the interactive debug displays. With IMAGE
ExPress, you can use settings on interactive displays to produce actual code for your test
program. (See “IMAGE ExPress” on page 1-1 in the IMAGE Software Tools Manual for
information.)
Displays for individual instruments have different interactive parameters. The following
sections describe general features of these displays. For detailed information on the
displays, see the instrumentation manual for each test system type.
Debug Display and IMAGE ExPress Controls
When you invoke an interactive display, the control panel for the display includes the
following buttons:
REFRESH Refreshes the display. Ensures that the display matches the
state of the tester. The display may get out of sync if text items
are edited but not entered.
STORE Saves a snapshot in memory of the currently visible setup. Each
instrument has one setup memory.
CODE Produces code in either the immediate window or the source
window as specified in the CODE DESTINATION menu item. (This
button only appears in IMAGE ExPress windows.)
SETUP Controls the setup of display options available from the button’s
pop-up menu.
SETUP>SHOW SETUP Displays the current settings for the other SETUP menu items:
HIGHLIGHT
SELECT PIN NAMES/NUMBERS
This information appears in the message line at the bottom of the
control panel.
SETUP>HIGHLIGHT>ALL INTERACTIVE PARAMETERS
Highlights, in reverse video, all interactive features of the display.
DIFFERENCES FROM STORED STATE
Compares the present state of the display to the state saved
using the STORE button and highlights the differences. See
“Differences From Stored State” on page 7-53.
IMAGE Solutions V8.3 7-49
IMAGE Base Language: Debugging Test Programs: Interactive Debug Displays
Table of Contents Index Home Master Index Search Help
DIFFERENCES IN PIN GROUP
Compares the present state of the display to the state of all other
pins in the same pin group and highlights the difference.
OFF
Removes all highlighting from the display.
SETUP>SELECT PIN NAMES/NUMBERS> PIN NAMES
PIN NUMBERS
DIB NAMES
SLOT NUMBERS
Labels display inputs and outputs using DUT pin names (the
default), DUT pin numbers, DIB names, or slot numbers.
SETUP>CODE MODE Selects the rules used to generate code from the display setup.
(This menu item only appears in IMAGE ExPress windows.)
Menu choices are:
AUTO-STORE Automatically store every change to the
display since the last time the CODE button was pressed (the
default).
DIFFS FROM STORED STATE Change the instrument
from the stored state to the current state of the display when
CODE is pressed.
EVERY DISPLAY ACTION Generate code each time the
display is changed. (The CODE button is not used in this mode.)
SETUP>CODE DESTINATION
Sends the code to the test program or to the immediate window.
(This menu item only appears in IMAGE ExPress windows.)
SELECT Selects the instrument to display. This button is not on all
displays. It is included when a display controls more than one
instrument.
PRINT Allows you to print the display. (See “Printing Windows in
IMAGE” on page 3-19.)
QUIT Exits from the display.
Interactive Setup Changes
Each instrument display is an interactive panel, allowing you to edit the instrument setup. In
most cases, every parameter that you can set from a test program can also be set using the
display. The major types of programming interfaces are used, depending on the parameter
to be programmed are:
• Choice items
• Numerical or text input items
• Push-buttons
IMAGE Solutions V8.3 7-50
IMAGE Base Language: Debugging Test Programs: Interactive Debug Displays
Table of Contents Index Home Master Index Search Help
The Low Frequency Source (lfsrc) on the AC Instrument Setup display (vbacdisp) is used
to illustrate examples in this section. Figure 7-9 shows this display with interactive
parameters highlighted.
Figure 7-9. AC Instrument Display of Low Frequency Source, Interactive Parameters Highlighted
Choice Selections
Many instrument programming parameters are choices of one of several possible
selections. The Low Frequency Source low-pass filter (LPFILT), for example, can have nine
different values or be bypassed. Anything that can be expressed this way is implemented
as a choice-panel item.
To see all the choices, press MENU and move the pointer to the desired choice. You can
also use SELECT to cycle through all the choices. Pressing SELECT previews the next
choice, and releasing the button selects it. (If you press SELECT and decide the next choice
is not the one you want, move the pointer off the item entirely. The item remains
unchanged.)
NOTE
Toggling through the selections actually programs each selection momentarily and may,
therefore, cause run-time errors as other programmed parameters become “out of range.”
A choice item may appear as words, such as in ACLOCK:A0, or as a picture, such as an open
or closed relay.
IMAGE Solutions V8.3 7-51
IMAGE Base Language: Debugging Test Programs: Interactive Debug Displays
Table of Contents Index Home Master Index Search Help
Sometimes the same parameter appears more than once on the display. For example
LOCALGND is shown both as ON/OFF and as a relay. When either is programmed, both
change.
Numerical or Text Input
Some parameters require numerical input, such as amplitude (AMP), or text input, such as
an SMEM segment name (SEGNAME). These are shown as text items. You can identify them
by clicking ADJUST over the parameter value; an editing caret appears. Click SELECT to
select the edit insertion point. After editing, press Return to enter the text and update the
instrument. Before you press Return, the display is out of sync with the tester. If you think
you may have edited something and are not sure of the real tester setup, use the REFRESH
button to match the display to the instrument.
The input to a text item can be any C expression which is valid at the present location in the
test program, including variable references. Constant values can include standard IMAGE
units such as 10.0MA.
Push-Buttons
The third type of user interface is the familiar panel button. These are used to initiate
actions, such as starting and stopping an S_MEM, and are identified by the familiar button
image. If the button has an arrow, press MENU to bring up a menu (usually containing
variations on the function). Selecting something from the menu executes the command.
Clicking SELECT chooses the first item in the menu. If there is no menu, click SELECT to
initiate the action.
DC Matrix Connections
Some displays include a special item which allows connections to the DC matrix, identified
by a DC MATRIX label which has a menu behind it listing possible DC connections. Press
MENU and select an instrument to connect or disconnect it. The DC MATRIX label changes
to show which instrument is connected.
To support having more than one instrument connected, the menu displays a check mark
to show the instruments currently connected. If you have connected more than one, the
label changes to read <N> DC CONNS. to tell you how many matrix connections you have
made.
Custom Interfaces
Some instruments have parameters that do not fit well into any of the above programming
models. In these cases, custom panel items are used. These are explained in the sections
about the individual instruments’ displays.
IMAGE Solutions V8.3 7-52
IMAGE Base Language: Debugging Test Programs: Interactive Debug Displays
Table of Contents Index Home Master Index Search Help
Color Support
Display items appear in color if you are running IMAGE on a color monitor. Items are shown
in one of three colors:
• Stored. The item state does not differ from the stored state. The default color is blue.
• Running. The display is executing a command. The default color is firebrick.
• Modified. The item is not currently running and its state differs from its stored state. The
default color is yellow.
The highlight state of a display item does not affect the color. In other words, if the highlight
selection is currently ALL INTERACTIVE PARAMETERS, each item appears inverted in whatever
color applies to its state. If the highlight selection is currently DIFFERENCES FROM STORED
STATE, all modified items appear inverted in the modified color. All other items appear
normally in their appropriate color.
You can change the default colors of display items using IMAGE Properties. (See “Setting
IMAGE Properties” on page 3-34.) The procedure for display color defaults is as follows:
1. Select PROPERTIES>IMAGE PROPERTIES from the IMAGE Workspace menu. The
Properties window appears.
2. Press MENU on the CATEGORY menu button at the top of the window and select COLOR.
The color properties page appears.
3. Click SELECT on MODIFY. The Color Manager window is displayed.
4. Press MENU on the menu button and select a property from the menu.
5. Click SELECT to select a color.
6. Click SELECT on the APPLY button to confirm your choice.
The display colors are also listed in the .Xdefaults file in $IMAGEBIN/custom as the
following entries:
color.stored
color.running
color.modified
Differences From Stored State
A debug display can show you the differences between the stored state of the instrument
shown in the display and its current state. The procedure is:
1. Run the test program to a breaktrap (TO TRAP).
2. Store the state of the instrument at this breaktrap by clicking on the STORE button.
3. Change the state of the instrument in one of the following ways:
– Continue running (CONT) the test program to the next breaktrap
– STEP through the test program
– Execute a series of immediate statements from the Immediate Window
– Use the display’s interactive features to change the instrument state
4. Select SETUP>DIFFERENCES FROM STORED STATE from the SETUP button submenu.
IMAGE Solutions V8.3 7-53
IMAGE Base Language: Debugging Test Programs: Interactive Debug Displays
Table of Contents Index Home Master Index Search Help
The display highlights all differences between the current state and the stored state.
This feature is useful during debugging sessions to look for instrument setup errors. First, it
can help you to verify that all differences between two instrument setups are intentional.
This procedure is valuable when debugging two similar tests where one is working and the
other is not.
Second, you can compare displays of different instruments at the same or different points
in the test program. Click STORE while looking at one instrument, SELECT the other
instrument, and highlight differences. This only works for comparing copies of the same
instrument (such as two DC Sources).
Error Conditions
When running interactive displays, several error conditions can occur. These are described
in the following sections.
Conflict With Running Program
When a test program is running, it locks the test hardware for its exclusive use. To change
a parameter, therefore, the test program must be stopped. If the program is running or
waiting for input, the display shows the current data and the following message appears in
the footer:
TEST PROGRAM IS RUNNING
When the program is no longer running (when it stops at a trap, for instance), the display
refreshes with the new information.
Run-Time Errors
As with test-program statements, interactive display commands can try to put an instrument
in an invalid state. When such a run-time error occurs, the default behavior is:
• The run-time error message appears both in the footer of the display and in the station
window.
• The default error handler or a user-defined error handler (if one is set in the program
using set error handler=<function>;) is called. (See “Intercepting Errors in a Test
Program” on page 15-32.)
• The test program stops, the test system is reset, and the program must be rerun to a
trap (stop on fail termination mode). If the program is set to continue on error
mode, the program remains at the trap.
You can change the way displays handle run-time errors using the IMAGE Properties
window. Select the Miscellaneous page of that display and modify the property DEBUG
DISPLAY OPTIONS: ERROR HANDLING. (See “Miscellaneous Options” on page 3-36.) If you
change this option from DEFAULT to IGNORE, display-generated errors are now handled as
follows:
IMAGE Solutions V8.3 7-54
IMAGE Base Language: Debugging Test Programs: Interactive Debug Displays
Table of Contents Index Home Master Index Search Help
• The run-time error message appears both in the display footer and in the station
window.
• A user error handler (if installed) is not called.
• The test program is not reset (as with program termination mode continue on error).
The effect of ignoring run-time errors from the display is that any display errors will not stop
the test program.
Compiler Errors
When expressions are used in text items, the text is error-checked by the IMAGE compiler
in the same way as if it were compiled as part of the test program. If any errors occur, such
as undefined variables or values out of range, the first compiler error that would occur is
shown in the message region of the display.
IMAGE Solutions V8.3 7-55
IMAGE Base Language: Debugging Test Programs: Variables Display
Table of Contents Index Home Master Index Search Help
Variables Display
The Variables display (figure 7-10) is a window that shows the current values of variables in
a test program. The display is refreshed with the latest data whenever the program changes
state (at each run, cont, step, next, or immediate command). This enables you to examine
the value of variables as you debug a program.
Figure 7-10. Variables Display
Invoking the Display
To invoke the Variables display, select DISPLAY>PROGRAM DEBUG>VARIABLES (see “Debug
Displays” on page 7-47) or type vardisp in the station window. The syntax for the vardisp
command is:
vardisp {-scaled/-unscaled/-xprec -noautos -radix [doxb]
-tl -lines <n> -autoadjust}
where:
-scaled/-unscaled/-xprec
Displays variables as scaled (in scientific notation), unscaled, or
with extended precision. (See “Scaling Variables” on page 7-59.)
-noautos Initializes the display not to show automatic variables.
-radix [doxb] Changes the radix in which integers are displayed. The options
d, o, x, and b result in decimal, octal, hexadecimal, and binary
output, respectively. (See “Specifying the Radix for Integers” on
page 7-60.)
-tl Displays variables beginning with tl_ that are otherwise
suppressed.
IMAGE Solutions V8.3 7-56
IMAGE Base Language: Debugging Test Programs: Variables Display
Table of Contents Index Home Master Index Search Help
-lines Specifies the number of array elements to display. The default is
four. To override the default, request the array with a range, as
in myarray[0 to 100].
-autoadjust Initializes the display to automatically adjust the display region to
show the last changed variable.
Contents of the Display
The Variables display is a text window you can stretch, move, open, or close like other text
windows. The display region (where variables are displayed) has a pop-up edit menu for
such things as splitting the screen or finding selected text. The footer at the bottom of the
window displays the function where the variables are located and the line number in the test
program.
The window also has a drag-and-drop target. You can use this target to print the contents
of the display using Print Tool or to paste the contents to a Text Editor window.
The control panel for the window includes the following buttons and items:
REFRESH Update the values from the test program and redisplay them.
Other window events can occasionally corrupt the display. Use
the REFRESH button to redisplay it. When the display refreshes
due to a change in program state, the first variable in the display
that changed is made visible.
PRINT Display the value of the selected variable at the bottom of the
display. Specify the name of the variable to print by clicking the
PRINT button to display the Print Variable window (figure 7-11).
Enter the function and variable and click PRINT. If you select a
variable before bringing up the window, the window appears with
the variable already filled in. This text is cleared when the display
refreshes.
Figure 7-11. Print Variable Window
REQUEST Adds variables to the display. Request a variable by clicking the
REQUEST button to display the Request Variable window (figure
7-12). Enter the function and variable and click REQUEST. If you
select a variable before bringing up the window, the window
appears with the variable filled in. (See “Requesting and
Unrequesting Variables” on page 7-61.)
IMAGE Solutions V8.3 7-57
IMAGE Base Language: Debugging Test Programs: Variables Display
Table of Contents Index Home Master Index Search Help
Figure 7-12. Request Variable Window
UNREQUEST Deletes variables from the display. Press MENU on this button
to display all the selected variables. Select the one to unrequest.
DECIMAL/OCTAL/HEX/BINARY
Change the radix in which variable integers are displayed. Press
MENU on the abbreviated menu button and select from the pop-
up menu. Default is DECIMAL. (See “Specifying the Radix for
Integers” on page 7-60.)
QUIT Quit the Variables display.
ARRAY LINES Specify the maximum number of array elements to display. (The
default is 4.)
REQUESTED ONLY Display only requested variables. (The default is all variables.)
ADJUST Have the display automatically position the view into the display
region to show the last changed variable. (The default is not
adjusted.)
SCALED/UNSCALED/EXTENDED PRECISION
Display variables as scaled (in scientific notation), unscaled, or
with extended precision. See “Scaling Variables” on page 7-59.
(The default is unscaled.)
How Variables are Displayed
The Variables debug display can show many types of variables. Table 7-1 describes what
is displayed for each type.
Table 7-1. Variables Shown on the Variables Display
Variable Items Shown on Display
simple variable Value of the variable
arrayname First elements of the array (by default, the first four elements).
Override this default using the vardisp -lines command or
entering a number in the display.
arrayname[N] Nth element
IMAGE Solutions V8.3 7-58
IMAGE Base Language: Debugging Test Programs: Variables Display
Table of Contents Index Home Master Index Search Help
Table 7-1. Variables Shown on the Variables Display (Continued)
Variable Items Shown on Display
arrayname[N to All elements from N to M
M]
pointer Value of the pointer and the item pointed to
structure Each element of the structure
union Each member of the union exactly as if it were a struct. Only one
of the union members displayed is valid.
enumeration Name of the item
When printing pointers, arrays, or structures whose elements are pointers, indirection is
limited to three levels. For example, a pointer to a structure (one of whose elements is an
array of pointers to character pointers) is expanded to only three levels of indirection.
Character arrays and pointers to strings are shown as strings.
Dynamically allocated arrays are usually pointed to by a pointer. The declaration is either of
the following:
int *arrayname;
int arrayname[];
rather than either of the following:
int arrayname[30];
int arrayname[]= {1,4,23,56,22};
One element or range of elements of such an array can be displayed using the same syntax
as in a normal array. The only difference is if the compiler does not know the size of the
array. Specifying only the name of the array, without any index, gives only the first element,
not the first four.
In the Variables display, DARRAYs are displayed as simple variables (ints), much the same
as it displays DSPBUFFERs or SEGMENTs. In the current IMAGE version, you cannot view
the contents of a data array in the Variables display.
Scaling Variables
Using the Variables display, you can display variables as scaled, unscaled, or with extended
precision. The PRINT command (see “Printing Variables in a Station Window” on page 7-63)
also prints variables to the station window in these formats.
Scaled variables are displayed as scaled to the nearest third exponent of 10 and printed with
the standard letter. Thus, 1.234E-8 would be displayed as 12.34N.
Extended precision scales the value to engineering units, and the value is output showing
18 digits for doubles and eight digits for floats. (Double variables have 56 bits of mantissa,
IMAGE Solutions V8.3 7-59
IMAGE Base Language: Debugging Test Programs: Variables Display
Table of Contents Index Home Master Index Search Help
which can be expressed in 18 decimal digits. Float variables have 23 bits of mantissa, which
requires 8 decimal digits to represent.)
The following example uses scaled_pi as the variable and shows the effect on the output
using the print -xprec command:
double scaled_pi = M_PI * 1e-6;
float f_pi = M_PI;
print scaled_pi
scaled_pi = 3.14159e-06
print scaled_pi -xprec
scaled_pi = 3.1415926535897931160u
print f_pi
f_pi = 3.14159
print f_pi -xprec
f_pi = 3.14159274101
Specifying the Radix for Integers
You can specify the radix for integers in the Variables display. You can change the setting
in the display or use the command:
vardisp -radix [doxb]
For example, to bring up the display with integers displayed as octal, use:
vardisp -radix o
You can abbreviate the radix parameter to r. So, the command can be written:
vardisp -r o
When using the print command, specify the radix using:
print -radix [doxb]
If you specify binary, all long and int variables are represented as B followed by a string
of 1’s and 0’s. The string is broken into groups of four. All short variables show 16
characters, and char variables show eight characters. Field members of each struct show
their specified width. Doubles, floats, strings, and enums are unaffected.
The following shows the variable short printed as decimal, hex, and binary:
short mask = 0x83;
print mask
mask = 131
print mask -r x
mask = 0x83
print mask -r b
mask = B 0000 0000 1000 0011
IMAGE Solutions V8.3 7-60
IMAGE Base Language: Debugging Test Programs: Variables Display
Table of Contents Index Home Master Index Search Help
For the data type char, if you select the hex, octal, or binary radix, the char value is printed
first in ASCII, then in the selected radix. The following shows the variable byte_mask printed
as decimal, hex, and binary:
char byte_mask = 0x61;
print byte_mask
byte_mask = 'a'
print byte_mask -r x
byte_mask = 'a' 0x61
print byte_mask -r b
byte_mask = 'a' B 0110 0001
Requesting and Unrequesting Variables
When you open the Variables display, values are automatically displayed for:
• All variables local to the function that the program is stopped in
• All global variables referenced in the function
To add variables to the display, click REQUEST to bring up the Request Variable window
(figure 7-12 on page 7-58), in which you type the name of the variable you want. Enter the
variable and click REQUEST.
You can specify array boundaries for array or pointer variables and the variables window
will display the appropriate values. For example, to request elements 50 to 55 in the variable
array_1000 you would enter:
array_1000[50 to 55]
The display keeps a list of variables you have requested be displayed at all times. Typically,
these are globals not referenced in every function but ones you want to track.
Variables are displayed in three groups, each separated by a blank line:
• Requested variables
• Referenced global variables
• Local (automatic, static, and parameter) variables
If a test program is stopped in the function in which a requested automatic variable is
declared, the variable is displayed with the other automatic variables rather than with the
requested variables.
To remove a variable from the requested list, press MENU on UNREQUEST. This displays a
menu listing all current requests. Select a variable to remove it. You can also select the text
of the variable to unrequest and click UNREQUEST. The text must match exactly that of the
requested variable.
IMAGE Solutions V8.3 7-61
IMAGE Base Language: Debugging Test Programs: Variables Display
Table of Contents Index Home Master Index Search Help
Variables in Other Functions
In addition to global variables and variables local to the current function, you can also
examine any active variable. An active variable is one declared in a function that calls
(directly or indirectly) the current function. This includes all functions that appear on the list
printed by the where command. (See “Halting a Test Program” on page 7-19.)
For example, if a program is stopped in myfunc(), which was called by firstfunc(), you
can display any variable local to firstfunc(). As long as the variable is still active, its value
is displayed. You can still see firstfunc()’s variables if you step into nextfunc(), called
from myfunc(). When the variables are no longer active (after firstfunc() returns), the
display writes a message to that effect, instead of a value.
To request a variable not in the function where the program is currently stopped, click
REQUEST and enter the function name in the FUNCTION FIELD in the Request Variable
window. You can also select the name in the source window, inside its function, and click
SELECT. If no such variable exists, and there is a global variable named count, it is
displayed.
Variables Display Error Messages
The Variables display can produce the following error messages (error messages in the
display window are erased at the next refresh):
Only one variables display permitted
Badly formed variable [or array] specification '...'
Print or request variable has nonalphanumeric characters, bad array syntax, negative
indices, or some other gross malformation.
Array indices out of order
'...' is not a valid variable
Specified variable does not exist. If the variable name is a request, the request remains
on the list.
'...' not active
The specified variable is not in the stopped function or a function in the calling chain to
the stopped function.
NOTE
When a program is not stopped, no automatic variable is active. If the variable was
requested, this is only an informative message.
IMAGE Solutions V8.3 7-62
IMAGE Base Language: Debugging Test Programs: Variables Display
Table of Contents Index Home Master Index Search Help
Printing Variables in a Station Window
The PRINT button in the station window control panel prints the value of one or more
variables in a station window. Use it if you do not want to spend the time or screen space to
get the Variables display. You can select text and click PRINT.
You can also enter the print command in the station window. This command has the
following syntax:
print [<variable>] [-station <#>] [-radix [doxb]]
[-scale | -unscaled | -xprec]
where:
<variable> Specifies the variable name. The variable can be written as
either of the following:
<array/pointer[#]>
<array/pointer[# to #]>
-station <#> Specifies a station number.
-radix [doxb] Change the radix in which integers are displayed to decimal (d),
octal (o) hexadecimal (x), or binary (b). (See “Specifying the
Radix for Integers” on page 7-60.)
-scale | -unscaled | -xprec
Display variables as scaled (in scientific notation), unscaled, or
with extended precision. (See “Scaling Variables” on page 7-59.)
If you enter print without parameters, you are prompted for a variable name.
The print command uses the same syntax, and displays the same values, as the Variables
display, with the following exceptions:
• When specifying one element of an array or a subrange or the contents of a pointer, the
parameters must be enclosed in quotes (' or ") to pass the C-shell. The PRINT button
and print command do this automatically.
• If you specify only the name (no subrange) of an array whose size is known at compile
time, the print command prints the entire array.
• Selecting in the source window has no special effect on the scoping of the variable. If
the program is stopped at a breaktrap, and there is a local variable with the specified
name, the local variable is printed. Otherwise, if there is a global variable with the
specified name, it is printed. You can print <function>.<variable>, to get the variable
from a specific function.
IMAGE Solutions V8.3 7-63
IMAGE Base Language: Debugging Test Programs: Immediate Commands
Table of Contents Index Home Master Index Search Help
Immediate Commands
To execute any ITL statement immediately without editing your test program, use an
immediate command. This facility allows you to quickly examine or change hardware and
call functions and to reference or change variables.
An “immediate” command is essentially a temporary test-program section consisting of one
or more statements. If the program is stopped at a breaktrap, you can reference local
variables. You can also call library functions not previously referenced and, therefore, not a
part of the program. The new library function is located and linked into the program when
the immediate command is executed. (Most tester instruments can also be programmed
using their interactive displays. See “Interactive Debug Displays” on page 7-49.)
Using the Immediate Window to Enter Immediate Commands
The easiest way to enter immediate commands is using the Immediate window (figure 7-
13). To invoke it, press MENU on the DISPLAY menu button and select IMMEDIATE from the
pull-right menu.
Figure 7-13. Immediate Window
You can also type the command immedwin in a station window. This command has the
following syntax:
immedwin [-station <#>]
where:
-station <#> Specifies a station window.
You can only use Immediate windows in debug, and only one can be used at a time. It
disappears automatically when you exit debug or delete the program.
The Immediate Window is a text window and can be manipulated like any other text window.
It can be stretched, moved, opened, or closed. The display region (where immediate
commands are displayed) has a pop-up edit menu for such things as splitting the screen or
finding selected text. The window control panel includes the following buttons:
IMAGE Solutions V8.3 7-64
IMAGE Base Language: Debugging Test Programs: Immediate Commands
Table of Contents Index Home Master Index Search Help
NEW TEXT Execute an immediate command using the new text in the
immediate window. Click SELECT on this button after you enter
the text.
SELECTION Execute an immediate command using selected text in any
window. Click SELECT on this button after you select (highlight)
the text.
AGAIN Execute the most recent immediate command again.
STOP Stop the compile/execution of the immediate command.
To execute an immediate command, type in one or more statements and click NEW TEXT. Or
invoke the command by typing it in the window and pressing the escape key (ESC). All text
following the last --- IMM --- prompt is used (if the window is set to display prompts). This text
can include multiple lines and multiple statements. The text executed is highlighted in
reverse video. While the immediate command is being compiled and run, the bottom portion
of the window displays the message STATE: RUNNING. This message is removed when
execution is complete.
If the text you want to execute is not at the end of the immediate window, you can select it,
then execute it by clicking SELECTION. For example, if you type a complicated immediate
command in the window and it contains errors, you can edit it in place, select it, and click
SELECTION. (You can also select the text, put it on the shelf, get it back at the end of the
window, edit it, and press F1 key or click on NEW TEXT.) Again, when the STATE: RUNNING
item disappears from the bottom portion of the window, and a new prompt appears, the
command is complete.
If you get errors from immediate commands invoked by either of these methods, the error
messages appear in the immediate window. The line number of the error message
corresponds to the window the text was in. Usually, this is a line number in the immediate
window. However, the text can come from a different window. For example, you can select
a statement in the source window and click SELECTION. The line numbers in any error
message refer to the lines in the source window. This allows you to select the number, go
to the window the text came from, and find the line with the error using the VIEW>SELECT
LINE AT NUMBER in the source window.
Immediate commands are like small test programs. Therefore, any output from immediate
commands goes to the station window. If you execute printf statements, the text appears
in the terminal pane of the station window. If you execute a sequencer statement, any
datalog values are output to the station window (unless otherwise specified).
To stop an immediate statement, you can either type CONTROL-C or click SELECT on STOP.
This stops the immediate command as fast as the CONTROL-C can get through, whether it
is compiling, executing, or just partially typed in.
Since the Immediate Window is a text window, you can edit in it. You can put and get
commands from other windows, save your immediate session to a file, or reset the text to
clear out old commands.
IMAGE Solutions V8.3 7-65
IMAGE Base Language: Debugging Test Programs: Immediate Commands
Table of Contents Index Home Master Index Search Help
Immediate Commands in a Station Window
You can execute immediate commands from a station window. This may be more
convenient for short immediate commands or if the Immediate window is buried or iconic.
Use the imm command. This command has the following syntax:
imm ['<statement>'] [-station <#>]
where:
'<statement>' Specifies a single-line statement.
-station <#> Specifies a station number.
To issue a one-line command enter imm followed by the text enclosed in single quotes (')
and Return. The statement is then compiled and any errors appear in the station window.
This allows the statement to pass through the C shell. Some statements are, however,
unacceptable to the shell even when in quotes.
To issue multiline commands, enter imm with no statement on the command line and no
quotes. Enter the first line and press Return. Enter the second line. Continue in this way until
you finish. Press Return twice to end the command.
Using Immediate Commands With Custom Buttons
You can program your own buttons in the station window. (See“Changing the Station-
Window Control Panel” on page 8-10.) By combining this feature with immediate
commands, you can create some powerful tools. For example, the following string will print
a double precision value:
imm 'printf( "%%g\n", (double) $SELECTION)';
Note the extra % sign. This is important. It tells IMAGE to view the argument literally and not
substitute an argument.
Changing the Immediate Display Prompt
The IMAGE Properties utility allows you to specify a prompt in the Immediate window after
executing a command. (See “Miscellaneous Options” on page 3-36.) One choice is
feedback in IMAGE comment form: /*- imm -*/. This form allows you to cut and paste
entire sequences, including prompts into a test program.
Using the Immediate Command From the Source Window
The source window includes an IMMEDIATE button. This button duplicates a subset of the
functionality of the Immediate Window. You can use the IMMEDIATE button when you wish to
repeatedly execute a portion of the code in a test program. IMMEDIATE button menu options
are as follows:
IMAGE Solutions V8.3 7-66
IMAGE Base Language: Debugging Test Programs: Immediate Commands
Table of Contents Index Home Master Index Search Help
IMMEDIATE USING SELECTION
Immediately executes the selected code. This is the default.
ABORT Aborts the running code.
IMMEDIATE WINDOW Brings up the Immediate window. (See “Using the Immediate
Window to Enter Immediate Commands” on page 7-64.)
HELP ON IMMEDIATE Displays a window describing the functionality of the IMMEDIATE
button.
IMAGE Solutions V8.3 7-67
IMAGE Base Language: Production Environment
Table of Contents Index Home Master Index Search Help
8 PRODUCTION ENVIRONMENT
IMAGE has two operating modes: engineering mode and production mode.
In engineering mode, the mode described throughout most of this manual, IMAGE operates
in a way which allows engineers the full capabilities of the window environment.
Production mode offers limited capability suitable for production operators. This mode alters
the windowing system and the way in which users interact with the tester (including whether
or not to use the mouse). This mode does not affect the tester or test programs.
The IMAGE production environment is designed to permit simultaneous testing of different
products in as many stations as the tester can accommodate. Interaction with the tester in
production mode is primarily through a handler or prober, with the keyboard being used for
brief periods of time for activities such as setting up lots. IMAGE also allows you to use the
keyboard to access the engineering capabilities of the tester while the test system is still
running in production.
This section describes invoking the environment and ways in which you can customize the
environment for production operators. It includes the following topics:
• “Features of the Production Environment” on page 8-2
• “Setting Up Files for the Production Environment” on page 8-4
• “Production Mode With Mouse” on page 8-5
• “Production Mode Using Menus” on page 8-15
• “Run-Time Error and Alarm Messages” on page 8-43
• “Setting Up Production Environment Defaults” on page 8-46
• “The Station Monitor” on page 8-49
Another type of production environment in IMAGE is also available. This environment,
called the Production Menu Control (PMC) system, offers greater programming flexibility
and additional menu features. For information on PMC, see “Production Menu Control” on
page 9-1.
IMAGE Solutions V8.3 8-1
IMAGE Base Language: Production Environment: Features of the Production Environment
Table of Contents Index Home Master Index Search Help
Features of the Production Environment
Major features of the IMAGE production environment include the following:
• Buttons, features, and menus of production-mode windows are fully configurable.
• Window characteristics, such as fonts and button layout, and production defaults, such
as test program and test data directories, are inherited from the user currently logged in
to the station window.
• Production window positions can be configured.
• Stations can be individually changed between engineering and production modes,
independently of other stations or the IMAGE window environment. If present, the
station monitor associated with a particular station will automatically assume the same
mode as the station.
• Standard directories can be defined, using the IMAGE PROPERTIES item from the
IMAGE Workspace menu, for storing production test programs, test data, error logging,
and screen fonts. Limited engineering activity is permitted, along with concurrent
production-related activities. However, if engineering and production activities occur
simultaneously on a tester, stopping at breakpoints temporarily suspends activity on the
production stations until the engineering station is no longer stopped at a breakpoint.
• Two production modes are available:
– Operation of IMAGE with a mouse. Station window control panel has a limited
number of buttons displayed in large type. Button functions are simpler and easier
to read. Figure 8-1 shows a production window with the mouse.
– Operation of IMAGE with menus. The mouse can be removed. Menus appear in the
station window instead of buttons. Commands are made by typing a menu selection.
Figure 8-2 on page 8-15 shows a production window with menus.
IMAGE Solutions V8.3 8-2
IMAGE Base Language: Production Environment: Features of the Production Environment
Table of Contents Index Home Master Index Search Help
Station Monitor
Station Window
Figure 8-1. Production Mode with Mouse Operation
IMAGE Solutions V8.3 8-3
IMAGE Base Language: Production Environment: Setting Up Files for the Production Environment
Table of Contents Index Home Master Index Search Help
Setting Up Files for the Production Environment
Since IMAGE supports two types of production interfaces (one which uses the mouse and
one which uses menus), you must configure your test system so that operators are
presented with the interface of your choice.
Setting .login Files
The type of production interface is determined by the .login file of the account used.
IMAGE has two production operator accounts:
• operator. The .login file for the operator account invokes the production mode with
the mouse
• operator2. The .login file for the operator2 account invokes the production interface
without the mouse.
To set up your test system, you can either instruct operators to log in as operator or oper2,
or you can create new accounts and copy the operator or operator2 home directories to
your new accounts. The new accounts need new entries to the password file, /etc/passwd.
NOTE
To log in to the operator2 account, you must type oper2. The shorter login name is needed
because the maximum length of an account name is eight characters.
Setting the Windows
The station, console, and station monitor windows are the only windows controlled in
production mode. Some windows normally found on the engineering mode IMAGE
Workspace menu are not available from this menu. These include ShellTools, Command
Tools, textedit, and the IMAGE Properties menu. They are omitted because production
mode does not normally use these functions. Also, if one of these windows is inadvertently
brought up, the window might obscure the production window.
Since limited engineering activity is allowed, you can bring up each of these windows by
executing the appropriate command (shelltool, cmdtool, or textedit) in the station
window when it is in engineering mode. If desired, you can put these functions back into the
production Workspace menu.
To operate the tester successfully in production mode you may want to set the .image-
init file (in $IMAGEBIN/custom or /home/tester) not to bring up any windows other than
station, console, or station monitor windows when IMAGE is started. Operation of the
.image-init file is explained in “Additional Ways to Customize Your Environment” on page
3-42.
IMAGE Solutions V8.3 8-4
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
Production Mode With Mouse
Production mode using the mouse (figure 8-1) is described in this section. Production mode
with menus is described in “Production Mode Using Menus” on page 8-15.
Starting IMAGE in Production Mode
IMAGE sets up the operator account for production mode testing with the mouse. To start
IMAGE in the production mode:
1. Log in at the Solaris prompt as operator.
2. Invoke IMAGE.
3. Switch to production mode by clicking on the PROD button in the control panel of the
station window.
The production-mode test station windows and mouse cursor appear, and you can use all
of the mouse functions.
Another way to bring up IMAGE in production mode with the mouse is using the command
image -production. (By default, the image command brings IMAGE up in engineering
mode.)
You can also start IMAGE from a .login file by inserting the following two lines in your
.login file:
echo "Starting Image... (PRODUCTION)"
image -production
When /image/common/.login is executed, production-mode IMAGE starts.
Switching Between Production Mode and Engineering Mode
You can switch between engineering and production mode by clicking on the ENG or PROD
button in the station-window control panel. When you are in engineering mode, the button
is labeled PROD. When you are in production mode, the button is labeled ENG.
You can also switch between modes using the engineering and production commands.
Type these commands into any window running a shell.
Engineering and production commands have a required parameter, -station <snum>,
which you must provide if either command is entered in a window other than the station
window. For example, to change the station window from production mode to engineering
mode, you can type the following command in a window such as the console window:
engineering -station 1
IMAGE also has a “lockout” mechanism that prevents unauthorized operators from
switching to engineering mode. This mechanism uses a Solaris account in the /etc/passwd
file called ENGINEER. This account has a password (the default password is engineering),
and a pop-up password prompt appears whenever a request is made to change to
IMAGE Solutions V8.3 8-5
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
engineering mode. If you have no account or type the incorrect password, the request is
denied.
Changing from engineering to production mode has no lockout.
NOTE
You cannot change to or from production mode on any station while any station is in debug.
If you try, IMAGE prompts you to exit debug.
Switching Between Windows
In production mode, the station and console windows are automatically opened and placed
(overlapping) on the right side of the workstation screen. Only a single station or console
window is visible at one time. You can cycle between these windows using the FRONT key
on the keyboard.
You can also select stations using the select command:
select [-station # | -console] [-tester <tester_name>]
This command brings the specified station or console to the front of the overlapping
windows. If a station window does not exist for the requested station, one is automatically
created and brought to the front. If a console window does not exist, this command does not
create a console window.
Control Panel in Production Mode
The station window for production mode includes a control panel that displays a set of
command buttons and menu selections. The buttons in this region are somewhat different
than those in engineering mode. They are larger and represent a restricted set of functions
appropriate to production operation.
The station window control panel has a set of buttons that includes common functions in
production operation. You can change these buttons and their functions to suit your needs
(see “Changing the Station-Window Control Panel” on page 8-10).
The buttons supplied as standard in production mode are:
STARTLOT Specify information for a lot.
ENDLOT End testing of a lot and generate a final summary.
SETUP A button used to supply help to the operator. This button comes
with a pull-right menu that includes two selections: HELP and
SAMPLE JOB. You must supply the text for these menu items.
RUN Run the loaded test program. This button also includes a pull-
right menu item, RETEST, that allows the operator to rerun the
program using the same device number.
IMAGE Solutions V8.3 8-6
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
HANDLER Turn the handler setup on or off.
CHECKERS Include the full checker program menu for setting and running
hardware checkers. (See “Checkers” on page 19-1.)
ENG Change to engineering mode.
STATION Bring the test station or console window to the front. If the test
station window does not exist, it is created. If the console window
does not exist, a new console window is not created. The pull-
right menu lists stations 1 to 10 and the console.
ABORT Stop running the test program immediately.
Station Monitor
When you load and run a test program, a station monitor (see figure 8-2 on page 8-15)
appears in the upper left part of the workspace showing:
• Bin number for the device and site number (for a multisite test)
• Test program name
• Insertion
• Lot and sublot ID
• Number of devices tested and device number
• Software bin number (SBIN)
• Current yield percentage for all sites
• Cumulative yield percentage for all sites
• Numbers used to calculate the current and cumulative percents
To customize the station monitor, see “The Station Monitor” on page 8-49.
Commands in Production Mode
The following commands are commonly used in production mode:
• Setting a device number:
device # [-station #]
• Configuring a handler (see “Using the handlerconf Command” on page 2-1 in the
Handler/Prober Manual):
handlerconf
[-connect <hp_name>] [-disconnect [<hp_name>]] [-port <port #>]
[-disable [<hp_name>]] [-enable [<hp_name>]] [-get_setup <filename>]
[-put_setup <filename>] [-local] [-wafer_map] [-check_freq <device_count>]]
[-condition N [-getstatus]] [-noconfirm] [-independent] [-show]
[-startswitch_on | -startswitch_off][-startswitch_show] [-station #]
• Setting a lot ID (see “Lot Identification” on page 6-3):
lot [<lot_id>] [-station #]
IMAGE Solutions V8.3 8-7
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
• Setting the operator name (see “Setting Lot and Sublot Using the lot Command” on page
6-9):
operator [<operator_name>] [-station #]
• Redrawing the screen:
refresh
• Selecting the station window to display:
select [-station # | -console] [-tester <test_name>]
• Showing the lot setup parameters (see “Displaying Lot Information” on page 6-11):
showlot [-station #] [-lotid | -program]
• Starting a new lot (see “Opening a Lot Using the startlot Command” on page 6-7):
startlot [-lotid <XX>] [-parttype <XX>] [-testcond <XX>]
[-operator <XX>] [-retestcode <XX>] [-supervisor <XX>]
[-jobrev <XX>] [-processid <XX>] [-noconfirm] [-nosummary]
[-show] [-station #] [-fullstats <on/off>]
When you issue a startlot command, you get a summary report for the previous lot
as if you had typed the command summary -auto. This default can be overridden using
the -nosummary option to startlot.
• Showing station window information, including whether the window is in production or
engineering mode (see “Displaying Station Window Information” on page 3-14):
station_info [-station #] [-mode] [-debugmode] [-program] [-type]
• Turning user power on or off (see “Controlling User Power” on page 5-28):
usrpower [-off | -on] [-show] [-station #]
• Reread the buttons file (production or engineering):
newbuttons [-station <snum>] [-all]
This can only happen when no test program is loaded in the station. If you specify the
-all switch, an attempt is made to reread the buttons files for all the currently existing
stations. However, only stations that do not have a program loaded are updated.
Customizing the Production Mode Interface
Although IMAGE production mode comes with a control panel already configured for the
station window, you can change the size and positions of the windows and the size, order,
and function of any and all buttons.
Controlling Production Window Sizes and Positions
You may want to alter the default IMAGE production window setup. For this reason, IMAGE
includes the .production_window_info file to control the sizes and positions of station
windows, station monitor windows, and console windows when IMAGE is in production
mode. When a window is changed to production mode or returns to production mode, the
window assumes the size and position specified in this file. The
.production_window_info file is reread every time you switch into production mode.
IMAGE Solutions V8.3 8-8
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
Therefore, to reread the .production_window_info file, type production in the station
window.
The .production_window_info file is similar to the .image file because it contains a list
of programs along with Sun-style window position and size arguments. It is different from
the .image file because it does not determine the set of windows that appear when IMAGE
is brought up. It determines only the size and position of a certain set of IMAGE windows.
The following is an example of a .production_window_info file:
station -Wp 418 140 -Ws 724 753 -s1
station -Wp 418 140 -Ws 724 753 -s2
station -Wp 418 140 -Ws 724 753 -s3
statmon -Wp 10 5 -Ws 406 310 -station 1
statmon -Wp 10 305 -Ws 406 310 -station 2
statmon -Wp 10 605 -Ws 406 310 -station 3
console -Wp 418 5 -Ws 724 135 -Wl "<< CONSOLE >>" -WL console -C
Each line specifies the size and position of a window. For example, in the file above, the first
line determines the size and position of station #1 when IMAGE is in production mode, the
second line determines the size and position of station #2, and so on. This example provides
for three test stations with station monitors, and a console. The station monitor windows are
enlarged to display yield monitor information.
Similar to the .image file, you can generate the .production_window_info file by putting
windows in the appropriate size and position by hand and using the output of the UNIX
owplaces command.
The layout of IMAGE production windows can be specified on a “per tester” basis using the
.production_window_info file. When first executed, IMAGE first searches for this file in
the /image/tester/<tester name>_s directory. If the file is not found there, IMAGE uses
the default .production_window_info file in the $IMAGEBIN/custom directory. Put
customized window information files in the /image/tester directory to assure the file is
used. This file specifies the production window layout of the entire tester, regardless of the
user executing IMAGE.
Controlling Production Window Behavior
You can also use the .production_window_info file to control the behavior of windows in
production mode. You do this by adding any of the following keywords to this file:
MOVABLE_WINDOWS Allows you to move and resize windows while in production
mode.
NO_QUIT Prevents users from quitting the station window and station
monitor window in production mode.
NO_CHANGE_SCROLL Prevents users from changing the station window scroll mode in
production mode.
IMAGE Solutions V8.3 8-9
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
Changing the Station Window Font
When IMAGE is in production mode, the station window command region uses a large font
for legibility (see figure 8-1 on page 8-3). By default, IMAGE uses a 16-point bold font
(screen.b.16) for this purpose. If IMAGE is switched back to engineering mode, the default
font is used.
This behavior (switching to larger fonts when in production) can be disabled using the
IMAGE Properties window. Disable the font switching using the following procedure:
1. Select PROPERTIES>IMAGE WORKSPACE PROPERTIES from the IMAGE Workspace
menu. The IMAGE Properties window appears.
2. Press MENU on the CATEGORY menu button and select GLOBAL STATION WINDOW
OPTIONS.
3. Press MENU on the USE PRODUCTION FONT item and select FALSE.
4. Click the APPLY button to save the settings.
5. Exit the IMAGE Properties window.
You can also use IMAGE Properties window to control the font used in production. Do this
by specifying a new font name for the PRODUCTION FONT defaults item (located immediately
after the USE PRODUCTION FONT item). If you enter the pathname of a font, the station window
uses this font when in production. You can also use this mechanism to provide better
foreign-language support (in the case of a language which requires a non-English font) or
for using a larger font than the default 16-point font.
Changing the Station-Window Control Panel
You can modify the control panel of a station window. That is, you can create and add your
own buttons or menus to the window, modify existing ones, or change the position of the
buttons. This is done by editing one of two files located in $IMAGEBIN/custom:
production_station_buttons
engineering_station_buttons
These files are searched for in the following order (using the engineering buttons file as an
example):
~/.engineering_station_buttons (note the dot)
~/engineering_station_buttons
$IMAGEBIN/custom/.engineering_station_buttons
$IMAGEBIN/custom/engineering_station_buttons
Only the first file found is used (but see the INCLUDE keyword, below). This allows you to
have a hidden, customized station_buttons file in your home directory. Existing visible
files will still work.
These files define the characteristics of the buttons and menus for the production and
engineering station windows. Each file operates on a set of keywords used to define each
button and menu. Changes to these files become effective after you log in again or issue
the newbuttons command (see “Commands in Production Mode” on page 8-7). The file is
IMAGE Solutions V8.3 8-10
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
processed sequentially and each item appears in the window in that order. The keywords
used in the file are as follows:
INCLUDE Specifies the absolute pathname of a station button description
file to be read as if its text appeared at this point in this file. This
keyword allows you to put an engineering_station_buttons
file in your home directory which first includes the system-wide
file and then specifies only the additional custom buttons you
want.
Note that if the system-wide file includes the FONT keyword, as it
usually does, the INCLUDE statement which refers to it must
appear at the start of the user’s station_buttons file. This is
because no buttons can be created before the FONT keyword
appears.
Usage: INCLUDE <absolute path name>
Example:
INCLUDE /image/bin/custom
/.engineering_station_buttons
FONT Specifies the font to use for labeling station window buttons.
Usage: FONT <fontname>
Example: FONT /screen.b.16
GAP Specifies how may pixels to leave between rows of buttons. (The
default for engineering buttons is 10. The default for production-
window buttons is 32.)
Usage: GAP <integer>
Example: GAP 50
SPACE Specifies how many horizontal pixels to skip between buttons.
Usage: SPACE <integer>
Example: SPACE 20
NEWROW Defines the start of a new row of buttons. The number of rows is
unlimited, but note that additional rows will enlarge the height of
the control panel and decrease the size of the terminal pane.
Usage: NEWROW
Example: NEWROW
BUTTON Defines a button image, help string, and command to be issued.
Usage:
BUTTON "<label>" "<help string>"
<command>
Example:
BUTTON "Endlot" "Print a final summary"
summary -final | print
IMAGE Solutions V8.3 8-11
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
MENU/END Defines a button with a pull-right menu and the selections in that
menu. (Menus can be nested.)
Usage:
MENU "<menu label>"
"<selection label>" <selection command>
"<selection label>" <selection command>
: :
"<selection label>" <selection command>
END
Example:
# Define a "Select" Menu for selecting the
# console, OR station 1, 2, or Aux station 5
MENU "Select"
"Console" select -console
MENU "Station"
"Station 1" select -station 1
"Station 2" select -station 2
"Aux Station 5" select -station 5
END
END
NOTE
Comment lines can be added to a file by placing a # as the first character of the line.
Using Standard IMAGE Buttons
In addition to the above keywords, you can also use several standard IMAGE buttons in the
button files. These standard buttons provide both backward compatibility to earlier versions
of IMAGE and capabilities not possible with the above keywords. Examples include the
LOAD button, which displays a menu of .tl and .load files in the current directory, and the
DEBUG/EXITDEBUG button, which changes its label according to a state of IMAGE.
Although you cannot change the functions of standard buttons, you can modify their
graphical features. You can specify button labels, fonts, and positioning using the keywords
described in “Changing the Station-Window Control Panel” on page 8-10.
To include or modify a standard IMAGE button, you must use the correct keyword listed in
table 8-1:
Table 8-1. Standard IMAGE Button Names
STANDARD_LOAD_BUTTON STANDARD_RUN_BUTTON STANDARD_LOOP_BUTTON
STANDARD_DEBUG_BUTTON STANDARD_ABORT_BUTTON STANDARD_HELP_BUTTON
STANDARD_CATD_BUTTON STANDARD_UPOWER_BUTTON STANDARD_DATAC_BUTTON
STANDARD_DISPLAY_BUTTON STANDARD_USER_BUTTON STANDARD_PROD_ENG_BUTTON
IMAGE Solutions V8.3 8-12
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
Table 8-1. Standard IMAGE Button Names (Continued)
STANDARD_CHECKER_BUTTON STANDARD_TOTRAP_BUTTON STANDARD_SETTRAP_BUTTON
STANDARD_UNSET_BUTTON STANDARD_STEP_BUTTON STANDARD_NEXT_BUTTON
STANDARD_CONT_BUTTON STANDARD_HALT_BUTTON
STANDARD_COMMUNICATIONS_BUTTON
Use these buttons in the button file as follows:
Keyword ["label_1"] ["label_2"]
Use the optional label parameters to define the label for a button. Buttons that change their
labels have two label specifications, one for each state. Standard buttons that change their
labels are:
STANDARD_LOAD_BUTTON STANDARD_LOOP_BUTTON
STANDARD_DEBUG_BUTTON STANDARD_PROD_ENG_BUTTON
For example, to define the standard LOAD button labels you could use:
STANDARD_LOAD_BUTTON "LOAD" "DELETE"
You can specify a button label in languages other than English, as in:
STANDARD_LOAD_BUTTON "Fardeau Prog" "Effacer"
The following lines from the default engineering_station_buttons file show the use of
standard buttons. Note that standard debug buttons do not appear unless the test program
is in debug, but screen space must be allocated for them.
###########################################################################
# Engineering Mode station window button configuration file
# /image/a500/bin/custom/engineering_station_buttons
#
# @(#)engineering_station_buttons3.8 10/16/91 Teradyne Inc
##########################################################################
# CREATE THESE BUTTONS FOR ENGINEERING MODE
###########################################################################
##########################################################################
# If desired: Specify a particular font to be used for the buttons.
# Some possible fonts are:
# FONT screen.b.14
# FONT screen.r.12
# THE Default GAP between buttons is 10
GAP 6
# Define the first row of buttons
# ( These are the standard Teradyne Buttons )
STANDARD_LOAD_BUTTON
STANDARD_RUN_BUTTON
IMAGE Solutions V8.3 8-13
IMAGE Base Language: Production Environment: Production Mode With Mouse
Table of Contents Index Home Master Index Search Help
STANDARD_LOOP_BUTTON
STANDARD_DEBUG_BUTTON
STANDARD_ABORT_BUTTON
STANDARD_HELP_BUTTON
STANDARD_CATD_BUTTON
#
# Define the second row of buttons
NEWROW
STANDARD_UPOWER_BUTTON
STANDARD_DATAC_BUTTON
STANDARD_DISPLAY_BUTTON
STANDARD_USER_BUTTON
STANDARD_PROD_ENG_BUTTON
STANDARD_CHECKER_BUTTON
################################################
# DEBUGGER BUTTONS - SHOULD ALWAYS BE LAST
################################################
NEWROW
STANDARD_TOTRAP_BUTTON
STANDARD_SETTRAP_BUTTON
STANDARD_UNSET_BUTTON
STANDARD_STEP_BUTTON
STANDARD_NEXT_BUTTON
STANDARD_CONT_BUTTON
STANDARD_HALT_BUTTON
# If the 'disappearing' print button is undesirable,
# It can be removed and replaced with ...
# BUTTON "print" "Print value of selected variable" print "$SELECTION"
STANDARD_PRINT_BUTTON
##################################################################
########################## E O F #########################
##################################################################
IMAGE Solutions V8.3 8-14
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
Production Mode Using Menus
You can operate in production mode without using the mouse. This mode uses the same
windows described in “Production Mode With Mouse” on page 8-5, but the mouse cursor is
frozen in the lower right corner of the production window and menus appear (figure 8-2).
You issue commands by typing the number or letter corresponding to a menu selection.
In this mode, disconnect and remove the mouse. If you do not disconnect the mouse, the
mouse is fully functional and can be used as in the production environment with the mouse
(see “Production Mode With Mouse” on page 8-5).
Station monitor
Station window
Figure 8-2. Production Environment with Menus
Starting IMAGE in Production Mode with Menus
You can start IMAGE in production mode for use without a mouse in any of the following
ways:
• Type oper2 at the Solaris prompt.
• Type image -production -nomouse.
IMAGE Solutions V8.3 8-15
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
The .login file for the production mode account determines the type of production operator
interface used. To set up your test system for production mode without the mouse, you can
either instruct operators to log in under the operator2 accounts, or you can create new
accounts and copy the operator2 home directories to your new accounts. The new
accounts need new entries to the password file, /etc/passwd.
Switching Between Production Mode and Engineering Mode
For production mode without the mouse, the TESTER UTILITIES menu item allows you to
change to engineering mode. Remember that changing modes changes the operating
mode for all the station, console, and monitor windows (not just the one that issued the
command).
IMAGE has a “lockout” mechanism that prevents unauthorized operators from switching to
engineering mode. This mechanism uses a Solaris account (in the /etc/passwd file) called
ENGINEER. This account has a password (the default password is engineering) and a pop-
up password prompt appears whenever a request is made to change to engineering
mode. If you have no account or type the incorrect password, the request is denied.
Changing from engineering to production mode has no lockout.
NOTE
You cannot change to production mode from any station while any station is in debug. If you
try, IMAGE prompts you to exit debug.
Switching Between Windows
In production mode, the station and console windows are automatically opened and placed
(overlapping) on the right side of the workstation screen. Only a single station or console
window is visible at one time. You can cycle between these windows using the Front
function key (on some keyboards, L5 for left-handed operation for or R9 for right-handed
operation).
Station Monitor
When you load and run a test program, a station monitor window (see figure 8-2) appears
in the upper left part of the workspace showing:
• Bin number for the device and site number (for a multisite test)
• Test program name
• Insertion
• Lot ID and sublot ID
• Number of devices tested and device number
• Software bin number (SBIN)
IMAGE Solutions V8.3 8-16
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
• Current yield percentage for all sites
• Cumulative yield percentage for all sites
• Numbers used to calculate the current and cumulative percents
Using Production Menus
Menus appear in the order that you would use them. Make menu selections by typing the
number of the selection followed by a Return.
Some menu items execute commands when they are selected. For example, the EXIT
TESTER EXECUTIVE item executes a command that halts the IMAGE executive. These item
numbers are enclosed in parentheses, as in (3).
Other menu items display submenus. For example, selecting the TESTER UTILITIES item
displays a submenu with a different set of selections. Items which correspond to submenus
are numbered in the menu using square brackets, as in [1].
Once you enter a submenu, that submenu is displayed until you give the command q or
quit; then the interface returns you to the menu you were in before. Typing qa returns you
to the topmost menu level.
If you are at any menu other than the top level menu, you can tell your position in the menu
tree by the name printed in brackets above the current menu title. For example:
[MAIN MENU:]
SELECT HANDLER:
(1) SELECT MANUAL TEST
(2) ELECTROGLAS 2001 PROBER
(3) DAYMARC 757 SERIES HANDLER
(H) HELP FOR THIS MENU
[Q ] QUIT MENU
SELECTION:
In this example, we are at the SELECT HANDLER menu. We came from the Main menu by
typing 5 and can return to the Main menu by typing q. You can get help for the current menu
by typing h or help.
Main Menu
The Main menu consists of the following items:
MAIN MENU:
(1) DISPLAY CURRENT SETUP
(2) DISPLAY TEST HEAD CONFIGURATION
(3) DELETE CURRENT SETUP
(4) SELECT TEST PROGRAM
[5] SELECT HANDLER/INSERTION
(6) SELECT LOT ID
IMAGE Solutions V8.3 8-17
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
(7) SELECT TEST CONDITION
[8] SELECT DATALOG
(9) CHANGE STATION NUMBER
[10] TESTING-IN-PROGRESS OPTIONS
[11] TESTER UTILITIES
(H ) HELP FOR THIS MENU
where:
DISPLAY CURRENT SETUP
Displays the information filled in so far for the lot to be tested,
including:
TEST PROGRAM
HANDLER/PROBER
INSERTION
DATALOG
TEST CONDITION
LOT ID
DELETE CURRENT SETUPDeletes the currently loaded test program and associated setup.
SELECT TEST PROGRAM
Allows you to view a list of available test programs and select
one by number. Programs listed are from the directory specified
in Production setup section of the IMAGE Properties window
under TEST PROGRAM DIRS. (See “Production Setup Options” on
page 3-37.)
SELECT HANDLER/INSERTION
Brings up a submenu with specific handler and prober choices.
The choices are:
(1) SELECT MANUAL TEST
(2) ELECTROGLAS 2001 PROBER
(3) DAYMARC 757 SERIES HANDLER
(H) HELP FOR THIS MENU
[Q] QUIT MENU
SELECT LOT ID Allows you to type in an alphanumeric lot ID.
SELECT TEST CONDITION Displays any test conditions in the test program.
SELECT DATALOG Brings up a submenu with the following choices:
(1) DATALOG ALL TESTS TO STDF FILE
(2) DATALOG FAILED TESTS TO STDF FILE
(3) NO DATALOGGING
(H) HELP FOR THIS MENU
[Q] QUIT MENU
CHANGE STATION NUMBER
Prompts you for a new station number and makes that station
the current one.
IMAGE Solutions V8.3 8-18
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
TESTING-IN-PROGRESS OPTIONS
Brings up a submenu, including a selection that enables the
handler or prober to begin testing, as well as items that can be
executed while testing is in progress. Items include:
(1) BEGIN TESTING
(2) SUSPEND TESTING
(3) PRINT PARTIAL SUMMARY TO LINE PRINTER
(4) DISPLAY PARTIAL SUMMARY ON SCREEN
(5) FINAL SUMMARY
(H) HELP FOR THIS MENU
[Q] QUIT MENU
TESTER UTILITIES Brings up a submenu with the following items:
(1) CHANGE STATION NUMBER
(2) CHANGE TO ENGINEERING MODE
(3) EXIT TESTER EXECUTIVE
(4) RE-INITIALIZE TESTER HARDWARE
(5) VIEW UNIX CONSOLE
(6) TERMINATE MENU INTERFACE
(H) HELP FOR THIS MENU
[Q] QUIT MENU
CHANGE TO ENGINEERING MODE and TERMINATE MENU INTERFACE
prompt you for a password.
Selecting Stations
Select or change stations from the Main menu or from the Tester Utilities menu by selecting
CHANGE STATION NUMBER. When you select a new station, IMAGE switches to the new
station. You can also see the console window by selecting VIEW UNIX CONSOLE from the
Tester utilities menu.
Loading Test Programs
The Main menu contains a SELECT TEST PROGRAM item which displays a list of all available
test programs. Only the test programs installed in the directory or directories specified by
the IMAGE Properties window TEST PROGRAM DIRS option are displayed. (See “Setting Up
a Load File” on page 8-46.)
The SELECT TEST PROGRAM item prompts for the first few characters of the program name.
If you just press RETURN, all available programs are listed. If you enter a prefix, only those
programs which match the prefix are listed, narrowing the list of programs if the entire list is
large. Choose a test program by typing the number or letter to the left of the test program
name.
Setting Up a Lot
To set up a lot of parts for testing, use the following procedure:
IMAGE Solutions V8.3 8-19
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
1. Load a test program.
2. Set the lot ID.
3. Select handler/prober/manual insertion.
4. Turn on datalog (optional).
5. Select BEGIN TESTING from the TESTING-IN-PROGRESS OPTIONS menu.
Partial Summaries
While a lot is being tested, you can request partial summaries by selecting the PRINT PARTIAL
SUMMARY item. Partial summaries have no effect other than to show a snapshot of the lot
results at the time of the request.
Closing a Lot
When a lot is complete, select the FINAL SUMMARY item from the TESTING IN PROGRESS
menu. This item closes the lot and prints a final summary. After the final summary is printed,
you can either test a new lot of parts or change the setup for a different type of parts. If the
new lot of parts uses the same test program, handler, and fixtures, only the lot ID needs to
be changed. If the setup must be changed, you must clear the current setup by selecting
DELETE CURRENT SETUP from the Main menu.
Customizing the Menus
You can customize the menu interface. You can alter the contents and appearance of the
menus and the commands executed when menu items are selected. “Changing the Menu
Description File” on page 8-30 and “Enabling Temporary Menus” on page 8-32 describe
changes you can make to the production mode with menus.
The menu interface is based on an ASCII description file which you can edit using a
standard text editor. This file, menufile, is located in $IMAGEBIN/custom and contains a
description of each menu and menu item in a language created for that purpose. You can
modify menufile to make a new menufile which becomes the input for a program called
compilemenu. The compilemenu program reads the new menufile and compiles
menufile to produce a program called menuprogram which displays the new menu
interface when the program is executed.
If you are running IMAGE under Solaris 2, compilemenu compiles menufile and produces
a file called menuprogram.svr4.
Structure of the Menu Description File
The menu description file is an ASCII file containing:
• Keywords, all in uppercase
• Operators, such as {
• Strings enclosed in double quotes
IMAGE Solutions V8.3 8-20
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
Any characters after a #, but up to the next newline, are considered to be comments. White
space (spaces, tabs, and newlines) is allowed between keywords.
The following conventions are recommended for use when developing menu description
files:
• Menu names are lower case
• Environment variables are all upper case
• A tab is four spaces
• Indent one tab setting within clauses with curly braces ({})
• Within a MENU_ITEM definition, HELP appears before the COMMAND definition
• Within a file, environment variable declarations appear first, followed by the STARTUP
and MENU_DEFAULTS clause, and then the MENU definitions. The top-level menu is
defined last.
Menu and Menu Items
The MENU clause defines a menu which appears in the menu interface. The format of the
MENU clause is as follows:
MENU <menuname> {
<options>
<menu items>
}
where:
menuname Is a unique identifier for the menu. This identifier is an
alphanumeric name that immediately follows the MENU keyword.
options Is a MENU clause that defines an option for that menu.
menu items Is one of the items (selections) in the menu.
TITLE
An example of a menu option is the TITLE option:
TITLE <string_specifier>
This item specifies the title to display for this menu. The title is the text printed above the list
of menu selections. The argument to this option, <string_specifier>, can be either a
single double-quoted string followed by a semicolon, or a list of double-quoted strings
enclosed in curly braces ({}). Examples of legal string specifiers are:
TITLE "this is one line";
TITLE {
"this is the first line"
"this is the second line"
}
IMAGE Solutions V8.3 8-21
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
HELP
A second option is the HELP option:
HELP <string_specifier>
Use this option to specify the strings printed if you ask for help while this menu is being
displayed. The <string_specifier> argument uses the same format as described above.
For example:
MENU empty_menu {
TITLE "Title goes here";
HELP {
"This menu contains commands which"
"allow you to ..."
}
<menu items>
}
MENU_ITEM
The most important options in a MENU clause are the ones that determine the appearance
and function of the individual selections (or “menu items”) in the menu. For each selection
in a menu, a MENU_ITEM clause is defined. This clause is made up of the keyword
MENU_ITEM, followed by the name and then a series of optional keywords or clauses
surrounded by curly brackets. For example:
MENU dummy {
MENU_ITEM "<name>"{
HELP <string_specifier>
COMMAND {
<list of commands>
}
}
}
When the menu is printed so you can make a selection, the <name> string is printed as the
text that describes the item.
COMMAND
The COMMAND section lists the commands executed when you choose that menu item. The
elements that appear in the COMMAND clause can be UNIX or IMAGE keyboard commands,
such as ls, date, or run or one of a set of special keywords corresponding to predefined
commands.
For example:
MENU simple_menu {
TITLE "Simple";
MENU_ITEM "print date"
COMMAND {
IMAGE Solutions V8.3 8-22
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
PRINT "The date today is as follows:"
"date"
}
}
}
PRINT
The first command in this example is a PRINT command. PRINT is a predefined command
that causes its argument (a string) to be printed to the screen. The second command is the
UNIX command date, which prints the current date to the screen. If the menu above were
displayed, the menu would look like:
SIMPLE
(1) PRINT DATE
(H) HELP FOR THIS MENU
[Q] QUIT MENU
SELECTION:
If item 1 were selected from this menu, first the PRINT command would be executed, and
then date would be run, resulting in the following being printed (the date varies, of course):
The date today is as follows:
Tue Oct 10 10:40:41 EDT 2000
SUBMENU
Instead of a COMMAND clause, a MENU_ITEM can have a SUBMENU clause. The SUBMENU clause
links a submenu to a menu item. If the item is selected, the system switches to displaying a
new menu until you quit from that menu. Syntax for this construct is as follows:
SUBMENU <menu name>;
For example:
MENU date_menu {
TITLE "Date" ;
MENU_ITEM "print date" {
COMMAND {
PRINT "The date today is as follows:"
"date"
}
}
}
MENU simple_menu {
TITLE "Simple" ;
MENU_ITEM "Bring up date menu" {
SUBMENU date_menu ;
IMAGE Solutions V8.3 8-23
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
}
}
Note the use of the SUBMENU keyword in the second MENU clause. When selected, this item
brings up the submenu date_menu, rather than executing a command.
MENU_ITEM HELP
The MENU_ITEM clause can contain a HELP construct for supplying on-line help for the
selection. The syntax of the HELP construct for menu items is identical to that used in the
MENU clause. For example:
MENU_ITEM "print date" {
HELP {
"If you select this item, it will"
"cause the date to be printed."
}
COMMAND {
PRINT "The date today is as follows:"
"date"
}
}
Using Environment Variables
The operator menu interface provides a method for storing and accessing state information
for a given session using UNIX environment variables. UNIX environment variables are set
pairs of names and values associated with every UNIX program. New environment
variables can be created and the values of existing variables can be read or written. For
more on environment variables, see the section entitled environ in section 5 of the Sun on-
line manual (and the references which follow that section) by typing the command man 5
environ.
When a command is specified in the COMMAND clause of a MENU_ITEM, this command is
executed using the Bourne shell. In other words, the command is executed as if you had
typed the command at the shell prompt. To use environment variables in a menu-item
command, assign and reference them as you would in a Bourne shell script. For example:
"MYVAR=FOO" #Assigns the value FOO to variable MYVAR
PRINT "$MYVAR" #Prints value of variable MYVAR
Note that environment variables can be referenced from PRINT commands, as shown
above. Within the context of the menu interface, environment variables can be used to store
“global” state information and to record values temporarily to be reused later. For example:
MENU_ITEM "set variable" {
COMMAND {
PRINT "Setting variable FOO to 'abc'"
"FOO=abc"
PRINT "The value of 'Foo' is $FOO"
PRINT "Setting variable FOO to 'def'"
IMAGE Solutions V8.3 8-24
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
"FOO=def"
PRINT "The value of 'Foo' is $FOO"
}
}
In the above example, the environment variable FOO is used to store a string which is used
in subsequent PRINT commands.
READ_RESPONSE
You can use environment variables to store your response to a question. The menu
description language provides a special command for this purpose, READ_RESPONSE, which
reads a single line of your response and stores the text in an environment variable. The
syntax is as follows:
READ_RESPONSE $<variablename> ;
For example:
MENU_ITEM "Echo response" {
COMMAND {
PRINT "Enter a line of text"
READ_RESPONSE $User_response ;
PRINT "You just typed $User_response"
}
}
When executed, this command prompts you for a line of input, stores the text in the
environment variable User_response, and then echoes the text to the screen.
DECLARE_VARIABLE
Certain environment variables are already defined and used by IMAGE. For example, the
environment variable STATION_NUMBER is defined when a shell program is within the
command area of a station window. Altering the value of these environment variables can
have hazardous results. To ensure that no environment variable “collisions” occur, declare
all environment variables to be used in a menu program at the beginning of the menu
description file using the DECLARE_VARIABLE statement. The syntax is as follows:
DECLARE_VARIABLE <variablename>;
In this syntax, <variablename> is an environment variable which is to be used later in the
description file. If the variable name conflicts with an IMAGE environment variable, a
warning is issued by the menu file compiler.
STARTUP
All user environment variables start with no value assigned to them. If a variable must be
initialized before the start of the menu interface, use the STARTUP clause to set the variable
to a value. The syntax is as follows:
IMAGE Solutions V8.3 8-25
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
STARTUP {
<commands>
}
When you place this construct into the menu description file, commands specified in the
construct are executed as the menu interface is started, before any user interaction. In the
following example, the variable MYNAME is set to Terwillicker:
DECLARE_VARIABLE MYNAME ;
STARTUP {
"MYNAME=Terwillicker"
}
MENU ...
Reserved Environment Variable Names
The following names are reserved environment variables. Do not define any user
environment variables using these names.
DATASERV_HOST IMAGEBIN IMAGEHOST
I_CURMENU I_DONEFLAG I_MENUSTACK
I_RESPONSE I_STATION I_STATION
I_STATUS I_TMP1 I_TMP2
PATH STATION_HOST STATION_NUMBER
SYSCOM_HOST TESTER_NUMBER TSTC0
HOME SHELL TERM
USER PATH LOGNAME
PWD OPENWINHOME LD_LIBRARY_PATH
CKRBIN LM_LICENSE_FILE IMAGE_GRAPHICS
DISPLAY TSTC COMMON_DIR
SCHOME MANPATH HELPPATH
EDITOR
Additional Menu Item Commands
When you choose a menu selection, typically it is not enough to execute a command.
Usually, some checks and tests must be made before execution of the command to be sure
the conditions are correct. Checks are sometimes required to make sure a previous
command had the desired effect. For example, if a menu contains an item which turns on
datalog for a test program, IMAGE should be able to check before performing this operation
to see if a test program is loaded (since datalog cannot be enabled before loading a test
program).
The menu description language provides constructs which can be used to check conditions
when an item is selected.
IMAGE Solutions V8.3 8-26
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
CHECK_STATUS
The CHECK_STATUS keyword allows you to execute a command and take some action if the
command passes or fails. Most Solaris and IMAGE commands end with an “exit status,” a
number passed back to the calling program to indicate whether the called program was
successful or failed. The CHECK_STATUS construct uses this “exit status.” The syntax is as
follows:
CHECK_STATUS "<testcommand>" {
IF_PASS <passcommands>
IF_FAIL <failcommands>
}
The command <testcommand> is executed and the exit status of this command is
examined. In Solaris, an exit status of 0 is considered successful. If the exit status is 0, any
commands in the IF_PASS clause are executed. If the exit status is nonzero,
<testcommand> fails, and commands specified in the IF_FAIL clause are executed instead.
For example:
CHECK_STATUS "date -illegal_flag" {
IF_FAIL {
PRINT "the command ‘date -illegal_flag‘ failed"
}
IF_PASS {
PRINT "the command ‘date -illegal_flag‘"
" completed successfully"
}
}
In this example, the command date -illegal_flag is executed, the exit status of the
command is checked, and the commands in one of the two following clauses are executed.
In this case, since -illegal_flag is an invalid option to the Solaris date command, the
exit status is always nonzero. Hence, commands in the IF_FAIL clause are always
executed.
ABORT
You can halt execution of a command sequence if a check or test fails using the ABORT
keyword. If ABORT is encountered at any point during execution of a command sequence,
processing of commands is terminated for the menu item. For example:
COMMAND {
CHECK_STATUS "load myprogram" {
IF_FAIL {
#
# We were not able to load program
# ‘myprogram’, so do not proceed any
# further.
#
ABORT
}
IMAGE Solutions V8.3 8-27
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
PRINT "Load completed."
}
In this COMMAND clause above, if the load command in the CHECK_STATUS clause fails, the
ABORT causes command processing to halt, before the execution of the final PRINT
command.
CHECK_VARIABLE
Another language construct, the CHECK_VARIABLE clause, can be used to take conditional
action based on the value of an environment variable. The syntax is as follows:
CHECK_VARIABLE $<variable_name> <op> "<stringvalue>" {
IF_TRUE <truecommands>
IF_FALSE <falsecommands>
}
where:
<variable_name> Is the name of an environment variable to evaluate.
<op> Is one of the logical operators: == | !=.
<stringvalue> Is a string to use for comparison.
The environment variable’s value is compared against the string given. If the comparison
yields TRUE, <truecommands> is executed, otherwise <falsecommands> is executed. For
example:
CHECK_VARIABLE $MYVAR== "1" {
IF_TRUE {
PRINT "Variable MYVAR is set to 1"
}
IF_FALSE {
PRINT "Variable MYVAR is not set to 1"
ABORT
}
}
When this construct is executed as part of the COMMAND clause of a menu item, this construct
tests the environment variable MYVAR. If MYVAR is set to 1, IF_TRUE is executed. If MYVAR is
not equal to 1, IF_FALSE is executed.
Command Execution
Solaris and IMAGE commands in a COMMAND clause are passed to the Bourne shell when
executed. This allows the Bourne shell to be used for such things as input/output
redirection, wildcard expansion, and so on. The following sections cover some of the
Bourne shell features you can use for command execution.
IMAGE Solutions V8.3 8-28
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
Suppressing or Redirecting Output
When an IMAGE or Solaris command fails, the error message that appears on the screen
is usually not suitable for operators. You may want to suppress the output of a command
and print an error message using the menu language instead. The following examples show
two ways of printing an error message using the menu language:
COMMAND {
"load foobar" # Loads test program foobar
PRINT "Load complete"
}
COMMAND {
CHECK_STATUS "load foobar 1> /dev/null 2>&1" {
IF_FAIL {
PRINT "Load of program foobar failed."
PRINT "Please notify your supervisor."
ABORT
}
}
PRINT "Load complete"
}
In the first example, the load command prints messages to the screen during operation (for
example, LOAD IN PROGRESS). If the load command encounters an error (for example, if a
program is already loaded), the load command prints an error message to the screen. This
example has the following disadvantages:
• The operator must be trained to ignore the "..." status messages.
• If the load fails, the error message printed by the load command tells the operator that
something failed but gives no instructions on what to do next.
In the second example, when the load command is executed, the Bourne shell operators
1> /dev/null 2>&1
are given, which redirect the Solaris standard output and standard error for the command
to the null device. If the load fails, the CHECK_STATUS clause prints the error message:
Load of program foobar failed...
Quoting
Different types of quotes have special meaning to the Bourne shell. The three types of
quotes which can be used in a Bourne shell command are double quote ("), single quote
('), and back quote (‘).
Back quotes are used to capture the output of a command and to use the output as an
argument for another command. For example:
"MYVAR=‘hostname‘"
In the above command, the Bourne shell treats the contents of the backquotes as a
command to be executed, and runs the command and replaces the back-quoted section
IMAGE Solutions V8.3 8-29
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
with the output of the command. In effect, the hostname command is executed and the
output put into the environment variable MYVAR. You do not have to use a temporary file
when initializing an environment variable using the output of a program.
Text placed inside double quotes is not subjected to wildcard expansion by the Bourne
shell. For example:
"MYVAR=foo*"
"MYVAR=\"foo*\""
In the first example, the Bourne shell tries to expand the * wildcard by trying to match any
files which begin with foo and placing the names of these files into the environment variable
MYVAR.
In the second example, since the * is surrounded by double quotes, the * is interpreted
literally and the environment variable MYVAR is set to the string foo*. Since double quotes
are already used as delimiters for strings in the menu description file language, you must
enclose foo* with escape characters (\) to use them within a command string.
Text placed inside single quotes is not subject to wildcard expansion and does not have
environment variable references expanded. For example:
"echo $MYVAR"
"echo '$MYVAR'"
In the first example, the expression $MYVAR is replaced with the value of the environment
variable MYVAR, and that string is passed to the UNIX program echo. In the second example,
because of the single quotes, no environment variable substitution takes place, resulting in
the literal string $MYVAR being passed to the program echo.
Changing the Menu Description File
You may want change the operator interface by editing the IMAGE menu description file,
menufile (located in $IMAGEBIN/custom). Several common changes are described in this
section.
Adding Menu Selections for New Handlers and Probers
The default IMAGE menufile contains a menu which allows operators to select the type of
handler or prober being used for testing. Each selection in this menu allows the operator to
enable a particular handler type, as defined by the handcap handler database (see “Setting
Up a handcap File” on page 1-7 in the Handler/Prober Manual).
IMAGE provides support for many handler types and allows you to define new handler types
by creating new entries in the handcap database file. As a result, the handler selection menu
in the default IMAGE menufile does not contain selections for all possible handler and
prober types, and you may have to add selections in this menu for handler and prober types
in use at your site. This can be done fairly easily by copying one of the existing entries in
the SELECT HANDLER menu and substituting the name of the new handler and prober for the
old one.
IMAGE Solutions V8.3 8-30
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
Using a Different Datalogging Strategy
Datalogging strategies vary widely. Some applications require STDF datalogging
(particularly if FIRMS is in use), some require ASCII datalogging (usually for
characterization situations), and many require no datalogging at all.
The default IMAGE menufile provides a simple view of datalogging to the operator: you
can either turn the datalogging on or off, and only one setup is provided (STDF datalogging).
To implement a more complex datalogging strategy, copy the items in the default menufile
and alter them. You can add more selections (to allow different types of datalogging), or you
can remove a datalog step altogether by commenting out the menu item (and commenting
out the check for datalog selection in the BEGIN TESTING item).
Using a Different Language
The menu description file format is specifically designed to allow versions of the menu
interface to be developed which support different languages. The default IMAGE menufile
uses English text for all of its menu selection descriptions, error messages, prompts, and
help, but you can translate these items to another language if necessary. By translating text
in the PRINT, HELP, and TITLE statements in the menufile, as well as the names given to
each MENU_ITEM, you can create a version of the menu interface which uses a different
language but still executes the same commands.
Sometimes the menu interface prints messages not specified anywhere in the menu
description file. For example, if the user chooses a menu item number which does not exist,
the menu interface prints (by default) the error message:
Illegal selection.
Since these messages must be translated as well when developing menu interface in a
different language, a special language construct, the MENU_DEFAULTS clause, is provided
which allows you to substitute foreign language versions of these messages as well. Syntax
is as follows:
MENU_DEFAULTS {
SELECTION_PROMPT <string_specifier>
SELECTION_ERROR <string_specifier>
QUITITEM_NAME <string> ;
HELPITEM_NAME <string> ;
NOHELP_ERROR <string_specifier>
}
In the above statement, <string> is a string enclosed in double quotes, and
<string_specifier> is either a single string followed by a semicolon, or a list of strings,
enclosed by curly braces. Each of the items in this clause is optional (although the clause
must contain at least one option).
The SELECTION_PROMPT item determines what message is printed to prompt for a menu
selection. This string is printed each time a menu is displayed; the default is the string
SELECTION:.
IMAGE Solutions V8.3 8-31
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
The SELECTION_ERROR item determines the message printed when the user makes an
illegal menu selection. The default is:
""
"Illegal selection."
""
The QUITITEM_NAME and HELPITEM_NAME items determine the text displayed when each
menu is displayed which describes the q and h items. (These selections appear by default
for every menu.) The defaults for these items are QUIT MENU and HELP FOR THIS MENU,
respectively.
The NOHELP_ERROR item determines the error message printed if a user asks for help on a
menu or menu item for which no help was given in the menu description file. The default for
this item is the following:
""
"No help available for this menu or menu item."
""
Enabling Temporary Menus
The QUIT_MENU_ON_SELECTION option is provided for temporary submenus. A temporary
menu brings you back up to the previous menu after a single selection is made. Temporary
submenus can be useful if the operator must choose a single option from a list of possible
options.
To enable this feature, add the following clause to the menu definition:
OPTIONS { QUIT_MENU_ON_SELECTION; }
This clause must appear before any of the menu items. If a particular menu is defined as
temporary, none of the items within the menu can bring up a submenu.
Menu Keywords
Following is a list of all keywords which can appear in a menu description file. Also included
are syntax descriptions and a few examples. More examples are in the default
$IMAGEBIN/custom/menufile.
ABORT
ABORT is a predefined command which is used in the IF_FAIL, IF_PASS, IF_TRUE, or
IF_FALSE clauses of a CHECK_STATUS or CHECK_VARIABLE clause. If executed, this keyword
causes processing to be terminated for the commands in the current COMMAND sequence.
Syntax: ABORT
Example:
IMAGE Solutions V8.3 8-32
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
COMMAND {
CHECK_STATUS "<command1>" {
IF_FAIL {
"<command2>"
ABORT
}
}
"<command3>"
}
In this example, <command1> is always executed. If <command1> passes, <command3> is
executed. If <command1> fails, the IF_FAIL clause is processed, which causes <command2>
to be executed and then an ABORT. The ABORT terminates processing, which means that
<command3> (and any subsequent commands, if any) are not executed.
CHECK_STATUS
CHECK_STATUS executes a command, determines whether the command passes or fails,
and takes some action based on the pass/fail result. In the syntax description, <command>
is a Solaris or IMAGE command (surrounded by double quotes) that is to be executed. For
the IF_PASS and IF_FAIL clauses, <cmds> is either a single command followed by a
semicolon, or a list of commands enclosed in curly braces.
When this construct is executed, the first <command> is executed and the exit status is
checked. If the exit status is 0, commands in the IF_PASS clause are executed (if present).
If the exit status is nonzero, commands in the IF_FAIL clause are executed (if present).
Note that you must specify at least one of the IF_FAIL or IF_PASS clauses, but you need
not specify both.
Syntax: CHECK_STATUS "<command>" {
[IF_FAIL <cmds>]
[IF_PASS <cmds>]
}
CHECK_VARIABLE
CHECK_VARIABLE performs a logical test on the value of an environment variable. The name
of the environment variable to examine is given by <variablename>, the logical operation
(either != or ==) is given by <op>, and the string to compare the value against is given by
<comparestring> (a string enclosed in double quotes). If the comparison is successful
(that is, the value of the environment variable is equal/not-equal to the compare string),
commands in the IF_TRUE clause are executed. If the comparison fails, commands in the
IF_FALSE clause are executed. For the IF_TRUE and IF_FALSE clauses, <cmds> is either a
single command followed by a semicolon, or a list of commands enclosed in curly braces.
Note that you must specify at least one of the IF_FAIL or IF_PASS clauses, but you need
not specify both.
Syntax:
CHECK_VARIABLE $<variablename> <op> "<comparestring>"
IMAGE Solutions V8.3 8-33
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
{
[IF_TRUE <cmds>]
[IF_FALSE <cmds>]
}
CLEAR
CLEAR is a predefined command which clears the window (screen) when executed. After a
clear, all subsequent messages printed to the window (screen) start at the top of the output
area.
Syntax: CLEAR
COMMAND
The keyword COMMAND is part of the definition for a menu item; it appears as an option within
the MENU_ITEM clause. It specifies the commands to be executed if the user selects the item.
In the syntax description, <cmds> can be either a single command followed by a semicolon
or a list of commands enclosed in curly braces.
A command is either a quoted string containing a Solaris or IMAGE command (example:
date), or one of a set of predefined commands made available by the menu description
language. Predefined commands include PRINT, PRINT_N, READ_RESPONSE,
READ_PASSWORD, CLEAR, ABORT, CHECK_STATUS, and CHECK_VARIABLE.
Syntax: COMMAND <cmds>
Example:
COMMAND "date" ; #Simple command
COMMAND { #Compound command
PRINT "the date is: "
"date"
}
DECLARE_VARIABLE
DECLARE_VARIABLE is used to declare an environment variable for later use in the menu file.
In the syntax description, <variablename> is the name of the variable to be used. This
statement is provided primarily as a means of avoiding collisions between user variables
and variables used by IMAGE or by the menu interface itself. The menu description file
compiler does not make it mandatory to declare environment variables before use. You
must ensure that all variables are declared properly.
Syntax: DECLARE_VARIABLE <variablename> ;
HELP
The HELP construct specifies help string(s) to be provided to the user for a given menu or
menu item. It appears as an option in the MENU or MENU_ITEM clauses.
IMAGE Solutions V8.3 8-34
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
In the syntax description, <strings> is either a single string followed by a semicolon or a
list of strings enclosed in curly braces.
Syntax: HELP <strings>
Example:
MENU_ITEM "example item" {
HELP {
"If you select this item, it will"
"print the current date and time."
}
COMMAND {
"date"
}
}
If the user were to ask for help on the menu item in the example above, the messages
printed in response would be the ones specified in the HELP clause.
HELPITEM_NAME
HELPITEM_NAME is one of the options appearing in the MENU_DEFAULTS clause (see “Using
a Different Language” on page 8-31). In the syntax description, <string> is an ASCII string
surrounded by double quotes. By default, the help selection is displayed along with each
of the menu selections when a menu is displayed:
<Menu title>
<Menu selections>
...
(h) Help message for this menu
When the HELPITEM_NAME is placed in a MENU_DEFAULTS clause, the string specified is used
in place of the description used above (Help message for this menu). This keyword is
used primarily for creating menus in a language other than English.
Syntax: HELPITEM_NAME "<string>" ;
IF_FAIL
The IF_FAIL keyword is used only in the CHECK_STATUS clause. For more information, see
“CHECK_STATUS” on page 8-27.
Syntax: IF_FAIL <commands>
IF_FALSE
The IF_FALSE keyword is used only in the CHECK_VARIABLE clause. For more information,
see “CHECK_VARIABLE” on page 8-28.
Syntax: IF_FALSE <commands>
IMAGE Solutions V8.3 8-35
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
IF_PASS
The IF_PASS keyword is used only in the CHECK_STATUS clause. For more information, see
“CHECK_STATUS” on page 8-27.
Syntax: IF_PASS <commands>
IF_TRUE
The IF_TRUE keyword is used only in the CHECK_VARIABLE clause. For more information,
see “CHECK_VARIABLE” on page 8-28.
Syntax: IF_TRUE <commands>
MENU
The MENU keyword is used to define a menu. In the syntax description, <menuname> is a
unique alphanumeric name assigned to the menu being defined. (This name is used to refer
to the menu later on.) The <options> section of the MENU clause can contain the following
clauses: TITLE and HELP. The <menu items> section which follows contains one or more
MENU_ITEM clauses, which describe the selections in the menu. The <options> must
precede the definitions of the menu items.
Syntax: MENU <menuname> {
<options>
<menu items>
}
MENU_DEFAULTS
The MENU_DEFAULTS construct is used to modify certain prompt strings and error messages
used by the menu interface. It is usually used for creating a menu description file which uses
a language other than English. Legal options in the <options> section of this construct are
HELPITEM_NAME, NOHELP_ERROR, QUITITEM_NAME, SELECTION_ERROR, and
SELECTION_PROMPT. This clause must contain at least one of these options, but not all are
mandatory.
Syntax: MENU_DEFAULTS {
<options>
}
MENU_ITEM
The MENU_ITEM keyword appears within a MENU clause. It is used to define a new menu item
for the enclosing MENU. In the syntax description, <menu item name> is a string that gives
the name of the menu item as it is to be shown when the selections for the menu are
displayed. The <options> for a menu item are a HELP clause and a COMMAND or SUBMENU
clause. Typically, a menu item has a single HELP clause and either a SUBMENU clause or a
COMMAND clause.
IMAGE Solutions V8.3 8-36
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
Syntax: MENU_ITEM "<menu item name>" {
<options>
}
NOHELP_ERROR
The NOHELP_ERROR keyword is one of the options appearing in the MENU_DEFAULTS clause
(see “Using a Different Language” on page 8-31). In the syntax description, <strings> is
either a single string followed by a semicolon or a list of strings enclosed by curly braces.
The NOHELP_ERROR specifies the error message the menu interface prints if the user asks
for help on a menu or menu item for which no help was specified. By default, this message
is:
""
"No help available for this menu or menu item."
""
This option is usually used to translate this error message into a language other than
English.
Syntax: NOHELP_ERROR <strings>;
OPTIONS
The OPTIONS clause is used to specify optional information about a menu definition. The
OPTIONS clause, similar to the TITLE and HELP clauses, must appear before any menu
items in the menu definition. Currently, the only option available for a menu is
QUIT_MENU_ON_SELECTION.
Syntax: OPTIONS { <option keywords> }
PRINT
The PRINT keyword is a predefined command which you can use in a COMMAND clause (or a
subclause) in the definition of a MENU_ITEM. In the syntax description, <string> is a string
surrounded by double quotes. The specified string is output to the user (the string is treated
as an entire line of output). This command is usually used to prompt the user or convey a
set of instructions.
Syntax: PRINT "<string>"
PRINT_N
The PRINT_N keyword is identical to the PRINT keyword with one exception. When the text
string is printed, no newline is printed after it. (Hence, any subsequent output or input
appears on the same line.)
Syntax: PRINT_N <string>
IMAGE Solutions V8.3 8-37
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
QUIT_MENU_ON_SELECTION
The QUIT_MENU_ON_SELECTION keyword appears in the OPTIONS clause within a menu
definition. If this keyword is present, the menu being defined becomes a “temporary” menu.
When you enter the menu, the selections are displayed as with normal menus, but when
you make a selection, after the selection is through, control switches back to the previous
menu immediately. In a normal menu, this happens only when you quit from the menu.
The top level menu cannot be specified as a temporary menu. Temporary menus cannot
have menu items which invoke submenus.
Syntax: QUIT_MENU_ON_SELECTION ;
QUITITEM_NAME
The QUITITEM_NAME keyword is one of the options appearing in the MENU_DEFAULTS clause
(see “Using a Different Language” on page 8-31). In the syntax description, <string> is an
ASCII string surrounded by double quotes. By default, the quit selection is displayed along
with each of the menu selections when a menu is displayed:
<Menu title>
<Menu selections>
...
(q) Quit menu
When the QUITITEM_NAME is placed in a MENU_DEFAULTS clause, the string specified is used
in place of the description used (Quit menu) for the quit selection. This keyword is used
primarily for creating menus in a language other than English.
Syntax: QUITITEM_NAME "<string>" ;
READ_PASSWORD
The READ_PASSWORD statement is used to read back a password from the user. When the
password is typed, the characters typed are not echoed, and the user’s response is placed
into an environment variable. In the syntax description, <variablename> receives the text
of the response.
Syntax: READ_PASSWORD $<variablename> ;
This keyword is typically used to restrict access to a particular menu item to only those users
who know a certain password.
Example:
MENU_ITEM "Remove all files in current directory" {
HELP {
"Selecting this item will remove all"
"files in the current directory. You"
"must give a password to use"
"this item."
}
IMAGE Solutions V8.3 8-38
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
COMMAND {
PRINT_N "Enter the password to continue: "
READ_PASSWORD $PASSWD ;
CHECK_VARIABLE $PASSWD == "apple" {
IF_FALSE {
PRINT ""
PRINT "Incorrect password. No action
taken."
PRINT ""
ABORT
}
}
PRINT "Removing all files...."
"rm *"
}
}
In the example, READ_PASSWORD is used in combination with the CHECK_VARIABLE
statement to make sure the user gives the correct password before a sensitive command
(removing all files) is executed.
READ_RESPONSE
The READ_RESPONSE command provides a way to read back a response from the user.
When executed, it reads back a line of input from the user and stores that input in the
environment variable specified. In the syntax description, the environment variable is given
by <variablename>.
Syntax: READ_RESPONSE $<variablename> ;
The following example, in which a line of input is read from the user and then echoed,
illustrates its use:
COMMAND {
PRINT "Enter a line of input:"
READ_RESPONSE $TMP_RESPONSE ;
PRINT "The line was: $TMP_RESPONSE"
}
SELECTION_ERROR
The SELECTION_ERROR keyword is one of the options appearing in the MENU_DEFAULTS
clause (see “Using a Different Language” on page 8-31). In the syntax description,
<strings> is either a single string followed by a semicolon or a list of strings enclosed by
curly braces.
The SELECTION_ERROR specifies the error message that the menu interface prints if the user
tries to select a menu item that does not exist. For example: selecting menu item 9 if there
are only four choices. By default, this message is as follows:
IMAGE Solutions V8.3 8-39
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
""
"Illegal selection. Type ‘h’ for help."
""
This option is used primarily to translate an error message into a language other than
English.
Syntax: SELECTION_ERROR <strings>;
SELECTION_PROMPT
The SELECTION_PROMPT keyword is one of the options appearing in the MENU_DEFAULTS
clause (see “Using a Different Language” on page 8-31). In the syntax description,
<strings> is either a single string followed by a semicolon or a list of strings enclosed by
curly braces.
SELECTION_PROMPT specifies the prompt printed when the menu interface asks the user for
a selection. By default, this prompt is set to the string Selection:. This option is used
primarily to translate a system message into a language other than English.
Syntax: SELECTION_PROMPT <strings>;
STARTUP
The STARTUP clause specifies a command or list of commands to be executed when the
menu interface is started, before displaying any menus. It is usually used to do things like
initialize environment variables or perform other one-time initializations. In the syntax
description, <commands> is a command list similar to the argument to the COMMAND keyword
(either a single command or a list of commands enclosed by curly braces).
Syntax: STARTUP <commands>;
Example:
STARTUP {
PRINT "Starting menu interface..."
# Print startup message
"COUNT=0" # Initialize environment variable
}
SUBMENU <name> ;
SUBMENU
The SUBMENU keyword is used as part of the MENU_ITEM clause. It is used to specify that
when a particular menu item is selected, a submenu should be brought up (as opposed to
executing a command). The <name> given as the argument to SUBMENU must be the name
of a menu which is defined somewhere in the menu description file.
Syntax: SUBMENU <name> ;
IMAGE Solutions V8.3 8-40
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
TITLE
The TITLE construct specifies the title to be used for a particular menu; it must appear as
an option inside a MENU clause. The title for a menu is the text printed immediately before
the menu selections are printed. In the syntax description, <strings> is either a single
string followed by a semicolon or a list of strings enclosed in curly braces.
Syntax: TITLE <strings>;
Example:
MENU my_menu {
TITLE {
"***MY MENU***"
}
...
}
Menu File Example
The following is an example of a menu description file:
MENU top_level_menu {
TITLE "Main menu:";
HELP {
""
"This is the main menu. To make a selection, type the number
of the selection followed by <return>"
}
MENU_ITEM "Select datalog"{
#This line is a non-printing comment.
HELP {
""
"Selecting this item brings up a submenu which allows you
to choose the kind of datalog to use"
}
COMMAND{
PRINT "The date is:"
"date"
}
SUBMENU datalog_selection_menu ;
}
MENU_ITEM "Delete current setup"{
...
}
MENU_ITEM "Select test program"{
...
}
}
IMAGE Solutions V8.3 8-41
IMAGE Base Language: Production Environment: Production Mode Using Menus
Table of Contents Index Home Master Index Search Help
Running the Menu Description File Compiler
Once you create a menu description file, you must compile it using the menu description file
compiler, named compilemenu. The syntax for compilemenu is:
compilemenu [-default] [-input<filename> -output<filename>]
where:
-default Looks for a file named menufile in the current directory and
writes an output file named menuprogram. If you are running
IMAGE under Solaris 2, the output file is called
menuprogram.svr4.
-input Specifies an input file name.
-output Specifies an output file name.
Menuprogram
The file menuprogram resides in the directory $IMAGEBIN/custom. The .login file of the
account used for production invokes menuprogram. If you make changes to the menu
description file and recompile the file to produce a new output file, you must copy this output
file to the home directory of the production account.
If you are running IMAGE under Solaris 2, the output file is called menuprogram.svr4.
Switching Between Modes
To allow an engineer to debug problems during production, a Change to engineering
mode command is provided in the Tester Utilities menu to switch IMAGE back to
engineering mode and bring up a standard UNIX shell for debugging. IMAGE can be set up
to prompt for a password when switching between production and engineering mode. (See
“Switching Between Production Mode and Engineering Mode” on page 8-16.) When the
switch to engineering mode is complete, the normal engineering station window is displayed
with a standard UNIX shell running in it. When the debug session is complete, return to
production mode by typing exit to terminate the shell.
Accelerator Keys
Some Sun keyboards have function keys at the top of the keyboard. You can use these keys
(such as F1 and F2) as accelerators. Typing function key F1 is equivalent to 1 followed by
Return, typing function key F2 is equivalent to 2 followed by Return, and so on. The top row
of keys on the right hand side of the keyboard, R1, R2, and R3, are accelerators for quit,
help, and qa (quit to top) respectively.
IMAGE Solutions V8.3 8-42
IMAGE Base Language: Production Environment: Run-Time Error and Alarm Messages
Table of Contents Index Home Master Index Search Help
Run-Time Error and Alarm Messages
When a tester is in production, the test program may issue alarm and run-time error
messages. Some alarms and errors can be due to a bad device (a source connected to
ground through a shorted pin, for example). Other alarms or errors may indicate a more
serious problem, such as an incorrectly set up device adaptor board.
When an error occurs in production mode, the test program issues the error message, bins
the parts accordingly, and continues testing. By default, error and alarm messages are sent
to the screen.
Error and alarm messages are intended to be read and interpreted by engineers. Do not
send them to the screen when the tester is in production, since the messages may confuse
operators. You can direct run-time error and alarm messages to the error log files by
selecting the RECORD_IN_LOG item in the IMAGE Properties window. You also have the
option of handling alarm messages separately using the ALARM MESSAGE HANDLING item in
IMAGE Properties. You can also use the Alarm Manager to redirect messages; see
“Reporting Alarms” on page 22-5 for more information.
Logging Error and Alarm Messages to a File
Store error and alarm messages in a file using error logging. When error logging is enabled,
error messages are written to a log file instead of to the screen. If a tester is having problems
on a lot (for example, low yield), a lead operator or test floor manager can halt production
on the tester and examine the log file to see if the low yield is due to a repeated alarm or
error.
Note that even when errors and alarms are logged to a file instead of printed to the screen,
IMAGE takes the same action based on the error or alarm (fails the test, bins the part in the
error bin, and so on).
Error logging in production mode is controlled using IMAGE Properties. For more
information on the using IMAGE Properties to control production setup, see “Setting Up
Production Environment Defaults” on page 8-46.
To enable error logging:
1. Select PROPERTIES>IMAGE PROPERTIES from the IMAGE Workspace menu. The
IMAGE Properties window appears.
2. Switch to the PRODUCTION SETUP category by pressing MENU on the CATEGORY menu
button in the upper left corner of the window and selecting from the menu.
3. Locate the RUNTIME ERROR AND ALARM LOGGING section. Press MENU on the ERROR
ALARM HANDLING menu button and select RECORD_IN_LOG or SCREEN_AND_LOG from the
menu.
4. Use the ERROR ALARM LOG LIFETIME item to set the number of days to keep a log before
automatically trimming it. The default is 21.
5. Click APPLY to save the changes.
IMAGE Solutions V8.3 8-43
IMAGE Base Language: Production Environment: Run-Time Error and Alarm Messages
Table of Contents Index Home Master Index Search Help
6. Exit IMAGE Properties. If more than one account is used for production, you must repeat
this procedure for each account, since default settings are kept on an account-by-
account basis.
NOTE
Error logging applies only to test programs loaded when IMAGE is in production mode. All
programs loaded in engineering mode generate error and alarm messages in the station
window, or in Alarm Manager if you enable it.
Handling Alarm Messages Separately
You can use an item in IMAGE Properties to handle alarm messages separately from error
messages. The item ALARM MESSAGE HANDLING gives you the following choices:
SAME_AS_ERROR_MESSAGES
Send alarms to the destination set by the ERROR ALARM
HANDLING property. (This is the default.)
SCREEN_DISPLAY Send alarms to the screen.
RECORD_IN_LOG Send alarms to a log file. Format of the alarm log name and
content are the same as for the error/alarm log.
SCREEN_AND_LOG Send alarms to both the screen and a log file.
IGNORE Do not log or print alarm messages.
You can also set the alarm destination from a test program using the function
tl_set_alarm_msg_mode(). This function has the following syntax:
enum TL_MSG_MODE tl_set_alarm_msg_mode(newmode)
enum TL_MSG_MODE newmode;
where newmode is one of the following:
MSG_MODE_ALRM_MSGS_DEFAULT
Return to default. Alarm messages are sent to the same
destination as error messages.
MSG_MODE_PRINT_ALRM_MSGS
Write alarm messages to screen.
MSG_MODE_LOG_ALRM_MSGS
Write alarm message to log file.
MSG_MODE_PRINT_AND_LOG_ALRM_MSGS
Write alarm messages to screen and log file.
MSG_MODE_IGNORE_ALRM_MSGS
Do not write alarm messages anywhere. This will lose all record
of an alarm ever having occurred.
IMAGE Solutions V8.3 8-44
IMAGE Base Language: Production Environment: Run-Time Error and Alarm Messages
Table of Contents Index Home Master Index Search Help
MSG_MODE_SHOW No change. Return value of current alarm message destination
only.
Log File Location and Log Message Format
Error and alarm message log files are written to the directory
/image/tester/<testcomputer>/errlog, where <testcomputer> is the host name of
the test system tester computer. Filenames are of the form:
errors_<station>_<timestamp> [for error messages]
alarms_<station>_<timestamp> [for alarm messages]
where <station> is the station number of the test program producing the errors, and
<timestamp> is the time the file was created. The format of the messages in these files is
as follows:
PC: <partcount> TN:<testnumber> “error or alarm message”
where <partcount> is the number of parts binned when the message was logged and
<testnumber> is the number of the test in which the error or alarm happened (if it was in a
test function). The error or alarm message portion that follows is identical to the message
normally printed to the screen.
Error or alarm log files are opened when the first alarm or error is logged. They are closed
when the test program is deleted.
You can bring up a textedit with the most recent error or alarm log file by inserting the
following aliases in your .cshrc file and then typing the alias:
showlasterrorfile ‘(pushd /image/tester/$TSTC0/errlog;textedit ‘ls -t errors* |
head -1‘) &’
showlastalarmfile ‘(pushd /image/tester/$TSTC0/errlog;textedit ‘ls -t alarms* |
head -1‘) &’
IMAGE Solutions V8.3 8-45
IMAGE Base Language: Production Environment: Setting Up Production Environment Defaults
Table of Contents Index Home Master Index Search Help
Setting Up Production Environment Defaults
You can set up the production environment to automate some functions. For example, you
can set up IMAGE to load production test programs from a specified list of directories. This
makes loading programs easier for production operators who may be unfamiliar with the
Solaris directory structure. You can also direct datalog data files to a specific directory.
These directories can be local to the tester or centralized on one fileserver or on several
fileservers.
Set up this access mechanism using IMAGE Properties to establish the Xdefaults
database for an account. IMAGE Properties is a tool which helps you set up default values
which are maintained within a workstation’s defaults database. (See “Setting IMAGE
Properties” on page 3-34 and Sun’s on-line Help Viewer.)
Database information for each user is maintained in the .Xdefaults file in that user’s
account. To establish a default setting for a group of users (such as production operators)
you must create a common .Xdefaults file in the manager account and set up a symbolic
link to the .Xdefaults file from the individual accounts. The Xdefaults database (and the
IMAGE Properties window) contains a category called PRODUCTION SETUP for specifying
where production test programs are found and where datalog data files are to be placed.
Invoke IMAGE Properties by selecting PROPERTIES>IMAGE PROPERTIES from the IMAGE
Workspace menu. When the window appears, press MENU on the CATEGORY menu button
and select PRODUCTION SETUP. Figure 8-3 shows the items for this selection.
These properties are discussed in the following sections. Error and alarm functions are
described in “Run-Time Error and Alarm Messages” on page 8-43.
Setting Up a Load File
To set up IMAGE to load test programs from a specified list of directories, use the TEST
PROGRAM DIRS item. This item specifies a list of directories which are searched (in order)
when a load <programname> is executed. The directories can be on the local (tester) disk
or on a remotely mounted fileserver.
The order of the directories is important. Loading from a local disk is slightly faster but many
testers must be updated when the program is updated. Loading programs from a local disk
is useful if a server becomes unavailable.
In the example in figure 8-3, the directory /home/system1_s/operator2 would be
searched for the test program.
IMAGE Solutions V8.3 8-46
IMAGE Base Language: Production Environment: Setting Up Production Environment Defaults
Table of Contents Index Home Master Index Search Help
Figure 8-3. Production Setup in IMAGE Properties
When a station is in engineering mode, the directories listed in the TEST PROGRAM DIRS
defaults item are no longer automatically searched when the load command is given. If
these directories are needed in the search path, use the -production option when invoking
the load command.
For example, assume a station has been changed to engineering mode to debug a
production test program stored in one of the directories listed in TEST PROGRAM DIRS. To add
these directories to the search path, execute the load command in the following way:
load -production <test_program_name>
Setting Up a Test Data File
The TEST DATA DIRS item allows you to specify a directory (local or remote) for storing
datalog data files. You can specify only a single directory for storing datalog data files. In
the example in figure 8-3, data files are placed in /home/system1_s/operator.
You can use environment variables when specifying the names of directories or portions of
directories. For example, specifying TEST DATA DIRS as $HOME/data would place all datalog
files in the subdirectory data of the user’s home directory.
IMAGE Solutions V8.3 8-47
IMAGE Base Language: Production Environment: Setting Up Production Environment Defaults
Table of Contents Index Home Master Index Search Help
Setting Datalog Filename Length
The filenames of IMAGE data files may be too long when transferring test data outside of
the test system. Some hardware and software may not allow filenames above a certain
number of characters. The MAX FILENAME LENGTH item allows you to specify a maximum
number of characters for a data filename. The minimum for this item is 13 because IMAGE
needs at least that many characters to ensure that each filename is unique. (See “Output
Selection” on page 6-37 for information on data filenames.)
Window Defaults
The defaults specified in the previous sections are inherited from the user currently logged
into the station window. For example, if two users with completely different sets of defaults
log in to different station windows, each user can access his own production test data and
test program directories. Also, users can inherit other defaults they have specified, such as
scroll bar, button layout, and font.
IMAGE Solutions V8.3 8-48
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
The Station Monitor
The station monitor (figure 8-4) shows the current setup and state of a test station. The
station monitor is not displayed when you enter production mode.
Bin
region
Monitor
region
Figure 8-4. Station Monitor
Invoke the station monitor display using the statmon command:
statmon [-station #] [-off] [-soft (D)] [-hard]
where:
-off Turn station monitor off.
-soft (default) Display software bin numbers. By default, the station monitor
displays the software bin number. (See “Assigning Bin Numbers”
on page 15-6.)
-hard Display hardware bin numbers. (See “Assigning Bin Numbers”
on page 15-6.)
NOTE
Bin assignment in the yield_monitor.yield file (see “Specifying Hardware or Software
Bins” on page 8-63) overrides the bin assignment from the command line.
-station # Specifies a station number.
You cannot invoke the station monitor if you do not have a test program loaded.
The station monitor display is divided into two regions:
IMAGE Solutions V8.3 8-49
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
• The bin region at the top shows the results of the last bin assignment for the device
tested for each active test site in large type. It also can display the first failed test for each
device that failed.
• The monitor region at the bottom of the window displays the current settings of
production related variables within the test program. It also includes yield monitor items.
Specifying Items in the Station Monitor
The station monitor displays production variables for the test program being run. Table 8-2
lists the items that can be monitored and a definition for each. These variables are stored in
the file $IMAGEBIN/custom/statmon.data. You can create your own version of the station
monitor by copying statmon.data into your home directory ($HOME). This file overrides the
default directory in $IMAGEBIN/custom.
Table 8-2. Station Monitor Items
Label on
Keyword Definition
Display
Program JOB_NAM Test program name
Lot Id LOT_ID Lot identification number
Sub Lot Id SBLOT_ID Sublot name or ID
Tested PART_CNT Number of devices tested so far
Device PART_ID Device identification number
Message MEMO Message to the operator
Insertion TEST_COD Test conditions code
Part Type PART_TYP Part type (or product ID)
Node NODE_NAM Name of node that generated data
Tester Type TSTR_TYP Tester type
N/A JOB_REV Job (test program) revision number
N/A EXEC_TYP Tester executive software type
Proc ID PROC_ID Fabrication process ID
Supervisor SUPR_NAM Supervisor name or ID
SBIN Software bin — to display the software
bins in the station monitor change the
contents of the yield_monitor.yield file
(see “Specifying Hardware or Software
Bins” on page 8-63).
IMAGE Solutions V8.3 8-50
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
Table 8-2. Station Monitor Items (Continued)
Label on
Keyword Definition
Display
HBIN Hardware bin — to display the hardware
bins in the station monitor change the
contents of the yield_monitor.yield file
(see “Specifying Hardware or Software
Bins” on page 8-63).
CURR% Current yield (see “Using Yield Monitor
Items” on page 8-54)
CUM% Cumulative yield (see “Using Yield Monitor
Items” on page 8-54)
Operator OPER_NAM Operator name
Lot Started START_T Time lot started
Test Head HEAD_NUM Test-head number
Handler HAND_ID Handler identification number
1stF SHOW_FIRST_FAIL First failed test for each failing device
IMAGE Solutions V8.3 8-51
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
Table 8-2. Station Monitor Items (Continued)
Label on
Keyword Definition
Display
N/A SHOW_BINS_IN_COLOR Bin values in IMAGE pass/fail colors
PARALLEL_BIN_LARGE_F Large font for bin values on multisite test
ONT programs
ENG_ID Engineering lot ID
DSGN_REV Device design revision
FACIL_ID Test facility ID
FLOOR_ID Test floor ID
FAMLY_ID Product family ID
FLOW_ID Test flow ID
HEAD_NUM Test-head number
NODE_NAM Name of node generating data
OPER_FRQ Operation frequency or step
PKG_TYP Package type
PROC_ID Fabrication process ID
SETUP_ID Test setup ID
SPEC_NAM Test specification name
SPEC_VER Test specification version number
WAFER_ID Wafer ID
The following statmon.data file was used to create the station monitor in figure 8-4. (This
figure also includes yield monitor fields. See “Using Yield Monitor Items” on page 8-54.)
##################################################################
# statmon.data
# "@(#)statmon.data /main/9 02/06/96 09:35:26 Teradyne, Inc."
#
# This is the layout file for the Test Station Monitor
# Utility (statmon).
# The layout of an item is specified as follows:
#
# ( <row> , <column> ): <fieldwidth> "<Label>" <KEYWORD>
#
# See also "yield_monitor.yield".
#
IMAGE Solutions V8.3 8-52
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
##################################################################
#
# Some example fonts:
# FONT gallant.r.19
# FONT courier.16
# FONT cmr.r.8
# FONT screen.b.14
# FONT serif.r.14
# FONT screen.b.12
# FONT times-bold10
# FONT times-italic14
# FONT times-roman16
# FONT statmon_font.r.19
# FONT times-bolditalic12
# FONT screen.b.12
# FONT lucidasans12
# FONT -adobe-courier-bold-r-normal--10-100-75-75-m-60-iso8859-1
#
#
FONT lucidasans12
(0,0):25 "Program" JOB_NAM
#FONT times-bold10
(0,27):3 "Insertion" TEST_COD
#(0,27):25 "Operator" OPER_NAM
#(1,0):50 "Lot Started" START_T
#FONT times-italic14
(1,0):25 "Lot Id" LOT_ID
#FONT times-roman16
(1,27):25 "Sub Lot Id" SBLOT_ID
#FONT times-bolditalic12
(2,0):15 "Tested" PART_CNT
(2,27):15 "Device" PART_ID
#FONT helvetica-bold14
#(4,0):5 "Test Head" HEAD_NUM
#(4,34):10 "Handler" HAND_ID
#(5,0):50 "Message" MEMO
#
##################################################################
# The following options are on if present and off if commented out:
# PARALLEL_BIN_LARGE_FONT... Use full size bin font even for parallel test
# SHOW_FIRST_FAIL........... Show first failed test number
# SHOW_BINS_IN_COLOR........ Show bin values using IMAGE pass/fail colors
#
#PARALLEL_BIN_LARGE_FONT
SHOW_FIRST_FAIL
#SHOW_BINS_IN_COLOR
In this file, any line beginning with a # is a comment line and is ignored. Note that some
variables in the example are commented out, providing a default set of variables for the
display. The FONT keyword specifies a particular font to use when displaying monitor
information. Fonts are not restricted to those listed in the file, but you must use a valid Sun
font or an error occurs.
IMAGE Solutions V8.3 8-53
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
NOTE
In the statmon.data file, select fonts so that all information can be displayed in the space
allowed. If you use large fonts, some information may not fit in the monitor region of the
display.
Showing the First Failure
The item to show the first failed test, SHOW_FIRST_FAIL, is somewhat different from other
entries in table 8-2. Placing this keyword anywhere in the statmon.data file causes the
1stF item to appear in the bin (upper) region of the station monitor (see figure 8-4). If you
use this keyword, place it on a line by itself in the file.
Using IMAGE Pass/Fail Colors
You can use IMAGE pass/fail colors to show binning values by using the keyword
SHOW_BINS_IN_COLOR in the statmon.data file. The default is to show the bins in black.
The keyword is commented out.
Displaying a Large Font
To display a large bin number in the Station Monitor, even when multiple sites are displayed,
add a keyword to the file $IMAGEBIN/custom/statmon.data. If the keyword
PARALLEL_BIN_LARGE_FONT is specified in the file, the Station Monitor takes up a little more
room on the screen and displays the bin number for multisite displays in the same large font
used for single-site displays.
Displaying a Message in the Station Monitor
The Message (MEMO) item in the monitor region can be used to alert operators to certain
conditions which may exist in the tester. In a test program, use the function
tl_statmon_memo("text"); to send ASCII text to the Message item. (See
“tl_statmon_memo” on page 26-399.) To clear a message, call:
tl_statmon_memo("");
Using Yield Monitor Items
The station monitor includes the yield of parts binned in various bins. You can display the
yield for up to 10 bins, and the monitor also allows you to set alarms for the bins. Setup
parameters for this display are contained in a file, yield_monitor.yield in
$IMAGEBIN/custom, which you can modify.
The yield monitor displays two types of yield (see figure 8-4 on page 8-49):
IMAGE Solutions V8.3 8-54
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
• Current yield is the percentage of parts falling into a particular bin in the recent past,
where the recent past is the last n number of parts (n is a user-selectable number). Think
of the number as a sliding window that specifies the most recent history of testing.
• Cumulative yield is the percentage of all parts tested since a particular lot was started.
In addition to displaying the current and cumulative percents for each selected bin, the
actual numbers used to calculate these values are also displayed. For example:
SBIN 0 1
CURR% 80.0 20.0
CUM% 60.0 40.0
CURR# 20 5
out of: 25
CUM# 120 80
out of: 200
In this example, the window size is set to 25, and 20 of the last 25 were bin 0. But out of the
full lot of 200 tested so far, 120 were bin 0. Before you have tested 25 parts (or whatever
your window size is), the display will look as follows:
SBIN 0 1
CURR% N/A N/A
CUM% N/A N/A
CURR# 10 2
out of: <25
CUM# 10 2
out of: 12
The bins displayed on the yield monitor portion of the station monitor can be individual bins
or several bins grouped together and treated as a single unit. The yield monitor can display
up to 40 different bins per column.
For example, assume bins 5, 6, 7, and 8 are failing bins and bins 1 and 2 are passing bins.
You can specify a label such as Fail and have the yield monitor calculate the yield based
on three bins: Fail, 1, and 2. Whenever a part is binned in bins 5, 6, 7, or 8, the count and
percentages for Fail are incremented and updated.
The station monitor can also show yield-by-site information, which appears in the bin region
of the window. Including yield-by-site information may increase the size of the monitor
window by up to three lines.
Yield-by-site information options are:
Cum% - Cumulative yield percentage by site
Cur% - Current yield percentage by site
Cnt: - Number of parts tested on a particular site
You specify these display options by placing any or all of the following tags on a line by itself
anywhere in the .yield file:
CUM_YIELD_BY_SITE Displays cumulative yield percentage by site. This field displays
the percentage of all parts tested on each site since a particular
IMAGE Solutions V8.3 8-55
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
lot was started. This data is not available until after the first n
parts are tested.
CUR_YIELD_BY_SITE Turns on the current yield percentage by site feature. This field
displays the passing percentage of the last n tested parts. This
feature is similar to the current yield per bin except that it is
calculated per site. n is the size of the sliding window which
specifies the most recent history of testing. This data is not
available until after the first n parts are tested.
COUNT_BY_SITE Turns on a display of the number of parts tested per site.
Yield-by-site information is available for multisite test programs only and is not displayed for
single site test programs. There are no alarms to be set or triggered for each site's yields.
Figure 8-5 shows a sample station monitor window with yield-by-site information.
Yield-by-site
Bin Region
Information
Monitor Region
Figure 8-5. Station Monitor Display Window with Yield-by-Site Information
The following setup file was used to create the yield monitor fields in figure 8-5:
########################################################
#yield_monitor.yield
#
#This is the layout file for the Yield Monitor Utility
#(part of Statmon) for the Stamon window shown above.
########################################################
WINSIZE 10
FONT lucidasans12
#
IMAGE Solutions V8.3 8-56
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
CUM_YIELD_BY_SITE
CUR_YIELD_BY_SITE
COUNT_BY_SITE
#
BIN 0 LABEL 0
CUM_ULIM CUM_LLIM LABEL 0
CUR_ULIM CUR_LLIM LABEL 0
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL 0
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL 0
#
BIN 1 LABEL 1
CUM_ULIM CUM_LLIM LABEL 1
CUR_ULIM CUR_LLIM LABEL 1
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL 1
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL 1
#
PASS_BINS LABEL PASS
CUM_ULIM CUM_LLIM LABEL PASS
CUR_ULIM CUR_LLIM LABEL PASS
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL PASS
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL PASS
#
FAIL_BINS LABEL FAIL
CUM_ULIM CUM_LLIM LABEL FAIL
CUR_ULIM CUR_LLIM LABEL FAIL
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL FAIL
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL FAIL
#
##################################################################
Standard Setup File
Setup information for the yield monitor is contained in a setup file called
yield_monitor.yield located in $IMAGEBIN/custom. You can override this setup file in
either of two ways. One way is to create a yield_monitor.yield file in your home directory
($HOME). The other way is to create a file with any name (but it must have the extension
.yield) and list it in your .load file. This setup file will override both the default
yield_monitor.yield file in $IMAGEBIN/custom and the one in your home directory.
NOTE
In the yield monitor setup file, select fonts so that all yield information can be displayed in
the space allowed. If you use large fonts, some yield information may not fit in the yield
monitor region of the display.
Setup File Example
The following setup file was used to create the yield monitor fields in figure 8-4 on page
8-49:
IMAGE Solutions V8.3 8-57
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
##################################################################
# yield_monitor.yield
#
# This is the layout file for the Yield Monitor Utility
# (part of statmon).
#
# See also "statmon.data".
#
##################################################################
#
# Some example fonts:
# FONT gallant.r.19
# FONT courier.16
# FONT cmr.r.8
# FONT screen.b.14
# FONT serif.r.14
# FONT screen.b.12
# FONT times-bold10
# FONT times-italic14
# FONT times-roman16
# FONT statmon_font.r.19
# FONT times-bolditalic12
# FONT screen.b.12
# FONT lucidasans12
# FONT -adobe-courier-bold-r-normal--10-100-75-75-m-60-iso8859-1
#
WINSIZE 10
FONT lucidasans12
#
BIN 0 LABEL 0
CUM_ULIM CUM_LLIM LABEL 0
CUR_ULIM CUR_LLIM LABEL 0
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL 0
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL 0
#
BIN 1 LABEL 1
CUM_ULIM CUM_LLIM LABEL 1
CUR_ULIM CUR_LLIM LABEL 1
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL 1
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL 1
#
BIN 2 LABEL 2
#CUM_ULIM CUM_LLIM LABEL 2
#CUR_ULIM CUR_LLIM LABEL 2
#CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL 2
#CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL 2
#
BIN 3 LABEL 3
#CUM_ULIM CUM_LLIM LABEL 3
#CUR_ULIM CUR_LLIM LABEL 3
#CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL 3
#CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL 3
IMAGE Solutions V8.3 8-58
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
#
BIN 4 LABEL 4
#CUM_ULIM CUM_LLIM LABEL 4
#CUR_ULIM CUR_LLIM LABEL 4
#CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL 4
#CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL 4
#
BIN 5 LABEL 5
#CUM_ULIM CUM_LLIM LABEL 5
#CUR_ULIM CUR_LLIM LABEL 5
#CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL 5
#CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL 5
#
#PASS_BINS LABEL PASS
#CUM_ULIM CUM_LLIM LABEL PASS
#CUR_ULIM CUR_LLIM LABEL PASS
#CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL PASS
#CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL PASS
#
#FAIL_BINS LABEL FAIL
#CUM_ULIM CUM_LLIM LABEL FAIL
#CUR_ULIM CUR_LLIM LABEL FAIL
#CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL FAIL
#CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL FAIL
#
#PASS_FAIL_PANEL
#
#CUM_ULIM CUM_LLIM LABEL PASS_INFO
#CUR_ULIM CUR_LLIM LABEL PASS_INFO
#CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL PASS_INFO
#CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL PASS_INFO
#
#CUM_ULIM CUM_LLIM LABEL FAIL_INFO
#CUR_ULIM CUR_LLIM LABEL FAIL_INFO
#CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL FAIL_INFO
#CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL FAIL_INFO
##################################################################
In this setup file, any line beginning with a # is a comment line and is ignored. The FONT
keyword specifies a particular font to use when displaying yield information. Fonts are not
restricted to those listed in the file, but you must use a valid Sun font or an error occurs.
The WINSIZE <integer value> line specifies the sample size used to calculate the current
yield. This is the size of the sliding data window. No yield information is displayed until at
least WINSIZE parts are tested.
Each statement following the WINSIZE declaration ends with the LABEL <value>
declaration. Information on that line is assigned to a particular bin or bin group. The BIN
<integer value1> ...<integer valuen> statement assigns the particular bins to a
particular bin group named LABEL <value>. The value for the label can be an integer or a
character, but more than two characters may not fit in the yield monitor region. The minimum
IMAGE Solutions V8.3 8-59
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
number of arguments to use with the BIN statement is one, and a maximum of 40 bins can
be grouped together. Bins exceeding the limit are ignored.
Use the CUM_ULIM <float> and CUM_LLIM <float> keywords to specify the upper and
lower yield alarm values. Yield values (and alarms) are calculated to one decimal point
accuracy. To specify the current upper and lower yield alarm values use the CUR_ULIM
<float> and CUR_LLIM <float> keywords. Each of these statements must be terminated
with a LABEL <value> statement. You must group the statements for a particular bin group
together with the BIN statement as the first statement. The yield alarm statements must also
precede the statements specifying the yield alarm values. Within each type of statement,
you can place the keywords in any order.
Pass and Fail Columns
You can add pass and fail columns to the station monitor by adding the keywords
PASS_BINS and FAIL_BINS to the setup file. These keywords will add a column to the
display for counts of passing or failing items. You can also use the individual bins in other
yield items. The LABEL used with these keywords are PASS and FAIL. You can also use the
standard yield monitoring items with these columns. An example of a display using pass and
fail columns is shown in figure 8-6.
Figure 8-6. Station Monitor Display Window with Pass and Fail Columns
To have the Station Monitor display the pass and fail columns, add the following lines to the
setup file:
PASS_BINS LABEL PASS
CUM_ULIM CUM_LLIM LABEL PASS
CUR_ULIM CUR_LLIM LABEL PASS
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL PASS
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL PASS
FAIL_BINS LABEL FAIL
CUM_ULIM CUM_LLIM LABEL FAIL
IMAGE Solutions V8.3 8-60
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
CUR_ULIM CUR_LLIM LABEL FAIL
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL FAIL
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL FAIL
Pass and Fail Panel
Pass and fail information can also be displayed as a panel at the bottom of the station
monitor by using the keyword PASS_FAIL_PANEL in the setup file. When you use the
PASS_FAIL_PANEL keyword, you can carry out all the yield monitor operations that are
possible when using the PASS_BINS and FAIL_BINS keywords. However, the valid LABEL
values are PASS_INFO and FAIL_INFO. You can also use the standard yield monitoring
items with these columns. An example of a display using pass and fail at the bottom of the
display is shown in figure 8-7.
Figure 8-7. Station Monitor Display Window With Pass and Fail Panel
To have the station monitor display the pass and fail panel, add the following lines to the
setup file:
PASS_FAIL_PANEL
#
CUM_ULIM CUM_LLIM LABEL PASS_INFO
CUR_ULIM CUR_LLIM LABEL PASS_INFO
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL PASS_INFO
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL PASS_INFO
#
CUM_ULIM CUM_LLIM LABEL FAIL_INFO
CUR_ULIM CUR_LLIM LABEL FAIL_INFO
IMAGE Solutions V8.3 8-61
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
CUM_HYIELD_ALARM CUM_LYIELD_ALARM LABEL FAIL_INFO
CUR_HYIELD_ALARM CUR_LYIELD_ALARM LABEL FAIL_INFO
Specifying Alarms
Each bin group you select comes with four different alarms. Each group can have:
• Cumulative high-yield alarm
• Cumulative low-yield alarm
• Current high-yield alarm
• Current low-yield alarm
Specify alarms using the following keywords:
CUM_HYIELD_ALARM <scriptname>
Specifies cumulative high-yield alarm.
CUM_LYIELD_ALARM <scriptname>
Specifies cumulative low-yield alarm.
CUR_HYIELD_ALARM <scriptname>
Specifies current high-yield alarm.
CUR_LYIELD_ALARM <scriptname>
Specifies current low-yield alarm.
If the script names are short enough, the cumulative or current statements for each type of
alarm can appear on the same line or they can be separated. Each line must end with the
LABEL statement.
The high-yield alarms can be set at a yield percentage and be triggered if the yield is
unusually high. For example, a 100% yield may indicate a good part is stuck in the jaws of
a handler and is being retested over and over. A high-yield alarm appears as a + (plus) sign
to the left of the yield being displayed.
You can also set the low-yield alarms to occur if the current or cumulative yields fall below
values that you select. A low-yield alarm appears as a - (minus) sign to the left of the yield
that is alarming.
You can select distinct values for either high or low yields. You can also have a script file
execute if a particular yield alarms. The default script provided by Teradyne sends a
T_ALARM event to the FIRMS host, if one exists. You can also edit these scripts to perform
other functions. At the end of a lot you must undo anything an alarm script has performed.
Therefore, create another script that is executed at the end of every lot to undo the actions
of the alarm scripts. In a future release, Teradyne will provide an option to specify such a
script to be executed.
NULL values for particular types of alarms are ignored, so that a particular keyword can
appear on a line without any scriptname specified. Alarm scripts are executed, if specified,
if the yield goes above or below a particular value, depending on the type of alarm. If the
yield value hovers below (or above) a particular threshold so that the yield remains alarmed,
IMAGE Solutions V8.3 8-62
IMAGE Base Language: Production Environment: The Station Monitor
Table of Contents Index Home Master Index Search Help
the alarm script is executed only once. If the yield alarm returns to acceptable limits the
alarm is reset and executed again if the yield falls into unacceptable limits.
Specifying Hardware or Software Bins
In addition to specifying the bin assignment from the command line, you can display either
hardware or software bins in the station monitor by changing the contents of the
yield_monitor.yield file. Enter either SOFT_BIN (to display software bins) or HARD_BIN
(to display hardware bins) as the first noncomment entry in the yield_monitor.yield file.
The specification in the yield_monitor.yield file overrides the specification from the
command line.
IMAGE Solutions V8.3 8-63
IMAGE Base Language: Production Menu Control
Table of Contents Index Home Master Index Search Help
9 PRODUCTION MENU CONTROL
The Production Menu Control (PMC) allows you to design a custom graphic user interface
with menus and buttons for production operation. Using a PMC interface, test system
operators can run tests and collect data while having a minimum of technical interaction with
the test system computer.
PMC consists of a programming language (Menu Description Language, or MDL), a library
of functions and program definitions, and a graphic tool (PMCtool) configured to your
requirements. PMC can use IMAGE commands, UNIX commands, and scripts to perform
operations. You can partition menus into many files so that product-specific choices are
reflected in a particular PMC.
This section includes the following topics:
• “How to Use PMC” on page 9-3
• “Elements of a PMC Interface” on page 9-9
• “A Simple MDF” on page 9-15
• “MDF Structure” on page 9-18
• “Steps for Creating an MDF” on page 9-22
• “Using Collection and Auxiliary Files” on page 9-37
• “PMC Library” on page 9-43
• “MDL Keywords” on page 9-46
You can use the PMCtool for your production needs with minor changes to a database file,
see “Starting PMC” on page 9-4, or you can design your own PMC interface, see “Steps for
Creating an MDF” on page 9-22.
IMAGE also includes a production environment. For information on the IMAGE production
environment, see “Production Environment” on page 8-1.
IMAGE Solutions V8.3 9-1
IMAGE Base Language: Production Menu Control:
Table of Contents Index Home Master Index Search Help
Auxiliary Files Database Files
Functions Product Data
& Variables
Menu Description PMCtool
IMAGE commands
File (MDF)
UNIX commands
written in Menu
PMC library functions Description
Language (MDL)
Figure 9-1. Production Menu Control User Interface
IMAGE Solutions V8.3 9-2
IMAGE Base Language: Production Menu Control: How to Use PMC
Table of Contents Index Home Master Index Search Help
How to Use PMC
PMC is a binary program that interprets an ASCII control file, known as a menu description
file (MDF). This file causes the PMCtool to display a menu to an operator. The menu is
defined in the MDF.
The MDF contains the menu functions, variables, and commands used by the PMCtool.
Some of these are stored in collection and auxiliary files, which are referenced by the MDF.
The MDF tells the PMCtool what to display and enables or inhibits certain predefined
functions on each screen.
An MDF is written using Menu Description Language (MDL) syntax and keywords; see
“MDL Keywords” on page 9-46. Menu Description Language (MDL) is a standard language
used to implement menu-driven interfaces for the test system.
You can create different PMC interfaces by creating several MDFs. For example, you could
design a production MDF and an engineering MDF, each of which would present choices to
the user specific to that use of the test system. Although you can have several MDFs, only
one MDF is active for any particular session of PMC.
Operators use the PMCtool to communicate with the test system by choosing input
parameters, selecting actions, or receiving test data. The PMCtool menu screen reflects the
instructions programmed in the MDF. A typical screen is illustrated in figure 9-2.
Display
items
Menu
selections
Control
buttons
Figure 9-2. PMCtool Screen Using an MDF that References a Product Database
IMAGE Solutions V8.3 9-3
IMAGE Base Language: Production Menu Control: How to Use PMC
Table of Contents Index Home Master Index Search Help
Starting PMC
To start the PMCtool, enter the following command in a station window:
pmctool [-station <#>][-file_name <file>] [-nomouse] [-j9_paths]
where:
-station <#> Starts the PMCtool in the station number specified. The PMCtool
automatically attaches to the station where it is started. If starting
from outside the station window, identify the station number.
-file_name <file> Specifies the Menu Description File (MDF) to load. If no file
name is specified, the default is:
$IMAGEBIN/custom/menufile.mdl
-nomouse Indicates you want to use the keyboard for input and not the
mouse.
-j9_paths Specifies J9 style (IG900) path variable settings (see “Variable
Styles” on page 9-14).
After typing pmctool, two screens appear asking for the following information:
1. Enter the database directory by typing:
/image/bin.6.3/custom
2. Enter the operator name by typing:
Test
The initial PMC screen appears (see figure 9-2).
NOTE
When entering the database directory, the PMCtool does not accept $IMAGEBIN. Use the
path /image/bin.6.3/custom.
Modifying the Product Database
The PMCtool is ready for you to use. You can use the MDF which created figure 9-2 as is.
For testing your own parts, modify the product database file:
$IMAGEBIN/custom/product_db
This file lists the parts for testing in a collection format and is interpreted by the MDF (see
“Collection Files” on page 9-37). You can copy this file to your directory and modify it to your
needs.
IMAGE Properties
Set PMCtool properties using IMAGE properties, GLOBAL STATION WINDOW OPTIONS (see
figure 9-3) and MISCELLANEOUS options (see figure 9-4 on page 9-6).
IMAGE Solutions V8.3 9-4
IMAGE Base Language: Production Menu Control: How to Use PMC
Table of Contents Index Home Master Index Search Help
Figure 9-3. Setting PMCtool IMAGE Properties
The two items to set are:
• ACTION ON PMC ATTACH
• ACTION ON PMC DETACH
These properties control what happens to a station window when the PMCtool attaches or
detaches. Both properties have three settings:
DO NOTHING TO STATION
Default. Nothing is done to the station window.
ICONIFY STATION WINDOW
Causes the station window to close to an icon.
UNICONIFY STATION WINDOW
Reverses the iconify action.
IMAGE Solutions V8.3 9-5
IMAGE Base Language: Production Menu Control: How to Use PMC
Table of Contents Index Home Master Index Search Help
Figure 9-4. IMAGE Properties Miscellaneous Window
For example, you are running the PMC to control multiple stations and do not want to use
the Job I/O screen. You can have the station window displayed whenever the PMC
attaches. To do this, select UNICONIFY STATION WINDOW from the ACTION ON PMC ATTACH
and ICONFIY STATION WINDOW from the ACTION ON PMC DETACH.
From the Miscellaneous window, you can choose the ICD (default) or J9 style (IG900) path
variable settings in MDL files (see “Variable Styles” on page 9-14).
Quitting PMC
Normally, a quit function is written into the Menu Description File (MDF), but you can also
select QUIT from the PMCtool window menu to exit the program.
Customizing Screen Attributes
The size, location, and other attributes of the PMC window can be set to your requirements.
Default values for these fields are contained in the file:
$IMAGEBIN/custom/.pmctool_defaults
You can copy this file to your home directory and modify it.
The PMCtool defaults file structure is shown in figure 9-5. Windows and fields in this file are
defined in tables 9-1 and 9-2.
IMAGE Solutions V8.3 9-6
IMAGE Base Language: Production Menu Control: How to Use PMC
Table of Contents Index Home Master Index Search Help
Table 9-1. PMC Windows in PMCtool Defaults Files
Window Name Description
bin Runtime (Binning Display Window)
control Control Buttons Window
datalog Job Data Window
jobio Job Input/Output Window
menu Main Menu Window
status Runtime (Status Display Window)
Table 9-2. Fields in PMCtool Defaults Files
Field Name Description
FollowMenu (For nomouse operation) If true, the Job I/O window follows the main
menu window so that input typed from the keyboard is received into it.
font Font to use in the window. Takes the name of any valid font.
height The vertical size of the window, in pixels. (One inch = 83 pixels,
SPARC)
lock Prevents the window from being moved. (It snaps it back into place
according to its x, y, width, and height properties.) May be set to True
or False.
title Title for the window’s name bar. Takes any string.
scrolling Whether the named window should scroll as incoming data is
received. The following values are specified for this field:
True — the window scrolls, so that data is displayed as it is received.
After it is completely received, the end of the data remains displayed.
False — the window does not scroll the data. The first screenful of
data remains displayed until the user manually scrolls the window.
show If the value is True, the named window is displayed when PMCtool is
started up.
width The horizontal size of the window, in pixels. (One inch = 83 pixels,
SPARC)
x,y The horizontal (x) and vertical (y) coordinates for the upper left corner
of the named window, in pixels, with (0,0) indicating the upper left
corner of the user’s screen.
IMAGE Solutions V8.3 9-7
IMAGE Base Language: Production Menu Control: How to Use PMC
Table of Contents Index Home Master Index Search Help
Field
Window name Value
Tool name
PMCtool.control.x: 0
PMCtool.control.y: 430
PMCtool.control.width: 640
PMCtool.menu.x: 0
PMCtool.menu.y: 0
PMCtool.menu.width: 640
PMCtool.menu.height: 400
PMCtool.menu.show: True
PMCtool.jobio.x: 0
PMCtool.jobio.y: 470
PMCtool.jobio.width: 640
PMCtool.jobio.height: 400
PMCtool.jobio.scrolling: True
PMCtool.jobio.FollowMenu: True
PMCtool.datalog.x: 500
PMCtool.datalog.y: 470
PMCtool.datalog.width: 640
PMCtool.datalog.height: 400
PMCtool.datalog.scrolling: True
PMCtool.status.x: 650
PMCtool.status.y: 0
PMCtool.bin.x: 650
PMCtool.bin.y: 122
Figure 9-5. PMCtool Defaults File Structure
NOTE
Do not initiate automatic window scrolling if running Solaris 1. Initiation of the scrolling
command can cause a system malfunction.
IMAGE Solutions V8.3 9-8
IMAGE Base Language: Production Menu Control: Elements of a PMC Interface
Table of Contents Index Home Master Index Search Help
Elements of a PMC Interface
The elements of a PMC interface include screens, buttons, and command sequences (see
figure 9-6).
Menu
screens
Control
buttons
Figure 9-6. PMCtool Main Menu Showing Control Buttons and Menu Screens
Menu Screens
Operators use PMC screens to communicate with the test system. They can input
parameters, select actions, or receive information. Three screens are available for use with
the PMCtool (see figure 9-6). You can minimally customize two of these screens:
• Job I/O screen
• Datalog screen
To add either of these screens to a PMC interface see, “Job I/O and Datalog Screens” on
page 9-31.
A major portion of the third screen can be customized:
• Runtime/Binning screen
To add this screen to a PMC interface see, “Runtime/Binning Display Screen” on page 9-34.
Control Buttons
PMC screens feature control buttons used to execute certain predefined functions (see
figure 9-6). Each predefined control button is associated with an MDL standard variable
(see table 9-3).
IMAGE Solutions V8.3 9-9
IMAGE Base Language: Production Menu Control: Elements of a PMC Interface
Table of Contents Index Home Master Index Search Help
Buttons with functions not appropriate for certain screens are individually suppressed in
either of two ways:
• Use the keyword SUPPRESS in the MENU clause for that menu. (See “SUPPRESS” on
page 9-81.)
• Set the value of a button’s variable to zero. (To reactive the button set the variable to
one.)
Control buttons are activated by clicking with the mouse or pressing the associated function
key (F1 through F8) if you are in nomouse mode.
Table 9-3. Control Buttons for PMC Screens
Nomouse Standard
Button Action
Mode Variable
F1 MSG MDL_BTN_MSG Displays messages, if any are present.
F2 HELP MDL_BTN_HELP Provides help for the current menu.
F3 BACK MDL_BTN_BACK Ascends the menu hierarchy, changing to the
screen that was active previous to the current
screen.
If the current screen is at the top of the
hierarchy, this key will not be available. If the
current screen was entered as the initial
screen or by using the HOME control key, this
key will not be available.
F4 HOME MDL_BTN_HOME Changes to the screen defined as HOME in
the active MDF. If HOME screen is not
defined in the MDF, display changes to the
initial screen display.
F5 PG UP MDL_BTN_PREV Pages up when information does not fit on
one screen.
F6 PG DN MDL_BTN_NEXT Pages down when information does not fit on
one screen.
F7 RUN MDL_BTN_RUN Runs the test program.
F8 ABORT MDL_BTN_ABORT Aborts the command sequence if executed or
test program if running.
Command Sequence
Command sequences contain executable actions. A single command sequence (in Menu
Description Language, known as a COMMAND clause) is associated with a single menu item
and contains the actions executed when that item is selected by the user.
IMAGE Solutions V8.3 9-10
IMAGE Base Language: Production Menu Control: Elements of a PMC Interface
Table of Contents Index Home Master Index Search Help
A command sequence can contain IMAGE commands, UNIX commands, and MDL
keywords that perform actions or functions. For a description and examples of defining a
command sequence, see “Defining Menus and Menu Items” on page 9-25. For the syntax
and description of MDL keywords, see “MDL Keywords” on page 9-46.
When a command sequence is executed, the following events occur:
1. The screen is cleared and ABORT becomes the only available control button on the user’s
screen.
2. The command sequence begins execution. Anything typed after this point becomes
input to the currently executing command. Sometimes input is needed by the command
itself or by a script.
3. If any output is produced by the command sequence, the output is displayed on the
screen.
4. The command sequence can be terminated in any of the following ways:
a. You select the control button labeled ABORT or (F8) for nonmouse mode.
b. The ABORT command is encountered in the command sequence.
c. The end of the command sequence is reached.
5. Once the command sequence has terminated, if output has been generated, the user is
prompted to continue.
6. After the user responds to the prompt, the menu from which this item was selected
reappears, unless the sequence terminated because of a CHANGE_MENU or SUBMENU
command. In this case, the menu specified in the SUBMENU command is displayed.
NOTE
IMAGE and UNIX commands are generally all lowercase characters, while MDL keywords
are always all uppercase characters.
Variables
Variables are used in the MDF to pass or generate values used by the PMCtool. MDL uses
environmental variables in the form $<variablename> where a quoted string is required.
Wherever they are found, variables are replaced by their values before the string is used.
Variable names are all uppercase alphanumeric characters, including underscore
characters. The prefix MDL_ is reserved for Teradyne use in standard variables.
Two types of variables are used in an MDF:
• User variables, which are not predefined in the PMCtool
• Standard variables, which are predefined in the PMCtool
To set and declare variables, see “Setting Variables” on page 9-22.
IMAGE Solutions V8.3 9-11
IMAGE Base Language: Production Menu Control: Elements of a PMC Interface
Table of Contents Index Home Master Index Search Help
User Variables
User variables are defined in the MDF as needed, see “Setting Variables” on page 9-22.
They are also defined in collections and auxiliary files, see “Using Collection and Auxiliary
Files” on page 9-37.
Standard Variables
A standard variable is predefined in the PMCtool. It has the same meaning whenever it is
used and cannot be changed. You can write to some of the variables and set their values.
After setting their values, you can read those values. Other standard variables are read-only
variables that receive information from IMAGE. For a listing of the standard variables see
table 9-4.
Table 9-4. Standard PMC Variables
Read or
Standard Variable Possible Values Description of Variable
Write
MDL_EXEC_TYPE IMAGE read only Type of tester executive
system
MDL_JOBNAME Full test program read only Set to test program name
name, including loaded with PMC in the
path. (J9 style)1 form
/u/username/jobdir/
job
Only test program (J9 style)1
name, no path. (ICD
Name of file that loaded
style)1
the test program (ICD
style)1
MDL_JOBNUM Station #1-10 read only Set to the station number
attached to the PMC
MDL_JOBPATH Directory name read only
where test program
resides (J9 style)1
Directory and name
of file that loaded the
test program (ICD
style)1
MDL_JOBREV Set by startlot read only Test program description
command or title, as set by lot
control commands
IMAGE Solutions V8.3 9-12
IMAGE Base Language: Production Menu Control: Elements of a PMC Interface
Table of Contents Index Home Master Index Search Help
Table 9-4. Standard PMC Variables (Continued)
Read or
Standard Variable Possible Values Description of Variable
Write
MDL_JOBSTATE ABORTED read only Set to the current state of
CONTINUING the test program
IDLE
LOADED
NO JOB
RUNNING
TRAPPED
UNAVAILABLE
UNLOADED
MDL_LOT_ID Set by startlot and read only String identifying the lot
lot commands on the station
MDL_OPER_NAME Set by startlot read only Test system operator
command name
MDL_PERIPHERAL_ID Set by startlot read only Handler or prober
command identification
MDL_SUBLOT_ID Set by startlot and read only Number of the lot on the
lot commands station
MDL_SUPV_NAME Set by startlot read only Test floor supervisor
command name
MDL_TEST_CODE Set by startlot read only Three-character user-
command defined field specifying
phase of device testing or
test conditions (such as
WFR for wafer test)
MDL_TESTER_TYPE A5xx read only String identifying test
system type
MDL_WAFER_ID Set by startlot read only String identifying wafer
command on the station
MDL_USR_HOMESCR menu identifier write (and Set this variable to
read after contain the identifier of
written) the menu that appears
when the user presses
the HOME control button
(either in a mdl_startup
function or in a startup
clause in the MDF).
IMAGE Solutions V8.3 9-13
IMAGE Base Language: Production Menu Control: Elements of a PMC Interface
Table of Contents Index Home Master Index Search Help
Table 9-4. Standard PMC Variables (Continued)
Read or
Standard Variable Possible Values Description of Variable
Write
MDL_USR_INITSCR menu identifier write (and Set this variable to
read after contain the identifier of
written) the menu that appears
when PMC is started
(either in mdl_startup
function or in a startup
clause in the MDF).
1. See “Variable Styles” on page 9-14.
Variable Styles
Note that the IMAGE PMC variables, MDL_JOBNAME and MDL_JOBPATH, differ from the
variable names used by the Teradyne J9 series. The ICD/IMAGE job name variable is the
name of the file used to load the test program. The J9 equivalent is the fully rooted
pathname for the test program. The ICD/IMAGE job path variable is the fully rooted
pathname from which the test program was loaded. The J9 equivalent is the fully rooted
directory in which the test program resides. You can choose the ICD style or J9 style
settings by using the IMAGE properties tool (see Miscellaneous Options section on page
3-36) or by starting the PMCtool with the -j9_paths switch (see “Starting PMC” on page
9-4).
IMAGE Solutions V8.3 9-14
IMAGE Base Language: Production Menu Control: A Simple MDF
Table of Contents Index Home Master Index Search Help
A Simple MDF
This section describes the MDF that created the PMC interface in figure 9-7. This interface
does not call a collection database as in the default MDF. However, it does use all menu
screens available to the PMCtool.
Figure 9-7. Example PMC Interface Main Menu
MDF Syntax
The following MDF created the PMCtool menu interface in figure 9-7:
DECLARE_VARIABLE JOBNAME;
DECLARE_VARIABLE STATION;
DECLARE_VARIABLE SITES;
DECLARE_VARIABLE TMP;
STARTUP {
"MDL_USR_HOMESCR = control"
"MDL_USR_INITSCR = control"
"JOBNAME = /u/writers/Programs/adv_mixed/tester_util"
"SITES = """
}
RUNTIME {
BINNING_ITEM {
FONTSIZE 36
LABEL "Hardware Bin"
LAST_SORT
}
IMAGE Solutions V8.3 9-15
IMAGE Base Language: Production Menu Control: A Simple MDF
Table of Contents Index Home Master Index Search Help
BINNING_ITEM {
FONTSIZE 24
LABEL "Software Bin"
LAST_BIN
}
STATUS_ITEM {
ROW 1
COL 1
FONTSIZE 36
SIZE 12
VARIABLE $MDL_JOBNUM
LABEL "STATION:"
}
STATUS_ITEM {
ROW 2
COL 1
FONTSIZE 18
SIZE 25
VARIABLE $MDL_JOBNAME
LABEL "JOB NAME:"
}
STATUS_ITEM {
ROW 3
COL 1
FONTSIZE 18
SIZE 25
VARIABLE $MDL_JOBREV
LABEL "JOB REV:"
}
}
MENU control {
DISPLAY "STATION: $MDL_JOBNUM" {
COL 4
}
DISPLAY "JOB: $JOBNAME" {
COL 4
}
DISPLAY "STATE: $MDL_JOBSTATE" {
COL 4
}
MENU_ITEM "Select Job" {
COMMAND {
PRINT ""
PRINT "Hitting Return only causes the item to
remain as previously defined."
IMAGE Solutions V8.3 9-16
IMAGE Base Language: Production Menu Control: A Simple MDF
Table of Contents Index Home Master Index Search Help
PRINT_N "Enter Job Name:"
READ_RESPONSE $JOBNAME;
}
}
MENU_ITEM "Load Job" {
COMMAND {
PRINT "Loading $JOBNAME..."
"load $JOBNAME"
}
MENU_ITEM "Enable Datalog To PMC Datalog Screen" {
COMMAND "datalog -on -test all -pmc";
}
MENU_ITEM "Show Job I/O Screen" {
COMMAND SHOW_SERVICE "MDL_SVC_JOBIO";
}
MENU_ITEM "Show Datalog Output Screen" {
COMMAND SHOW_SERVICE "MDL_SVC_DATALOG";
}
MENU_ITEM "Show Runtime/Binning Display" {
COMMAND SHOW_SERVICE "MDL_SVC_RUNTIME";
}
MENU_ITEM "Unload Job" {
COMMAND "delete";
}
MENU_ITEM "Exit PMC" {
COMMAND EXIT;
}
}
IMAGE Solutions V8.3 9-17
IMAGE Base Language: Production Menu Control: MDF Structure
Table of Contents Index Home Master Index Search Help
MDF Structure
A menu description file (MDF) contains any or all of the following:
• MDL keywords (all uppercase)
• Operators (such as {)
• Strings (enclosed in double quotes)
• Variables (properly defined, uppercase, preceded by $)
• Comments (characters following # until the next newline)
• White space (spaces, tabs, and newlines)
The file is free-form. White space (spaces, tabs, and newlines) and comments are allowed
between keywords. Figure 9-8 shows an example of MDF structure using comments and
formatting.
Comments in an MDF
Liberal use of comments helps you (and others) understand your MDF. Any characters
between a pound sign (#) and a new-line character are treated as comments and are not
interpreted by the compiler.
IMAGE Solutions V8.3 9-18
IMAGE Base Language: Production Menu Control: MDF Structure
Table of Contents Index Home Master Index Search Help
1. Declare and DECLARE_VARIABLE VARNAME1 ; #declare variable
Set Variables DECLARE_VARIABLE VARNAME2 = "value1" ;#declare & set initial value
MENU menu1 { #define first menu
TITLE "title" ;
HELP "help text" ;
OPTIONS { QUIT_MENU_ON_SELECTION ; }
SUPPRESS key_name ;
DISPLAY "string" {
ROW N
COL N
}
MENU_ITEM "menu item one" { #define menu item
COMMAND {
<mdl or unix commands>
}
}
MENU_ITEM "menu item two" {
2. Define Menus COMMAND {
and Menu Items <mdl or unix commands>
}
}
}
MENU menu2 { #define second menu
MENU_ITEM "first item" {
COMMAND {
CHECK_VARIABLE $VARNAME1 == "value2" {
IF_FALSE {
ABORT
}
}
<mdl or unix commands>
}
}
MENU_ITEM "second item" {
COMMAND SUBMENU "menu1" ; #branch to another menu
}
}
FUNCTION mdl_startup{
<mdl or unix commands>
PRINT "WELCOME TO PMC"
3. Define Startup "MDL_USR_HOMESCR = menu2" #set home screen
Conditions "MDL_USR_INITSCR = menu2" #set initial screen
"VARNAME1 = value2" #set initial value for variable
}
Figure 9-8. MDF Format
IMAGE Solutions V8.3 9-19
IMAGE Base Language: Production Menu Control: MDF Structure
Table of Contents Index Home Master Index Search Help
Formatting the MDF
Most MDL (Menu Description Language) keywords take arguments in either of two formats:
• Single double-quoted string followed by a semicolon
• List of double-quoted strings enclosed in curly braces ( { } )
For example:
TITLE "This title has a single line." ;
TITLE {
"This title has two lines, and"
"this is the second line."
}
MDL keywords use curly braces to enclose multiple associated items. For instance, a MENU
clause uses curly braces to enclose all keywords, operators, and text describing a particular
menu. Within a MENU clause, a MENU_ITEM clause uses curly braces to enclose its keywords,
operators, and text associated with the menu item.
Indent one tab within each set of curly braces. This formatting technique helps you find
missing curly braces. For example:
MENU menu_name {
MENU_ITEM "echo response" {
COMMAND {
PRINT "Enter a line of text."
READ_RESPONSE $USER_RESPONSE ;
PRINT "You just typed $USER_RESPONSE."
}
}
}
Placement of Text on the Menu Screen
You control placement of text on the user’s screen. The MDL keywords TITLE, DISPLAY,
MENU_ITEM, PRINT, and PRINT_N all cause text to appear in a menu.
Horizontal placement To move text to the right on the user’s screen, use blank spaces
before the text. For example, the text in a TITLE phrase usually
appears in the extreme upper left hand corner of a menu screen.
By adding blank spaces, you can place the title closer to the
center of the screen where it is more visible, as in
TITLE " CONTROL MENU" ;
Vertical placement Within STARTUP and COMMAND clauses, text is moved downwards
by inserting a blank line before the text. Use the keyword PRINT
to insert a new-line character before your text. For example:
PRINT ""
PRINT "Now this line is one line lower on the screen."
IMAGE Solutions V8.3 9-20
IMAGE Base Language: Production Menu Control: MDF Structure
Table of Contents Index Home Master Index Search Help
Direct placement Within DISPLAY or MENU_ITEM clauses, use the MDL keywords
ROW and COL to position text in specific locations on the menu
screen. For example:
DISPLAY "Select one item from the group above." {
ROW 25
COL 15
}
See “MDL Keywords” on page 9-46 for more information on keywords.
IMAGE Solutions V8.3 9-21
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
Steps for Creating an MDF
To create an MDF:
1. Set and declare the variables.
2. Specify the startup conditions in a FUNCTION clause.
Startup conditions are placed anywhere in the MDF. Startup defines the values in effect
and the commands executed before the first menu is displayed.
3. Define the menus and menu items.
Within each menu, each menu item is defined, along with the actions you want to occur
when the menu item is selected.
4. Add advanced commands to the COMMAND clause.
5. Add menu screens.
For an example of these parts and their placement in an MDF see figure 9-8 on page 9-19.
Setting Variables
All variables (including write-only standard variables) can be set in any of the following
ways:
• In a DECLARE_VARIABLE statement (sets initial value; do not use for write-only standard
variables since they do not need to be declared)
• In the mdl_startup function (sets initial value; use for any variable that can be set)
• In a COMMAND clause of a menu item (use for any variable that can be set)
– Sets value to a predetermined value named in the COMMAND clause
– Sets value to a user-response read in the COMMAND clause
Setting Initial Value With DECLARE_VARIABLE Statement
All variables (except standard) are declared at the beginning of the MDF with
DECLARE_VARIABLE statements. For example:
DECLARE_VARIABLE <variablename> [= "<initial_value>"];
where:
<variablename> Is the name of the variable used later in the MDF. For example:
DECLARE_VARIABLE STATION ;
DECLARE_VARIABLE SITES ;
DECLARE_VARIABLE JOBNAME = "/u/jones/job" ;
<initial_value> Is the assignment of an initial value in a DECLARE_VARIABLE
statement is optional. The value of the variable defaults to the
empty string if no initial value is specified.
IMAGE Solutions V8.3 9-22
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
Setting Initial Variable Values Using mdl_startup
Initial values of variables can also be set in a mdl_startup function. (See “Specifying
Startup Conditions” on page 9-24.)
Setting Variable Values Within a COMMAND or FUNCTION Clause
Another use for variables is to store global information and to record temporary values.
COMMAND clauses are included in menu item clauses. They contain commands that execute
when the user selects the menu item. There are three ways to set variables within COMMAND
clauses.
In the following example, the variable FOO is used to store a string used in subsequent PRINT
commands:
MENU_ITEM "set variable" {
COMMAND {
PRINT "Setting variable FOO to 'abc'"
"FOO=abc"
PRINT "The value of 'Foo' is $FOO"
PRINT "Setting variable FOO to 'def'"
"FOO=def"
PRINT "The value of 'Foo' is $FOO"
}
}
Another way to set a variable is to store a user response. MDL provides a special keyword
for this purpose, READ_RESPONSE, which reads a single line of text from the user and stores
it in a variable. READ_RESPONSE appears inside COMMAND clauses.
READ_RESPONSE $<variablename> ;
For example:
MENU_ITEM "echo response" {
COMMAND {
PRINT "Enter a line of text."
READ_RESPONSE $USER_RESPONSE ;
PRINT "You just typed $USER_RESPONSE"
}
}
When executed, this command prompts the user for a line of input, stores the text in the
variable USER_RESPONSE, and then echoes the text to the screen.
Lastly, you can set variables to explicit values or to other variables as in this FUNCTION:
FUNCTION backup_stage {
"$THIS_ITEM = """
"THIS_ITEM = product_variation"
CALL_FUNCTION "backup"
}
IMAGE Solutions V8.3 9-23
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
Specifying Startup Conditions
To specify initial conditions when the PMCtool starts, write a function called mdl_startup.1
The mdl_startup function is defined in a FUNCTION clause:
FUNCTION mdl_startup {
<commands>
}
This FUNCTION allows you to execute a set of commands before the menu interface begins.
If mdl_startup is defined, it is called before the initial menu is displayed.
Use mdl_startup to:
• List messages you want the user to see before the first menu is displayed
• Specify commands to execute before the first menu is displayed
• Set initial values for variables
• Establish the initial screen a user sees when starting the PMCtool. To do this, set the
variable MDL_USR_INITSCR. If you do not specify an initial screen, the PMCtool uses the
last menu defined in your MDF as the initial screen. The example below defines signin
as the initial menu.
• Specify the home menu by setting the variable MDL_USR_HOMESCR. This menu is brought
up when a user selects the HOME control button. In the example below, the home menu
is control.
NOTE
MDL_USR_INITSCR and MDL_USR_HOMESCR are predefined (standard) variables and do not
need to be declared in your MDF.
In the following example, the mdl_startup FUNCTION:
• Prints a welcome message and the current date
• Sets the variable MYNAME
• Names menus used as the initial screen and home screen
DECLARE_VARIABLE MYNAME ;
.
.
.
MENU ....
.
.
.
1. In previous versions of PMC, a STARTUP clause performed this function. STARTUP will continue to be
supported for backwards compatibility.
IMAGE Solutions V8.3 9-24
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
FUNCTION mdl_startup {
PRINT "Welcome to PMC"
PRINT "The current date is "
"date"
"MYNAME=Terwillicker"
"MDL_USR_HOMESCR = control"
"MDL_USR_INITSCR = signin"
}
Defining Menus and Menu Items
The body of the MDF defines the menu(s) used by the operator.
MENU
A menu is defined by a MENU clause, which contains one or more MENU_ITEM clauses. For
example:
MENU <identifier> {
<optional keywords>
<menu items>
}
Give each menu a unique identifier immediately following the MENU keyword. Use
alphanumeric and underscore characters (lowercase letters for identifiers is a convention).
Inside the curly braces of the MENU clause are a series of options for that menu and one or
more MENU_ITEM clauses. The MENU_ITEM clauses describe the items (selections) in the
menu.
The MENU clause can contain the following keywords:
TITLE
HELP
OPTIONS
DISPLAY
SUPPRESS
MENU_ITEM
For a complete listing of keywords, see “MDL Keywords” on page 9-46.
TITLE
The TITLE keyword specifies the title to display with a particular menu.
TITLE <string_specifier>
The title is the text printed in a menu above the list of menu selections. The argument,
<string_specifier> is either a single double-quoted string followed by a semicolon or a
list of double-quoted strings enclosed in curly braces ({}).
TITLE "this is one line" ;
IMAGE Solutions V8.3 9-25
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
TITLE {
"This is the first line"
"this is the second line"
}
HELP
The HELP keyword specifies strings to print if the user selects the HELP control button.
HELP <string_specifier>
The argument <string_specifier> is either a single double-quoted string followed by a
semicolon or a list of double-quoted strings enclosed in curly braces ({}).
MENU empty_menu {
TITLE "Title goes here" ;
HELP {
"This menu contains commands that"
"allow you to ..."
}
<menu items>
}
OPTIONS
The OPTIONS keyword is used to specify a temporary menu (also called a quit-on-selection
menu). These menus disappear after the user makes a selection from them, returning the
user to the previously displayed menu. Use them if you want the user to select a single
menu item from a list of menu items.
OPTIONS { QUIT_MENU_ON_SELECTION ; }
You might have a menu containing setup parameters
SETUP:
(1) Stage
(2) Product
(3) Station(s)
Selection:
If the user selects Stage, a temporary menu appears
STAGE:
(1) Probe
(2) Final
(3) Manual Test
Selection:
IMAGE Solutions V8.3 9-26
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
When a user selects an item from the STAGE menu, the menu disappears and the screen
displays the previously displayed SETUP menu. None of the items in the STAGE menu can
bring up a submenu.
MENU_ITEM
For each selection in a menu, a MENU_ITEM clause is defined. This clause is made up of the
keyword MENU_ITEM, followed by the item’s text, and then a COMMAND clause.
Optional keywords are defined within a menu item. (See “Advanced Commands” on page
9-29.) For example:
MENU menu1 {
MENU_ITEM "Print my name." {
COMMAND {
PRINT ""
PRINT "Your name is $MYNAME."
}
}
MENU_ITEM "Bring up the Control Menu." {
COMMAND SUBMENU "control" ;
}
}
The text that follows MENU_ITEM is the text that appears for an item when the menu is
displayed.
COMMAND
The COMMAND clause lists the commands executed when a menu item is chosen by the user.
Elements that appear in a COMMAND clause are IMAGE commands, UNIX commands, or one
of the MDL keywords that represent predefined commands. For example:
MENU simple_menu {
TITLE "Simple Menu" ;
MENU_ITEM "print date" {
COMMAND {
PRINT "The date today is"
"date"
}
}
}
The first command in the clause above, is the MDL keyword, PRINT, which prints a string
on the screen. The second command is the UNIX command, date, which prints the current
date to the screen.
The above example displays the following menu:
Simple Menu
(1) print date
IMAGE Solutions V8.3 9-27
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
Selection:
If the user selects item 1, PRINT and date execute resulting in the following:
The date today is
Thu Jul 16 10:40:41 EDT 2000
SUBMENU
The SUBMENU keyword links a menu item to another menu.
When a user selects a menu item containing the command SUBMENU, the current menu
disappears and the named submenu is displayed.
The SUBMENU is displayed until the user quits, unless it is designated as a temporary menu.
(See “OPTIONS” on page 9-26.) You cannot place another command after the SUBMENU
command.
Define the menu name of the SUBMENU in the MDF.
SUBMENU <menu name> ;
The following example shows two MENU clauses. The first clause describes a MENU called
date_menu, which is called as a submenu by the second MENU clause.
MENU date_menu {
TITLE "Date Menu" ;
MENU_ITEM "print date" {
COMMAND {
PRINT "The date is as follows:"
"date"
}
}
}
MENU simple_menu {
TITLE "Simple Menu" ;
MENU_ITEM "Bring up date menu" {
COMMAND SUBMENU date_menu ;
}
}
The above example produces the following menu on the user’s screen:
Simple Menu
(1) Bring up date menu
Selection:
If the user selects item 1, the following menu appears:
Date Menu
(1) print date
IMAGE Solutions V8.3 9-28
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
Selection:
If the user selects item 1, PRINT and date execute, printing the following to the screen:
The date is as follows:
Thu Jul 16 10:40:41 EDT 2000
Advanced Commands
When the user chooses a particular menu item, sometimes checks and tests must run
before execution of a command. At other times, checks make sure a previous command
had the desired effect. For example, if a menu contains an item that turns on datalog for a
test program, the PMCtool checks before performing this operation to see if a test program
is loaded.
Use the following commands in the COMMAND clause for a menu item: CHECK_STATUS,
CHECK_VARIABLE, and ABORT. Use CHECK_STATUS and CHECK_VARIABLE to implement
checks.
CHECK_STATUS
Within a COMMAND clause, the CHECK_STATUS keyword provides a way to take action based
on whether a previous command passed or failed. CHECK_STATUS uses the exit status, a
number passed back to the calling program to indicate whether the called program was
successful.
CHECK_STATUS <testcommand> {
IF_PASS <passcommands>
IF_FAIL <failcommands>
}
The command specified, <testcommand>, is executed and the exit status of this command
is examined. If the exit status indicates a successful execution (by UNIX convention, an exit
status of 0 is considered successful), the command in the IF_PASS clause is executed.
If <testcommand> fails for some reason (signaled by a nonzero exit status), the command
specified in the IF_FAIL clause is executed. For example:
CHECK_STATUS "date -illegal_flag" {
IF_FAIL {
PRINT "the command 'date -illegal_flag'"
PRINT "failed"
}
IF_PASS {
PRINT "the command 'date -illegal_flag'"
PRINT "completed successfully"
}
}
In this example, the command date -illegal_flag is executed, the exit status of the
command is checked, and the commands in one of the two following clauses are executed.
IMAGE Solutions V8.3 9-29
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
(In this case, since -illegal_flag is an invalid option to the UNIX date command, the exit
status is always nonzero, and the commands in the IF_FAIL clause are executed.)
CHECK_VARIABLE
A CHECK_VARIABLE clause takes conditional action based on the value of a variable. The
syntax is:
CHECK_VARIABLE $<variable_name> <op> "<stringvalue>" {
IF_TRUE <truecommands>
IF_FALSE <falsecommands>
}
where:
<variable_name> The name of a variable to evaluate.
<op> One of the logical operators, == or !=.
<stringvalue> A string used for the comparison.
The variable is compared to the string. If the comparison yields true, <truecommands>
executes. Otherwise, <falsecommands> executes. For example:
CHECK_VARIABLE $MYVAR == "1" {
IF_TRUE {
PRINT "Variable MYVAR is set to 1"
}
IF_FALSE {
PRINT "Variable MYVAR is not set to 1"
ABORT
}
}
This example tests the variable MYVAR to see if it is set to 1. Then it executes one of the two
clauses depending on the outcome.
ABORT
To halt the execution of a command, use the ABORT keyword.
If the ABORT keyword is used in a command sequence, it terminates the commands for that
menu item. Therefore, use it as the last item in any command sequence.
COMMAND {
CHECK_STATUS "load myprogram" {
IF_FAIL {
#
# We were not able to load program
# 'myprogram', so do not
# proceed any further.
#
ABORT
}
IMAGE Solutions V8.3 9-30
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
}
PRINT "Load completed."
}
In the COMMAND clause above, if the load command in the CHECK_STATUS clause fails, ABORT
halts the program and Load completed is not printed.
Job I/O and Datalog Screens
Your MDF can contain menu items that bring up predefined screens.
The Job I/O screen allows you to monitor messages from the test program or input data
directly to the test program (see figure 9-10).
The Datalog screen displays datalog test results if datalogging to PMC is enabled before
the test program run (see figure 9-12 on page 9-34).
Table 9-5 summarizes information about the Job I/O and Datalog screens.
NOTE
Do not use the Job I/O window while using the PMC to multiplex across stations. This can
confuse the operator if input is required.
Table 9-5. Job I/O and Datalog Screens
Screen Standard Variable Screen Description
Job I/O MDL_SVC_JOBIO Handles all input to and output from the test
program. Any input entered from this screen, other
than activation of control buttons, is passed to the
standard input of the test program.
Do not use this window when using PMC for
multiplexing. See note.
Active control buttons on this screen are BACK,
HOME, ABORT, and RUN.
Datalog MDL_SVC_DATALOG Displays output from data collection, if output to
Output PMCtool is enabled.
Active control buttons on this screen are BACK,
HOME, ABORT, and RUN.
Adding a Job I/O Screen to Your Menu
To add a Job I/O screen to your PMCtool
1. Create a menu item in the MDF.
IMAGE Solutions V8.3 9-31
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
MENU_ITEM "Show Job I/O Screen" {
COMMAND SHOW_SERVICE "MDL_SVC_JOBIO";
}
2. Run the test program using the RUN control key.
3. Select the SHOW JOB I/O SCREEN (see figure 9-9). The Job I/O Service Window displays
the test program results (see figure 9-10).
Figure 9-9. Selecting the Job I/O Screen
Figure 9-10. Job I/O Service Window
IMAGE Solutions V8.3 9-32
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
Adding a Datalog Screen to Your Menu
To add a Datalog screen to your PMCtool, use the following steps:
1. Create a menu item in the MDF to enable datalog output to the PMCtool.
MENU_ITEM "Enable Datalog To PMC Datalog Screen"{
COMMAND "datalog -on -test all -pmc";
}
2. Create a menu item in the MDF to allow the user to switch to the Datalog screen.
MENU_ITEM "Show Datalog Output Screen"{
COMMAND SHOW_SERVICE "MDL_SVC_DATALOG";
}
3. Select ENABLE DATALOG TO PMC DATALOG SCREEN from the menu (see figure 9-11).
4. Run the test program using the RUN control key.
5. Select SHOW DATALOG OUTPUT SCREEN from the menu (see figure 9-11).
In IMAGE, the datalog command collects and displays certain test results. See “Datalog
Setup Using the datalog Command” on page 6-31.
Figure 9-11. Selecting the Enable Datalog To PMC Datalog Screen and Show Datalog Output Screen
The Datalog Service Window displays the data collection results (see figure 9-12).
IMAGE Solutions V8.3 9-33
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
Figure 9-12. Datalog Service Window
Runtime/Binning Display Screen
The Runtime/Binning display window allows the user to view the results of a test program
in a graphical representation. Table 9-6 summarizes information regarding the Runtime/
Binning display screen.
Table 9-6. Runtime/Binning Display Screens
Screen Standard Variable Screen Description
Runtime/Binning MDL_SVC_RUNTIME Displays the binning item, site number, and status
Display information for a test program.
Site Numbers in the binning display window have the
following color coding:
Green—Last device passed
Yellow— No device tested on this site during last run
Red—Last device failed
Pink—Site currently running
Active control buttons on this screen are BACK,
HOME, ABORT, and RUN.
To create a Runtime/Binning Display:
1. Define the status items and binning items in the MDF using the RUNTIME keyword, as in:
IMAGE Solutions V8.3 9-34
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
RUNTIME {
BINNING_ITEM {
FONTSIZE 36
LABEL "Hardware Bin"
LAST_SORT
}
BINNING_ITEM {
FONTSIZE 24
LABEL "Software Bin"
LAST_BIN
}
STATUS_ITEM {
ROW 1
COL 1
FONTSIZE 36
SIZE 12
VARIABLE $MDL_JOBNUM
LABEL "STATION:"
}
STATUS_ITEM {
ROW 2
COL 1
FONTSIZE 18
SIZE 25
VARIABLE $MDL_JOBNAME
LABEL "JOB NAME:"
}
STATUS_ITEM {
ROW 3
COL 1
FONTSIZE 18
SIZE 25
VARIABLE $MDL_JOBREV
LABEL "JOB REV:"
}
2. Create a menu item in the MDF. For example:
MENU_ITEM "Show Runtime/Binning Display" {
COMMAND SHOW_SERVICE "MDL_SVC_RUNTIME";
}
3. Run the test program using the RUN control key.
4. Select SHOW RUNTIME/BINNING DISPLAY screen from the menu (see figure 9-13).
IMAGE Solutions V8.3 9-35
IMAGE Base Language: Production Menu Control: Steps for Creating an MDF
Table of Contents Index Home Master Index Search Help
Figure 9-13. Selecting the Show Runtime/Binning Display
The Bin and Status windows display the test program results and status (see figure 9-14).
Site number
Figure 9-14. Bin and Status Windows
IMAGE Solutions V8.3 9-36
IMAGE Base Language: Production Menu Control: Using Collection and Auxiliary Files
Table of Contents Index Home Master Index Search Help
Using Collection and Auxiliary Files
The previous section described creating a simple PMC user interface in which commands,
functions, and variables were defined in a single file, the Menu Description File (MDF). This
method works well when you have a single test program with a single product.
When you have a family of related products to test or a single product to test in several
phases of development, you need separate testing scenarios, or test programs, for each
product or phase. It is time-consuming and cumbersome to write a separate PMC interface
for each of the related products or phases of development.
This section describes using collections and auxiliary files. First, you can create collections
to contain program-specific or product-specific data using a common MDF for several
programs or products.
You can put functions or variables used with several test programs into a single auxiliary file
and put test-program-specific information in a separate MDF.
Additionally, you can create menus “on the fly” using collections developed with information
obtained from the current test program.
Examples of collection and auxiliary MDL files are provided in the directory $IMAGEBIN/
custom.
Collection Files
A PMC collection file is a set of records each containing a list of field-value pairs of data (see
figure 9-15). All the records contain the same fields, but they can contain different values
associated with the fields. An example of a collection file is:
$IMAGEBIN/custom/product_db
IMAGE Solutions V8.3 9-37
IMAGE Base Language: Production Menu Control: Using Collection and Auxiliary Files
Table of Contents Index Home Master Index Search Help
PMC
Database Files
Job-Specific
Product Data
product: cgb458
product_variation: cgb458_1
stage: probe
periph: kla1007r
Record setup: xyz_grade
test_program: $IMAGEBIN/custom/mdl_sample_job
periph_script: "$IMAGEBIN/custom/start_remote.script"
setup_script: cgb458_probe.script
kill_periph: "$IMAGEBIN/custom/kill_remote.script"
Separated by blank line aux_mdl: cgb458_probe.mdl
product: cgb458
product_variation: cgb458_1
stage: final
periph: AET3000handler
Record setup: xyz_grade
test_program: $IMAGEBIN/custom/mdl_sample_job
periph_script: "$IMAGEBIN/custom/start_remote_script"
setup_script: cgb458_package.script
kill_periph: "$IMAGEBIN/custom/kill_remote.script"
aux_mdl: cgb458_package.mdl
Field Value
Separated by colon (:)
Figure 9-15. Format for Inputting Information Into a PMC Collection
The main purpose of a collection file is to generate menus. An operator makes a selection
which triggers the generation of a menu. You can use collection files in several ways:
• Create collection files from text files
• Create collection files from directory contents
• Create collection files from existing collections
• Rename collection files
• Delete collection files
• Count the number of records in a collection file or unique values in a field
• Select values for a given field for all records in a collection file
• Create menu items based on all unique field values
IMAGE Solutions V8.3 9-38
IMAGE Base Language: Production Menu Control: Using Collection and Auxiliary Files
Table of Contents Index Home Master Index Search Help
Creating Collection Files From Text Files
To create a collection file, enter the data you want in the above format (see figure 9-15).
Enter the following keywords in a COMMAND or FUNCTION clause:
CREATE_COLLECTION "products" {
FILENAME "$MDL_DIR/product_db"
}
Creating Collection Files From Directory Contents
You can also create collection files using file names with a given extension within a
particular directory. To create a collection file, use the following syntax in a COMMAND or
FUNCTION clause:
CREATE_COLLECTION "workspaces" {
DIRECTORY "$JOB_DIR"
EXTENSION ".tl"
}
The above example creates a collection file containing all the files with the extension .tl in
the user’s test program directory.
Creating Collection Files From Existing Collections
The two ways to create a collection file from existing collections are:
• Merge two collection files
• Select a subset of a collection file
To merge two or more existing collection files, use the following syntax in a COMMAND or
FUNCTION clause:
MERGE_COLLECTIONS "new_collection_name" {
COLLECTIONS {
"first_collection"
"second_collection"
}
}
To select a subset of an existing collection file, use the following syntax in a COMMAND or
FUNCTION clause:
SELECT_SUBSET "station_collection" {
FIELD "station"
VALUE "$station"
RESULT_COLLECTION "new collection"
}
Renaming Collection Files
You can rename an existing collection file by merging an old collection into a new collection
and deleting the old collection:
IMAGE Solutions V8.3 9-39
IMAGE Base Language: Production Menu Control: Using Collection and Auxiliary Files
Table of Contents Index Home Master Index Search Help
MERGE_COLLECTIONS "new_collection_name" {
COLLECTIONS {
"old_collection_name"
}
}
DELETE_COLLECTION "old_collection_name"
Deleting Collection Files
To delete a collection file, enter the following in a COMMAND or FUNCTION clause:
DELETE_COLLECTION "station_collection"
Counting Records or Values in a Collection File
To count the total number of records in a collection file, enter the following in a COMMAND or
FUNCTION clause. The result is placed in the variable named with the keyword
RESULT_VARIABLE.
TOTAL_RECORDS "station_collection" {
RESULT_VARIABLE "TOTAL_RECORDS"
}
To count the total number of unique values in a field within a collection file, enter the
following in a COMMAND or FUNCTION clause:
TOTAL_UNIQUE_VALUES "station_collection" {
FIELD "station"
RESULT_VARIABLE "TOTAL_STATIONS"
}
Selecting Field Values in a Collection File
To select the value(s) for a given field for all the records in a collection file, enter the
following in a COMMAND or FUNCTION clause:
SELECT_FIELD "station_collection" {
FIELD "station"
RESULT_VARIABLE "STATION_VALUES"
}
The result is placed in the variable named with the keyword RESULT_VARIABLE. If there is
more than one value for the named field in the collection file, all unique values are listed
separated by spaces.
Creating Menu Items Based on Unique Field Values
To create menu items based on the unique values of a given field, enter the following in a
MENU clause:
IMAGE Solutions V8.3 9-40
IMAGE Base Language: Production Menu Control: Using Collection and Auxiliary Files
Table of Contents Index Home Master Index Search Help
COLLECTION_MENU "station_collection" {
FIELD "station"
RESULT_VARIABLE "STATION_VALUE"
COMMAND {
PRINT "Station Selected is $STATION_VALUE"
}
}
In this example, when one of these menu items is selected, the value of station for that menu
item is stored in the variable STATION_VALUE and the command clause is executed.
Auxiliary Files
Auxiliary files are appended to an MDF. The auxiliary file gives additional instruction to the
MDF. Auxiliary files are written in Menu Description Language (MDL) and contain variable
declarations, function definitions, and menu definitions.
An example of an auxiliary file that specifies a runtime/binning display is in:
$IMAGEBIN/custom/cgb458_package.mdl
Creating an Auxiliary File
Use a text editor to create an auxiliary MDL file. The file can contain any keywords and
syntax used in an MDF. (See “Steps for Creating an MDF” on page 9-22 and “MDL
Keywords” on page 9-46.) The following is an example of the syntax in a auxiliary file:
DECLARE_VARIABLE DLOG_DISABLE = "Disable Data Collection";
DECLARE_VARIABLE DLOG_ENABLE = "Enable Data Collection";
DECLARE_VARIABLE DATALOG_ITEM = "Enable Data Collection";
#include "display_items.h"
.
.
.
MENU datacollection {
TITLE "Data Collection Menu";
COMMON_DISPLAY_ITEMS
MENU_ITEM "$DATALOG_ITEM" {
ROW 9
COMMAND {
CHECK_VARIABLE $ENDISABLEDLOG == "Enable" {
IF_TRUE {
PRINT "Enabling Datalog"
"ENDISABLEDLOG = Disable"
"DATALOG_ITEM = $DLOG_DISABLE"
"datalog -on -test all -pmc"
IMAGE Solutions V8.3 9-41
IMAGE Base Language: Production Menu Control: Using Collection and Auxiliary Files
Table of Contents Index Home Master Index Search Help
IF_FALSE {
PRINT "This selection will TURN OFF data collection."
PRINT_N "Are you sure you want to continue(Y/N):"
READ_RESPONSE $RESPONSE;
CHECK_VARIABLE $RESPONSE != "Y" {
IF_TRUE {
CHECK_VARIABLE $RESPONSE != "y" {
IF_TRUE {
PRINT "Data collection has NOT been turned off."
ABORT
}
}
}
}
Appending the Auxiliary File to Your MDF
You can append an auxiliary file to your MDF by using the LOAD_MDL_FILE command in a
FUNCTION or COMMAND clause. This example shows the syntax needed in the MDF.
FUNCTION LoadJobMDL {
CHECK_VARIABLE $JOB_AUX_MDL == " " {
IF_FALSE {
LOAD_MDL_FILE "$(MDL_DIR)/$JOB_AUX_MDL"
CALL_FUNCTION "job_aux_func"
}
IF_TRUE {
SUBMENU "confirmer_menu"
}
}
}
In this example a function in the MDF contains the LOAD_MDL_FILE keyword. The auxiliary
file name is represented by one variable for the pathname and a second variable for the file
name.
This FUNCTION is called from a COMMAND clause or from another FUNCTION.
IMAGE Solutions V8.3 9-42
IMAGE Base Language: Production Menu Control: PMC Library
Table of Contents Index Home Master Index Search Help
PMC Library
PMCtalk is a static .a library written in C, with EXTERN_FUNCTION declarations provided for
use with C++. This section describes programs and functions used in an MDF.
The following activities are provided by this library. The functions are encapsulated in
transients to make these activities available to shell scripts.
• Updating MDL variables
• Displaying an error or informational message to the user
• Loading and executing MDFs
All functions are prefaced by pmct_. A return value of one indicates success, and a return
value of zero indicates failure. Any memory allocated by these functions is deleted on the
next call to the function.
PMCtalk’s file name is $IMAGEBIN/libpmctalk.a.
Program Definitions
Program definitions communicate with the PMC process from which they were started. If
they were not started from a PMC process, you must specify the station number attached
to a particular PMC process, or -all_pmcs to specify all PMC processes.
The following command outputs the value of the named MDL variable:
pmc_get_var [-variable <string>] [-station <#> | -all_pmcs]
The following command sets the named variable to the specified value:
pmc_set_var [-variable <string>] [-value <string>]
[-station <#> | -all_pmcs]
PMC Functions
The following sections describe functions that communicate with the PMC.
pmct_init
The pmct_init function initializes communication to a specified PMC or PMCs. All other
functions talk to the PMC or PMCs specified in this function call. The syntax is:
pmct_init <int station>
where:
<int station> Is one of the following:
PMCT_NOSTATION_ATTACHED Talks to PMCs not
attached to a station.
PMCT_ALL_PMCS Talks to all PMCs attached to a station.
IMAGE Solutions V8.3 9-43
IMAGE Base Language: Production Menu Control: PMC Library
Table of Contents Index Home Master Index Search Help
PMCT_THIS_PMC Talks to the PMC that started the
process.
pmct_load_mdl_file
The pmct_load_mdl_file function tells PMC to pull in an auxiliary file. The syntax is:
pmct_load_mdl_file (char *filename)
where:
*filename Is a pointer to the filename string of the file to load. Returns one
for success and zero for failure.
pmct_call_function
The pmct_call_function function tells PMC to call the specified function clause. User
action is required (press ACTION button). This function does not return until the
ANSWER_REMOTE_CALL clause is reached in the MDL flow. The syntax is:
pmct_call_function (char *func_name)
where:
*func_name Is a pointer to the function string of the function to load. Returns
one for success and zero for failure.
pmct_auto_call_function
The pmct_auto_call_function function tells PMC to call the specified function clause
without any user action required. This function does not return until the
ANSWER_REMOTE_CALL clause is reached in the MDL flow. The syntax is:
pmct_auto_call_function (char *func_name)
where:
*func_name Is a pointer to the function string of the function to load. Returns
one for success and zero for failure.
pmct_update_mdl_varlist
The pmct_update_mdl_varlist function updates the named MDL variables for all PMCs
specified in pmct_init. The syntax is:
pmct_update_mdl_varlist (Pmct_mdl_var list *var_list)
where:
*var_list[] Is a structure containing the variables to update and their new
values. Returns one for success and zero for failure. The
structure definition is:
IMAGE Solutions V8.3 9-44
IMAGE Base Language: Production Menu Control: PMC Library
Table of Contents Index Home Master Index Search Help
typedef struct {
u_int Pmct_mdl_varlist_len; //the number of variables
Pmct_mdl_var *Pmct_mdl_varlist_val //an array of variables
} Pmct_mdl_varlist; //and their values
struct Pmct_mdl_var {
char *keyword;
char *value;
};
pmct_get_mdl_varlist
The pmct_get_mdl_varlist function retrieves the values for a list of MDL variables. The
syntax is:
pmct_get_mdl_varlist (Pmct_vars *var_list)
where:
var_list Is a structure containing the list of MDL variable names. The
structure definition is listed below. Returns a structure containing
the variables and their values or null if the call fails. (See
pmct_update_mdl_varlist above for the structure definition.)
typedef char *Pmct_string;
typedef struct {
u_int Pmct_vars_len; // the number of variables
Pmct_string *Pmct_vars_val; // an array of variable
// names
} Pmct_vars;
pmct_display_message
The pmct_display_message function sends a message to the PMCs specified by
pmct_init(). The priority of the message tells PMC how to display it. The highest priority
messages display immediately. The syntax is:
pmct_display_message (int priority, char *msg)
where:
priority Is the priority of the error message.
*msg Is the message to display. Returns one for success and zero for
failure.
enum Pmct_msg_pri {
PMCT_PRI_EMG = 0,
PMCT_PRI_ERROR = 1,
PMCT_PRI_INFO = 2
};
IMAGE Solutions V8.3 9-45
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
MDL Keywords
This section lists all MDL keywords that appear in a menu description file (MDF) with their
syntax and a brief description of their actions. A listing shows how each keyword is used in
an MDF; see “Listing of MDL Keywords” on page 9-46.
MDF Conventions
Follow these guidelines when developing Menu Description Files:
• Use menu names that are all lower case.
• Use variable names that are all upper case.
• Indent one tab setting within clauses with curly braces ({}).
• Avoid using the Job I/O window if you are using the PMC to multiplex across stations.
• Use this order within an MDF:
a. Declare variables (DECLARE_VARIABLE statements).
b. Define runtime (binning) displays, if any (RUNTIME clauses).
c. Define menus (MENU clauses).
d. Define the top-level, or initial, menu last.
e. Define functions, if any (FUNCTION clauses).
f. Specify initial conditions by defining a function named mdl_startup. If
mdl_startup exists, it is called to set up initial conditions.
Listing of MDL Keywords
Table 9-7 shows how all MDL keywords are used in relation to each other within a menu
description file. For the exact syntax of a keyword, see its alphabetical reference in the
following pages. Note that all keywords listed under COMMAND are legal under FUNCTION.
Table 9-7. MDL Keywords
MDL Keyword Page
DECLARE_VARIABLE <variable> = "<initial_value>" page 9-58
STARTUP <cmds> page 9-79
FUNCTION <func_name> <cmds> page 9-62
RUNTIME page 9-75
BINNING_ITEM page 9-52
BAD_UNITS page 9-52
GOOD_UNITS page 9-62
IMAGE Solutions V8.3 9-46
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
Table 9-7. MDL Keywords (Continued)
MDL Keyword Page
FONTSIZE <num> page 9-61
LABEL "<string>" page 9-65
LAST_BIN page 9-66
LAST_SORT page 9-66
PERCENT_BAD page 9-71
PERCENT_GOOD page 9-71
UNITS_TESTED page 9-84
STATUS_ITEM page 9-79
COL <num> page 9-56
ROW <num> page 9-75
FONTSIZE <num> page 9-61
SIZE <num> page 9-79
LABEL "<string>" page 9-65
VARIABLE $<variable> page 9-85
MENU <menu_name> page 9-67
COLLECTION_MENU "<collection>" page 9-57
FIELD "<field>" page 9-61
RESULT_VARIABLE "<result>" page 9-75
COMMAND <cmd> page 9-57
DISPLAY "<string_and/or_$variable>" page 9-60
COL <num> page 9-56
ROW <num> page 9-75
SIZE <num> page 9-79
HELP "<string>" page 9-62
NUM_COLS <num> page 9-70
OPTIONS {QUIT_MENU_ON_SELECTION} page 9-70
SUPPRESS <button_name> page 9-81
IMAGE Solutions V8.3 9-47
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
Table 9-7. MDL Keywords (Continued)
MDL Keyword Page
TITLE page 9-82
MENU_ITEM page 9-68
ACTIVE "<variable>" page 9-50
COL <num> page 9-56
ROW <num> page 9-75
SIZE <num> page 9-79
COMMAND page 9-57
ABORT page 9-50
ANSWER_REMOTE_CALL page 9-51
ATTACH "$<variable>" page 9-51
BACK page 9-51
CALL_FUNCTION "<function>" page 9-52
CALL_HELP page 9-53
CHANGE_MENU "<menu>" page 9-53
CHECK_STATUS "<command>" page 9-54
IF_FAIL <cmds> page 9-63
IF_PASS <cmds> page 9-64
CHECK_VARIABLE $<variable> <op> page 9-55
"<comparestring>"
IF_FALSE <cmds> page 9-64
IF_TRUE <cmds> page 9-65
CLEAR page 9-56
CREATE_COLLECTION "<new_collection>" page 9-58
DIRECTORY "<pathname>" page 9-58
EXTENSION "<extn>" page 9-61
FILENAME "<filename>" page 9-61
DELETE_COLLECTION "<collection>" page 9-59
DETACH "$<variable>" page 9-59
IMAGE Solutions V8.3 9-48
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
Table 9-7. MDL Keywords (Continued)
MDL Keyword Page
EXIT page 9-60
HOME page 9-63
LOAD_MDL_FILE "<filename>" page 9-66
MERGE_COLLECTIONS "<new_collection>" page 9-69
COLLECTIONS page 9-56
"<collection_1>"
"<collection_2>"
PGDN page 9-71
PGUP page 9-71
PRINT page 9-72
PRINT_N page 9-72
READ_PASSWORD $<variable> page 9-73
READ_RESPONSE $<variable> page 9-74
SCRIPT "<shell_program>" {<shell code>} page 9-76
SELECT_FIELD "<collection>" page 9-77
FIELD "<field>" page 9-61
RESULT_VARIABLE "<variable>" page 9-75
SELECT_SUBSET "<old_collection>" page 9-78
FIELD "<field>" page 9-61
VALUE "$<variable>" page 9-85
RESULT_COLLECTION "<new_collection>" page 9-74
SHOW_SERVICE "<service_window>" page 9-78
SUBMENU "<menu>" page 9-80
TOTAL_RECORDS "<collection>" page 9-83
RESULT_VARIABLE "<variable>" page 9-75
TOTAL_UNIQUE_VALUES "<collection>" page 9-83
FIELD "<field>" page 9-61
RESULT_VARIABLE "variable>" page 9-75
IMAGE Solutions V8.3 9-49
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
Table 9-7. MDL Keywords (Continued)
MDL Keyword Page
UNLOAD_MDL_FILE "<filename>" page 9-84
UNSHOW_SERVICE "<service_window>" page 9-84
ABORT
Used in COMMAND clauses to terminate processing.
ABORT
Example:
COMMAND {
CHECK_STATUS "<command1>" {
IF_FAIL {
"<command2>"
ABORT
}
}
"<command3>"
}
In this example, <command1> is always executed. If <command1> passes, the sequence
continues on to execute <command3>. If <command1> fails, the IF_FAIL clause is processed,
causing <command2> and then ABORT to be executed. Any subsequent commands are not
executed.
ABORT is a predefined command used in the IF_FAIL, IF_PASS, IF_TRUE, or IF_FALSE
clauses of a CHECK_STATUS or CHECK_VARIABLE clause. See “Advanced Commands” on
page 9-29.
ACTIVE
Used in COMMAND clauses. In the example below, ACTIVE is used in a MENU_ITEM clause to
set the active state of the MENU_ITEM. If the quoted string evaluates to zero the item is not
active, otherwise the item is active.
ACTIVE <variable>
where:
<variable> A string that evaluates to zero or one.
Example:
MENU_ITEM "Display Help screen for this menu."{
ACTIVE "$ACTIVE_STATE"
COMMAND {
<commands>
IMAGE Solutions V8.3 9-50
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
}
}
If a menu item is active, the user can select it. If a menu item is not active, it is grayed out
and cannot be selected.
ANSWER_REMOTE_CALL
Used in COMMAND clauses. If the current command sequence is initiated from a
pmct_call_function, this command answers the calling process back. If no call is waiting,
this clause does nothing.
ANSWER_REMOTE_CALL
Example:
COMMAND <command_name> {
"<command1>"
"<command2>"
ANSWER_REMOTE_CALL
"<command3>"
}
ATTACH
Used in COMMAND clauses to attach a PMC interface to a station.
ATTACH $<variable>
where:
<variable> Contains the station number to connect to the PMC.
Example:
COMMAND {
ATTACH "$NUM"
}
BACK
Used in COMMAND clauses to change the current screen to the previous one.
BACK
Example:
MENU_ITEM "Return to previous menu."{
COMMAND BACK ;
}
This keyword is not used in a menu that appears as the initial screen or in a menu that is
accessed by using the HOME control key.
IMAGE Solutions V8.3 9-51
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
BAD_UNITS
Used in BINNING_ITEM clauses to name the type of binning used for this item.
BAD_UNITS
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Bad Units"
BAD_UNITS
}
BINNING_ITEM
Defines a binning item for the runtime display.
BINNING_ITEM {
<options>
}
where:
<options> Can contain one or all of the following elements:
FONTSIZE Is the point size of the binning item characters in the runtime
display. Default is 12 points.
LABEL<type_of_binning>
Is an optional label to display with the binning item. Enclose in
double quotes. <type_of_binning> can be one of the following
keywords:
UNITS_TESTED
LAST_SORT
LAST_BIN
PERCENT_GOOD
PERCENT_BAD
GOOD_UNITS
BAD_UNITS
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Bad Units"
BAD_UNITS
}
CALL_FUNCTION
Used in COMMAND clauses to call a named function.
CALL_FUNCTION "<function_name>"
IMAGE Solutions V8.3 9-52
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
where:
<function_name> Is the name of a function surrounded by double quotes.
Example:
COMMAND {
CALL_FUNCTION "get_lot_id"
}
FUNCTION get_lot_id {
PRINT_N "Enter the lot id"
READ_RESPONSE $LOT_ID
}
CALLHELP
Used in COMMAND clauses to call up the help screen for the current menu.
CALLHELP
Example:
MENU_ITEM "Display Help screen for this menu." {
COMMAND CALLHELP ;
}
CHANGE_MENU
Used in COMMAND clauses to start a new menu hierarchy.
CHANGE_MENU "<menu_name>"
where:
<menu_name> The name of a menu surrounded by double quotes.
Example:
MENU date_menu {
TITLE "Date" ;
MENU_ITEM "print date" {
COMMAND {
PRINT "The date is as follows:"
"date"
}
}
}
MENU simple_menu {
TITLE "Simple" ;
MENU_ITEM "Bring up date menu" {
COMMAND {
PRINT_N "Are you sure? y or n: "
READ_RESPONSE $TMP ;
CHECK_VARIABLE $TMP == "y" {
IMAGE Solutions V8.3 9-53
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
IF FALSE {
ABORT
}
}
CHANGE_MENU "date_menu"
}
}
}
The menu named in CHANGE_MENU appears in quotation marks. Menus are defined in any
order. This command is preceded by CHECK_VARIABLE so that the menu a user changes to
is based on the value of a variable or on the return status of a command.
CHECK_STATUS
Used in COMMAND clauses to determine whether a command passes or fails and take action
based on the result.
CHECK_STATUS "<command>" {
[IF_FAIL <cmds>]
[IF_PASS <cmds>]
}
where:
<command> Is a command enclosed in double quotes.
<cmds> Is either a single command followed by a semicolon or a list of
commands enclosed in curly braces.
Example:
COMMAND {
PRINT_N "Enter the letter \"u\": "
READ_RESPONSE $FLAG ;
CHECK_STATUS "date -$FLAG" {
IF_PASS {
PRINT "This is Greenwich Mean Time."
}
IF_FAIL {
PRINT "This command failed."
}
}
}
Example:
COMMAND {
PRINT_N "Enter the letter \"u\": "
READ_RESPONSE $FLAG ;
CHECK_STATUS "date -$FLAG" {
IF_FAIL {
PRINT "This command failed."
ABORT
IMAGE Solutions V8.3 9-54
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
}
PRINT "This is Greenwich Mean Time."
}
}
When CHECK_STATUS is executed, the first <command> is executed and the exit status is
checked. If the exit status is zero, commands in the IF_PASS clause are executed (if
present). If the exit status is nonzero, commands in the IF_FAIL clause are executed (if
present).
Specify at least one of the IF_FAIL or IF_PASS clauses. It is not required that you specify
both. (See “Advanced Commands” on page 9-29.)
CHECK_VARIABLE
Used in COMMAND clauses to perform logical tests on a variable.
CHECK_VARIABLE $<variable> <op> "<comparestring>" {
[IF_TRUE <cmds>]
[IF_FALSE <cmds>]
}
where:
<variable> Is the variable to examine.
<op> Is the logical operation != or ==.
<comparestring> Is the string to compare the value against. Enclose the string in
double quotes.
<cmds> Is either a single command followed by a semicolon or a list of
commands enclosed in curly braces.
Example:
MENU_ITEM "Remove all files in current directory" {
COMMAND {
PRINT_N "Enter password to continue: "
READ_PASSWORD $PASSWD ;
CHECK_VARIABLE $PASSWD == "apple" {
IF_FALSE {
PRINT ""
PRINT "Incorrect password."
PRINT "No action taken."
PRINT ""
ABORT
}
}
PRINT "Removing all files . . . "
"rm *"
}
}
IMAGE Solutions V8.3 9-55
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
If the comparison is successful, the commands in the IF_TRUE clause are executed. If the
comparison fails, the commands in the IF_FALSE clause are executed.
Specify at least one of the IF_FAIL or IF_PASS clauses. Both are not required. The example
shows a case in which only an IF_FALSE clause is specified. See “Advanced Commands”
on page 9-29.
CLEAR
Used in COMMAND clauses to clear the window (screen).
CLEAR
This is a predefined command. After the window is cleared with this command, all
subsequent messages printed to the window (screen) start at the top of the output area.
COL
Used in MENU_ITEM, STATUS_ITEM, or DISPLAY clauses to indicate the starting column for
the menu item or display text. Often used together with ROW.
COL <column>
where:
<column> Is a column number on the screen.
Example:
MENU_ITEM "Go to the Stage Menu." {
ROW 5
COL 5
SUBMENU "stage" ;
}
COLLECTIONS
Used in MERGE_COLLECTION clauses to specify the collections to merge.
COLLECTIONS {
"collection_1"
"collection_2"
}
Example:
MERGE_COLLECTIONS "new_collection" {
COLLECTIONS {
"collection_1"
"collection_2"
}
}
IMAGE Solutions V8.3 9-56
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
COLLECTION_MENU
Used in MENU clauses to create menu items based on the contents of the named collection.
COLLECTION_MENU "<collection>" {
<item_options>
}
where:
<collection> Names the collection from which this item is drawn. Enclose the
collection name in double quotes.
<item_options> Selects the data to create the item and indicates the action to
occur when this item is selected.
Example:
COLLECTION_MENU "collection_1" {
FIELD "field"
RESULT_VARIABLE "RESULT"
COMMAND {
PRINT "Item selected = $RESULT"
}
}
COMMAND
Used in MENU_ITEM or COLLECTION_MENU clauses to specify the commands executed if the
user selects the menu item.
COMMAND <cmds>
where:
<cmds> Is either a single command followed by a semicolon or a list of
commands enclosed in curly braces.
Example:
MENU date {
MENU_ITEM "Print the date." {
COMMAND "date" ;
}
MENU_ITEM "Print date and current directory." {
COMMAND {
PRINT_N "The date is: "
"date"
PRINT ""
PRINT_N "The current directory is: "
"pwd"
}
}
}
IMAGE Solutions V8.3 9-57
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
A COMMAND is either a quoted string containing an IMAGE command (for example,
"datalog"), a UNIX command (for example, "date"), or one of a set of predefined
commands made available by MDL. (See “Defining Menus and Menu Items” on page 9-25.)
CREATE_COLLECTION
Used in COMMAND clauses to create a new collection file based on the contents of a file or
directory.
CREATE_COLLECTION "<collection>" {
<specifications>
}
where:
<collection> The name of the new collection file enclosed in double quotes.
<specifications> Either the file name used or the directory and file extension used.
Example:
CREATE_COLLECTION "products" {
FILENAME "$MDL_DIR/product_db"
}
CREATE_COLLECTION "workspaces" {
DIRECTORY "$JOB_DIR"
EXTENSION ".tl"
}
The following keywords can appear in a CREATE_COLLECTION clause:
FILENAME A file formatted for use in a collection, see “Collection Files” on
page 9-37. The name must be enclosed in double quotes.
DIRECTORY A list of files in a directory used as a collection. Use this keyword
to specify the directory’s path name. Enclose the path name in
double quotes. This creates a collection that uses the field name
BASENAME, like this:
basename:file_1
basename:file_2
basename:file_3
EXTENSION The collection is the list of files in a directory that has this
extension. The extension is enclosed in double quotes.
DECLARE_VARIABLE
Used at the beginning of an MDF to declare variables used in your MDF.
DECLARE_VARIABLE <variablename> [ = <initial_value> ]
where:
<variablename> Is the name of the variable used.
IMAGE Solutions V8.3 9-58
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
<initial value> Is the starting value for the variable (optional), enclosed in
double quotes.
Example:
DECLARE_VARIABLE OPERATOR_NAME = "no operator" ;
DECLARE_VARIABLE LINEPRODUCT = "Product: " ;
DECLARE_VARIABLE PRODUCT ;
DECLARE_VARIABLE LINESTATE = "Tester Status: " ;
DECLARE_VARIABLE STATE = "No Job" ;
DECLARE_VARIABLE STAGE ;
<startup conditions>
<menus>
You can also specify variables in the STARTUP clause. Specifying initial values for variables
is optional. (See “Setting Variables” on page 9-22.)
DELETE_COLLECTION
Used in COMMAND clauses to delete a collection.
Format:
DELETE_COLLECTION "<collection>"
where:
<collection> Is the name of the collection deleted enclosed in double quotes.
Example:
DELETE_COLLECTION "products"
DETACH
Used in COMMAND clauses to detach the PMC from a station.
DETACH "$<variable>"
where:
<variable> Contains the station number currently attached to the PMC.
Enclose in double quotes.
Example:
COMMAND {
DETACH "$NUM"
}
IMAGE Solutions V8.3 9-59
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
DISPLAY
Used in MENU clauses to display text or variables (or both) in specified locations on the menu
screen. Defines content and location of display-only areas on a menu screen.
MENU menu_name {
DISPLAY "<string and/or $VARIABLE>"{
ROW N
COL N
}
<menu items>
}
Example:
MENU menu1 {
TITLE "Menu 1" ;
DISPLAY "$LINEPRODUCT" ;
<menu items>
}
MENU menu2 {
TITLE "Menu 2" ;
DISPLAY "Select an item from this group." {
ROW 20
COL 5
}
<menu items>
}
You can use ROW and COL to specify the starting point for the display. If you do not specify
a row, the display is placed on the next available line. If the location of a menu item conflicts
with the location of a display item, the last item listed is displayed.
The value of a displayed variable can be changed from outside the program, thereby
changing the contents of the display area.
The SIZE keyword is used to truncate DISPLAY text or variable contents as specified.
EXIT
Used in COMMAND clauses to exit the PMC interface.
EXIT
Example:
COMMAND {
EXIT
}
This is a predefined command which causes the PMCtool to exit.
IMAGE Solutions V8.3 9-60
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
EXTENSION
Indicates the file extension of files selected for a collection file with CREATE_COLLECTION.
EXTENSION "<extension>"
Example:
CREATE_COLLECTION "workspaces" {
DIRECTORY "$JOB_DIR"
EXTENSION ".tl"
}
FIELD
Names the field used to select a subset of records from an existing collection file to create
a new collection file.
FIELD "<fieldname>"
Example:
SELECT_SUBSET "old_collection" {
FIELD "field"
VALUE "$RESULT"
RESULT_COLLECTION "new_collection"
}
FILENAME
Names a file whose contents are used for a new collection created with
CREATE_COLLECTION.
FILENAME "<filename>"
Example:
CREATE_COLLECTION "products" {
FILENAME "$MDL_DIR/product_db"
}
FONTSIZE
Used in BINNING_ITEM and STATUS_ITEM clauses to specify the point size of the characters
for the binning display or status item.
FONTSIZE <number>
where:
<number> The point size used for characters in the binning display.
Example:
IMAGE Solutions V8.3 9-61
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
BINNING_ITEM {
FONTSIZE 15
LABEL "Bad Units"
BAD_UNITS
}
The default is 12 if FONTSIZE is not specified.
FUNCTION
Specifies the commands executed when CALL_FUNCTION is executed.
FUNCTION <function> <cmds>
where:
<function> A string naming the FUNCTION.
<cmds> A list of COMMANDs enclosed in curly braces.
Example:
COMMAND {
CALL_FUNCTION "get_lot_id"
}
FUNCTION get_lot_id {
PRINT_N "Enter the lot id"
READ_RESPONSE $LOT_ID
}
Keywords used in COMMAND clauses can also be used in FUNCTION clauses.
GOOD_UNITS
Names the type of binning used for this item.
GOOD_UNITS
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Good Units"
GOOD_UNITS
}
HELP
Used in MENU clauses, appearing before menu items, or MENU_ITEM clauses, before the
commands for that item. Specifies help string(s) provided to the user for a given menu.
HELP "<strings>"
where:
IMAGE Solutions V8.3 9-62
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
<strings> Either a single string followed by a semicolon or a list of strings
enclosed in curly braces. Enclose each line containing a string in
double quotes.
Example:
MENU empty_menu {
TITLE "Title of Menu" ;
HELP {
"This menu contains commands which"
"allow you to do something"
}
MENU_ITEM {
HELP {
"This is help for the menu item"
<cmds>
}
}
}
When the user activates the HELP function button with a menu displayed on the screen, the
messages printed in response are the strings specified in the HELP clause for that menu.
The user can then select help for an item.
HOME
Used to change the screen to the HOME screen.
HOME
Example:
MENU_ITEM "Change to the Home menu." {
COMMAND HOME ;
}
If the HOME screen is not defined in the MDF, the screen changes to the initial screen when
this item is chosen.
IF_FAIL
Names the command(s) to execute if the command specified in CHECK_STATUS exits with a
nonzero status.
IF_FAIL <cmds>
where:
<cmds> Is either a single command followed by a semicolon or a list of
commands enclosed in curly braces.
Example:
IMAGE Solutions V8.3 9-63
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
COMMAND {
PRINT_N "Enter the letter \"u\": "
READ_RESPONSE $FLAG ;
CHECK_STATUS "date -$FLAG" {
IF_PASS {
PRINT "This is Greenwich Mean Time."
}
IF_FAIL {
PRINT "This command failed."
}
}
}
See “CHECK_STATUS” on page 9-54 and “IF_PASS” on page 9-64.
IF_FALSE
Names the command(s) executed if the comparison specified in CHECK_VARIABLE fails.
IF_FALSE <cmds>
where:
<cmds> Is either a single command followed by a semicolon or a list of
commands enclosed in curly braces.
Example:
MENU_ITEM "Remove all files in current directory" {
COMMAND {
PRINT_N "Enter password to continue: "
READ_PASSWORD $PASSWD ;
CHECK_VARIABLE $PASSWD == "apple" {
IF_FALSE {
PRINT ""
PRINT "Incorrect password."
PRINT "No action taken."
PRINT ""
ABORT
}
}
PRINT "Removing all files . . . "
"rm *"
}
}
See “CHECK_VARIABLE” on page 9-55 and “IF_TRUE” on page 9-65.
IF_PASS
Names command(s) executed if the command specified in CHECK_STATUS exits with a zero
status.
IMAGE Solutions V8.3 9-64
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
IF_PASS <cmds>
where:
<cmds> Is either a single command followed by a semicolon or a list of
commands enclosed in curly braces.
Example:
COMMAND {
PRINT_N "Enter the letter \"u\": "
READ_RESPONSE $FLAG ;
CHECK_STATUS "date -$FLAG" {
IF_PASS {
PRINT "This is Greenwich Mean Time."
}
IF_FAIL {
PRINT "This command failed."
}
}
}
See “CHECK_STATUS” on page 9-54 and “IF_FAIL” on page 9-63.
IF_TRUE
Names command(s) to execute if the comparison specified in CHECK_VARIABLE is true.
IF_TRUE <cmds>
where:
<cmds> Is either a single command followed by a semicolon or a list of
commands enclosed in curly braces.
Example:
CHECK_VARIABLE $STAGE == " " {
IF_TRUE {
PRINT "no stage"
ABORT
}
}
See “CHECK_VARIABLE” on page 9-55 and “IF_FALSE” on page 9-64.
LABEL
Provides a string displayed for a binning item in the runtime window.
LABEL "<string>"
where:
<string> Is the label you want displayed, enclosed in double quotes.
IMAGE Solutions V8.3 9-65
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Bad Units"
BAD_UNITS
}
See “BINNING_ITEM” on page 9-52.
LAST_BIN
Names the type of binning used for this item.
LAST_BIN
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Software Bin"
LAST_BIN
}
See “BINNING_ITEM” on page 9-52.
LAST_SORT
Names the type of binning used for this item.
LAST_SORT
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Hardware Bin"
LAST_SORT
}
See “BINNING_ITEM” on page 9-52.
LOAD_MDL_FILE
Used in COMMAND clauses to load an auxiliary file.
LOAD_MDL_FILE "<filename>"
where:
<filename> Is the name of the file surrounded by double quotes.
Example:
COMMAND {
LOAD_MDL_FILE "/u/test/jobs/$PRODUCT/$PRODUCT.mdl"
IMAGE Solutions V8.3 9-66
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
SUBMENU "SPECIAL_MENU"
}
The contents of the named file are added to the list of menus and functions available to the
SUBMENU and CALL_FUNCTION clauses.
If the file contains a runtime display, its runtime display overrides the previous runtime
display.
This action is also available using the PMC talk library. See “PMC Library” on page 9-43.
MENU
Defines a menu. A MENU clause can contain the following elements: TITLE, HELP, and
OPTIONS. They must precede definitions of menu items.
MENU <identifier> {
<options>
<menu items>
}
where:
<identifier> Is a unique alphanumeric identifier assigned to the menu being
defined.
<options> Can contain the following clauses: HELP, TITLE, OPTIONS,
DISPLAY, SUPPRESS.
<menu items> Contains one or more clauses: MENU_ITEM, COLLECTION_MENU,
or DISPLAY.
Example:
MENU load {
TITLE " JOB ACTIONS" ;
HELP {
"Select one of the actions listed on this menu by"
"entering its number followed by <RETURN>."
}
MENU_ITEM "Select Test Program" {
ROW 7
COMMAND {
PRINT_N "Enter Program name: "
READ_RESPONSE $TMP ;
CHECK_VARIABLE $TMP== "" {
IF FALSE {
"JOBNAME = $TMP"
}
}
}
}
MENU_ITEM "Load Test Program" {
ROW 9
IMAGE Solutions V8.3 9-67
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
COMMAND {
CHECK_VARIABLE $JOBNAME== "" {
IF_TRUE {
PRINT "You must enter a program name."
}
PRINT "Loading Program ..."
"load $JOBNAME"
}
}
}
<identifier> Is the menu identifier (required), a unique name composed of
lowercase alphanumeric characters. It can include the
underscore character.
TITLE clause Is optional. The title text starts in row zero, column zero of the
screen. To move the title toward the center, add blank spaces
after the opening quotation mark, as shown in the example. See
“TITLE” on page 9-82.
HELP clause Is optional. Enter one or more lines of text, each line surrounded
by quotation marks. This text appears if the user activates the
HELP control button while this menu is being displayed. See
“HELP” on page 9-62.
OPTIONS clause Is optional. This clause can contain QUIT_MENU_ON_SELECTION.
Use it if this menu is one that will revert to the previous menu
after the user makes a selection. See “OPTIONS” on page 9-70.
DISPLAY clause Is optional. Enter one or more lines of text and/or variables you
want displayed when this menu is on the screen. See “DISPLAY”
on page 9-60.
SUPPRESS clause Is optional. Enter the names of function buttons you do not want
to appear while this menu is on the screen. See “SUPPRESS”
on page 9-81.
COLLECTION_MENU Is optional. Creates menu items based on the contents of the
named collection.
<menu items> Define the selections in the menu. Each menu item is made up
of the keyword MENU_ITEM, followed by the menu item name in
quotes (which is displayed on the menu as the menu selection),
and then a series of optional keywords and/or clauses
surrounded by curly brackets (which represent the actions to
occur if the item is selected). See “MENU_ITEM” on page 9-68.
MENU_ITEM
Defines a new menu item for the menu enclosing it.
MENU_ITEM "<item_name>" {
<options>
IMAGE Solutions V8.3 9-68
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
COMMAND {
<cmds>
}
}
where:
<item_name> Is a quoted string displayed as the item selection. Enclose in
double quotes.
<options> Include COL, ROW, SIZE, and HELP.
<cmds> Consists of one or more commands that appear in a COMMAND
clause. See “COMMAND” on page 9-57.
Example:
MENU_ITEM "Lot ID"
COMMAND {
PRINT_N "Enter Lot ID: "
READ_RESPONSE $LOTID ;
}
}
A MENU_ITEM clause can contain the following:
"<item_name>" Required. This quoted string appears on the menu screen as the
menu item.
COL Optional. Specifies column number in which the item starts.
ROW Optional. Specifies row number in which the item starts.
SIZE Optional. Specifies the maximum number of characters that a
menu item name can have. Subsequent characters are not
displayed.
HELP Optional. Specifies strings to be displayed when user requests
help.
COMMAND clause Contains the commands and/or checks executed if this item is
selected.
MERGE_COLLECTIONS
Used to combine all named collection files into one collection file.
MERGE_COLLECTIONS "<new_collection>" {
COLLECTIONS {
"<collection_a>"
"<collection_b>"
}
}
where:
IMAGE Solutions V8.3 9-69
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
"<new_collection>" Is the name used for the resulting merged collection file,
enclosed in double quotes.
"<collection_X>" Names the collection files merged.
Example:
MERGE_COLLECTIONS "all_products" {
COLLECTIONS {
"abc"
"xyz"
}
}
Collections are renamed by specifying the old collection file name after COLLECTIONS.
Example:
MERGE_COLLECTIONS "new_name" {
COLLECTIONS {
"old_name"
}
}
NUM_COLS
Used in MENU clauses. Cannot be used with ROW or COL. Specifies the maximum number of
columns to display menu items or display items in the PMC window. Default value is one.
NUM_COLS <number>
Example:
MENU menu1 {
TITLE "DATE MENU" ;
NUM_COLS 2
<menu items>
}
OPTIONS
Specifies optional information about a menu definition. OPTIONS appears in a MENU clause,
before the definition of a menu item.
OPTIONS { <option keywords> }
Example:
MENU menu1 {
TITLE "DATE MENU" ;
OPTIONS { QUIT_MENU_ON_SELECTION ; }
<menu items>
}
IMAGE Solutions V8.3 9-70
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
The keyword for OPTIONS is QUIT_MENU_ON_SELECTION. See
“QUIT_MENU_ON_SELECTION” on page 9-73.
PERCENT_BAD
Names the type of binning used for this item.
PERCENT_BAD
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Percent Bad"
PERCENT_BAD
}
See “BINNING_ITEM” on page 9-52.
PERCENT_GOOD
Names the type of binning used for this item.
PERCENT_GOOD
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Percent Good"
PERCENT_GOOD
}
See “BINNING_ITEM” on page 9-52.
PGDN
Used in COMMAND clauses to page down when information does not fit on one screen.
PGDN
Example:
MENU_ITEM "Go to next page of data." {
COMMAND PGDN ;
}
PGUP
Used in COMMAND clauses to page up when information does not fit on one screen.
PGUP
Example:
IMAGE Solutions V8.3 9-71
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
MENU_ITEM "Go to previous page of data." {
COMMAND PGUP ;
}
PRINT
Outputs the specified string to the user.
PRINT "<string>"
where:
"<string>" Is an ASCII string, which can include variables, surrounded by
double quotes.
Example:
MENU_ITEM "Sign In" {
COMMAND {
PRINT_N "Sign in to continue: "
READ_RESPONSE $SIGNIN ;
PRINT "Welcome to the system, $SIGNIN."
}
}
PRINT is used in COMMAND clauses within menu items, to display text and/or variable
contents. The displayed string is treated as an entire line of output.
To display text or variable contents associated with a menu rather than with a menu item,
use DISPLAY.
PRINT_N
PRINT_N is used in COMMAND clauses within menu items to display text and/or variable
contents. Outputs the specified string to the user with no new-line character.
PRINT_N "<string>"
where:
<string> Is an ASCII string surrounded by double quotes, which can
include variables.
Example:
MENU_ITEM "Sign In" {
COMMAND {
PRINT_N "Sign in to continue: "
READ_RESPONSE $SIGNIN ;
PRINT "Welcome to the system, $SIGNIN."
}
}
The string displayed does not have a new-line character at its end. Subsequent output or
input will appear on the same line.
IMAGE Solutions V8.3 9-72
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
To display text or variable contents associated with a menu rather than with menu items,
use DISPLAY.
QUIT_MENU_ON_SELECTION
Appears in the OPTIONS clause of a menu definition. Defines the current menu as
temporary, control switches back to the previous menu immediately after a selection is
made from the current menu.
OPTIONS { QUIT_MENU_ON_SELECTION ; }
Example:
MENU menu1 {
TITLE "DATE MENU" ;
OPTIONS { QUIT_MENU_ON_SELECTION ; }
<menu items>
}
When this keyword is present, the menu defined is considered a temporary, or transient,
menu. Although selections and format appear similar to other menus, the screen display
reverts to the previous menu immediately after a user makes a selection from a temporary
menu. With normal menus, the menu display remains until the user explicitly chooses to exit
the menu.
The top level (initial) menu cannot be specified as a temporary menu. Temporary menus
cannot have menu items that invoke submenus.
READ_PASSWORD
Used in a COMMAND clause to read input from the user without echoing it on the screen. The
user’s entry is placed into a variable for later use.
READ_PASSWORD $<variable>
where:
<variable> Is a variable that receives the text of the user’s input.
Example:
MENU_ITEM "Remove all files in current directory" {
COMMAND {
PRINT_N "Enter password to continue: "
READ_PASSWORD $PASSWD ;
CHECK_VARIABLE $PASSWD == "apple" {
IF_FALSE {
PRINT ""
PRINT "Incorrect password."
PRINT "No action taken."
PRINT ""
ABORT
}
}
IMAGE Solutions V8.3 9-73
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
PRINT "Removing all files . . . "
"rm *"
}
}
In the example above, READ_PASSWORD is used in combination with the CHECK_VARIABLE
statement to make sure the user gives the correct password before a sensitive command is
executed.
This keyword is typically used to restrict access to a particular menu item to those who know
a certain password.
READ_RESPONSE
Used in a COMMAND clause to read input from the user into a variable that can be used later.
READ_RESPONSE $<variable>
where:
<variable> Is the variable where the line of input is stored.
Example:
COMMAND {
PRINT "Enter a line of input:"
READ_RESPONSE $TMP_RESPONSE ;
PRINT "The line was: $TMP_RESPONSE"
}
RESULT_COLLECTION
Used in SELECT_SUBSET items, which are found in COMMAND clauses. Names a new
collection resulting from the selection of a subset of records from an existing collection
based on the matching of a value in a field.
RESULT_COLLECTION "<string>"
where:
<string> Is the name for the new collection file, surrounded by double
quotes.
Example:
SELECT_SUBSET "old_collection" {
FIELD "field"
VALUE "$RESULT"
RESULT_COLLECTION "new_collection"
}
IMAGE Solutions V8.3 9-74
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
RESULT_VARIABLE
Names a variable holding the result of a PMC action in one of the following clauses:
COLLECTION_MENU, TOTAL_UNIQUE_VALUES, SELECT_FIELD, or TOTAL_RECORDS.
RESULT_VARIABLE "<variable>"
where:
<variable> Names the variable in which to put the result of the previous
action.
Example:
CHECK_VARIABLE $TOTAL == "1" {
IF_TRUE {
SELECT_FIELD "y_col" {
FIELD "Y"
RESULT_VARIABLE "Y_VAR"
}
PRINT "X = $X_VAR, Y = $Y_VAR"
}
IF_FALSE {
SUBMENU "y_menu"
}
}
ROW
Used in a MENU_ITEM, STATUS_ITEM, or DISPLAY clauses to place the menu item, status
item, or display text in a specific row on the screen. Often used with COL to specify an exact
location on the screen.
ROW <row>
where:
<row> Is a row number on the screen.
Example:
DISPLAY "Select a menu item by entering its number." {
ROW 20
<commands>
}
MENU_ITEM "Stage: $STAGE" {
ROW 5
COL 5
<commands>
}
RUNTIME
Defines status items and binning items for the runtime display.
IMAGE Solutions V8.3 9-75
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
RUNTIME {
BINNING_ITEM {
<bin_setup>
}
STATUS_ITEM {
<status_setup>
}
}
where:
<bin_setup> Includes the binning setup keywords FONTSIZE, LABEL, and their
values, as well as the type of binning: BAD_UNITS, GOOD_UNITS,
LAST_BIN, LAST_SORT, PERCENT_BAD, PERCENT_GOOD, and
UNITS_TESTED.
<status_setup> Includes the status setup keywords ROW, COL, FONTSIZE, SIZE,
VARIABLE, and LABEL.
Example:
RUNTIME {
BINNING ITEM {
FONTSIZE 12
LABEL "Hardware Bin"
LAST_SORT
}
STATUS_ITEM {
ROW 1
COL 1
FONTSIZE 12
SIZE 25kill
VARIABLE $product
LABEL "Part Type"
}
}
Only one runtime display is allowed. If an auxiliary file is loaded and contains a runtime
display, that runtime display overrides the previous runtime display. (The last runtime
display loaded is always the one displayed.)
SCRIPT
Used in COMMAND clauses to execute a block of shell script code.
SCRIPT "<shell_program>" {
<shell_code>
}
where:
<shell_program> Is the shell program, such as /bin/sh or /bin/csh, surrounded
by double quotes.
IMAGE Solutions V8.3 9-76
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
<shell_code> Is the number of lines of shell script code.
Example:
COMMAND {
SCRIPT "/bin/csh" {
lot_id_tmp = 'pmc_get_var -variable LOT_ID'
while [ "$lot_id_tmp" = "" ]; do
echo "Enter lot id"
read lot_id_tmp
echo $lot_id_tmp
done
pmc_set_var -variable LOT_ID -value $lot_id_tmp
}
PRINT "Lot id: $LOT_ID"
}
This command creates a script and executes it. It provides the power of a regular shell
language from within PMC. The shell scripts are created on the fly, so all the code needed
is located in one file.
The code between the braces is not interpreted. Therefore, any variables referred to in the
shell script code are real environment variables rather than MDL variables. Accessing MDL
variables must be done through the pmc_get_var and pmc_set_var transients. Note that
pmc_get_var and pmc_set_var communicate from the script to the PMC to get and set
MDL variables through the PMCtalk library.
SELECT_FIELD
Used in COMMAND clauses to stuff RESULT_VARIABLE with the values of FIELD found in the
named collection.
SELECT_FIELD "<collection_name>" {
FIELD "<field_name>"
RESULT_VARIABLE "<variable>"
}
where:
<collection> Is the collection from which you want to select values. The
collection name is surrounded by double quotes.
<field> Names the field from which unique values are selected. The field
name is surrounded by double quotes.
<variable> Names the variable into which the values are placed. The
variable name is surrounded by double quotes.
Example:
CHECK_VARIABLE $TOTAL == "1" {
IF_TRUE {
SELECT_FIELD "y_col" {
FIELD "Y"
IMAGE Solutions V8.3 9-77
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
RESULT_VARIABLE "Y_VAR"
}
PRINT "X = $X_VAR, Y = $Y_VAR"
}
IF_FALSE {
SUBMENU y_menu
}
}
If there are multiple values for the field, each unique value will appear once in
RESULT_VARIABLE, separated from other values with a space.
SELECT_SUBSET
Selects from an existing collection, records in which the value of a specified field matches
a given value and creates a new collection file composed of that subset.
SELECT_SUBSET "<old_collection>" {
<selection_items>
}
where:
<old_collection> Is the collection from which you want to select a subset of
records, enclosed in double quotes.
<selection_items> Includes: FIELD, VALUE, and RESULT_COLLECTION.
Example:
SELECT_SUBSET "old_collection" {
FIELD "field"
VALUE "$RESULT"
RESULT_COLLECTION "new_collection"
}
SHOW_SERVICE
Used in COMMAND clauses to bring up the named service window.
SHOW_SERVICE "<service_window>"
where:
<service_window> Is one of the following enclosed in double quotes:
MDL_SVC_JOBIO
MDL_SVC_DATALOG
MDL_SVC_RUNTIME
Example:
SHOW_SERVICE "MDL_SVC_DATALOG"
IMAGE Solutions V8.3 9-78
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
SIZE
Used in a MENU_ITEM, STATUS_ITEM, or DISPLAY clause to limit the number of characters
displayed.
SIZE <number>
Example:
DISPLAY "The job is $JOBNAME" {
ROW 20
COL 40
SIZE 20
}
Often used with ROW and COL to specify the exact beginning and ending location of text on
the screen. Any text that does not fit into the specified area is truncated. The default size is
(maximum columns - starting column).
STARTUP
Specifies a command or commands to be executed and a variable or variables to be
initialized when the menu interface is started up.
STARTUP <commands>
where:
<commands> Is either a single command followed by a semicolon or a list of
commands enclosed in curly braces.
Example:
DECLARE_VARIABLE USER_NAME ;
STARTUP {
PRINT "Starting menu interface..." #Print startup message
PRINT ""
PRINT_N "The current date is: "
"date"
"USER_NAME = unknown" #Initialize variable
"MDL_USR_HOMESCR = control" #Specify home screen
"MDL_USR_INITSCR = signin" #Specify initial screen
}
MENU menu1{
<menu items>
}
See “Specifying Startup Conditions” on page 9-24.
STATUS_ITEM
Defines a status item to appear in the runtime display.
IMAGE Solutions V8.3 9-79
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
STATUS_ITEM {
<descriptors>
}
where:
<descriptors> Is the set of values that define where and how the item appears
in the display, as well as the content it holds.
ROW Is the starting row on the screen for the item.
COL Is the starting column on the screen for the item.
FONTSIZE Is the size of characters displayed in points. The default is 12.
SIZE Is the maximum number of characters to appear in the item.
VARIABLE Is the variable whose content appears in the item.
LABEL Is a string to appear with the item, surrounded by double quotes.
Example:
STATUS_ITEM {
ROW 1
COL 1
FONTSIZE 12
SIZE 25
VARIABLE $product
LABEL "Part Type:"
}
SUBMENU
Used in COMMAND clauses to specify a menu displayed at the end of a command sequence.
SUBMENU "<menu_name>"
where:
<menu_name> Is the name of the menu displayed when this item is selected.
Enclose the menu in double quotes.
Example:
MENU date_menu {
TITLE "Date" ;
MENU_ITEM "print date" {
COMMAND {
PRINT "The date is as follows:"
"date"
}
}
}
MENU simple_menu {
IMAGE Solutions V8.3 9-80
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
TITLE "Simple" ;
MENU_ITEM "Bring up date menu" {
COMMAND {
PRINT_N "Are you sure? y or n: "
READ_RESPONSE $TMP ;
CHECK_VARIABLE $TMP == "y" {
IF FALSE {
ABORT
}
}
SUBMENU "date_menu"
}
}
}
This command can be preceded by a CHECK_VARIABLE or CHECK_STATUS command so that
the menu the display changes to (the one named with SUBMENU) is based on the value of a
variable or on the return status of a command rather than the user’s explicit selection of a
new menu. See “Defining Menus and Menu Items” on page 9-25.
SUPPRESS
Inhibits the appearance of the named function buttons on the menu screen in which the
command appears.
SUPPRESS {
<string>
}
where:
<string> Consists of one or more of the following keywords:
MDL_BTN_HELP
MDL_BTN_BACK
MDL_BTN_HOME
MDL_BTN_PREV
MDL_BTN_NEXT
MDL_BTN_RUN
MDL_BTN_ABORT
Example:
MENU setup {
TITLE "Setup" ;
SUPPRESS {
MDL_BTN_HOME
MDL_BTN_RUN
MDL_BTN_ABORT
}
<menu items>
}
IMAGE Solutions V8.3 9-81
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
Functions and positions of PMC function buttons are predefined and fixed. You cannot
change them. You can, however, suppress the appearance of the labels of one or more of
the buttons on any menu screen. See “Control Buttons” on page 9-9.
The label on the button INFO/ERROR appears only when there are pending informational
messages (INFO) or error messages (ERROR) from the test system.
Buttons can also be suppressed by setting the variable corresponding to the button’s name
to zero. For example, to suppress the HOME button:
MDL_BTN_HOME = 0
TITLE
Used in a MENU clause, before the menu items are defined to specify the title displayed for
a particular menu.
TITLE <strings>
where:
<strings> Is a single string followed by a semicolon or a list of strings
enclosed in curly braces. Each string on a different line is
enclosed in double quotes.
Example:
MENU stage {
TITLE "Stages" ;
HELP {
"Select your Production Stage from these"
"choices: Probe, Final, or Manual Test"
}
<menu items>
}
MENU signin {
TITLE {
" ** WELCOME TO PMC ** "
""
" Sign-In Screen "
}
<menu items>
}
The title for a menu is the text printed on the screen above the menu selections. For
instance, the first example above would display
Stages
(1) Item 1
Selection:
IMAGE Solutions V8.3 9-82
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
Titles normally start in the same column as menu items. To move a title to the right (toward
the center of the screen), add spaces after the opening quotation mark, before the text. The
second example above would create this display:
** WELCOME TO PMC **
Sign-In Screen
(1) Item 1
Selection:
TOTAL_RECORDS
Used in COMMAND clauses to count the number of records in the named collection file.
TOTAL_RECORDS "<collection>" {
RESULT_VARIABLE "<variable>"
}
where:
<collection> Is the collection file for which you want to know the total number
of records, surrounded by double quotes.
<variable> Is the variable into which you want the number placed,
surrounded by double quotes.
Example:
TOTAL_RECORDS "all_products" {
RESULT_VARIABLE "total_records"
}
This example uses RESULT_VARIABLE to place the number of records in a variable.
TOTAL_UNIQUE_VALUES
Used in COMMAND clauses to count the number of unique values in the named field.
TOTAL_UNIQUE_VALUES "<collection>" {
FIELD "<field>"
RESULT_VARIABLE "<variable>"
}
where:
<collection> Is the collection file for which you want to know the total number
of unique values in a field, surrounded by double quotes.
<field> Is the field of unique values you want counted, enclosed in
double quotes.
<variable> Is the variable in which you want the number placed, surrounded
by double quotes.
Example:
IMAGE Solutions V8.3 9-83
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
TOTAL_UNIQUE_VALUES "all_products" {
FIELD "Product_ID"
RESULT_VARIABLE "total_products"
}
This example uses RESULT_VARIABLE to place the number of unique values in a variable.
UNITS_TESTED
Names the type of binning used for this item.
UNITS_TESTED
Example:
BINNING_ITEM {
FONTSIZE 15
LABEL "Units Tested"
UNITS_TESTED
}
UNLOAD_MDL_FILE
Used in COMMAND clauses to unload an auxiliary file.
UNLOAD_MDL_FILE "<filename>"
where:
<filename> Is the name of the file, surrounded by double quotes.
Example:
COMMAND {
UNLOAD_MDL_FILE "/u/test/jobs/$PRODUCT/$PRODUCT.mdl"
}
If the file contained the active runtime display, the active runtime display reverts to what it
was before this file was loaded.
The contents of the named file are removed from the list of menus and command clauses
available to the SUBMENU and CALL_FUNCTION clauses.
This action is also available through the PMC talk library. See “PMC Library” on page 9-43.
UNSHOW_SERVICE
Used in COMMAND clauses to close the named service window.
UNSHOW_SERVICE "<service_window>"
where:
<service_window> Is one of the following enclosed in double quotes:
IMAGE Solutions V8.3 9-84
IMAGE Base Language: Production Menu Control: MDL Keywords
Table of Contents Index Home Master Index Search Help
MDL_SVC_JOBIO
MDL_SVC_DATALOG
MDL_SVC_RUNTIME
Example:
UNSHOW_SERVICE "MDL_SVC_DATALOG"
VALUE
Used in SELECT_SUBSET items, which are found in COMMAND clauses. Specifies a value to
match to create a new collection file containing a subset of records from an existing
collection file.
VALUE "<$var>"
where:
<$var> Contains the value you want to match enclosed in double
quotes.
Example:
SELECT_SUBSET "old_collection" {
FIELD "field"
VALUE "$RESULT"
RESULT_COLLECTION "new_collection"
}
VARIABLE
Used in STATUS_ITEM clauses. Defines a variable to appear in a status item in the runtime
display.
VARIABLE <$var>
where:
<$var> Contains the value of a defined variable.
Example:
STATUS_ITEM {
ROW 1
COL 1
FONTSIZE 12
SIZE 25
VARIABLE $product
LABEL "Part Type:"
}
IMAGE Solutions V8.3 9-85
IMAGE Base Language: Wafer Mapping
Table of Contents Index Home Master Index Search Help
10 WAFER MAPPING
This section describes IMAGE utilities for wafer mapping. It includes the following topics:
• “IMAGE Real Time Wafermap” on page 10-2
• “FIRMS Wafer Mapping” on page 10-19
• “Wafer Mapping for Off-Line Inking” on page 10-23
IMAGE Solutions V8.3 10-1
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
IMAGE Real Time Wafermap
The Real Time Wafermap tool allows examination of tests performed on wafers in real time
(as they are being tested). This enables early detection of potential problems with the tester
and the test program during the production process.
Using the Real Time Wafermap you can:
• Monitor wafers as they are tested, either locally or remotely
• Review wafer data stored in STDF format
• View data on any die and store and print wafer results on up to 50 wafers
• View results as hardware bins, software bins, pass/fail, or by sites if using multisite
testing
• View wafer using bin values, ASCII codes, colors, or textures (for monochrome
monitors)
• Display a preview of the wafer showing where each die is located
The Real Time Wafermap is displayed in a large window for easy viewing by engineers and
production operators.
Setting Up the Real Time Wafermap
The Real Time Wafermap is easy to set up and use. You can use it with existing wafer test
programs without having to edit them. This tool also includes features to enhance its
flexibility.
Monitoring wafer testing using the Real Time Wafermap requires:
• A wafer and prober ready for testing
• A test program for testing the wafer that includes the set wafer and device_bin
statements (see “Writing a Test Program for Use With the Wafermap” on page 10-9)
• A preview file that defines the wafer dimensions (see “Creating a Preview File” on page
10-5)
You can use additional files to change the wafer’s features.
Once a wafer is ready for testing and a test program is chosen, using the Real Time
Wafermap requires the following steps:
1. Create a preview file using the file name
<program_name>.wmap_preview
(See “Creating a Preview File” on page 10-5.) If no .wmap_preview file is located for a
test program, the wafermap display looks for a .wafr file and uses that (see “Creating
the Wafer Configuration File” on page 10-23).
2. Load the wafer test program in a test station.
3. Bring up the Real Time Wafermap display by typing wafermap at the station window
prompt. (See “Starting the Wafermap” on page 10-3.)
IMAGE Solutions V8.3 10-2
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
4. Connect the Real Time Wafermap to the station where the test program is loaded. (See
“Connecting to a Station” on page 10-4.) If the wafermap is started from a station window
that has a test program loaded, the wafermap will automatically connect. The
appropriate preview file is also loaded.
5. Run the test program.
At this point, wafer results begin to appear. The default wafermap shows pass/fail results in
color. If your wafer preview file includes coordinate pairs for the wafer die, you will also see
a map of the entire wafer showing both tested and untested dice.
NOTE
Restart the wafermap each time a new test program is loaded. If the wafermap is not
restarted, it may display an incorrect quadrant directional.
Starting the Wafermap
Start the IMAGE Real Time Wafermap from a station window using the command:
wafermap [-station #] [-variable <display variable>] [-mode <display mode>]
[-scramble <scramble_filename>] [-preview <preview_filename>]
[-stdf <file>] [-condensed | -nocondensed]
where:
-station <#> Starts the wafermap and tries to connect to the specified station.
If the connection is refused, station # becomes the default for
connect. (See “Connecting to a Station” on page 10-4.)
-variable <var> Starts the wafermap using the specified display variable to
display test results. (See “Changing the Way Data is Displayed
on the Wafermap” on page 10-16.) This option overrides any
default from the .Xdefaults file or the application. Display
variables (var) include
hw_bin Display the hardware bin result for each die in the
wafermap.
sw_bin Display the software bin result for each die in the
wafermap.
pass_fail Display the pass/fail result for each die in the
wafermap. (This is the default.)
site_num Display the site number for each die in the
wafermap. (Used for multisite testing.)
-mode <mod> Starts the wafermap using the specified display mode to display
test results. (See “Changing the Way Data is Displayed on the
Wafermap” on page 10-16.) This option overrides any default
from the .Xdefaults file or the application. Display modes (mod)
include
IMAGE Solutions V8.3 10-3
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
color Display test results for each die using a color. (This
is the default.)
code Display test results for each die using a code. (See
“Creating a Scramble File” on page 10-8.)
value Display test results for each die using a bin value.
Value displayed is the one selected using -variable.
texture Display test results for each die using a texture.
(Used for monochrome monitors.)
color+code Display test results for each die using a color
and a code. (See “Creating a Scramble File” on page 10-8.)
color+value Display test results for each die using a color
and a bin value. Value displayed is the one selected using
-variable.
-scramble <file> Specifies a scramble file to load. Overrides the
<programname>.wmap_scramble default filename. (See
“Creating a Scramble File” on page 10-8.)
-preview <file> Specifies a preview file to load. Overrides the default
<programname>.wmap_preview filename. (See “Creating a
Preview File” on page 10-5.)
-stdf <file> Specifies an STDF file to load. This option starts the wafermap
and tries to load this file. If specified, the program does not try to
connect to a station and ignores the -preview switch.
-condensed Specifies a condensed statistics mode for displaying results in
the statistics area of the Real Time Wafermap window. (See
“Choosing Condensed Statistics” on page 10-17.)
-nocondensed Specifies a noncondensed statistics mode.
Connecting to a Station
The Real Time Wafermap automatically tries to connect to the station specified by the
environmental variable STATION_NUMBER when you start it, unless you use the -station
switch. If you start the wafermap from a station window, it is set to the current station
number. If you start the program outside a station window, the wafermap comes up not
connected to any station unless you use the -station switch. The current station is shown
in the title bar.
To connect to a station after the tool is started, select the desired station number using the
STATION>CONNECT menu. This menu lists all 10 possible stations.
An error can occur during connection if you try to connect to a station and:
• That station does not exist
• No test program is loaded
IMAGE Solutions V8.3 10-4
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
• The tool is already connected to that station
Changing between stations requires that you connect to a station that exists and has a test
program loaded.
NOTE
If the TESTER_NUMBER environment variable is not set before the Real Time Wafermap is
started, the station menu is grayed out and connections are not allowed. This variable is
required to retrieve information on IMAGE stations. This is only an issue when running
IMAGE remotely.
Creating a Preview File
The preview file contains the minimum and maximum coordinates for x and y directions on
the wafer. The wafermap tool uses this information to draw the wafer. This information must
be available before any data is sent to the wafermap.
If you have a SECS wafer configuration file (.wafr) for a test program, you can use the
.wafr file as your wafermap preview file (see “Setting Up a Wafer Map” on page 10-23).
The wafermap program allows a .wafr file anywhere it would allow a .wmap_preview file.
The wafermap display can even read a .wafr file, then generate a .wmap_preview file that
you can edit. The wafermap program calculates the MIN and MAX for X and Y from the row
entries and calculates the preview dice from the INK, SKIP, and, PROBE entries.
The preview file below (figure 10-1) created the preview map of the wafer in figure 10-2. This
file contains the MAXX, MINX, MAXY, MINY, and a list of coordinate pairs for the wafer. The
coordinate pairs are not required to create a preview file.
IMAGE Solutions V8.3 10-5
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
Figure 10-1. Preview File
IMAGE Solutions V8.3 10-6
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
Figure 10-2. Preview Map of a Wafer
To create a preview file:
1. Identify the x and y values in a preview file using the following keywords: MAXX, MINX,
MAXY, and MINY. An example is:
MAXX 5
MINX -4
MAXY 5
MINY -4
2. As an option, the preview file can include a list of coordinate pairs which identify the die
location of each die on the wafer. In this case, the wafermap reviews the coordinate list
and retrieves the maximum and minimum values. If the list of coordinates is present in
a preview file, the wafermap draws a preview map of the wafer before any testing is
done. (See figure 10-2.) This option provides a reference for each die on the wafer.
During testing, the wafermap tool generates such a preview map. Therefore, even if the
IMAGE Solutions V8.3 10-7
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
original preview file does not include coordinates, a preview map is displayed by the
time the second wafer is tested.
The Real Time Wafermap indicates the die at location (0,0) on the preview display by
labelling it (0,0) (see figure 10-2).
3. You can specify the axis orientation in your wafermap preview (.wmap_preview) file by
adding the following lines:
POSX R [or POSX L]
POSY D [or POSY U]
These statements preset which way the axes run on the display, where X can increase
to the right or left and Y can increase up or down. Specifying axis orientation in the
preview file overrides directions specified in the set wafer statement of your test
program (see “Using the set wafer Statement” on page 10-19). You cannot specify axis
orientation in a .wafr file.
4. Name the preview file using <program_name>.wmap_preview. This file becomes the
default file and is automatically read when a connection is attempted. If this file or a
.wafr file for the test program does not exist or has an error, connection does not occur.
You can do either of the following to override the default file:
• Enter a filename at startup using the wafermap -preview command.
• Load a preview file from the wafermap window using FILE>LOAD>LOAD PREVIEW.
NOTE
Any device result received with coordinates outside the maximum and minimum
coordinates defined in the preview file is ignored.
Creating a Scramble File
Two of the wafermap display modes (the code and color+code modes) use a code to
display data on the wafermap. The code is shown as a single character representing a
display variable value. These codes make up a scramble map, and they are defined in a
scramble file.
The wafermap automatically uses an IMAGE default scramble map when no scramble file
is indicated. This map consists of:
• The letters A to Z representing data values 0-25
• P and F representing pass/fail codes
• ? indicating a value that does not have a defined code
You can load a new scramble file at any time, or you can use the default map by selecting
FILE>CLEAR SCRAMBLE from the Wafer Map menu. (See “File Menu” on page 10-13.) A
scramble file <program_name>.wmap_scramble is automatically used if it exists.
Use the following format when creating a scramble file:
• One scramble file entry is allowed per line
• Lines with comments (starting with #) and blank lines are ignored
IMAGE Solutions V8.3 10-8
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
• Each scramble file line (mapping) has two parts:
Value Code
Each part is separated by white space (spaces or tabs). These parts are defined as follows:
Value The bin data value. This appears as a hardware or software bin
in the wafermap, depending on how the display is set. It is a
decimal number from 0 to 255 or the character P or F to define
pass and fail codes.
Code An ASCII symbol (one character) to be displayed if a die has a
specified value. This can be any keyboard character, but avoid
using the ? symbol.
To create a scramble file:
1. Define the bin value and code.
For example, your test program uses five bins (1–5). You would like bin1 to be a
premium bin, bins 2–4 to be normal quality, and bin 5 to be lower quality. You could set
up the following scramble file:
# Value Code
1 A
2 B
3 B
4 B
5 C
In this case, A on the wafermap would indicate the premium parts, B the normal parts,
and C the lower quality parts.
2. Name the scramble file using <program_name>.wmap_scramble.
For more information regarding defining bins, see “Assigning Bin Numbers” on page 15-6.
Writing a Test Program for Use With the Wafermap
Once the wafermap application is connected to a station, it is automatically sent the same
data as an STDF file. Most programs do not need modification if the current STDF files
created by the test program contain a WCR and one or more WIR’s and WRR’s, along with
the normal datalog STDF records.
The WCR record is used by the wafermap program to determine the wafer orientation when
it draws the wafer. (For information on the WCR, see “Wafer Configuration Record (WCR)”
on page 24-34 and the Standard Test Data Format Specification.) This information is
defined in the test program using the set wafer statement (see “Using the set wafer
Statement” on page 10-19).
The WIR record indicates the start of a wafer run. This record is generated by a
tl_dlg_startwafer() statement included in your test program. (For information on the
WIR, see “Wafer Information Record (WIR)” on page 24-36 and the Standard Test Data
Format Specification.)
IMAGE Solutions V8.3 10-9
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
The WRR record indicates that the wafer run has ended. This record is generated by a
tl_dlg_endwafer() statement used in the test program. Include startwafer and endwafer
statements in the following handler/prober callbacks inside the test program:
tl_handlerprober_cond_eow()
tl_handlerprober_cond_eol()
tl_handlerprober_cond_eoc()
These functions indicate end-of-wafer, end-of-lot, and end-of-cassette respectively. (For
information on the WRR, see “Wafer Results Record (WRR)” on page 24-36 and the
Standard Test Data Format Specification. See also “Using Callback Functions” on page
1-35 of the Handler/Prober Manual.)
WIR and WRR records also contain a wafer ID field used to label the wafer. To set this field,
add a tl_set_wafer_id() statement to the test program. The wafermap tool displays this
wafer ID along with the wafer start and end times for every wafer tested in the lot, up to the
maximum number of wafers (50). If a wafer ID is not set in the test program, a default ID of
Wafer <#> is used.
Your test program must include a device_bin statement. This statement controls the pass/
fail drawing of the devices. If the statement is not in the test program, the wafer will draw
incorrect results.
Starting a new lot clears all wafer data from the wafermap tool in preparation for receiving
the new lot data.
If the Real Time Wafermap is connected to a test program after it was run, all prior results
are not sent to the tool. Only the most current wafer information and then the subsequent
die results are received by the wafermap.
Using the Real Time Wafermap Window
The IMAGE Real Time Wafermap (figure 10-3) displays all important information in the main
window. Parts of the window group information according to function. Select DATA>REAL
TIME WAFERMAP... to display the IMAGE Real Time Wafermap window.
Features of the Real Time Wafermap Window
The IMAGE Real Time Wafermap window (figure 10-3) has the following sections:
Title Bar The title bar contains the tester name, the current default station
number, the test program name, lot number and wafer number.
If no program is loaded, the program name displays “(Not
Connected)” to indicate no connection to the current station.
Control Area This area contains the following menu buttons and display
controls:
FILE A menu that allows you to manipulate and print files.
(See “File Menu” on page 10-13.)
IMAGE Solutions V8.3 10-10
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
Control Wafer Statistics
Wafer information Title Bar area Canvas buttons
Message area Statistics Single die information
Figure 10-3. Main Real Time Wafermap Window Displaying Coded Software Bins
VIEW A menu that includes functions for controlling the
wafer canvas. (See “View Menu” on page 10-14.)
STATION A menu that allows you to connect and disconnect
the wafermap to and from stations. (See “Station Menu” on page
10-15.)
PROPS Displays the Properties window that allows you to
select the default display variable and mode for the wafermap
and statistics mode. (See “Properties Button” on page 10-16.)
IMAGE Solutions V8.3 10-11
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
DISPLAY VARIABLE Changes the current wafermap display
variable.
DISPLAY MODE Changes the current wafermap display
mode.
WAFER # Lists the current wafer number and allows you to
display a different wafer.
NORMAL/CONDENSED STATISTICS BUTTONS Allows you to
toggle between normal (one column of data) and condensed
(two columns of data) statistics modes. (See “Choosing
Condensed Statistics” on page 10-17.)
Wafer Information The wafer information area contains individual wafer information
for the wafer being displayed. This includes the current test
program name, the lot number, the wafer ID, and the start and
end times.
Statistics The statistics area contains the wafer dice statistics. It displays
the value, color/code/value/texture, count, and percent of each
value for the current display variable. The second column
changes depending on the display mode selected.
If you have more bins displayed than there is room for in the
statistics area, you can choose the condensed statistics mode
(see “Choosing Condensed Statistics” on page 10-17). Only the
HW Bin and SW Bin statistics can be condensed, as Site
Number and Pass/Fail data can never exceed the area allotted.
The condensed statistics option also affects PostScript output
(see “Printing Wafer Information” on page 10-18).
Wafer Canvas The main canvas displays the current wafer. (It may also display
preview dice.) Each die is displayed according to the specified
display variable and mode. For example, the display in figure 10-
3 shows software bins displayed using codes. A horizontal and
vertical line in the upper left corner shows the quadrant
directional of probing for X and Y.
Single Die Information This area displays individual statistics for any die in the
wafermap when you click on that die. It shows the X/Y location,
site number, and display variable values (hardware bin, software
bin, and pass/fail) for the die.
A feature in the wafermap display allows you to get the X/Y
coordinates of a preview die by clicking on the die location even
before that location has been datalogged.
Message Area Displays error and status messages.
IMAGE Solutions V8.3 10-12
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
File Menu
The FILE menu contains selections that allow you to manipulate files used with the Real
Time Wafermap. Selections include the following:
FILE>LOAD This menu allows you to load files into the wafermap. Selections
include the following:
LOAD STDF FILE Brings up the Load STDF file window (figure
10-4) and allows you to load any file with a .stdf extension.
Figure 10-4. Load STDF file Window
LOAD SCRAMBLE Brings up the Load Scramble file window
(figure 10-5) and allows you to load any file with a
.wmap_scramble extension. (See “Creating a Scramble File” on
page 10-8.)
Figure 10-5. Load Scramble file Window
LOAD PREVIEW Brings up the Load Preview file window
(figure 10-6) and allows you to load any file with a
.wmap_preview extension. (See “Creating a Preview File” on
page 10-5.)
Figure 10-6. Load Preview file Window
IMAGE Solutions V8.3 10-13
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
FILE>GENERATE PREVIEW FILE
Creates a preview file from the displayed wafer. This option is
grayed out (inactive) if no data is present.
FILE>CLEAR Clears items from the display. Menus items include the following:
CLEAR DATA Clears the current data from the display.
CLEAR SCRAMBLE Clears the current scramble file from
the display. Clearing a scramble file removes it from use. It does
not delete the saved file.
FILE>PRINT AS POSTSCRIPT
Prints the current wafer in a PostScript format. (See “Printing
Wafer Information” on page 10-18.)
FILE>PRINT... Brings up the Print window (figure 10-7). This window allows you
to specify printing of the current wafer or all wafers. It also allows
you to specify the printers used for PostScript printing. It has a
check-box for printing the current format to a file only and a line
for the filename. (See “Printing Wafer Information” on page
10-18.)
Figure 10-7. Wafermap Print Window
FILE>QUIT Exits the tool.
View Menu
The VIEW menu contains selections that allow you to manipulate the display and to see
which files are in use. Selections include the following:
VIEW MASK... Brings up the Wafermap View Mask window (figure 10-8) that
allows you to specify criteria to draw specific dice. A choice item
allows you to select the display variable and a mask value line
where you can enter a value to match. The button, DRAW
SELECTED DICE allows you to draw the dice that match the
variable and value specified. The button CLEAR DICE clears the
IMAGE Solutions V8.3 10-14
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
wafer display. The button REDRAW ALL redraws the entire wafer.
(See “Using View Mask to Mask the Display” on page 10-17.)
Figure 10-8. View Mask Window
FILE INFO... Brings up the File Information window (figure 10-9) showing the
names of the preview, scramble and STDF files currently in use.
Figure 10-9. File Information Window
SHOW/HIDE PREVIEW DICE
Show or hide the preview dice on the wafer canvas. The menu
item reads HIDE PREVIEW DICE if the preview dice are currently
displayed and SHOW PREVIEW DICE if they are not. This option is
grayed out (inactive) if no data is present.
Station Menu
The STATION menu allows you to connect and disconnect the Real Time Wafer map to test
stations. It has the following selections:
CONNECT Connects the wafermap to a test station. This item has a menu
listing all 10 stations that the wafermap can connect to. The
default choice for the CONNECT menu is the station where the
application was started from or the last connected station. This
default station is shown in the title bar. Click STATION to connect
to the default station.
DISCONNECT Disconnects the wafermap from the current station.
IMAGE Solutions V8.3 10-15
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
Properties Button
The PROPS... button opens the Wafermap Properties window (figure 10-10) which contains
three wafermap default properties. They are DISPLAY VARIABLE, DISPLAY MODE, and
CONDENSED STATISTICS. The variables determine what variable and mode is displayed
when the Real Time Wafermap is started and whether the statistics are displayed in
condensed or noncondensed (normal) mode. The default variable is PASS/FAIL, the default
mode is COLOR, and the default for condensed statistics is FALSE.
Figure 10-10. Wafermap Properties Window
These properties are stored in the .Xdefaults file in the IMAGE section under
image.wafermap.display.variable, image.wafermap.display.mode, and
image.wafermap.display.condensed_stats. These values correspond to the choice
items in the Display Variable and Display Mode controls and the NORMAL/CONDENSED
STATISTICS BUTTONS in the Real Time Wafermap display (see figure 10-3 on page 10-11).
For example, if you want the default for the display to be hardware bin data, set the DISPLAY
VARIABLE to HW BIN. The wafermap will automatically start using hardware bins as the
default.
Changing the Way Data is Displayed on the Wafermap
The Real Time Wafermap has several display variables and display modes that allow you
to view the wafer results in different variations (see figure 10-3 on page 10-11).
The display variable selects a single data region to be displayed. Data regions available
include: HARDWARE BIN, SOFTWARE BIN, PASS/FAIL, and SITE NUMBER.
The display mode selects the attributes of the data values drawn in the canvas. Display
modes include: COLOR, CODE, VALUE, TEXTURE, COLOR+CODE, and COLOR+VALUE.
The statistics canvas contains a legend to identify color, code, and texture for each data
value. A maximum of 16 data values are displayed in the legend. Only 16 colors and
textures are available. They are reused based on data value (that is, value 0 and value 16
share the same color and texture). The code mode of the display draws a single character
representing a data value inside the device square (see figure 10-3 on page 10-11). You can
define these codes in a scramble file. (See “Creating a Scramble File” on page 10-8.)
IMAGE Solutions V8.3 10-16
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
Using View Mask to Mask the Display
The view mask feature allows you to view devices that match specified variable and value
criteria using the current display settings. You can display dice that match some criteria and
mask (not display) all other dice on the wafer. This can help you to see patterns of results
on the wafer.
For example, you have tested a wafer using a multisite test program, and you want to see
to see site numbers of all failing devices. You can do the following:
1. Set the wafer Display Variable to SITE NUMBER.
2. Set a Display Mode such as COLOR.
3. Bring up the Wafermap View Mask window and select the PASS/FAIL mask variable with
a 0 value.
4. Click the DRAW SELECTED DICE button.
This clears the current wafer from the display and draws only those devices which failed,
displaying the site numbers in the current display mode.
Once you select the criteria and the devices are drawn, the wafermap enters a view mask
mode where only the selected dice are shown.
Either of the following redraws all the devices:
• Dismiss the Wafermap View Mask window
• Click the REDRAW ALL button in the Wafermap View Mask window to see all dice without
dismissing the window
Selection criteria are cumulative. For example, you select to view devices that match site 0.
If you then select devices that match software bin 5, the devices drawn to match site 0 are
still displayed. Clearing the dice or redrawing all resets the selection list.
Note that if you are in view mask mode, new devices received that match the selection
criteria are not automatically drawn. You must reselect the desired criteria to view any new
devices that may have been received.
Choosing Condensed Statistics
You can set the DEFAULT FOR CONDENSED STATISTICS to TRUE. All future invocations of the
wafermap will come up in condensed statistics mode.
Condensed statistics mode allows you to display two columns of data in the statistics area
of the Real Time Wafermap window (see figure 10-11). Only the HW Bin and SW Bin
statistics can be condensed, as Site Number and Pass/Fail data can never exceed the area
allotted. The condensed statistics option also affects PostScript output (see “Printing Wafer
Information” on page 10-18).
IMAGE Solutions V8.3 10-17
IMAGE Base Language: Wafer Mapping: IMAGE Real Time Wafermap
Table of Contents Index Home Master Index Search Help
Figure 10-11. Main Real Time Wafermap Window Displaying Condensed Statistics
Printing Wafer Information
The Real Time Wafermap allows you to produce PostScript output for printing. The file
menu includes two selections which print the current wafer to the designated output. The
print window allows you to print all wafers instead of only the current one (see figure 10-7
on page 10-14). You can specify which printer to use for PostScript outputs, and you can
select to print only to a file. The condensed statistics option also affects PostScript output.
IMAGE Solutions V8.3 10-18
IMAGE Base Language: Wafer Mapping: FIRMS Wafer Mapping
Table of Contents Index Home Master Index Search Help
FIRMS Wafer Mapping
A feature of FIRMS is the ability to map and store information on wafers. As part of its
support for FIRMS, IMAGE includes the following wafer mapping capabilities:
• Declaration of start and end of wafer events
• Support for STDF Wafer Information Records (WIR), Wafer Results Records (WRR),
and Wafer Configuration Records (WCR)
The set wafer statement informs the test program of wafer characteristics output in the
STDF Wafer Configuration Record. It also supports parallel wafer probe test.
Using the set wafer Statement
The set wafer syntax is shown below. Options for this statement are components of the
Wafer Configuration Record. For information about each field and the default values, see
“Wafer Configuration Record (WCR)” on page 24-34 and the Standard Test Data Format
Specification.
set wafer:
site:n = [x,y] /* Used for parallel wafer probe */
size = <float or var>/* WAFR_SIZ–Diameter of wafer in WF_UNITS */
die_height = <float or var>/* DIE_HT – Height of wafer in WF_UNITS */
die_width = <float> /* DIE_WID – Width of wafer in WF_UNITS */
units: <cm in> /* WF_UNITS – Units for dimensions */
centerx = <int or var> /* CENTER_X – X coordinate of center die */
centery = <int or var> /* CENTER_Y – Y coordinate of center die */
flat: <U D L R> /* WF_FLAT – Orientation of wafer flat */
posx: <L R> /* POS_X – Positive X direction of wafer */
posy: <U D> /* POS_Y – Positive Y direction of wafer */
;
<U D L R> used for flat, posx, and posy correspond to up, down, left, and right
orientations. Directions specified in the .wmap_preview file, override directions specified in
the set wafer statement (see “Creating a Preview File” on page 10-5).
Fields not specified in the set wafer statement are given the default values listed in the
STDF specification each time the set wafer statement is invoked. To preserve previous
settings you must store and respecify them each time the set wafer statement is invoked.
IMAGE expects a prober used for parallel wafer test to return the coordinates corresponding
to site 0, as determined by the wiring of the DIB. IMAGE computes the coordinates of the
other die based on the positions of the other prober needles relative to the one
corresponding to site 0.
Specify each wafer site used in a parallel wafer probe operation using the site:n=[x,y]
clause of the set wafer statement. n is the site number, which must be between 0 and the
total number of sites specified in the pinmap (1 less than the total number of sites specified
in the pinmap since the numbering starts at 0) and an offset from some site 0. Each site in
IMAGE Solutions V8.3 10-19
IMAGE Base Language: Wafer Mapping: FIRMS Wafer Mapping
Table of Contents Index Home Master Index Search Help
the pinmap must have a site clause and you can use variables to specify the site number
and the offsets.
The [x,y] specifies the position of prober sites relative to site 0. For example (figure 10-
12), offset [2,3] means the prober needle is two die positions to the right and three die
positions up from the [0,0] site.
Offset [2,3]
x
Site 0
x
Figure 10-12. Site With Offset [2,3]
The compiler checks that you have written the site clause correctly and that the number of
sites specified is less than the maximum allowed by IMAGE. The compiler prints an error
message if these two conditions are not met.
Runtime checks are performed to assure that:
• A site 0 is specified
• No site is specified more than once.
• All site numbers are within limits (greater than or equal to zero and less than the total
number of sites declared in the pinmap minus one)
• A site specification exists for each site declared in the pinmap.
• One site with [0,0] offset is declared
• No offset is specified more than once.
A site can have no offset. That is, it can have offset [0,0]. The positions of the other prober
needles are specified as offsets relative to this site. Examples are shown below. Some of
these configurations may be imaginary and are used only as examples. In each figure, the
x’s mark the positions of the prober needles on the wafer.
set wafer Examples
Example 1 (figure 10-13):
set wafer:
site: 0 = [0,0]
site: 1 = [1,-1]
site: 2 = [2,-2]
IMAGE Solutions V8.3 10-20
IMAGE Base Language: Wafer Mapping: FIRMS Wafer Mapping
Table of Contents Index Home Master Index Search Help
site: 3 = [3,-3]
;
Site 0
Site 1 x
x
x
Site 2 x
Site 3
Figure 10-13. Wafer Site Locations for Example 1
Example 2 (figure 10-14):
set wafer:
site: 0 = [3,-3]
site: 1 = [2,-2]
site: 2 = [1,-1]
site: 3 = [0,0]
;
Site 3
Site 2 x
x
x
Site 1 x
Site 0
Figure 10-14. Wafer Site Locations for Example 2
Example 3 (figure 10-15):
set wafer:
site: 0 = [0,0]
site: 1 = [1,0]
site: 2 = [0,-1]
site: 3 = [-1,-1]
;
IMAGE Solutions V8.3 10-21
IMAGE Base Language: Wafer Mapping: FIRMS Wafer Mapping
Table of Contents Index Home Master Index Search Help
Site 0
Site 1
Site 2 x x
x x
Site 3
Figure 10-15. Wafer Site Locations for Example 3
Set the wafer_id of a particular wafer using the tl_set_wafer_id() function. This is a
void type function that expects a pointer to a character string as its argument. The
wafer_id must conform to the STDF standard governing variable length strings and must
not exceed 255 bytes in length.
The code to set the wafer identification to Image_wafer_1 would look like
void tl_set_wafer_id(); /* Declare the function in the header */
char *wafer_id = "Image_wafer_1";/* Declare variable to hold wafer ID */
tl_set_wafer_id(wafer_id); /* Call to set wafer ID */
After you have set the wafer_id, include a tl_dlg_startwafer() statement in your test
program to create the WIR record which indicates the start of a wafer run.
IMAGE Solutions V8.3 10-22
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
Wafer Mapping for Off-Line Inking
IMAGE wafer mapping software is designed to perform inkless binning during wafer test. As
dice are tested, IMAGE stores the binning results and x,y coordinates in an STDF file. It
uses this STDF file to create a standard wafer map that conforms to the Semiconductor
Equipment and Materials International Equipment Communications Standard (SECS). This
wafer map can later be transferred to an offline ink station and used to ink the wafer.
The wafer mapping software receives information on the shape of the wafer from the
IMAGE set wafer statement. The location of dice on a wafer is specified by a wafer
configuration file. This wafer file has been designed using Electroglas probers. You can,
however, use this software with equipment from other vendors.
Once the wafer mapping software is initialized for a particular wafer, the prober must be set
up to have the same view of the wafer as is specified to IMAGE, including the probe pattern
specified. Once both IMAGE and the prober are initialized, you must turn datalogging on
and enable the prober. As dice are tested, the prober is periodically polled for X,Y
coordinates. These are compared against IMAGE’s current view, to assure that probing is
proceeding correctly. If the coordinates are incorrect, probing is disabled.
Setting Up a Wafer Map
The general procedure for creating an SECS wafer map is as follows:
1. Create a wafer configuration (.wafr) file that describes the layout of the dice on the
wafer. (See “Creating the Wafer Configuration File” on page 10-23.)
2. Include a set wafer statement in your test program to define the wafer. (See “Defining
the Wafer in the Test Program” on page 10-31.)
3. Set up the wafer prober. (See “Setting Up the Prober” on page 10-32.)
4. Load the test program for testing the wafer. (See “Using the load Command to Connect
to a Prober” on page 10-33.)
5. Turn on datalogging. (See “Setting Up Datalog” on page 10-34.)
6. Use the handlerconf -wafer_map command to enable wafer mapping and start
testing. (See “Invoking the Wafer Mapping” on page 10-34.)
7. At the end of the lot, run the STDF file created by probing the wafer through the SECS
filter to create an SECS wafer file. (See “Generating the SECS Map” on page 10-35.)
The inkless binning software is designed to work using a combination RS232/GPIB and
parallel interface. The parallel interface receives start signals and sends binning results.
The RS232 and GPIB interfaces retrieve x and y coordinates. These coordinates are sent
to IMAGE which compares them against its notion of what the current x and y coordinates
should be. This technique minimizes the RS232 or GPIB communication overhead.
Creating the Wafer Configuration File
The wafer configuration file provides IMAGE with the layout of dice on the wafer, by rows,
and the path the probe will take across the wafer. It is loaded in the same directory as the
IMAGE Solutions V8.3 10-23
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
test program you are using. This file must have the extension .wafr and is made up of four
sections:
• ROW list
• INK list
• SKIP list
• PROBE list
The ROW list specifies die positions on the wafer including partial die, landmarks, and ugly
die. You can exclude (that is, not test) later partial die and other locations in each row by
specifying the locations in either the INK or SKIP lists. All die specified in the ROW list are
ultimately binned, either by actual testing or by being assigned an ink bin, in the case of ink
and skip die. You can set the ink bin using the tl_set_wafer_mapping_ink_bin()
function.
Ink die and skip die are ultimately treated alike—both are inked. The distinction is made only
for conceptual purposes so that you can distinguish between ugly die and landmarks on the
wafer.
An example of a wafer configuration file would be as follows:
# Probe Quadrant 1
#
ROW
X0,Y0,X-3
X0,Y-1,X-3
X1,Y-2,X-4
X1,Y-3,X-4
X0,Y-4,X-3
X0,Y-5,X-3
INK
X0,Y0,X0
X-3,Y-1,X-3
X1,Y-2,X1
X-4,Y-3,X-4
X0,Y-4,X0
X-3,Y-5,X-3
SKIP
X-3,Y0,X-3
X-1,Y-1,X-1
X-4,Y-2,X-4
X-1,Y-3,X-1
X-3,Y-4,X-3
X0,Y-5,X0
PROBE
X0,Y-1,X-2
X1,Y-3,X-3
X0,Y-5,X-2
You can use the wafer configuration file (.wafr) for a test program as your wafermap
preview file (see “Creating a Preview File” on page 10-5). The wafermap program allows a
.wafr file anywhere it would allow a .wmap_preview file. If no .wmap_preview file is located
IMAGE Solutions V8.3 10-24
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
for a program, the wafermap display looks for a .wafr file and uses that. The wafermap
display can even read a .wafr file, then generate a .wmap_preview file that you can edit.
The wafermap calculates the MIN and MAX for X and Y from the ROW entries and calculates
the preview dice from the INK, SKIP, and PROBE entries.
The wafer configuration file also allows you to specify the order in which dice are probed. In
fact, the mapping software assumes you have defined the probe pattern. If the prober is
allowed to select its own probe pattern, wafers in a particular lot may not be probed in
exactly the same way, making the maps invalid.
The wafer configuration file specifies only the location of dice on a wafer. You must specify
other wafer information, such as wafer units, die size, orientation of the positive x and y axis,
using the set wafer statement. For multisite probing, you must also include orientation of
the probe needles which is essential to wafer mapping.
Understanding the Prober Coordinate System
Before creating the wafer configuration file, you must understand the prober coordinate
system, since the wafer configuration file is written using this system. This section describes
the Electroglas prober coordinate system. If using another make of prober, adapt this
discussion to that manufacturer’s standard.
Figure 10-16 shows the prober quadrants and the orientation of the x and y axes. It is
assumed that the die under the origin of each axis is the first die (the die under the probe
needles when the prober’s FIRST key is pressed) and has been assigned preset
coordinates of (0,0). Every other die on the wafer is specified in terms of positive or negative
die locations away from the origin (in this case the first die). In figure 10-16, die X1 and X2
are identified and their coordinate values listed, in terms of prober coordinates.
IMAGE Solutions V8.3 10-25
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
Y+ Y+
X- X+ X- X+
X2 X2
X1 X1
Y- X1 = (2, -3) X1 = (-1, -3) Y-
Quadrant 2 X2 = (1, -1) X2 = (-2, -1) Quadrant 1
Y+ Y+
X2 X2
X1 X1
X- X+ X- X+
Y- X1 = (2, 2) X1 = (-1, 2) Y-
Quadrant 3 X2 = (1, 4) X2 = (-2, 4) Quadrant 4
Figure 10-16. Electroglas Prober Coordinates
The first die need not be assigned the preset value of (0,0). If a value, say (x,y) other than
(0,0) is selected, this serves to identify that the first die is (x,y) die locations away from the
origin. In this case, each die specified is in die steps from the origin not from the first die
(since the first die is not the origin in this case). Note that the value selected for FIRST may
locate the origin off the wafer.
For Electroglas probers, you set the preset value using the menu selection called PRESET.
To assign this value to a particular die, you must physically move the die under the probe
needle and press the FIRST key. You must also select the prober quadrant.
IMAGE Solutions V8.3 10-26
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
You must express the ROW, SKIP, INK, and PROBE lists according to the coordinate system
of the prober quadrant chosen. If for some reason a wafer configuration file is written for a
particular prober quadrant and you choose another, you must change the coordinates in the
wafer configuration file to reflect the new quadrant. In Electroglas probers, the coordinate
quadrant must match the prober quadrant. If the coordinate quadrant differs, the X,Y
coordinates will be reported incorrectly, and the wafer mapping software will interpret the
coordinates as being incorrect and disable the prober.
Creating a Row List
Before probing the wafer, you must create a ROW list. This list specifies the position of dice
on the wafer. As the name implies, the wafer is described as rows of dice.
In the wafer configuration file, you first specify the ROW list by including the ROW keyword on
a specific line and then on subsequent lines writing the specification for each row. Each row
is described according the following format:
ROW
X<x-coord1>,Y<y-coord1>,X<x-coord2>
X<x-coord1>,Y<y-coord2>,X<x-coord2>
.
.
.
X<x-coord1>,Y<y-coordn>,X<x-coord2>
where:
X Indicates following value is an X coordinate.
Y Indicates following value is an Y coordinate.
x-coord1 Is the X-coordinate value of the first die in the row.
y-coord Is the row number.
x-coord2 Is the X-coordinate value of the last die in the row.
No white spaces are allowed on a line. The ROW list must specify all dice on a wafer,
including dice which will be later designated as skip or ink die. Dice not identified as ink or
skip dice are assumed to be valid dice which will be tested.
The following are the ROW lists for the wafer in figure 10-16. Rows are listed from the bottom
of the wafer (the region closest to the flat), where the FIRST die is located, to the top.
#Probe Quadrant 1 Probe Quadrant 2
ROW ROW
X0,Y0,X-3 X0,Y0,X3
X0,Y-1,X-3 X0,Y-1,X3
X1,Y-2,X-4 X-1,Y-2,X4
X1,Y-3,X-4 X-1,Y-3,X4
X0,Y-4,X-3 X0,Y-4,X3
X0,Y-5,X-3 X0,Y-5,X3
IMAGE Solutions V8.3 10-27
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
#Probe Quadrant 3 Probe Quadrant 4
ROW ROW
X0,Y0,X3 X0,Y0,X-3
X0,Y1,X3 X0,Y1,X-3
X-1,Y2,X4 X1,Y2,X-4
X-1,Y3,X4 X1,Y3,X-4
X0,Y4,X3 X0,Y4,X-3
X0,Y5,X3 X0,Y5,X-3
In a ROW list, the order of the die listed as the starting or ending die for each row is
unimportant. It is only important to use the correct die coordinates, identifying the two end
points. Their choice as the first or last die in a row is unimportant, since interchanging the
first and last die only implies direction.
Creating a Probe List
Assume we want to probe a wafer using to the pattern in figure 10-17, regardless of the
prober quadrant chosen. The pattern is serpentine beginning at the FIRST die and
proceeding left to right and right to left alternatively. This example assumes single die
probing. In multidie probing, probing proceeds several rows at a time and the PROBE list only
describes the touchdowns of probe0, the probe needle that the prober keys move from.
First die
Figure 10-17. Probe Pattern of a Wafer
The format of the PROBE list is exactly the same as the ROW list, except now the choice of
which die is the first die or last die in a row is important since this governs the direction the
probe needle takes along the wafer. The order, sequentially from top to bottom, of the rows
in the PROBE list determines the order the rows are probed.
The following are the probe lists to probe the wafer in the serpentine pattern shown in figure
10-17:
#Probe Quadrant 1 Probe Quadrant 2
PROBE PROBE
IMAGE Solutions V8.3 10-28
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
X0,Y0,X-3 X0,Y0,X3
X-3,Y-1,X0 X3,Y-1,X0
X1,Y-2,X-4 X-1,Y-2,X4
X-4,Y-3,X1 X4,Y-3,X-1
X0,Y-4,X-3 X0,Y-4,X3
X-3,Y-5,X0 X3,Y-5,X0
#Probe Quadrant 3 Probe Quadrant 4
PROBE PROBE
X0,Y0,X3 X0,Y0,X-3
X3,Y1,X0 X-3,Y1,X0
X-1,Y2,X4 X1,Y2,X-4
X4,Y3,X-1 X-4,Y3,X1
X0,Y4,X3 X0,Y4,X-3
X3,Y5,X0 X3,Y5,X0
NOTE
For multisite testing, be careful to step the prober so that at least one die out of all the sites
is a valid, testable die. IMAGE executes the test program, tests one part, and inserts an
extra part record in the STDF file. This die is subsequently inked, but the STDF file will
contain an extra part record.
Creating INK and SKIP Lists
Specify INK and SKIP lists in the same format as PROBE and ROW lists. This format allows
you to specify several consecutive dice in a row or individual die as ink or skip die. Skip and
ink dice are treated exactly alike in IMAGE, both are ultimately inked. Figure 10-18 identifies
various dice on a wafer as ink die (I) or skip die (S).
S I
I S
S I
I S
S I
This die specified I S
as (0,0)
Figure 10-18. Location of Skip and Ink Die
The following are the INK and SKIP lists for the dice in figure 10-18:
IMAGE Solutions V8.3 10-29
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
#Probe Quadrant 1 Probe Quadrant 2
INK SKIP INK SKIP
X0,Y0,X0 X-3,Y0,X-3 X0,Y0,X0 X3,Y0,X3
X-3,Y-1,X-3 X-1,Y-1,X-1 X3,Y-1,X3 X1,Y-1,X1
X-1,Y-2,X-1 X-4,Y-2,X-4 X-1,Y-2,X-1 X4,Y-2,X4
X-4,Y-3,X-4 X-1,Y-3,X-1 X4,Y-3,X4 X1,Y-3,X1
X0,Y-4,X0 X-3,Y-4,X-3 X0,Y-4,X0 X3,Y-4,X3
X-3,Y-5,X-3 X0,Y-5,X0 X3,Y-5,X3 X0,Y-5,X0
#Probe Quadrant 3 Probe Quadrant 4
INK SKIP INK SKIP
X0,Y0,X0 X3,Y0,X3 X0,Y0,X0 X-3,Y0,X-3
X3,Y1,X3 X1,Y1,X1 X-3,Y1,X-3 X-1,Y1,X-1
X-1,Y2,X-1 X4,Y2,X4 X1,Y2,X1 X-4,Y2,X-4
X4,Y3,X4 X1,Y3,X1 X-4,Y3,X-4 X-1,Y3,X-1
X0,Y4,X0 X3,Y4,X3 X0,Y4,X0 X-3,Y4,X-3
X3,Y5,X3 X0,Y5,X0 X-3,Y5,X-3 X0,Y5,X0
These lists show how you can designate single die as skip or ink die. The starting and
ending X-coordinates are the same. As previously mentioned, consecutive die can be
identified as skip or ink die in a single line. Simply use the X-coordinate of one of the die as
the starting X-coordinate and the last as the ending X-coordinate. Which die is designated
as the first or last is irrelevant since the direction does not matter in this case.
For example, assume that a row (Y15) has 30 die (die locations 0 and 29 are the opposite
ends of the row) and several groups of skip and ink die. Dice 0–4 are ink die, dice 13–15
and 20–22 are skip die, and dice 27–29 are ink die. The ROW, INK, SKIP, and PROBE lists for
this row would be as follows:
ROW
X0,Y15,X29
INK
X0,Y15,X4
X27,Y15,X29
SKIP
X13,Y15,X15
X20,Y15,X22
PROBE
X29,Y15,X0
This row will be probed from die position 29 to 0. Depending on the probe quadrant chosen,
this will be either left to right (probe quadrants 1 and 4) or right to left (probe quadrants 2
and 3). Although, some dice on this row are listed as skip and ink die, these die positions
will be touched by the probe needle. However, IMAGE will disable these sites and they will
not be tested. In multidie probing even though the master probe needle following the PROBE
list may not sit on a testable die, the other probe needles may touch down on valid and
testable die. Therefore, the master probe needle must touch down on these dice.
If you are not performing multisite probing, adjust the PROBE list so that ink or skip die are
not touched down upon since this constitutes unnecessary movement. The adjusted PROBE
list would be as follows:
IMAGE Solutions V8.3 10-30
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
PROBE
X26,Y15,X23
X19,Y15,X16
X12,Y15,X5
You must still include the skip or ink die in the INK and SKIP lists since these dice
(particularly the ink die) must be inked.
The wafer configuration file has been designed for Electroglas probers. Therefore, you can
transfer information in the wafer configuration directly to an Electroglas prober. Information
in the wafer configuration file may be incompatible with equipment from other vendors. To
use this file for another prober, you must be able to program the prober to follow a
consistent, predictable pattern over a wafer and to retrieve that information as part of the
setup. If this is the case, you can use the wafer configuration file to describe the pattern the
prober will take and initialize the wafer mapping software.
When using the set wafer statement with wafer mapping, this statement must appear in a
tl_init() function in the test program. In this way, IMAGE can construct its wafer map
before testing starts.
Defining the Wafer in the Test Program
To correctly set up the wafer mapping option, you must include the coordinates used to
describe the offsets of the probe needles in your test program. These coordinates must use
the prober’s coordinate system, not the standard X,Y coordinate system.
You include these coordinates using the set wafer statement. (See “Using the set wafer
Statement” on page 10-19.)
Referring to figure 10-16 on page 10-26, assume the following:
• X2 and X1 represent the actual locations of the probe needles.
• X2 represents probe0, the needle from which the other probe needle is keyed off.
(Probe0 is also the needle that will follow the PROBE list.)
The probe needle represented by X1 is two die locations below X2, in the Y direction, and
one die location to the right of X2 in the X direction. In the set wafer statement, the offset
specified for X2 is always (0,0), regardless of the probe quadrant chosen. However, the
value used for X1’s offsets changes between the different probe quadrants. In probe
quadrant1 X1’s offsets are (2,-1); for probe quadrant 2: (2, 1); in probe quadrant 3: (-2, 1);
and for probe quadrant 4: (-2,-1).
The set wafer statement only accepts two units, centimeters and inches. Unfortunately,
die sizes are more conveniently expressed in millimeters and mils. IMAGE ignores the value
entered for the wafer size field, for the dice. The wafer size units are assumed to relate to
the actual wafer itself. The units for the dice are listed as a parameter to the filter process
which generates the SECS wafer map from the STDF file.
Although the set wafer statement allows floating point numbers to be entered for the die
height (y) and die width (x), the SECS format expects them to be integer numbers. When
entering the numbers for the units, enter them in the form of XXX.0.
IMAGE Solutions V8.3 10-31
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
For example, if the die X dimension is 8.4 mils and the Y dimension is 12.8 mils, enter the
numbers as
set wafer:
die_height = 128 or (128.0)
die_width = 84 or (84.0)
;
When the SECS wafer map filter is invoked, it is invoked with the string 10^-1*mil to signify
that the unit of measure is in tenths of mils. The SECS wafer map filter and valid format
strings are discussed in “Generating the SECS Map” on page 10-35.
Setting Up the Prober
The handlerconf command includes several features to allow wafer mapping. These
features are supported using the RDP protocol and assume that the prober is connected to
tester by an RS232 interface. The RS232 interface can be used with the parallel interface
or alone.
Getting a Setup
RDP protocol supports block data transfers between the tester and prober. The
handlerconf -get_setup command allows you to transfer the prober’s current setup to a
file. To retrieve the setup from a prober and store it in a file called prober_setup.prober,
the command is:
handlerconf -get_setup prober_setup.prober
The information is automatically written to the directory
/image/tester/testername
In IMAGE V5.6 and later, you can use the -local switch to write the setup file to your
current working directory (the directory from which the command is initiated). The command
is:
handlerconf -get_setup -local prober_setup.prober
You can send this file later to the prober. Once the prober receives this information, it loads
the information into its memory and uses it as the current setup. Therefore, you need only
set up a prober manually once. You can save that setup and use it to automatically set up
the prober whenever a particular product must be tested.
When testing a new product, however, you must set the Z-height and reprofile the wafer.
Electroglas probers do not send this as part of the set up information.
You can include the setup file in a .load file, and the load command will automatically send
the name of the file to IMAGE.
Downloading a Setup
You can download a setup file to the prober by:
IMAGE Solutions V8.3 10-32
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
• Listing the file in the load command processor (in which case it must contain a .prober
extension)
• Using the handlerconf command
The command handlerconf -put_setup <filename> command searches for the named
file in:
/image/tester/testername
and downloads the file to the prober. Once the prober receives this file, it uses this
information as its current setup.
In IMAGE V5.6 and later, you can use the -local switch to write the setup file to your
current working directory (the directory from which the command is initiated). The command
is:
handlerconf -put_setup -local prober_setup.prober
You can issue this command at any time, once the tester is running. A test program need
not be loaded in the particular station. Note, however, that the last setup is the one that
takes effect. Issuing the -put_setup option overrides any current setups. Likewise, if the
prober setup file is listed in the .load file, it overrides any preexisting setups.
When using -get_setup and -put_setup, the directory where the files reside must have
appropriate read/write permission set to allow IMAGE to access the files.
Using the load Command to Connect to a Prober
The load command includes a switch, -handlerprober <name>, to allow you to connect a
particular prober and set it up. You must use this option either on the command line or
placed in a .load file. (See “Loading Using the load Command” on page 5-4.) This load
option is equivalent to invoking the command:
handlerconf -connect <name> -disable
The handcap file is first searched for name. If the name is found, the prober is connected
and initialized in software. You must later enable the prober using the handlerconf -
enable command.
As mentioned earlier, you can include the setup file in a .load file (see “Using .load Files to
Load Test Programs” on page 5-11). If the setup file is found at load time, its name is sent
to IMAGE. When you enable the wafer mapping option, the file is transferred to the prober.
For the load command to recognize a file as a valid prober setup file, it must end with the
.prober extension.
You can also include the wafer configuration file in a .load file. If the file is found at load
time, its name is also sent to IMAGE. When you enable the wafer mapping option, the wafer
mapping software initializes from this information. If no setup file is named in the .load file,
the information in the wafer configuration file is sent to the prober. Before you enable the
wafer mapping option, you must clear the prober’s current ROW list. If you do not clear the
list, information contained in the wafer configuration is appended to the current ROW list.
The following is a sample .load file for a test program named wafer.tl:
IMAGE Solutions V8.3 10-33
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
wafer.tl
3122.wafr
-autocal
-handlerprober eg2001
This file includes the wafer configuration file 3122.wafr and a switch that connects IMAGE
to the EG2001 prober (-handlerprober eg2001).
If the setup file named in the .load file is successfully transferred to the prober, the
information in the wafer configuration is not transferred to the prober. It is assumed that this
information is contained in the setup file. In this case, the ROW list is used only to initialize
the wafer mapping software.
Using the wafer configuration file may not be appropriate for all makes of probers. If,
however, the prober manufacturer adheres to the RDP standard, automatic prober setup
(either using the handlerconf -put_setup command or using a .load file and the
handlerconf -wafer_map command) will work correctly. For probers made by vendors
other that Electroglas, you may be able to manually set up the prober to follow the wafer
configuration and probe pattern contained in the wafer configuration file. Once you have
done this and saved the information in a setup file, you can use the wafer mapping software
successfully.
Enabling the Wafer Mapping Option
Enabling the wafer mapping software requires that you set up datalogging, set up the prober
correctly, and invoke the wafer software.
Setting Up Datalog
The SECS wafer map is generated from an STDF file. Before the prober is enabled, you
must be sure that datalogging is enabled. You must datalog all parts. You cannot use the
sample rate and limit options for data collection, since this writes a subset of part information
to the STDF file and, consequently, produces an incomplete wafer map.
Put all setup commands into a script file and execute the script to load the test program,
enable the wafer mapping function, and enable data collection. This helps assure that things
are set up properly.
Setting Up the Prober
Before you can enable the wafer mapping option, you must set up the prober correctly. You
may need to disable certain features or options since they may corrupt the wafer map.
Options which cause the prober to move the wafer in a way unanticipated by the wafer
mapping software cannot be enabled.
Invoking the Wafer Mapping
Once you load a test program, enable the wafer mapping option using either of the following
commands:
IMAGE Solutions V8.3 10-34
IMAGE Base Language: Wafer Mapping: Wafer Mapping for Off-Line Inking
Table of Contents Index Home Master Index Search Help
handlerconf -wafer_map -enable
handlerconf -wafer_map -disable
-enable causes the tester to start testing immediately. If you use -disable, testing does
not start until a handlerconf -enable command is issued. (See “Enabling and Disabling
Peripherals” on page 2-6 in the A500 Handler/Prober Manual.) Periodically, the tester polls
the prober for its current x,y location and compares it with its current coordinates. If an
mismatch occurs, an error is printed to the station window and the prober is automatically
disabled.
When you issue the handlerconf -wafer_map command, IMAGE tries to send the setup
file to the prober. If none is found, a warning is printed to the console. Next, the wafer
configuration file is read and the wafer map is initialized. If no setup file was sent to the
prober, the information in the wafer configuration file is sent to the prober.
Checking for X/Y Coordinates
You can also use the handlerconf command to set the frequency of checking for X/Y
coordinates. Use the command:
handlerconf -wafer_map -check_freq <device_count>
where device_count is the number of devices to refrain from polling. For example, the
command
handlerconf -wafer_map -check_freq 10
causes IMAGE to poll for X/Y coordinates every 10 devices. This eliminates the RS232
overhead associated with getting X/Y coordinates with every device.
Generating the SECS Map
A filter process called secs_map allows you to generate Electroglas compliant SECS wafer
maps. You can invoke this process from the command line, passing it the appropriate string
for units and the name of the STDF file. The data is output to a file whose name consists of
the wafer ID and the .secs extension. The syntax of the command is:
secs_map -stdf <filename> [-units "<unit_name>"]
The units parameter is optional. If it is not selected, the default unit is mil.
To generate a SECS wafer map, using mils for units, from an STDF file called wafer.stdf
the command line will look like:
secs_map -units "mil" -stdf wafer.stdf
Valid prefixes for the units include: 10^-1* (tenth), 10^-2 (hundredth), and 10^1* (tens). So
that if the resolution of the units is in hundredths of mils the string would be 10^-2*mil.
IMAGE Solutions V8.3 10-35
IMAGE Base Language: GPIB Programming
Table of Contents Index Home Master Index Search Help
11 GPIB PROGRAMMING
This section describes IMAGE programming for the General Purpose Interface Bus (GPIB).
It includes the following topics:
• “GPIB Overview” on page 11-2
• “The gpibcap File” on page 11-7
• “High-Level GPIB Programming” on page 11-10
• “Low-Level GPIB Programming” on page 11-15
• “Cabling and Configuration Issues” on page 11-18
IMAGE Solutions V8.3 11-1
IMAGE Base Language: GPIB Programming: GPIB Overview
Table of Contents Index Home Master Index Search Help
GPIB Overview
The GPIB consists of eight control lines and eight data lines. Instruments connected to the
GPIB share the bus. (See figure 11-1.)
HP 3458A
meter
TimeMaster High Speed Sampler Precision
Controller
Clock Auxiliary Clock Multimeter (PMM)
[address 0]
[address 1] [address 20] [address 22]
EOI
REN
GPIB SRQ
ATN
Control IFC
Lines NDAC
NRFD
DAV
GPIB
Data / Address
Lines
8
Figure 11-1. General Purpose Interface Bus Lines
The GPIB data/address lines carry three types of information:
• GPIB commands
• GPIB addresses
• Instrument commands and data
Each instrument on the bus can talk or listen for messages or ignore the bus, with the GPIB
driver regulating and managing the communications between instruments. Only one
instrument at a time can talk. The other instruments must either listen to the talker or ignore
the talker. In most cases, the GPIB controller is talking or listening to one or more
instruments. This is because the controller acts as the intermediary between your test
program and the GPIB.
GPIB Commands
The GPIB has a command set, listed in table 11-1. The GPIB driver gives you access to two
of these commands: Go to Local (GTL) and Selected Device Clear (SDC). The GPIB driver
manages the other commands; table 11-1 is provided for reference only.
IMAGE Solutions V8.3 11-2
IMAGE Base Language: GPIB Programming: GPIB Overview
Table of Contents Index Home Master Index Search Help
Table 11-1. GPIB Commands
Command Type Octal value GPIB command
Addressed Commands 001 Go To Local (GTL)
004 Selected Device Clear (SDC)
005 Parallel Poll Configure (PPC)
010 Group Execute Trigger (GET)
011 Take Control (TCT)
Universal Commands 021 Local Lockout (LLO)
024 Device Clear (DCL)
025 Parallel Poll Unconfigure (PPU)
030 Serial Poll Enable (SPE)
031 Serial Poll Disable (SPD)
077 Unlisten (UNL)
137 Untalk (UNT)
The Go to Local (GTL) command causes the currently addressed listeners to return to local
programming mode. The GPIB driver issues this command in response to the set
gpib...option: go_to_local statement (see “Setting Up the GPIB” on page 11-10).
The Selected Device Clear (SDC) command resets all the listeners. The reset state for each
listener is instrument dependent (refer to its user’s manual).
GPIB Addresses
The GPIB driver identifies each instrument on the bus (including the controller) using its
preset GPIB address. Instruments usually acquire a GPIB address at the factory, which can
be reset using an address switch, jumpers, or a control panel. (Refer to the instrument’s
user’s manual for an explanation of how to set its GPIB address.)
An instrument’s address is actually two addresses: a talk address and a listen address. If
an instrument detects its listen address on the GPIB, it begins listening for information on
the bus. If an instrument detects a talk address on the GPIB and has something to say, it
begins talking.
The high-level GPIB language eliminates talk and listen addresses and instead refers to
instruments using a single, decimal address. Table 11-2 lists the decimal GPIB addresses
along with the corresponding, low-level talk and listen address codes. The table also
identifies the addresses allocated to Teradyne instruments.
IMAGE Solutions V8.3 11-3
IMAGE Base Language: GPIB Programming: GPIB Overview
Table of Contents Index Home Master Index Search Help
Table 11-2. GPIB Addresses
High-Level Addresses Low-Level Addresses:
Instrument at That Address
(decimal) Listen / Talk (octal)
address 0 040 / 100 GPIB Controller
address 1 041 / 101 TimeMaster Clock
address 2 042 / 102
address 3 043 / 103
address 4 044 / 104
address 5 045 / 105
address 6 046 / 106
address 7 047 / 107
address 8 050 / 110
address 9 051 / 111
address 10 052 / 112
address 11 053 / 113
address 12 054 / 114
address 13 055 / 115
address 14 056 / 116
address 15 057 / 117
address 16 060 / 120
address 17 061 / 121
address 18 062 / 122
address 19 063 / 123
address 20 064 / 124 High Speed Sampler auxiliary
clock
address 21 065 / 125
address 22 066 / 126 Precision Multimeter (PMM)
address 23 067 / 127
address 24 070 / 130
address 25 071 / 131
IMAGE Solutions V8.3 11-4
IMAGE Base Language: GPIB Programming: GPIB Overview
Table of Contents Index Home Master Index Search Help
Table 11-2. GPIB Addresses (Continued)
High-Level Addresses Low-Level Addresses:
Instrument at That Address
(decimal) Listen / Talk (octal)
address 26 072 / 132
address 27 073 / 133
address 28 074 / 134
address 29 075 / 135
address 30 076 / 136
The GPIB has 31 available addresses, but it can support a maximum of only 19 instruments.
Four addresses are assigned to Teradyne instruments, leaving 15 GPIB addresses for other
instruments.
GPIB Control Lines
The GPIB driver uses the GPIB control lines to manage an orderly flow of information across
the bus. Although this control activity is transparent to the test system programmer, knowing
the function of these control lines provides a better understanding of some of the GPIB
programming statements and their parameters. They are summarized below:
ATN Attention. When this signal is true, signals on the GPIB data/
address lines are interpreted as either GPIB addresses or GPIB
commands. When this signal is false, signals on the GPIB data/
address lines are interpreted as data intended for listeners.
DAV Data Valid. When true, this signal indicates that the information
on the data/address lines is valid.
EOI End or Identify. When ATN is false and this signal is true, it
indicates the end of a transmission — that is, the current byte on
the data/address lines represents the last byte of the
command(s) or data.
IFC Interface Clear. When true, this signal halts bus
communications. Communications resume when IFC is false.
You can control whether IFC is asserted when resetting the
GPIB using a selection in the Miscellaneous options section of
IMAGE Properties. See “Miscellaneous Options” on page 3-36.
NDAC Data Not Accepted. Listeners use this line to indicate when they
have accepted (false) or have not accepted (true) the information
being transferred.
NRFD Not Ready For Data. Listeners use this line to indicate when they
are ready (false) or are not ready (true) to accept information.
IMAGE Solutions V8.3 11-5
IMAGE Base Language: GPIB Programming: GPIB Overview
Table of Contents Index Home Master Index Search Help
REN Remote Enable. When true, this signal places all listeners
capable of remote operation in remote programming mode.
When false, it returns all instruments to local programming
mode.
SRQ Service Request. Instruments use this line to request the
controller’s attention. Typically, this occurs when an instrument
has data ready to transmit or when it detects an error condition.
The control lines are active low — that is, the signal is true when its voltage is low (near 0
V), and the signal is false when its voltage is high (near 5 V).
IMAGE Solutions V8.3 11-6
IMAGE Base Language: GPIB Programming: The gpibcap File
Table of Contents Index Home Master Index Search Help
The gpibcap File
Once an instrument’s GPIB address is set, it is ready to respond to commands from the
GPIB driver. However, before the GPIB driver can send commands to instruments, it must
know what instruments are on the bus, their GPIB addresses, and their capabilities. It
derives this information from a global gpibcap file.
gpibcap File Location
Depending on how GPIB commands are used, the gpibcap file can be in one of several
places. If GPIB functions or commands are being used in the test program, IMAGE
searches in the following order:
• $HOME (of user loading the test program)
• /image/tester/<tester_computer_name>
• $IMAGEBIN/custom
Outside of a test program (in a handlerconf command for example) IMAGE only searches
in /image/tester/<name> and $IMAGEBIN/custom. The GPIB configuration in
$IMAGEBIN/custom applies to all workstations connected to the network.
If you plan to communicate with GPIB based material handling equipment from within the
test program and also through IMAGE, be careful that only one gpibcap is being used.
Otherwise, communication may be unsuccessful. IMAGE looks in /image/tester/
<tester_computer_name>, and the test program looks in the user’s home directory. If a
gpibcap file exists in both places, the two gpibcap files can contain different entries,
addresses or specifications for devices.
gpibcap File Syntax
A gpibcap file contains an entry for each instrument on the GPIB bus, including the name
of the instrument, its GPIB address, and its capabilities. Its syntax is:
# This is a comment
<instrument name>|[<comment>]:\
:addr=<GPIB address>:reset_code="[command(s)]":\
:[talker]:[listener]:[drivers=<open | tri>]:\
:[errbitmask=<mask>]:[moreinfo="<command>"]:
:[rterm="<terminator>"]:[tterm="<terminator>"]:
where:
# The pound sign is a comment symbol. It tells the GPIB driver that
what follows is a comment and can be ignored. For the driver to
recognize this symbol, it must be the first character on the line.
<instrument name#1>|...|<instrument name#N>|[<comment>]
<instrument name> is the software name for the instrument.
You can have multiple names for the same entry. The “|”
IMAGE Solutions V8.3 11-7
IMAGE Base Language: GPIB Programming: The gpibcap File
Table of Contents Index Home Master Index Search Help
separates individual instrument names from each other and from
their optional <comment> field, which typically is used to provide
a more descriptive name for the instrument. Spaces are not
allowed before the “|”.
For example, if you have a GPIB eg2001 and a GPIB KLA1201
on the same GPIB address, you can use the same entry with
eg2001 and KLA1201 as the instrument names.
KLA1201|eg2001|"eg and KLA address15":
: Colons act as field and line delimiters. Within an entry, every field
is separated by a colon; every line is terminated by a colon; and
every line (except for the first line) is preceded by a colon.
\ A backslash is a line continuation symbol. It allows you to
continue an entry to the next line by ignoring the carriage return
symbol after the backslash.
addr=<GPIB address>
This field specifies the instruments’s high-level GPIB address (in
decimal). Address 0 is reserved for the controller.
reset_code="[<command(s)>]"
This field allows you to send an instrument one or more
commands the first time it is referenced in your test program. If
no commands are specified (reset_code=""), the GPIB driver
automatically sends the GPIB command SDC.
talker Specifying talker gives the instrument talker capabilities. An
instrument must be able to talk to respond to serial polls of the
instrument and for error checking.
listener Specifying listener gives the instrument listener capabilities.
drivers=<open | tri>
drivers=open selects open collector drivers.
drivers=tri selects tri-state drivers, which allow for faster bus
transfers. (The default is open.)
errbitmask=<mask> The <mask> is ANDed with the result of the serial poll of the
instrument. If this results in a nonzero value, a run-time error is
issued followed by the value of <mask>. For error checking to
occur, the instrument must be able to talk (see talker above). If
this field is not specified, no error checking occurs. Also, no error
checking occurs unless you enable error checking using a set
gpib statement (see echeck in “Setting Up the GPIB” on page
11-10).
moreinfo="<command>"
This field extends the error message generated when an
instrument fails the errbitmask check. Some instruments have
commands for displaying additional error information. The
IMAGE Solutions V8.3 11-8
IMAGE Base Language: GPIB Programming: The gpibcap File
Table of Contents Index Home Master Index Search Help
moreinfo field allows you to issue one of these commands when
errbitmask detects an error.
rterm="<command>"
tterm="<command>" These fields are used with handlers and probers on the GPIB.
rterm specifies the terminator which marks the end of data for
data being transferred to the tester from the handler or prober.
tterm specifies the terminator to be appended to all messages
being sent to the handler or prober from the tester. See “Writing
a gpibcap File” on page 4-18 in the Handler/Prober Manual.
For example, here are some entries from a typical gpibcap file:
_______________________________________________________
#
# Master clock
master_clock|PTS 160MHz master clock:\
:addr=1:listener:reset_code="":\
:drivers=open:
#
# High Speed Sampler auxiliary clock
aux_clock|PTS 160MHz sampler clock:\
:addr=20:listener:reset_code="":\
:drivers=open:
#
# Entry for the Precision Multimeter
pmm|HP3458A meter:\
:addr=22:reset_code="PRESET NORM;OFORMAT DREAL":\
:talker:listener:drivers=tri:\
:errbitmask=32:moreinfo="ERRSTR?":
_______________________________________________________
Notes:
• At least one of the options, talker or listener, must be specified.
• The gpibcap file is reread after test system initialization. This includes when power is
cycled or the initialize command is issued.
• If an instrument has more than one GPIB address, the gpibcap file must contain
multiple entries for that instrument, one for each GPIB address.
• By default, error checking is disabled. To enable error checking, see the set gpib ...
echeck parameters in “Setting Up the GPIB” on page 11-10.
• The gpibcap file is similar to the handcap file that exists in the directory $IMAGEBIN/
custom. handcap informs the test system about the functionality of the various handlers
and probers. Using handlers and probers over the GPIB requires entries in the handcap
file. See “GPIB Handler/Prober Interface” on page 4-1 in the Handler/Prober Manual.
IMAGE Solutions V8.3 11-9
IMAGE Base Language: GPIB Programming: High-Level GPIB Programming
Table of Contents Index Home Master Index Search Help
High-Level GPIB Programming
IMAGE offers three high-level statements for programming the GPIB:
set gpib... ;
start gpib... ;
reset gpib;
Setting Up the GPIB
Use the set gpib statement to assign roles to each instrument on the bus. For instance,
this statement designates the talkers, the listeners, and the disinterested. It also sets an
instrument’s error checking mode (echeck). Finally, a special form of the set gpib
statement allows you to specify how long to wait for expected data before issuing a timeout
error. The syntax for the set gpib statement is:
set gpib instr= "<instrument name>"
addr= <GPIB address>
option: <option_selection>;
set gpib timeout= <integer>;
where:
instr= "<instrument name>"
Identifies the gpibcap file entry for this instrument.
addr= <GPIB address>
Identifies the instrument using its GPIB address. This allows
references to instruments not listed in the gpibcap file.
option: talk Designates the instrument as a talker. The bus only allows one
talker at a time. If you attempt to designate a second talker, the
first talker is disabled.
option: listen Designates the instrument as a listener.
option: clear Clears the bus and initializes the instrument. This leaves the
instrument disinterested — that is, it ignores all bus
communication.
option: echeck_send
Sets up error checking so that only information sent by the
instrument is checked for errors.
option: echeck_receive
Sets up error checking so that only information received by the
instrument is checked for errors.
option: echeck_both
Sets up error checking so that information both sent and
received is checked for errors.
IMAGE Solutions V8.3 11-10
IMAGE Base Language: GPIB Programming: High-Level GPIB Programming
Table of Contents Index Home Master Index Search Help
option: echeck_off
Turns error checking off.
option: go_to_local
Sends a Go To Local (GTL) GPIB command to the instrument.
timeout= <integer> Specifies, in seconds, how long to wait for a bus response before
generating a timeout. (The default is 7 seconds.)
Notes:
• If a test program is loaded that uses the set gpib instr=<instrument name> syntax,
IMAGE checks the gpibcap file for the entry. If the instrument has no entry in the
gpibcap file, the error message no current instrument definition appears.
IMAGE searches for the gpibcap file in the login directory, /image/tester/<tester
name>, and $IMAGEBIN/custom, in that order. IMAGE uses the first gpibcap file it finds
for all instrument definitions. The handler/prober software does not look in the user’s
directory for the gpibcap file.
• An instrument can be a talker or a listener, but not both.
• If you plan to have the controller communicate with a single instrument, you need not
designate the talker and the listener in a set gpib statement. (However, it is not an error
to do so.) In controller-to-instrument communications, the GPIB driver handles these
details for you when you initiate a transfer with a start gpib statement. The talk and
listen options are primarily for designating multiple listeners or instrument-to-
instrument communications.
• Error checking slows down bus transfers and is only recommended as a debugging tool.
• You can specify an echeck option only for an instrument listed in the gpibcap file.
Starting the GPIB
Use the start gpib statement to initiate the transfer of information on the GPIB bus. Its
syntax is:
start gpib instr= "<instrument name>"
addr= <GPIB address>
send=<pointer> size=<number bytes>
sendstr="<string>" [size=<number bytes>]
receive=<pointer> [size=<number bytes>]
receivestr=<array name> [size=<number bytes>]
serial_poll=<integer variable> ;
start gpib wait: srq [error=<integer variable>];
start gpib trigger;
where:
instr= "<instrument name>"
Identifies the gpibcap file entry for this instrument.
IMAGE Solutions V8.3 11-11
IMAGE Base Language: GPIB Programming: High-Level GPIB Programming
Table of Contents Index Home Master Index Search Help
addr= <GPIB address>
Identifies the instrument using its GPIB address. This allows
references to instruments not listed in the gpibcap file.
send=<pointer> Sends information stored at the pointer to the specified
instrument.
sendstr Sends the character string to the specified instrument.
receive=<pointer> Starts the transfer of information from the specified instrument to
the listener. The information is stored in memory beginning at
<pointer>.
receivestr Initiates the transfer of ASCII characters from the specified
instrument to the listener. The characters are stored in the
named array. This statement assumes that ASCII data is coming
over the bus. In this case, the GPIB driver terminates the transfer
when it detects the EOI control signal, the specified size limit, or
a CR-LF (carriage return-line feed) combination. After
terminating the transfer, it places the null character (\0) at the
end of the character string, replacing the CR-LF combination if
detected.
size=<number bytes>
Specifies the number of bytes to transfer. You can specify
<number bytes> directly as an integer value or indirectly using
the sizeof function, as in size=sizeof(double). For character
strings, you can specify <number bytes> directly as an integer
value or indirectly using the strlen function, as in size=
strlen(<array name>).
serial_poll=<integer variable>
Captures the result of a serial poll in the named integer
variable. Serial poll data is one byte and is stored in the least
significant byte of the integer variable. Use this option to check
the status of an instrument.
start gpib wait: srq
This statement forces the GPIB driver to wait for a Service
Request (SRQ) from one of the instruments. Use this statement
to synchronize the communications from different instruments.
error=<integer variable>
This option returns a zero into the named integer variable if
a timeout occurs while the GPIB driver is waiting for a Service
Request (SRQ). Otherwise, it returns a nonzero event code
indicating the wait was successful.
start gpib trigger;
This statement triggers all listeners.
Notes:
IMAGE Solutions V8.3 11-12
IMAGE Base Language: GPIB Programming: High-Level GPIB Programming
Table of Contents Index Home Master Index Search Help
• After the controller sends information to an instrument, it remains a talker and the
instrument remains a listener.
• After the controller receives information from an instrument, it remains a listener and the
instrument remains a talker.
• When a talker runs out of information to send to a listener, it sends an EOI control signal.
A listener stops receiving information when it detects the EOI control signal. However,
if you rely solely on EOI to terminate a transfer, you run the risk of runaway data
transfers—when the listener ceaselessly requests more data and the talker ceaselessly
sends it more data. Eventually, the system crashes leaving you with few clues as to why
it crashed. To avoid this problem, always specify the size parameter with start gpib
send and receive statements, even if you do not know the size of the transfer. In this
case, use the size parameter to set an upper limit for the transfer, so that the transfer
is guaranteed to terminate.
Resetting the GPIB
The reset gpib statement asserts the Interface Clear (IFC) control signal, re-initializes the
controller, and disables all talkers and listeners.
Asserting the IFC signal may, however, cause problems. Different GPIB communication
chips (and equipment) respond to IFC differently. Some devices and equipment continue to
operate properly, and others do not.
You can control whether IFC is asserted when resetting the GPIB. Use the selection in the
Miscellaneous options section of IMAGE Properties. See “Miscellaneous Options” on page
3-36. If you select this property, the reset function will not issue IFC except at IMAGE
startup.
Programming Examples
The instrument in these examples is the HP3458A multimeter, which is part of the Precision
Multimeter (PMM) subsystem. (See the PMM section in the instrumentation manual for your
tester.) The commands sent to the HP3458A over the GPIB are HPML (Hewlett-Packard
Multimeter Language) commands. (These commands are described in the HP3458A
Multimeter: Operating, Programming, and Configuration Manual.) The examples assume
that you have already created an entry for the PMM in the gpibcap file (see “The gpibcap
File” on page 11-7).
• Send the PMM an nplc (Number of Power Line Cycles) command.
start gpib instr="pmm" sendstr="nplc 2";
(This statement automatically designates the controller as talker and the PMM as
listener.)
• Designate the PMM and two other instruments as listeners. Then trigger all listeners:
set gpib addr=3 option:listen;
set gpib addr=10 option:listen;
set gpib instr="pmm" option:listen;
IMAGE Solutions V8.3 11-13
IMAGE Base Language: GPIB Programming: High-Level GPIB Programming
Table of Contents Index Home Master Index Search Help
start gpib trigger;
• Serial poll the PMM and place the result in sp:
int sp;
start gpib instr="pmm" serial_poll = sp;
• Trigger the PMM to take a reading (trig sgl command). Return the reading to variable
value. Then display the reading:
double value;
start gpib instr="pmm" sendstr="trig sgl";
start gpib instr="pmm" receive=&value
size=sizeof(double);
printf("result is %e\n",value);
IMAGE Solutions V8.3 11-14
IMAGE Base Language: GPIB Programming: Low-Level GPIB Programming
Table of Contents Index Home Master Index Search Help
Low-Level GPIB Programming
Releases of IMAGE before V2.6 require use of low-level GPIB function calls to program
instruments on the GPIB. Current versions of IMAGE use high-level gpib statements,
making these low-level function calls unnecessary.
Low-Level GPIB Syntax
If you encounter low-level GPIB function calls in an old test program, here are descriptions
for them. Otherwise, you can ignore this information.
tl_ibrd(pointer,size)
Reads size bytes from a GPIB talker into the buffer at pointer.
The transfer terminates when size bytes is received, or when
the function detects a CR-LF (carriage return-line feed)
combination, or when an EOI control signal is detected. This
function requires that the controller be a listener.
tl_ibrd_eoi(pointer,size)
Same as tl_ibrd, except a CR-LF combination cannot
terminate the transfer.
tl_ibwrt(pointer,size)
Writes size bytes from the memory buffer at pointer to all
listeners. Requires that the controller be a listener.
tl_ibcmd(pointer,size)
Sends to a listener size bytes of GPIB commands and/or GPIB
addresses stored in a buffer beginning at pointer (see tables
11-1 on page 11-3 and 11-2 on page 11-4).
tl_ibwait(srq) Waits for a Service Request (srq) signal from an instrument on
the bus.
tl_ibsic() Asserts an Interface Clear (IFC) signal for 100 µs. This must be
called before the first tl_ibcmd call.
tl_ibsre(0) Clears all remote instruments and causes them to go local.
tl_ibgts() Puts the controller in standby state (ATN signal high).
tl_ibcac() Puts the controller in active state (ATN signal low).
tl_ibonl(flag) Initializes the GPIB controller and leaves it off-line if the flag is
0, or on-line if it is 1.
tl_ibcmd2(pointer) A shorthand version of tl_ibcmd(), which expects a pointer to
a null (/0) terminated string of ASCII data.
tl_ibwrt2(pointer) A shorthand version of tl_ibwrt(), which expects a pointer to
a null terminated string of ASCII data.
IMAGE Solutions V8.3 11-15
IMAGE Base Language: GPIB Programming: Low-Level GPIB Programming
Table of Contents Index Home Master Index Search Help
Converting to the High-Level Language
The following examples demonstrate how to convert low-level GPIB function calls to the
high-level GPIB statements.
Send HPML Command to Meter
Low-level approach: Set the controller to talk (talk address is 100) and set the Precision
Multimeter (PMM) to listen (listen address is 066). Then send an HPML command (preset
norm) to the PMM.
/* Set controller to talk, meter to listen */
tl_ibcmd2("\100\066");
/* send "preset norm" command to meter */
tl_ibwrt2("preset norm");
High-level equivalent:
start gpib instr="pmm" sendstr="preset norm";
Trigger the Meter to Take a Reading
Low-level approach: Set the PMM to listen (listen address is 066) and send it a Group
Execute Trigger (GET code is 010), which triggers it to take a reading.
/* Set PMM to listen, send GET command */
tl_ibcmd2("\066\010");
High-level equivalent:
set gpib instr="pmm" option:listen;
start gpib trigger;
Request and Receive Single-Precision Result From Meter
Low-level approach: Set the controller to talk and set the PMM to listen. Inform PMM that
its output should be a single precision number. Send it a Group Execute Trigger. For the
PMM to return its reading, make it a talker and the controller a listener. Receive 8 bytes from
PMM and store it in a variable. The PMM reading is in the lower 4 bytes of the variable.
double val; /* variable to store PMM reading */
tl_ibcmd2("\100\066"); /* controller talk, meter listen */
tl_ibwrt2("oformat sreal"); /* tell meter to output result */
/* as single precision real number */
tl_ibcmd2("\010"); /* trigger the meter */
tl_ibcmd2("\040\126"); /* controller listen, meter talk */
tl_ibrd(&val,8); /* receive and store 8 bytes */
High-level equivalent: By default, the PMM outputs its readings as single-precision real
numbers. (The reset_code field in the gpibcap example in “The gpibcap File” on page 11-7
illustrates how to output readings as double-precision real numbers.)
IMAGE Solutions V8.3 11-16
IMAGE Base Language: GPIB Programming: Low-Level GPIB Programming
Table of Contents Index Home Master Index Search Help
float val;
set gpib instr="pmm" option:listen;
start gpib trigger;
start gpib instr="pmm" receive = &val size=4;
IMAGE Solutions V8.3 11-17
IMAGE Base Language: GPIB Programming: Cabling and Configuration Issues
Table of Contents Index Home Master Index Search Help
Cabling and Configuration Issues
The GPIB requires strict adherence to the following cable length and configuration
specifications:
• The total number of instruments on the GPIB cannot exceed 15.
• The cable distance between instruments (in meters) cannot be more than twice the
number of instruments and cannot exceed 20 meters overall.
Based on experience, connecting instruments in a daisy-chain arrangement seems to work
best, with the incoming signal line being stacked closest to the instrument.
Also, avoid cycling power of instruments on the bus while the bus is in operation. This may
cause faulty transfers.
Finally, you can have one-third of the instruments powered off without affecting the GPIB’s
operation. More than that may cause faulty transfers or an error message such as error #41,
“GPIB timeout”. See the IMAGE Quick Help runtime error list for more information about
error #41.
IMAGE Solutions V8.3 11-18
IMAGE Base Language: Simulator
Table of Contents Index Home Master Index Search Help
12 SIMULATOR
IMAGE includes software simulation of the tester hardware, allowing you to develop, run,
and debug test programs on a stand-alone workstation. To maintain a consistent work
environment, IMAGE does not change its behavior when running the simulator.
This section icludes the following topics:
• “Customizing Simulation” on page 12-2
• “Creating and Maintaining a Simulator DataBase File” on page 12-4
Invoking the simulator requires no special commands or procedures. When IMAGE is
invoked, it reads the contents of a file named confsim to determine the type of tester to
simulate (such as Advanced Mixed-Signal, Catalyst, or Catalyst Tiger) and its hardware
configuration. confsim files are located in the $IMAGEBIN/custom directory. For an
explanation of the confsim file, see “Configuring IMAGE” on page 4-1.
From this point on, the simulator imitates the functions of the hardware in its hypothetical
test system. You can extend the simulation using a Simulator DataBase file (see
“Customizing Simulation” on page 12-2).
IMAGE also includes a digital simulator (DSim) that detects timing violations in digital
patterns which the digital hardware cannot detect. These violations may result in a tester
rejecting good devices and passing faulty ones. (See “Digital Subsystem Simulator” on page
3-1 in the IMAGE Software Tools Manual.)
IMAGE Solutions V8.3 12-1
IMAGE Base Language: Simulator: Customizing Simulation
Table of Contents Index Home Master Index Search Help
Customizing Simulation
Executing a statement such as dc_result=read_meter() on a standalone workstation
does not fail because the simulator intercepts the read_meter call and returns a default
value, usually 0.0. To make hardware simulation more realistic, you can replace default
values with your test values by specifying test values in a special file called a Simulator
DataBase file.
Any time a test function in a test program requires data from an instrument, the simulator
responds by searching the current directory for the following files in the following order:
<program>_<site>.sdb
<program>.sdb
where:
program Is the name of the test program.
site Is a test site in a multisite test program (0–7). (See “Using
Simulator Database Files in Multisite Test” on page 12-8.)
.sdb Simulator DataBase file extension.
If it finds one of these files, it searches through the list of records in the file for a record
having the same name or number as the test function. For example, if the test function is
named vilpp, the simulator looks for a record named test vilpp.
If it finds this record, it then searches the record for the name of the instrument it requires
data from. For example, if the vilpp test function is trying to take a measurement with the
dc voltmeter, the simulator would search its test vilpp record for the word dcmeter.
If it finds an entry for the instrument, it takes the value assigned to that instrument and
returns it to the test program in place of the simulator’s default value. For example, a typical
record for the vilpp test function might look like this:
test vilpp
dcmeter = 2.34volts
acmeter = 1086mvolts
acmeter = 1221mvolts
;
The first read_meter() function call in vilpp would return 2.34 for the dcmeter reading and
would return 1.086E-3 for the acmeter reading. The second read_meter() function call of
the acmeter would return 1.221E-3. Further calls to read_meter() return the last reading
in the entry list (1.221E-3). The relevant debug displays would also show the simulated test
result.
Table 12-1 lists instruments that can be included in a Simulator DataBase file.
IMAGE Solutions V8.3 12-2
IMAGE Base Language: Simulator: Customizing Simulation
Table of Contents Index Home Master Index Search Help
Table 12-1. Simulator DataBase Instrument Names
System Type Instrument
Catalyst Tiger aapu (Advanced Analog Pin Unit)
dcmeter (DC voltmeter)
dig_cap (Digital Signal Capture Memory)
meter (any dc meter front end
ppmu (HSD Per Pin Parametric Unit)
Advanced Mixed-Signal, apu (Analog Pin Unit)
Catalyst
dcmeter (DC voltmeter)
dig_cap (Digital Signal Capture Memory)
hfdig (High Frequency Digitizer)
meter (any dc meter front end)
plfdig (Precision Low Frequency Digitizer)
pmm (Precision Multimeter)
tms (Advanced Time Measurement Subsystem)
ppmu (HSD50 Per Pin Parametric Unit)
Mixed-Signal apu (Analog Pin Unit)
dcmeter (DC voltmeter)
dig_cap (digital signal capture memory)
hfdig (High Frequency Digitizer)
lfdig (Low Frequency Digitizer)
meter (any dc meter front end)
pmm (Precision Multimeter)
tms (Time Measurement Subsystem)
IMAGE Solutions V8.3 12-3
IMAGE Base Language: Simulator: Creating and Maintaining a Simulator DataBase File
Table of Contents Index Home Master Index Search Help
Creating and Maintaining a Simulator DataBase File
A Simulator DataBase file is an ordinary text file you can create and edit with any ASCII text
editor. IMAGE also includes a Simulator DataBase editor, named simdbase, for editing and
debugging Simulator DataBase files. simdbase is a text editor that includes a built-in syntax
checker.
To invoke simdbase, press MENU on the DISPLAY button in the test station window and
select PROGRAM DEBUG>SIMULATOR DATABASE from the menu. You can also invoke
simdbase by entering the following command:
simdbase [-station #]
where:
-station # Test station window from which to start simdbase.
IMAGE responds by searching for a Simulator DataBase file with the same root name as
the test program it loaded in the test station (<program>.sdb). If it finds a Simulator
DataBase file, it brings up the simdbase window and loads it with the contents of the file.
Figure 12-1 shows a simdbase window loaded with the contents of verify.sdb. The test
program loaded at this test station is verify.tl.
Figure 12-1. simdbase Text Editor
NOTE
simdbase does not display site-specific .sdb files. See “Using Simulator Database Files in
Multisite Test” on page 12-8.
IMAGE Solutions V8.3 12-4
IMAGE Base Language: Simulator: Creating and Maintaining a Simulator DataBase File
Table of Contents Index Home Master Index Search Help
The simdbase syntax checker is automatically invoked when you try to save the edited file
by selecting FILE>SAVE. If it detects a syntax error, it aborts saving the file, displays an error
message indicating the line on which the error was detected, highlights that line, and returns
simdbase to text edit mode. To save a Simulator DataBase file with syntax errors, select
SIMDBASE>SAVE AND QUIT.
When the test program calls a function which performs more than one meter strobe, like
read_meter_n(), the simulator reads one entry from the simulator database. That value is
presumed to be the averaged reading, which is returned to the test program.
Simulator DataBase Syntax
A Simulator DataBase file contains a series of DataBase records. Each DataBase record
begins with the keyword test, ends with a semicolon, and is defined as follows:
# This is a comment
test <test identifier> [repeat]
<instrument> = <measurement> | "<waveform file>"
<instrument> = <measurement> | "<waveform file>"
<instrument> = <measurement> | "<waveform file>"
... ;
where:
# Indicates the beginning of a comment. The simulator ignores all
characters between # and the end of the line.
<test identifier> Is <test name> | <test number> | NONE
<test name> Is a test function name. In a test program, test functions are
preceded by the keyword TESTF, as in:
TESTF contin() { ...}
<test number> Is the test function number, as specified in a test program
sequencer statement. For example, in the sequencer statement
seq contin() $3 >0.4v <4.0v "continuity" f(2);
the <test number> is 3.
NONE Is for instrument measurements made outside of any test
function.
repeat Is short for “repeat from the top of the record,” which means that
every time the test is called, the simulator returns test results
beginning with the first test result in the Simulator DataBase
record.
<instrument> = <measurement>
Assigns a measurement to one of the instruments listed in table
12-1 on page 12-3. <measurement> can be any valid IMAGE
constant, such as 6.343volts, 104mv, or 9.86ma.
IMAGE Solutions V8.3 12-5
IMAGE Base Language: Simulator: Creating and Maintaining a Simulator DataBase File
Table of Contents Index Home Master Index Search Help
<instrument> = "<waveform file>"
Assigns the contents of the specified waveform file to one of the
following instruments: lf_dig, hfdig, dig_cap, c_mem, wdig, or
plfdig. Then, whenever a test program requests data from this
instrument during a simulation, the simulator substitutes the
contents of the named waveform file. The file can contain
waveform data in ASCII or binary waveform format. The name of
the file must be enclosed in quotes.
Simulator DataBase records are in free format, meaning all whitespace is ignored. A single
line in a Simulator DataBase file should not exceed 256 characters.
Examples
Test function:
TESTF special_bias()
{
tms_result = read_tms() ;
dc_result = read_meter() ;
}
Simulator DataBase record:
test special_bias
tms= 15.33us
dcmeter= -10.555V ;
When read_tms is called, read_tms returns 15.33us to tms_result. When read_meter is
called, read_meter returns -10.555V to dc_result.
Calling a Test Multiple Times
Test function:
TESTF vm()
{
result1 = read_meter() ;
result2 = read_meter() ;
result3 = read_meter() ;
}
By default, when more than one measurement is made with the same instrument within the
same test function, the simulator returns measurement results in the order listed in its
Simulator DataBase record. In the next call to the test function, the simulator continues
where it left off and returns the next measurement results in the list. When the simulator
reaches the end of the list, it continues returning the last measurement in the list. For
example:
test vm
meter = 1.2V
meter = 1.8V
IMAGE Solutions V8.3 12-6
IMAGE Base Language: Simulator: Creating and Maintaining a Simulator DataBase File
Table of Contents Index Home Master Index Search Help
meter = 2.0V
meter = 2.2V
meter = 2.4V ;
On the first call to vm, read_meter returns 1.2, 1.8, and 2.0. On the next call to vm,
read_meter returns 2.2, 2.4, and 2.4.
Specifying repeat in a Simulator DataBase record forces the simulator to always begin with
the first measurement value in the record when the test function is called. For example:
test vm repeat
meter = 1.2V
meter = 1.8V
meter = 2.0V
meter = 2.2V
meter = 2.4V ;
On the first call to vm, read_meter returns 1.2, 1.8, and 2.0. On the next call to vm,
read_meter returns 1.2, 1.8, and 2.0.
Calling a Test From A Compound Sequencer Statement
When a test function is called from a compound sequencer statement, the current test
number changes after each test is executed. In this case, the simulator uses a slightly
different search strategy. It first searches the Simulator DataBase file for the current test
number, then searches for the test name or initial test number.
For example, suppose you are testing a quad part and have the following sequencer
statement in your test program:
seq vilpp() { $60
< 2ma f(0);
< 2ma f(0);
< 2ma f(0);
< 2ma f(0);
}
To test program flow, you want the reading for the second test (test 61) to cause the test
to fail by returning 2.1mA and the other tests to pass. These two Simulator DataBase
records would produce that effect:
test 61
dcmeter = 2.1ma ;
test vilpp
dcmeter = 1.9ma ;
You could achieve the same effect using the initial test number (60) in place of the test
name:
test 61
dcmeter= 2.1ma ;
test 60
dcmeter= 1.9ma ;
IMAGE Solutions V8.3 12-7
IMAGE Base Language: Simulator: Creating and Maintaining a Simulator DataBase File
Table of Contents Index Home Master Index Search Help
When a Test is in a Loop
When a test function is in a program loop, a single instrument measurement is performed
multiple times. In this case, you can specify a different measurement value for each iteration
of the test by listing multiple instrument measurements in the DataBase record for that test.
For example, if the test function special_bias were called four separate times within a
loop, you could supply the test with four different dcmeter measurements by adding the
following record to a Simulator DataBase file:
test special_bias
dcmeter= -10.555V
dcmeter= -10.554V
dcmeter= -10.552V
dcmeter= -10.550V ;
The first iteration of special_bias, the dcmeter would return a measurement of -10.555V.
The second iteration it would return -10.554V and so on.
When a Test Calls Other Functions
For a given test function, the simulator can extract a measurement from the Simulator
DataBase file for any measurement made within that test function or within any function
called by that test function, no matter how deep the function calls are nested. For
example, in the following nested functions, the read_meter function returns a dcmeter
measurement from the Simulator DataBase file even though the measurement is made
within a subfunction.
TESTF vilpp()
{
double test_result;
test_result=sub_function();
test test_result;
}
double sub_function()
{
double measurement;
measurement= read_meter();
return measurement;
}
Using Simulator Database Files in Multisite Test
You can use simulator DataBase file with single-site test programs or with multisite
programs. The principle of using instrument values from the file in the test program is the
same in both cases. The difference is that, in a multisite program, each site requires a value.
One way to approach supply values for multiple sites is to write one .sdb file that supplies
values for all sites. For example, a multisite test program for two sites, dualsite.tl,
contains the following function:
IMAGE Solutions V8.3 12-8
IMAGE Base Language: Simulator: Creating and Maintaining a Simulator DataBase File
Table of Contents Index Home Master Index Search Help
TESTF vout5() /* spec: Vin =20v, i load = 5ma */
{
double vout5[2];
int x=0;
set pin= vin src:
vrng= 50v
v= 20.0v;
wait 10ms;
serial
{
set meter input:pin= vout src:v;
vout5[x]=read_meter();
test vout5[x++];
}
}
In the file dualsite.sdb, a Simulator DataBase record for this function might be as follows:
test vout5
dcmeter= 4.96
dcmeter= 4.99;
This file provides a dc meter reading value for each of the two sites in the test program for
this function.
The problem with this approach is that this .sdb file is hard to use during debugging. The
values for each instrument reading must be placed in the order in which the test program
reads them, site by site and read by read. This requires that you understand the test
program flow with regard to sites. Furthermore, this flow changes if the instrument values
are modified to simulate the behavior when a site fails.
A better solution is to use site-specific .sdb files. In IMAGE V5.7 and later, the simulator
reads .sdb files on a per-site basis, if such files exist. Therefore, you can create a .sdb file
with values for each site.
When a test program reads an instrument, the IMAGE simulator tries to open a file named:
<program>_<site>.sdb
where <site> is a site number from 0 to 7.
For example, our example test program dualsite.tl executing on site 1 would cause the
simulator to first look for a file named dualsite_1.sdb. If this file exists, the simulator
returns the instrument value specified in it. If this file does not exist, the IMAGE simulator
tries to open a file named:
<program>.sdb
(dualsite.sdb, in our example). If this file exists, the simulator returns the instrument value
specified in it. If this file does not exist, the simulator returns 0.
Using this method with the example above, the record for site 1 would be:
IMAGE Solutions V8.3 12-9
IMAGE Base Language: Simulator: Creating and Maintaining a Simulator DataBase File
Table of Contents Index Home Master Index Search Help
test vout5
dcmeter= 4.96;
The record for site 2 (in a separate file) would be:
test vout5
dcmeter= 4.99;
This feature makes .sdb files easy to use when debugging multisite test programs. Single
site test programs are not affected.
The simdbase editing window does not use site numbers. It only displays <program>.sdb
files, not <program>_<site>.sdb files. You must use a text editor (such as textedit, vi,
or emacs) to modify site-specific .sdb files.
Simulating Capture Memory Data
You can also use a Simulator DataBase file to simulate capture memory in Advanced
Mixed-Signal, Catalyst, and Catalyst Tiger testers. Do this as follows:
1. Create an array of waveform values and move them to a waveform file. For example:
move
adata= array size= <SAMPLE_SIZE>
to:
file= sim.wave
cap_sz= <SAMPLE_SIZE>
smpl_freq= <SAMPLE_FREQUENCY> ;
2. In your Simulator DataBase file, assign the waveform file to capture memory. For
example:
test NONE c_mem="sim.wave" ;
In this example, NONE implies that the capture memory operations are outside test
functions (TESTF).
3. Now you can simulate capture memory operations using the data in sim.wave. For
example:
set dsp create= (int_bh1)
type: integer
buf: temp
size= <SAMPLE_SIZE>;
move dig_cap:
offset= 0
size= <SAMPLE_SIZE>
to: dsp_data= int_bh1;
When the move dig_cap statement is executed, the simulator moves the data in the file
sim.wave to the DSP buffer named int_bh1.
The simulator automatically converts waveform file data to the format appropriate to the
calling statement or function.
IMAGE Solutions V8.3 12-10
IMAGE Base Language: Simulator: Creating and Maintaining a Simulator DataBase File
Table of Contents Index Home Master Index Search Help
If, instead of a waveform file, a single floating-point number is assigned to c_mem, the
simulator uses that value for every c_mem location. For instance, if the Simulator DataBase
record in the last example was entered as:
test NONE c_mem = 99;
the simulator would move 99 into every storage location in int_bh1.
If the simulator cannot find a Simulator DataBase file or an entry in a Simulator DataBase
file, it searches the current directory for a file named simwavedata.wav and substitutes data
in this file for capture memory. The simwavedata.wav file offers a second way to simulate
capture memory.
IMAGE Solutions V8.3 12-11
IMAGE Base Language: IMAGE Test Language Overview
Table of Contents Index Home Master Index Search Help
13 IMAGE TEST LANGUAGE OVERVIEW
The programming language for Catalyst test systems is called the IMAGE Test Language
(ITL). ITL is a superset of the “C” programming language. ITL supports the entire C
programming language as well as a set of enhancements designed for ATE. (IMAGE
operating under Solaris 2 uses ANSI C.) Specific testing-oriented functions and statements
have been added to help create device test programs. In addition, ITL provides pin-oriented
language statements for controlling Catalyst instrumentation.
C is a general-purpose programming language that allows you to write modular well-
structured programs using a rich set of data types, operators, and high-level statements. In
addition, it allows you to easily manipulate data and bits at a low level. It is a fully compiled
language that produces efficient object code for fast execution speed.
Using ATE-specific sequencer and test functions, ITL provides a framework that makes it
easy to create, debug, and maintain device test programs. The test list, pass/fail conditions,
and binning strategy are all specified in one place—a specialized function called the
sequencer. The sequencer, in turn, calls test functions to perform each test.
ITL is a pin-oriented programming language. In a pinmap at the beginning of each program,
you assign a specific tester channel to a specific device pin and indicate the hardware
resources available to each pin on the assigned channel. This assignment can include
giving a device pin a name indicative of its function. Thereafter, you can refer to device pin
names in your program and gain access to the resources assigned to each pin, rather than
having to refer to the resources by tester channel numbers or instrument names. Each type
of hardware resource has a customized set of high-level language statements used to
program it.
This section describes the base programming language portion of ITL. Language specific
to test system instruments is described in the Catalyst Instrumentation Manual, and the
Catalyst Tiger Instrumentation Manual.
This section includes the following topics:
• “Parts of a Test Program” on page 13-2
• “IMAGE Test Language Basics” on page 13-6
• “Variables and Operators” on page 13-11
• “Flow Control Statements” on page 13-19
• “Arrays and Other Data Structures” on page 13-24
• “Updating Test Programs Written Before Solaris 2” on page 13-29
IMAGE Solutions V8.3 13-1
IMAGE Base Language: IMAGE Test Language Overview: Parts of a Test Program
Table of Contents Index Home Master Index Search Help
Parts of a Test Program
An ITL test program is composed of several distinct sections of source code in one or more
source files with the extension .tl. Figure 13-1 is an overview of the major sections of an
ITL program. It shows you how a program is structured and what a test program looks like.
(“Test Program Structure” on page 14-1 describes the sections of an ITL program in detail.)
IMAGE Solutions V8.3 13-2
IMAGE Base Language: IMAGE Test Language Overview: Parts of a Test Program
Table of Contents Index Home Master Index Search Help
Header
#include <stdio.h> /*standard I/O header*/
#include <math.h> /*standard math functions*/
#include <image.h> /*standard IMAGE header*/
#define VMASK 0077 /*macro definition*/
#define SPECTRUM_SIZE 512
float spectrum[SPECTRUM_SIZE]; /*define a global array*/
int myflag = 0; /*define a global flag var*/
pinmap = {
/*DUT pin number pin name channel resource*/
1 "VIN" dc_matrix:1 (src:1),
2 "VOUT" dc_matrix:2,
dib "DIB" dc_matrix:3 (src:2),
24 "VCC" dutsrc:1,
};
Main Program—Beginning of executable code
main()
{ /*beginning of main*/
seq1(); /*execute the sequencer seq1 and assign bin_number*/
sort bin; /*sort the bin number result*/
} /*end of main*/
SEQUENCER Function
SEQUENCER seq1()
{ /*beginning of sequencer*/
/*
test function test test limits test binning
name # low/high label f/p */
seq contin() $1 >0 <.7v "continuity" f(0);
seq icc() $2 >20ma <25ma "supply i" f(2);
seq ac() $3 >1.55v <1.62v "amplitude" f(3) p(1);
} /*end of sequencer*/
TEST Function
TESTF icc()
{ /*beginning of testf*/
double supply_i; /*declare local variable*/
set pin=vcc dutsrc:v=5.125v; /*set up dc source*/
set meter input:pin=vcc dutsrc:i; /*set up dc meter*/
set power on: dc; /*turn power on*/
wait 10ms; /*wait for device to settle*/
supply_i=read_meter(); /*read dc voltmeter*/
test supply_i; /*test the result against limits*/
} /*end of testf*/
Figure 13-1. Structure of an ITL Program
IMAGE Solutions V8.3 13-3
IMAGE Base Language: IMAGE Test Language Overview: Parts of a Test Program
Table of Contents Index Home Master Index Search Help
Header Section
A typical ITL test program begins with a header section containing file #include directives,
macro definitions, external variable declarations, and global variable definitions. Here is a
sample header section:
#include <stdio.h> /*standard I/O header (required)*/
#include <math.h> /*standard math functions (required)*/
#include <image.h> /*standard IMAGE header (required)*/
#define VMASK 0077 /*macro definition (optional)*/
#define SPECTRUM_SIZE 512
float spectrum[SPECTRUM_SIZE];/*define a global array*/
int myflag = 0; /*define a global flag variable (optional)*/
pinmap = {
/*DUT pin number pin name channel resource*/
1 "VIN" dc_matrix:1 (src:1),
2 "VOUT" dc_matrix:2,
dib "DIB" dc_matrix:3 (src:2),
24 "VCC" dutsrc:1,
};
Pinmap
The sample header above also includes a pinmap. The pinmap is a special section that
describes the mapping between tester channels and device pins, including the test system
resources available behind each pin. You specify the pinmap once based on how your
device connects to tester channels. From then on, you program using device pin names.
Pinmaps are explained in the instrument manual appropriate for your tester.
Tester resources in a test program can also be assigned using DIBView. See “DIBView” on
page 2-1 in the IMAGE Software Tools Manual.
main() Function
The main() function is the highest level function of a test program; it is where execution
begins each time the program is run. In the following main function, a sequencer function is
called which returns a bin number. This bin number is used to sort the device using a sort
bin statement.
main()
{ /*beginning of main*/
seq1(); /*execute the sequencer seq1 and assign bin number*/
sort bin; /*sort the bin number result*/
} /*end of main*/
IMAGE Solutions V8.3 13-4
IMAGE Base Language: IMAGE Test Language Overview: Parts of a Test Program
Table of Contents Index Home Master Index Search Help
Sequencer Function
A sequencer function is like test program table of contents. In a sequencer function you
string together sequencer statements and, by doing so, list all tests to be performed in order
of execution. For each test, all limits, datalog formatting information, and binning information
is presented in a tabular, readable form, resembling a specification sheet. A test program
usually has one or more sequencer functions such as the following:
SEQUENCER seq1()
{ /*beginning of sequencer*/
/* test function test test limits test binning
name # low/high label fail/pass*/
seq contin() $1 >0 <.7v "continuity" f(0);
seq icc() $2 >20ma <25ma "supply i" f(2);
seq ac() $3 >1.55v <1.62v "amplitude" f(3) p(1);
} /*end of sequencer*/
Test Function
The test function is where you set up test system hardware to provide forcing functions or
take measurements. A test function includes one or more test statements that it calls to
determine pass or fail on one or more test results. A test program usually has many test
functions similar to the following which correspond to the tests to be performed.
TESTF icc()
{ /*beginning of TESTF*/
double supply_i; /*declare local variable*/
set pin=vcc dutsrc:v=5.125v; /*set up dc source*/
set meter input: pin=vcc dutsrc:i; /*set up dc meter*/
set power on: dc; /*turn power on*/
wait 10ms; /*wait for device to settle*/
supply_i=read_meter(); /*read dc voltmeter*/
test supply_i; /*test the result against limits*/
} /*end of TESTF*/
IMAGE Solutions V8.3 13-5
IMAGE Base Language: IMAGE Test Language Overview: IMAGE Test Language Basics
Table of Contents Index Home Master Index Search Help
IMAGE Test Language Basics
Because ITL is a superset of C, it provides both high-level structured statements and the
ability to easily manipulate low-level objects such as characters, addresses, and bits. All this
allows you to write fast, efficient code.
The following lists contain syntactic conventions, important facts, and general guidelines
and conventions concerning ITL:
• ITL (like C) is case-sensitive. Always use lower case except for macro names, tag
names, and the labels SEQUENCER and TESTF.
• Spaces, tabs, and carriage returns are ignored by the compiler.
• Parentheses () are used as part of a function name to pass arguments, to determine
arithmetic precedence, and to delimit branch and loop expressions.
• Brackets ([]) are used in defining array elements.
• Braces ({}) are used to mark the beginning and end of blocks of code and to initialize
array values.
• Double quotes (" ") define any characters placed between them as a string.
• Single quotes ('') are used for single-character constants.
• A semicolon (;) defines the end of a statement.
Statements
In ITL, all statements are terminated by a semicolon (;). For example:
set power on: dc;
Right and left braces ({ and }) are used to group statements together into a compound
statement to be executed as a block. For example:
TESTF()
{
set power on: dc;
wait 10ms;
}
This is similar to the use of the words “begin” and “end” in other languages. When braces
are used, a semicolon is not required after the right brace (}) to terminate the statement.
Assignment statements and flow-control statements are described in “Flow Control
Statements” on page 13-19.
Comments
Comments begin with a slash and an asterisk (/*) and end with an asterisk and slash (*/),
as in
/*This is a comment*/
IMAGE Solutions V8.3 13-6
IMAGE Base Language: IMAGE Test Language Overview: IMAGE Test Language Basics
Table of Contents Index Home Master Index Search Help
Comments can be placed anywhere in a source file. Nested comments are illegal and
produce a compiler error.
Functions
Functions are executable blocks of code structured in standard C format. Each function is
delimited by a left and right brace, and uniquely identified by a function name. Typically the
name of the function describes the operation that takes place when the function is executed.
Functions are executed by calling them, using the function name.
Functions can receive values through the passing of parameters and can return a value
through a return statement.
The parts of a function are:
• A declaration of the type of return value if a return statement is to be used
• The function name followed by parentheses
• A list of variable names that receive the values of the arguments or parameters being
passed to the function. This list is placed in the parentheses following the function name.
It gives the names and the order in which the function expects them.
• Declarations for each of the names in the arguments/parameters list. Declarations give
the type of values being passed.
• The body of the function (the block of executable code delimited by left and right braces)
• A return statement (when a value is to be returned)
Sample function definition is:
double vout(p, pname, supply)
int p;
char pname[];
double supply;
{
double x;
<statements - body of function>
return(x);
}
In this example, the word double in front of the function name vout is the declaration of the
type of value being returned by the return(x); statement. (double means “double
precision floating point.”) The default type for any returned value is an integer. (See “Data
Types and Constants” on page 13-11.)
The terms p, pname, and supply contained in the parentheses are the parameters being
passed to the function vout. If no arguments are passed, it is written vout(). (If using
Solaris 2, this can be written vout(void).)
Between the function name and the left brace ({) are:
int p;
char pname[];
double supply;
IMAGE Solutions V8.3 13-7
IMAGE Base Language: IMAGE Test Language Overview: IMAGE Test Language Basics
Table of Contents Index Home Master Index Search Help
These are declarations of the type of values being passed to the parameters p, pname, and
supply.
The body of the function is contained within the left and right braces ({}) and can be any
group of executable ITL statements.
The return statement contains the variable x between parentheses. x is a variable that has
been given a value during execution of the body of statements in the function. This value
will be returned to the statement that called function vout.
NOTE
A return statement does not require parentheses; you can give it an arbitrary expression,
such as return 4+x; or return func1();
If you are using Solaris 2, you can use the ANSI C format to write functions. This provides
compile time checking of parameters to verify that the parameters used in the call to a
function match the parameters expected by the function. The example function would be
rewritten as follows in ANSI C:
double vout
(int p, char pname[], double supply)
{
double x;
<statements - body of function>
return(x);
}
Use of this format in Solaris 2 is optional. The standard format used in OS4.1 works in
Solaris 2.
Calling Functions
The following are examples of function calls:
vin(); A function call with no parameters. The block of code vin() is
executed.
vout(a,b,c); A function call passing parameters a, b, and c to the called
function.
x = myfunc(); A function is called and the return value assigned to x.
x = myfunc() + 4; A function call used in an expression. A function is called and its
return value is added to 4.
IMAGE Solutions V8.3 13-8
IMAGE Base Language: IMAGE Test Language Overview: IMAGE Test Language Basics
Table of Contents Index Home Master Index Search Help
Differences Between ITL and C
ITL is C plus testing statements, minus a few features. The missing features are
incompatible with incremental recompile. The following sections describe features legal in
C but not in ITL.
Conditional Compilation Directives
Take care when using conditional compilation directives (#if, #ifdef, #ifndef, #else,
and #endif) in ITL. Braces must be balanced both inside and outside the conditional code.
(In standard C, braces need only be balanced outside the conditional code.) Any text
contained within conditional compilation directives must conform to compilation standards.
For example, single and double quote characters must be balanced, also.
For example:
#ifdef DO_NOT_COMPILE
Don’t forget that this code needs to be debugged!
...
...
#endif
The single quote in the word don’t causes the preprocessor to scan forward to find the next
single quote.
If conditional compilation directives are used around include file directives such as:
#ifdef TYPEA
#include "typea.h"
#else
#include "typeb.h"
#endif
both include files must exist, even though only one of these files is used during compilation
of the program.
Macros
The directives #define and #undef, used in C to define or undefine a macro, are illegal in
ITL outside of the header of a test program.
Macros cannot be used for function definitions; structure or enum definitions and cannot
contain unbalanced braces or parentheses.
Variables and Functions
A variable or function cannot be global inside its file but unknown everywhere else. That is,
static cannot be used in the header segment on a variable or on a function definition to
make it private to the current file. Variables can, however, be declared static within a
function.
IMAGE Solutions V8.3 13-9
IMAGE Base Language: IMAGE Test Language Overview: IMAGE Test Language Basics
Table of Contents Index Home Master Index Search Help
Structures, Unions, and Enumerations
Structures, unions, and enumerations in ITL must have tags. A structure, union, or
enumeration produces an error when you try to compile or load a file if you do not have a tag.
Structure or union definitions cannot include conditional compile directives (#ifdef).
Unit Modifiers
An ITL feature not available in C is the ability to use unit modifiers for test program values.
This allows you to use expressions such as 2mA and 3dB, rather than the equivalent
scientific notation that C requires. The ITL preprocessor converts any unit modifiers into the
correct notation for you.
NOTE
Unit modifiers can be a source of confusion when using the modulus operator. The symbol
for the modulus operator (%) is the same as the symbol for the units of scaling (percent).
Therefore, be careful when using the modulus operator that you use a space before and
after the operator. Otherwise, you can get compiler errors. See “Arithmetic Operators” on
page 13-13 for an explanation.
ANSI C
If you are using Solaris 2, the C compiler supports ANSI C extensions to the C language.
For information on differences when converting to Solaris 2 and ANSI C, see “Updating Test
Programs Written Before Solaris 2” on page 13-29.
IMAGE Solutions V8.3 13-10
IMAGE Base Language: IMAGE Test Language Overview: Variables and Operators
Table of Contents Index Home Master Index Search Help
Variables and Operators
The following sections describe how IMAGE handles local and global variables, data types,
and arithmetic operators.
Data Types and Constants
A compiler handles constants and variables in different ways. While a program is being run
the value of a variable can be assigned or changed, but the value of a constant remains the
same. Since variable data can change, you need to declare a data type so the compiler will
know how much memory space to assign for that variable.
ITL recognizes the following variable data types:
char A single byte that can hold one character (8 bits)
short A signed integer (16 bits)
int A signed integer (32 bits)
float A single precision floating point (32 bits)
double A double precision floating point (64 bits)
SEGMENT A handle that refers to a memory segment containing a
waveform
field A data structure to refer to a pinmap field
dsp buffer A data structure to refer to a DSP buffer
You can also apply the following qualifier to integers:
unsigned An unsigned integer positive for the full range of bits
Table 13-1 lists the types of constants in ITL and provides an example of each.
Table 13-1. ITL Constants
Constant Definition Example
decimal integer A string of digits. 45
octal A string of digits that begins with a zero 023
hexadecimal A string of digits that begins with a zero 0x59
followed by an x.
floating point A string of digits that includes a decimal point or 12mv
optional units.
Can also be represented by scientific notation. 123.456e10
character A single character in single quotes. 'z'
IMAGE Solutions V8.3 13-11
IMAGE Base Language: IMAGE Test Language Overview: Variables and Operators
Table of Contents Index Home Master Index Search Help
Table 13-1. ITL Constants (Continued)
Constant Definition Example
Nongraphic Represented by two characters, the first being '\n' represents
characters a backslash. newline
'\t' represents
tab
string constant Zero or more characters in double quotes. You "This is a
can use string constants in print statements or string.\n"
other functions requiring a constant string of
text. String constants are null terminated.
Variables
Variable names are made up of letters and digits. The first character must be a letter. The
underscore (_) is considered a letter. ITL differentiates between upper and lower case.
Therefore, ABC is not the same as abc.
Variable Names
You can use almost any name for a variable, but you cannot use any of the IMAGE reserved
words (such as set, wait, and tl_). See “Reserved Word List” on page 23-1 for a list.
Declaring Variables
All variables must be defined or declared before they are used. A definition consists of a
data type followed by a variable name. Some examples are:
int index;
double value;
char ch;
unsigned num;
Multiple variables of the same type can be defined on one line, as in:
int a, b, c;
Initializing Variables
Variables can be initialized in their definition by placing an equal sign and a constant after
the variable name:
int i = 0;
float pi = 3.14159;
char newline = '\n';
IMAGE Solutions V8.3 13-12
IMAGE Base Language: IMAGE Test Language Overview: Variables and Operators
Table of Contents Index Home Master Index Search Help
Local and Global Variables
A variable’s scope is its range within the file in which it can be used. ITL variables have two
levels of scope. A local variable is associated with a specific function and, therefore,
accessed only within that function. A global variable can be accessed from any function in
the file. (Another type of variable, the array variable, is described in “Arrays” on page 13-24.)
All variables defined inside a function are local to that function. Local variables can be
referenced only within the function they are defined in and exist only during execution of that
function. Local variables that are initialized are given their initial value each time the function
is called. For a local variable to keep its value between executions of the function, that
variable must be declared as static by putting the word static in front of the variable
definition.
To make a variable global to the entire file, it must be defined at the top of the file in the
header section. Global variables are initialized once when the program is loaded and retain
their values between test program executions. (Global variables cannot, however, be
declared static.)
NOTE
In ITL, uninitialized global variables are initialized to 0 at load time. From then on, their
values (when changed) are retained from run to run.
In ITL, programs can be divided into separate source files. Global variables can be defined
in any file. To access a variable defined in another source file, you must declare the variable
as external using an external declaration with the keyword extern in front of the variable
type and name. For example:
extern int status;
This indicates to the compiler that the variable is defined in another source file. You must
place external declarations in the header section at the top of the file or in a function.
Arithmetic, Relational, and Logical Operators
Arithmetic Operators
ITL has one unary (takes one operand) and five binary (takes two operands) arithmetic
operators. The unary operator “-” is used to negate a number. The five binary arithmetic
operators are: + (addition), - (subtraction), * (multiplication), / (division), and % (modulus).
The modulus operator (%) produces a remainder when two integers are divided. For
example, if:
a = 25 b = 10
then:
a % b = 5
IMAGE Solutions V8.3 13-13
IMAGE Base Language: IMAGE Test Language Overview: Variables and Operators
Table of Contents Index Home Master Index Search Help
Take care to use spaces around the modulus operator to avoid confusion with % used as a
scale factor. (See “Units” on page 13-17.) For example, consider the following expressions:
k= 2 % j
k= 2% j
The first is a legal expression. The second is equivalent to:
k= 2E-2 j
This expression is illegal and will produce a compiler error.
The order of precedence of ITL arithmetic operators is as follows:
unary - highest precedence
*, /, % equal and lower precedence
+, - equal and lowest precedence
Arithmetic operators of equal precedence execute from left to right with parentheses
overriding. For example:
c = 5 * 4 + 3; /*c is assigned the value 23*/
c = 5 * (4 + 3); /*c is assigned the value 35*/
Relational Operators
ITL relational operators for use in determining TRUE or FALSE are as follows:
> greater than
>= greater than or equal to
< less than
<= less than or equal to
== equal to
!= not equal to
== and != have lower precedence than the others. All relational operators have lower
precedence than arithmetic operators. For example:
if (x + 4 < 3 + y);
is the same as:
if ((x + 4) < (3 + y));
NOTE
Do not confuse the single = and double == equal sign operators. The == operator compares
two values, as in:
if (x==5)
The = operator is used for assigning a value to a variable.
IMAGE Solutions V8.3 13-14
IMAGE Base Language: IMAGE Test Language Overview: Variables and Operators
Table of Contents Index Home Master Index Search Help
Relational operators are most often used in flow control statements or conditional
statements, like loop conditions or if statements.
x=0; /*x is assigned the value 0 and then evaluated*/
if (x==1)...
Logical Operators
ITL logical operators for use in determining TRUE or FALSE are as follows:
&& logical AND
|| logical OR
! unary NOT
Expressions containing && or || are evaluated left to right and evaluation stops as soon as
TRUE or FALSE is known. For example:
if (i > 4 && x == y); /* if i > 4 AND x == y */
Bitwise Logical Operators
ITL provides a number of operators to facilitate bit manipulation. (Bit manipulation is used
only with integers.) These operators are:
& bitwise AND
| bitwise OR
^ bitwise EXCLUSIVE OR
<< left shift
>> right shift
~ ones complement
The bitwise AND and OR operators are often used to mask off or turn on bits. For example:
c = 075
mask = 0100;
c = c & 07; /*c = 05*/
c = c | mask; /*c = 0105*/
NOTE
Do not confuse the bitwise operators & and | with their logical counterparts && and || which
are used in Boolean expressions to determine TRUE or FALSE.
Shift operators are used to shift right or left some number of bits. The syntax for shift
operators is:
IMAGE Solutions V8.3 13-15
IMAGE Base Language: IMAGE Test Language Overview: Variables and Operators
Table of Contents Index Home Master Index Search Help
<operand> <operator> <number of bit positions to shift>
For example:
x = 01;
y = x << 2; /*y is now 04*/
operator number of positions to shift
Relational operators have a higher precedence than bitwise logical operators. For example,
the following statement would not work properly without parentheses:
"if ((readback & MASK) == 0) .."
Increment and Decrement Operators
Two operators are provided for incrementing and decrementing variables:
++ adds 1 to its operand
-- subtracts 1 from its operand
For example, ++x adds one to x, and --y subtracts one from y. You could write x=x+1 to get
the same result, but using ++x is more concise and efficient.
Increment or decrement operators can be placed before or after the variable name. If placed
before the variable it means increment first, evaluate second. If placed after the variable, it
means evaluate first, increment second. For example, if y = 5, then:
x = y++; /*sets x to 5, then increments y to 6*/
x = ++y; /*increments y to 6, then sets x to 6*/
In the first example, x is assigned the value of y, then y is incremented. In the second
example, y is incremented then x is assigned the value of y.
Assignment Operators
Three operators are provided for assigning values to variables:
a = x /*assign the value of x to a*/
a += x /*add x and a and assign the result to a*/
a -= x /*subtract x from a and assign the result to a*/
Precedence of Operators
Table 13-2 summarizes operator precedence and associativity (the degree of dependence
between two operators).
Table 13-2. Operator Precedence and Associativity
Operator Associativity
()[] -> . → (left to right)
IMAGE Solutions V8.3 13-16
IMAGE Base Language: IMAGE Test Language Overview: Variables and Operators
Table of Contents Index Home Master Index Search Help
Table 13-2. Operator Precedence and Associativity (Continued)
Operator Associativity
! ~ ++ - -- (type) * & sizeof ← (right to left)
* / % →
+ - →
<< >> →
< <= > >= →
== != →
& →
^ →
| →
&& →
|| →
?: ←
= += -= etc. ←
, →
Units
When programming instruments, you may wish to specify units in standard terms like
millivolts or kilohertz. ITL allows you to deal with floating point numbers in the scale and
units appropriate for each application.
To do this, ITL uses a format for floating point constants that includes a scale factor and
units string appended to a floating point constant. The scale factor (table 13-3) is a single
letter indicating which power of 10 to scale the number by. The units string is made up of
one to six alphabetic characters. The scale factor and units string are concatenated together
and placed immediately following the floating point constant with no space in between. The
scale factor and units string are each optional.
Table 13-3. ITL Scale Factors
Scale Factor Power of Ten
f femto -15
p pico -12
n nano -9
IMAGE Solutions V8.3 13-17
IMAGE Base Language: IMAGE Test Language Overview: Variables and Operators
Table of Contents Index Home Master Index Search Help
Table 13-3. ITL Scale Factors (Continued)
Scale Factor Power of Ten
u1 micro -6
m milli -3
% percent -2
c centi -2
k or K kilo 3
M mega 6
G giga 9
1. A unit must follow the u scale factor. In accordance with Solaris conventions, u or U following a
constant casts that number as an unsigned int unless a unit follows the u.
The units string is a label provided for readability and has no effect on floating point
arithmetic. It is checked by the compiler in certain cases to verify that the units are
appropriate for the instruments being programmed. In the sequencer statement, the units
string in a limit specification is used as a default for the units appearing in a datalog printout.
(See “Test Parameter List” on page 14-13 and “Datalog Format” on page 6-75.)
Common unit strings include the following:
A amperes
s seconds
dB decibels
V volts
Hz hertz
ohm ohms
The following are floating point constants that use units and the actual numerical value they
represent:
2.4mV 0.0024
65uA 0.000065
32.4kV 32400.
.45MHz 450000.
Units can only be used as part of a constant. They cannot be appended to variables.
IMAGE Solutions V8.3 13-18
IMAGE Base Language: IMAGE Test Language Overview: Flow Control Statements
Table of Contents Index Home Master Index Search Help
Flow Control Statements
This section describes the major ITL language statements used to control test program flow.
Table 13-4 lists these statements.
Table 13-4. ITL Program Flow Control Statements
Statement Purpose Syntax Example
assign Variable assignment x=4;
if-else Conditional branch if (x>y-3) <statement1>;
else <statement2>;
for Iterative loop for (i=0; i<100;++i)
<statement>;
while Conditional loop while (j>=5)
<statement>;
do-while Conditional loop do <statement>;
while (sflag 1= TRUE);
switch Selection switch (ch)
{
case'y': <statement>;
break;
case'n': <statement>;
break;
default: <statement>;
break;
}
break Break out of loop or switch break;
continue Continue at top of loop continue;
goto Go directly to label goto next;
next:
Assignment Statement
The assignment statement allows you to assign a value to a variable. The statement syntax
is:
<variable> = <expression>;
where <variable> can be any variable name, and <expression> can be any legal
expression in ITL. For example:
IMAGE Solutions V8.3 13-19
IMAGE Base Language: IMAGE Test Language Overview: Flow Control Statements
Table of Contents Index Home Master Index Search Help
x = 4;
y = vout/4;
result = read_meter();
If the value of the expression is not the same type as the variable, the value is converted to
that type before the assignment is made. For example:
double a;
int x;
x = 4.6 + 5.6; /*x = 10*/
a = 4.6 + 5.6; /*a = 10.2*/
In this example, x is declared as an integer. Therefore, x = 4.6 + 5.6 yields 10, since the
arithmetic is done first in floating point, giving you 10.2, and then converted to an integer
(10).
If-Else Statement
The if-else statement creates a simple conditional branch in the program. The format is:
if (<expression>) <statement1>;
else <statement2>;
This is a Boolean expression that must evaluate to TRUE (a nonzero value) or FALSE (a
zero value). If the expression evaluates to TRUE, <statement1> executes. If it evaluates
to FALSE, <statement2> executes. The else clause of the statement is optional. Here is
an example:
if (read_meter() > 2.4mv) vflag = 1;
else vflag = 0;
For Statement
Use the for statement to iterate a statement or group of statements a fixed number of times.
The syntax of a for loop is:
for (<init>; <cond>; <incr>)
{
<statements>
}
where:
<init> Sets the initial value of a variable that keeps count of the number
of times the loop is executed. (Can also call a function.)
<cond> Sets the condition by which looping continues. If the condition
evaluates to TRUE, the loop is executed. If the condition
evaluates to FALSE, the loop is not executed.
<incr> Sets the value by which the <init> variable is changed after
each pass of the loop. (Can also call a function.)
IMAGE Solutions V8.3 13-20
IMAGE Base Language: IMAGE Test Language Overview: Flow Control Statements
Table of Contents Index Home Master Index Search Help
<statements> The body of the loop (the actual statements to be executed)
contained within left and right braces.
For example, you can produce a loop that counts from 0 to 99 incrementing by one on each
pass, and printing the number of each loop executed using:
for (i=0; i<100; ++i)
{
printf("%d\n",i);
}
In this example:
• i=0 sets the initial value of i to 0. This statement is executed only once.
• i<100 sets the looping condition. If TRUE that i is less than 100, the loop executes
again. If FALSE, the loop does not execute.
• ++i sets the increment value for each loop. It causes i to increment by one after each
pass of the loop.
While Statement
The while statement provides a loop based on a condition remaining true. The condition is
checked before the first iteration of the loop. Therefore, the loop condition can prevent the
loop from executing. The syntax is:
while (<expression>)
{
<statements>
}
<expression> is a Boolean expression that must evaluate to TRUE or FALSE. If the
expression evaluates to TRUE, the statement executes. The expression is reevaluated
each time through the loop, and the statement is executed until the expression becomes
FALSE. If the expression is FALSE the first time it is evaluated, the statement does not
execute. For example:
while (vout < 30mv)
{
set src= 1 v= vout/4;
vout= read_meter();
}
Do-While Statement
The do-while statement is similar to the while statement except that the condition is
checked after the loop rather than before the loop. This means that the loop always
executes at least once. The syntax is:
do
{
<statements>
IMAGE Solutions V8.3 13-21
IMAGE Base Language: IMAGE Test Language Overview: Flow Control Statements
Table of Contents Index Home Master Index Search Help
}
while (<expression>);
Switch Statement
The switch statement provides an easy way to perform a multipath branch based on an
expression matching one of a number of constant values. It is similar to the “case” statement
in other languages. The syntax is:
switch(<expression>)
{
case <const>: <statements>;
break;
case <const>: <statements>;
break;
·
·
default: <statements>;
break;
}
The integer value of the expression is compared with the integer constant value <const>
specified in the first case. If the expression equals the value, the statements following that
case are executed. If there is no match, the next case is checked. If none of the cases
match, the statements following the reserved keyword default are executed.
When a case matches, execution begins at that case and automatically falls through to all
the other statements. In most cases, a break statement is used at the end of each case to
prevent execution from falling through. The break statement stops execution of the switch
statement at the end of the case that has executed.
For example, if you want to read a character from the terminal and call two different
functions based on whether the character is “Y” or “N”, you could use the following:
ch = getchar(); /*get a character from the terminal*/
switch(ch)
{
case 'Y': yesfunc();
break;
case 'N': nofunc();
break;
default: printf("answer must be Y or N\n");
}
An error message is printed by the default case if the character is neither “Y” or “N.”
Break Statement
The break statement provides a way to break out of a while, for, do-while, or switch
statement. The syntax is:
IMAGE Solutions V8.3 13-22
IMAGE Base Language: IMAGE Test Language Overview: Flow Control Statements
Table of Contents Index Home Master Index Search Help
break;
When a break statement executes, it immediately interrupts execution of statements in the
body of the loop or switch statement. Execution continues with the first statement outside
of and after the body of the loop or switch statement.
Continue Statement
The continue statement is related to the break statement. Rather than exiting the loop,
however, it stops the current iteration of the loop and execution continues again at the top
of the loop. The syntax is:
continue;
This statement stops execution within a loop, then continues at the beginning of the next
iteration of for, while, and do-while loops.
Goto Statement
Control can be transferred unconditionally using a goto statement and a label:
goto <label>;
.
.
.
<label>:
Labels must obey the rules for variable names but need not be declared the way variables
do. A label must be in the same function as the corresponding goto. The goto statement is
usually unnecessary and can make programs difficult to read, so avoid it when possible. A
label must be followed by a colon (:).
IMAGE Solutions V8.3 13-23
IMAGE Base Language: IMAGE Test Language Overview: Arrays and Other Data Structures
Table of Contents Index Home Master Index Search Help
Arrays and Other Data Structures
This section describes the operation of arrays, pointers, and other data structures in ITL.
Arrays
An array is a series of variables of the same data type stored in a row or in the form of a
table or matrix. The elements of an array are in sequentially numbered locations and can
be referenced using a subscript that indexes to the proper point in the table.
You declare an array variable by giving the data type followed by the array name and the
size of the array in square brackets. The following are examples:
int i[10];
char ch[80];
double d[1024];
In the first example, int is the data type integer, i is the array name, and [10] is the
subscript that represents the number of storage spaces allotted for integers in the array.
You can initialize arrays at compile time by specifying the initial value of each element in the
declaration statement. For example, to initialize an array of five integers to the powers of 2,
use the following declaration:
int powers[5] = { 1, 2, 4, 8, 16 };
NOTE
You cannot initialize arrays of local variables.
To declare multidimensional arrays, specify a size for each dimension. For example, to
specify a 5x10 matrix of integers, you would write:
int multi[5][10];
Refer to array elements using a subscript that indexes to the proper element. Numbering of
array elements always starts with zero. Thus, in an array of five elements, the elements are
referred to as 0 through 4:
0 1 2 3 4
Subscripts can be any expression. For example:
x = a[3];
a[x] = y;
z = a[i*2/x];
b[i] = a[x/y];
IMAGE Solutions V8.3 13-24
IMAGE Base Language: IMAGE Test Language Overview: Arrays and Other Data Structures
Table of Contents Index Home Master Index Search Help
NOTE
The C language has no “bounds checking.” Make sure, therefore, that an array is large
enough to hold all the values you are writing to it. Writing past the end of an array can
overwrite other program variables.
Pointers
A pointer represents the address of a storage element. Pointers are useful for accessing
and manipulating data in a program. To use pointers, you must declare pointer variables. A
pointer variable is a variable that can hold the address of data. For the purpose of
declaration, the asterisk (*) preceding the variable name distinguishes pointer variables
from regular variables. For example, the following are declarations of pointer variables:
int *tblptr;
char *ch;
double *fptr;
The variable tblptr is a pointer to an integer and can hold the address of an integer. The
variable ch is a pointer to a character and can hold the address of a character.
To get the address of a storage element so that this address can be stored in a pointer
variable, use the operator ampersand (&). The & means “get the address of.” For example,
if you have an integer variable x that currently has the value 4 and want to assign its address
to the pointer variable ptrx, use the following assignment:
ptrx = &x;
It is also useful to get the actual data to assign it to another variable, or to use it inside an
expression. This is done using the operator asterisk (*) which means “get the contents of.”
For example, if ptrx still points to x, which has the value 4, then:
y = *ptrx + 1;
assigns y the value 4 + 1 = 5.
Pointers are often used to pass parameters to a function. If parameters are passed using a
regular variable, the value of the variable passed is used inside the function but cannot be
changed by the function. If a pointer variable is passed to a function, you can change the
value pointed to by the variable inside the function. This change will still be in effect when
the function returns because you are changing the actual data that the pointer points to
rather than a local copy of it.
Character pointers are often used to pass character strings to functions. A string constant
inside double quotes evaluates to a pointer that marks the beginning memory location of the
string. This pointer can then be passed to various string manipulation functions. For
example:
char *mystring;
mystring = "This is my string.";
len = strlen(mystring);
IMAGE Solutions V8.3 13-25
IMAGE Base Language: IMAGE Test Language Overview: Arrays and Other Data Structures
Table of Contents Index Home Master Index Search Help
strlen returns the length of the string passed to it.
There is a unique relationship between a pointer and an array name. The array name is a
pointer to element 0 of an array. This allows the simple creation of functions that perform
array operation. For example:
copy(in_array,out_array,size) /*Copy data from one
double *in_array,*out_array; array to another.*/
int size;
{
int i;
for (i=0;i<size;i++) out_array[i]=in_array[i];
}
NOTE
Array names, when passed to functions, are pointers.
For more information on pointers, see The C Programming Language by Brian W.
Kernighan and Dennis M. Ritchie.
Structures
Structures are powerful tools for logically grouping similar pieces of data. They are useful
for creating and organizing tables of information and accessing them in a readable way.
Structures are used along with pointers and arrays to create powerful data structures that
are easy to understand.
To set up a structure, you must create a structure template, name the template (using a
“tag”), and define the fields the template contains. (ITL requires that all structures have
tags.) This is called structure declaration. An example using the tag Setup would be:
struct Setup {
char name[SETUP_NAME_SIZE+1];
double voltage;
double current;
double frequency;
int number;
};
This structure declaration provides a template for any structure that you want to define of
the type Setup. It contains information on the type of storage of the data for each field in the
structure.
To use a structure template, you must define a variable that gives you access to the fields
of the structure and allocates storage for each field as defined in the template. For the
structure Setup, such a variable would be:
struct Setup instrument_setup;
IMAGE Solutions V8.3 13-26
IMAGE Base Language: IMAGE Test Language Overview: Arrays and Other Data Structures
Table of Contents Index Home Master Index Search Help
To access any of the members of this structure use the structure variable name
(instrument_setup in this example) followed by the member field name separated by a
period (.). For example:
instrument_setup.voltage = 2v;
instrument_setup.frequency = 10MHz;
strncpy(instrument_setup.name, "func_name", SETUP_NAME_SIZE);
For more information on structures, see The C Programming Language by Brian W.
Kernighan and Dennis M. Ritchie.
Passing struct Arguments
In the C programming language, functions pass arguments to other functions by making a
copy of the arguments on the “stack.” The called function then references the copy of the
argument on the stack.
When an argument to a function is a C structure (struct), you can pass the entire struct
on the stack. However, this usage is rare. Information in structures is invariably passed by
passing a pointer to the struct and having the called function reference the data using that
pointer.
While the ITL supports passing of entire structs as arguments, this technique has the
following problems:
• It is slower. The calling function must copy every byte of data onto the stack.
• It is unconventional. This usage is so rare, that a C programmer will see the struct
argument and assume it is a pointer.
• It is confusing. When a C programmer assigns a structure element to a passed struct,
the programmer expects that the data modification will be apparent in the calling
function, as it is with pointers.
• IMAGE has a bug which will not allow print, vardisp, or immediate commands on the
argument. (This bug is noted on page 29 of the IMAGE V5.7 Release Notes and in
earlier release notes.)
If the entire struct is passed, a workaround exists for the IMAGE print/vardisp/
immediate bug. Have a local pointer variable to the struct and immediately set the pointer
to point to the argument struct. For example, given:
struct A {
double x;
int size;
short offset;
};
the preferred code would be:
int aa(a) struct A *a; {
int size;
size = a->size + (int)(a->offset);
}
IMAGE Solutions V8.3 13-27
IMAGE Base Language: IMAGE Test Language Overview: Arrays and Other Data Structures
Table of Contents Index Home Master Index Search Help
The following code is undesirable:
int aa(a) struct A a; {
int size;
size = a.size + (int)(a.offset);
}
The workaround for print, vardisp, and immediate commands (which is not necessary for
correct functioning of a test program) is as follows:
int aa(a) struct A a; {
int size;
struct A *aptr = &a; /* 'Aptr' is correctly handled by print, vardisp */
size = aptr->size + (int)(aptr->offset);
/* "imm 'aptr->size += sizeof(aptr->offset)' " */
}
IMAGE Solutions V8.3 13-28
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
Updating Test Programs Written Before Solaris 2
The following sections discuss special features and things to be aware of when using
IMAGE under Solaris 2.
Macros for Use With OS 4.1 and Solaris 2
The following macros are available to allow you to distinguish between operating systems:
• When a test program is compiled, a macro sparcV is defined. You can use it in the
program to differentiate between Solaris 2 code and non Solaris 2 code. The symbol
sparc is defined for SUN4 under either OS. For example:
#ifdef sparcV
/* this is svr4 code */
#elif defined sparc
/* this is sun4 OS 4.1.x code */
#else
/* this is sun3 code */
#endif
• The macro SUN3_4_4V(s3,s4,s4v) returns s3 on SUN3, s4 on SUN4 (BSD) and s4v
on SUN4 (Solaris 2). This macro is available in IMAGE V4.4 and later. An example
would be:
printf("You are currently using %s\n", SUN3_4_4V("sun3", "sun4",
"svr4"));
• The macro SUN__4V(not4v,s4v) returns not4v when running BSD UNIX and s4v
when running Solaris 2. This macro is available in IMAGE V4.4 and later. An example
would be:
printf("You are %s currently using svr4\n", SUN__4V("not", ""));
Conditionally Compiling Functions
If you are using both OS 4.1 (with the Kernighan & Ritchie [“K&R”] C compiler) and Solaris
2 (with the ANSI C compiler), you may want the ability to write functions in test programs
that can be compiled under either operating system.
Using a special format, you can write functions that can be conditionally compiled. The
format is as follows:
void <function>
#ifdef __STDC__
( <ANSI C parameters> )
#else
( <K&R parameters> )
#endif
{
}
An example of a function written in this format is:
IMAGE Solutions V8.3 13-29
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
void newfunc
#ifdef __STDC__
(int val, char *cptr)
#else
(val, cptr)
int val;
char*cptr;
#endif
{
}
Using ANSI C
The Solaris 2 operating system uses the ANSI C standard. The following sections describe
differences you may encounter between ANSI C and the C standard used in OS 4.1.
ANSI C Error Messages
The major problem you are likely to encounter when porting test programs to Solaris 2 is the
stricter compiler which implements the ANSI C standard. The following is a list of error
messages you may see when porting. The explanations below refer to two compilers: the
K&R compiler and the ANSI C compiler. The former is the compiler which IMAGE uses
under Solaris 4.1.x. The latter is the compiler under Solaris 2.
• a cast does not yield an lvalue
Code example:
f() {
int i;
(long) i=5;
(short) i=4;
(char *)i++;
}
An lvalue is anything that might be modified by a statement. Typically, lvalues appear
on the left-hand side of an = sign, hence the name. With the K&R compiler it is legal to
use a cast with an lvalue. With the ANSI C compiler it is not. This also applies to implicit
lvalues as with the ++ operator.
• argument is incompatible with prototype: arg #<num>
Code example:
struct s {int x;} q;
f(void) {
int g(int, int);
g(3, q);
}
yields:
argument is incompatible with prototype: arg #2
This error may occur after a program is translated to using ANSI C-style functions
prototyping. The compiler uses the prototype to perform type checking on the
IMAGE Solutions V8.3 13-30
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
parameters passed to a function. If the compiler cannot fit the specified parameter to its
prototype, this warning occurs.
• dubious escape: \<char>
Code example:
int i = '\q';
yields:
dubious escape: \q
This warning indicates that the character immediately following a \ is not a supported
escape character in the C language. The compiler notes this because additional letters
may be added to the escape character set in the future. Do not, therefore, specify an
escape sequence which may have a different meaning to a future compiler version.
• dubious tag declaration: <type> <tag>
Code example:
int f(x)
struct s *x;
{
}
yields:
dubious tag declaration: struct s
In this code example, the definition of struct s does not appear in the source file.
Although all pointers have the same size, the code could never use the members of this
structure since it does not have the definition. If the members were never specified, the
K&R compiler would simply accept this without comment. The ANSI C compiler notes
this as a potential problem.
• empty translation unit
Zero characters were sent to the IMAGE compiler. This would happen if you loaded a
file, then removed all text and tried to compile the file or if a source file contained only
comments using /*...*/ or #if 0...#endif.
• {}-enclosed initializer required
Code example:
int array[5] = 0;
You tried initializing a global array with out enclosing braces. ANSI C is stricter about
this sort of code. An array is a collection of values which can be initialized by an explicit
collection of values. By definition, such a collection must be enclosed with {} even if it
is only one value.
• end-of-loop code not reached
Code example:
int c;
while((c=getchar()) != EOF) {
switch(c) {
case 'a': return 1;
case 'B': return 2;
IMAGE Solutions V8.3 13-31
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
case 'x': return 24;
default: return -1:
}
}
In this code example, it is logically impossible to reach the end of this loop. The while
statement will execute once and the switch statement will cause the function to return
on the first pass. This is a potentially dangerous coding practice since it is an
inappropriate use of the while statement.
• initializer does not fit: <value>
Code example:
short x = 0xffff;
yields:
warning: initializer does not fit: 65535
In this code example, the compiler must fit a 16 bit initializer into a 16 bit variable. The
K&R compiler would do this without comment. The ANSI C compiler considers this as
fitting a value of 65535 into a variable whose legal values range from -32768 to 32767.
Since this value is out of range, the compiler issues a warning. Two equivalent solutions
to the problem are:
– Change the type of x to be unsigned short:
unsigned short x = 0xffff;
– Cast the initializer to be of type short:
short x = (short)0xffff;
• integer overflow detected: op "<<"
Code example:
unsigned x = (0x1 << 31);
yields:
integer overflow detected: op "<<"
initializer does not fit or is out of range: -2147483648
The ANSI C compiler interprets 0x1 as a signed integer value. Attempting to shift 0x1
by 31 will place the most significant bit in bit 31 of the result. For a signed value, this is
an integer overflow. Also, the result of the shift operation is a signed integer. The
compiler yields a second warning because it is trying to assign a negative number to an
unsigned variable. The solution is to cast 0x1 as unsigned:
unsigned x = ((unsigned) 0x1 << 31);
This yields the expected results.
• macro redefined: <name>
Code example:
#define BSIZE 1024
#define BSIZE 512
yields:
warning: macro redefined: BSIZE
IMAGE Solutions V8.3 13-32
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
The source code redefined the value of a preprocessor macro. The K&R compiler would
accept the new definition without comment. The ANSI C compiler gives a warning. This
warning usually occurs when a macro is defined in a header file and in the source code
which includes the header file. It is a warning because it may indicate that the program
is trying to use the same macro name for two different purposes.
• old-style declaration; add "int"
Code example:
#include <stdio.h>
i;
main()
{
i++;
}
The K&R compiler allowed this type of implicit integer declaration. The ANSI C compiler
does not. All identifiers must have a storage class specification.
• prototype mismatch: <n1> arg[s] passed, <n2> expected
Code example:
#include <stdio.h>
main()
{
fflush();
}
yields:
prototype mismatch: 0 args passed, 1 expected
If a function prototype appears in the source code, it is applied to the function call
statement. If the number of parameters passed does not agree with the prototype, this
error occurs. Even without porting test programs to ANSI C, system header files declare
C functions using prototypes. This error almost always indicates a bug in the program.
• semantics of "<op>" change in ANSI C; use explicit cast
Code example:
f()
{
int i=12;
unsigned short x = 3;
i = x/i;
}
yields:
warning: semantics of "/" change in ANSI C; use explicit
cast
This is probably the most subtle difference between the K&R and ANSI C compilers. In
the expression above, the value x must be promoted to match the width of the largest
value in the expression. In this case, x (16 bits) must have the same width as the
variable i (32 bits). The K&R compiler always promotes to an unsigned value where the
ANSI C compiler promotes this to a signed value. While in most cases this will not make
IMAGE Solutions V8.3 13-33
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
a difference in the calculation, there is no way to tell at the time the program runs if the
calculation is correct. Therefore, the compiler warns of a potential problem.
The solution is to indicate to the compiler which promotion it should make. When porting
from the K&R compiler to the ANSI C compiler, the safest thing to do is be sure that the
compiler uses the K&R interpretation of the promotion rules. In the code example, the
solution is:
i=(unsigned int)x/i;
• switch expression must have integer type
Code example:
f()
{
float x=4.0;
switch(x) {
case 4: break;
}
}
The argument of a switch statement must be an integer. While of questionable validity,
the K&R compiler would accept the code example. The ANSI C compiler does not. The
reason for this is that floating point variables may have different exact representations
depending on how they are arrived at. Even though a printf statement might indicate
that two variables are the same value, they may only appear so due to rounding.
Equating a float or double variable with an integer will usually yield unexpected
results.
• syntax error: empty declaration
Code example:
int i;;
The file header contains a null statement. This looks like an empty declaration
statement. The K&R compiler permits this, but the ANSI C compiler does not.
• useless declaration
Code example:
int; /* no identifier */
enum e { e1, e2 }; /* introduces enum e */
enum e; /* no new information */
The ANSI C compiler requires that each statement have meaning. The first and third line
of the code example give no new information to the compiler. While the K&R compiler
would ignore these statements, the ANSI C compiler warns of a potential error.
Initializing Structures
K&R C and ANSI C use different algorithms for parsing structure/union initializers. For
example, the code:
struct { int a[3]; int b; } w[] = { {1}, 2 };
yields this with the K&R compiler:
IMAGE Solutions V8.3 13-34
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
sizeof(w) = 16
w[0].a = 1, 0, 0
w[0].b = 2
but yields this with the ANSI C compiler:
sizeof(w) = 32
w[0].a = 1, 0, 0
w[0].b = 0
w[1].a = 2, 0, 0
w[1].b = 0
The way to overcome this confusion is to be explicit about structure initializers. For example:
struct { int a[3]; int b; } w[] = { {{1}, 2} };
yields:
sizeof(w) = 16
w[0].a = 1, 0, 0
w[0].b = 2
In this example, the first { begins the initialization of the array w[]. The second { begins the
initialization of the structure w[0]. The third begins the initailzation of the array w[0].a.
Preprocessor Differences
Another difference between K&R C and ANSI C is in the preprocessor directives. While
most basic functions of the preprocessor are the same, certain features are different. The
IMAGE compiler running with ANSI C defines the symbol __STDC__ having the value 0 to
allow for conditional compiles of ANSI C code.
• Macro pasting. With K&R C, preprocessor symbols can be pasted together using a
comment, /* */. ANSI C uses the symbol ## to accomplish the same functionality. For
example, the following compiles and prints 1 in either ANSI C or K&R C:
#include <stdio.h>
#ifdef __STDC__
#define PASTE(A,B) A##B
#else
#define PASTE(A,B) A/*a comment*/B
#endif
main()
{
int vara=1, varb=2;
printf("%d\n", PASTE(var,a));
}
• Macro strings. K&R C allows you to write a preprocessor macro which takes the
argument and puts quotes around it. The method for doing this in ANSI C is to use the
# operator as in:
#include <stdio.h>
#ifdef __STDC__
#define STRING(X) #X
#else
IMAGE Solutions V8.3 13-35
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
#define STRING(X) "X"
#endif
main()
{
printf("%s\n", STRING(this is a string));
}
This successfully compiles and prints this is a string.
Function Prototypes
Probably the most notable difference between K&R and ANSI C is the format of function
prototypes. In ANSI C you can declare variable types within the arguments list. K&R
requires you to declare them outside the arguments list. For example:
• ANSI C format:
int foo (int val1, int val2)
• K&R format:
foo (val1, val2)
int val1, val2;
The ANSI C compiler accepts either format for a function definition or declaration. However,
never mix the two for the same function.
Below are a few examples of both styles. Take special note of the variable argument
example. The two forms are completely incompatible.
• K&R style function takes no arguments:
int f() {} /* function definition */
int f(); /* function declaration */
• ANSI C style function takes no arguments:
int f(void) {} /* function definition */
int f(void); /* function declaration */
• K&R style function takes one argument:
int f(val) /* function definition */
int val;
{
}
int f(); /* function declaration */
• ANSI C style function takes one argument:
int f(int val) /* function definition */
{
}
int f(int); /* function declaration */
int f(int val); /* function declaration (variable
name is optional) */
• K&R style function takes three arguments
int f(val, fval, cptr) /* function definition */
int val;
IMAGE Solutions V8.3 13-36
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
float fval;
char *cptr;
{
}
int f(); /* function declaration */
• ANSI C style function takes three arguments:
int f(int val, float fval, char *cptr) /* function definition */
{
}
int f(int, float, char *); /* function declaration */
• K&R style function takes variable arguments:
#include <varargs.h>
int f(val, va_alist) /* function definition */
int val;
va_dcl
{
float fval;
va_arg ap;
va_start(ap);
while (val--) {
fval = va_arg(ap, float);
/* operate on fval */
}
}
int f(); /* function declaration */
• ANSI C style function takes variable arguments:
#include <stdarg.h>
int f(int val, float fval, ...) /*function definition*/
{
float fval2;
va_arg ap;
va_start(ap, fval); /* fval is the last fixed
argument in the definition */
while (val--) {
fval2 = va_arg(ap, float);
/* operate on fval2 */
}
}
int f(int, ...); /* function declaration */
A function prototype may be conditionally compiled to be a legal K&R declaration in Solaris
1 using the EXTERN_FUNCTION macro. For example:
/* Define a conditional macro for function prototypes */
#include <image.h>
EXTERN_FUNCTION (extern void
Foo,(int i, double j));
For functions with no arguments, use _VOID_. For example:
IMAGE Solutions V8.3 13-37
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
extern int Bar(void)
EXTERN_FUNCTION (extern int Bar,(_VOID_));
For functions5 with a variable arguments list, use DOTDOTDOT. For example:
EXTERN_FUNCTION (extern int f,(int, DOTDOTDOT));
The IMAGE compiler automatically generates function prototypes for functions defined in
the text of the user’s test program. However, all data types used in the ANSI function
definition must be “known” in all modules where the function is called. Therefore, you must
place the function prototype declaration in a header file if the function is shared among
modules.
Memory Allocation
The memory de-allocation function free() (used with malloc()) is different in Solaris 1 and
Solaris 2. free() is declared int free() in Solaris 1 and returns 1 on success and 0 on
failure. It is declared void free() in Solaris 2 and does not return a value. Therefore, when
porting test programs from Solaris 1 to Solaris 2, check for dependencies on the return value
for free().
Library Function Differences
Under the Solaris 2 operating system, several C library functions are removed and replaced
with equivalents. The IMAGE libraries support most of the removed functions, and you
should see no unresolved references to library functions when compiling test programs
under Solaris 2. The functions that are missing are mostly associated with operating system
communications and most test programs should not be using them in either operating
system.
One notable difference is use of the functions sprintf and vsprintf. While still supported,
the return value has changed. Under Solaris 4.1, these functions return a pointer to the
string passed as the first argument in the parameter list. Under Solaris 2, these functions
return the number of characters transferred to the string. The compiler should pick up
inappropriate uses since the header file stdio.h declares the function prototype and
checks for agreement of the function return value.
The remaining differences should be only with the system header files included with the test
program. Table 13-5 shows header files that are different. Note that the Solaris 2 compatible
header files are available in both operating systems.
Table 13-5. Differences Between OS 4.1 and Solaris 2.x Header Files
Solaris 4.1 Only Solaris 2 Compatible
#include <strings.h> #include <string.h>
#include <sys/file.h> #include <unistd.h> /* use with access() */
#include <fcntl.h> /* use with open() */
IMAGE Solutions V8.3 13-38
IMAGE Base Language: IMAGE Test Language Overview: Updating Test Programs Written Before Solaris 2
Table of Contents Index Home Master Index Search Help
Table 13-5. Differences Between OS 4.1 and Solaris 2.x Header Files (Continued)
Solaris 4.1 Only Solaris 2 Compatible
#include <sys/dir.h> #include <dirent.h> /* using struct dirent
/* using struct direct */ */
IMAGE Solutions V8.3 13-39
IMAGE Base Language: Test Program Structure
Table of Contents Index Home Master Index Search Help
14 TEST PROGRAM STRUCTURE
Functions are the basic building block of a test program written in the IMAGE Test Language
(ITL). A function is a distinct section of code similar to a procedure or a subroutine in other
languages.
This section includes the following topics:
• “Functions in IMAGE” on page 14-2
• “Header” on page 14-4
• “main() Function” on page 14-9
• “Sequencer and Tests” on page 14-10
• “Datalog and Summary Statements” on page 14-24
• “Creating Test Program Modules Without a Pinmap” on page 14-26
IMAGE Solutions V8.3 14-1
IMAGE Base Language: Test Program Structure: Functions in IMAGE
Table of Contents Index Home Master Index Search Help
Functions in IMAGE
Execution of a test program starts at the beginning of a function called main(). The main
function can, in turn, call other functions. ITL includes special types of functions, sequencer
functions and test functions, for creating test programs. An example of a function
definition is:
double vout(p, pname, supply) /*Type of value, function name, and params*/
int p;
char *pname; /*Parameter declarations*/
double supply;
{ /*Start of function body*/
double x; /*Definition of local variables*/
.
<statements> /*Executable statements*/
.
x = read_meter();
return(x); /*Return statement*/
} /*End of function body*/
A typical test program includes a header section, a main function, one or more
sequencer functions, a number of test functions, and some general-purpose functions.
The example test program in figure 14-1 shows how all the parts fit together. This section
describes each type of program section.
IMAGE Solutions V8.3 14-2
IMAGE Base Language: Test Program Structure: Functions in IMAGE
Table of Contents Index Home Master Index Search Help
Header
#include <stdio.h> /*standard I/O header*/
#include <math.h> /*standard math functions*/
#include <image.h> /*standard IMAGE header*/
#define VMASK 0077 /*macro definition*/
#define SPECTRUM_SIZE 512
float spectrum[SPECTRUM_SIZE]; /*define a global array*/
int myflag = 0; /*define a global flag var*/
pinmap = {
/*DUT pin number pin name channel resource*/
1 "VIN" dc_matrix:1 (src:1),
2 "VOUT" dc_matrix:2,
dib "DIB" dc_matrix:3 (src:2),
24 "VCC" dutsrc:1,
};
Main Program—Beginning of executable code
main()
{ /*beginning of main*/
seq1(); /*execute the sequencer seq1 and assign bin_number*/
sort bin; /*sort the bin number result*/
} /*end of main*/
SEQUENCER Function
SEQUENCER seq1()
{ /*beginning of sequencer*/
/*
test function test test limits test binning
name # low/high label f/p */
seq contin() $1 >0 <.7v "continuity" f(0);
seq icc() $2 >20ma <25ma "supply i" f(2);
seq ac() $3 >1.55v <1.62v "amplitude" f(3) p(1);
} /*end of sequencer*/
TEST Function
TESTF icc()
{ /*beginning of testf*/
double supply_i; /*declare local variable*/
set pin=vcc dutsrc:v=5.125v; /*set up dc source*/
set meter input:pin=vcc dutsrc:i; /*set up dc meter*/
set power on: dc; /*turn power on*/
wait 10ms; /*wait for device to settle*/
supply_i=read_meter(); /*read dc voltmeter*/
test supply_i; /*test the result against limits*/
} /*end of testf*/
Figure 14-1. Test Program Structure
IMAGE Solutions V8.3 14-3
IMAGE Base Language: Test Program Structure: Header
Table of Contents Index Home Master Index Search Help
Header
All test programs begin with a header section. The header section must be at the top of the
source file before the first function. It contains file #include directives, macro definitions,
external variable declarations, the pinmap, and global variable definitions. Here is a sample
header section:
/* Standard header files */
#include <stdio.h> /*standard I/O header file*/
#include <math.h> /*standard math functions*/
#include <image.h> /*standard IMAGE header file*/
#define VMASK 0077 /*macro definition*/
#define SPECTRUM_SIZE 512
float spectrum[SPECTRUM_SIZE]; /*define a global array*/
int myflag = 0; /*define a global flag variable*/
Limits to Header Files
One difference between ITL and standard C is in the way header files are treated. In
standard C, a .h file which is included using a #include can contain any legal C code. In
ITL, header files should only contain the following:
• typedef constructs and structure templates
• extern declarations
• Other compiler directives (such as #define)
In particular, you cannot define functions in an ITL program header file, as in:
foo()
{
return 0;
}
You cannot define any global variables (such as int x;) unless they are extern.
The restriction on defining functions in header files is enforced by the IMAGE compiler. If
you try to put a function body in a header file, a compiler error results. The restriction on
global variable declarations is not enforced at compile time but produces an error at link
time.
Include Compile Directives
ITL provides several compile-time directives, implemented by a preprocessor that passes
over source code before sending it to the main compiler. The directives are distinguished
by lines beginning with the character #.
The file inclusion directive #include allows you to keep define compile directives and
declarations in one file and then include them in each source file that requires them. An
IMAGE preprocessor includes the named file in the source file at the point that the #include
directive occurs. #include directives must be placed at the top of a source file.
IMAGE Solutions V8.3 14-4
IMAGE Base Language: Test Program Structure: Header
Table of Contents Index Home Master Index Search Help
Inclusion directives can contain either standard IMAGE header files or files you write. Such
a file, however, can only contain declarations. You cannot place executable code inside an
include file.
NOTE
You cannot place executable code in a header file. This restriction extends to variables. The
only variable declarations in an include file should be those that declare variables as
extern.
Inclusion directives for standard header files are written using angle brackets (<>), as in:
#include <stdio.h>
This header file is the standard IMAGE I/O file. You cannot modify any standard header files
in debug.
Inclusion header files you (or other users) write are written using double quotes (" "), as in:
#include "myheader.h"
This statement includes the file myheader.h from disk. You can modify header files you
create while in debug.
Including a Search File Path
In IMAGE V6.3 and later, you can add to the include file search path used to compile IMAGE
test programs by defining an environment variable named TL_INCLUDE_PATH. The format
of this variable is the same as other path environment variables, a colon (:) separated list
of directories. The environment variable is processed by the IMAGE commands itlc and
load. It behaves exactly like the -incdir switch and its value is processed after all explicit
options to those commands. (See “Loading Using the load Command” on page 5-4 and
“Using the itlc Command” on page 7-38.)
Define Compile Directives
The define compile directive #define provides macro substitution capability. Macros are
useful for giving a symbolic name to constants that never change in a program. The format
is:
#define <MACRO_NAME> <substitution string>
where:
MACRO_NAME This is the name of the macro in upper case (by convention) to
distinguish it from language statements and variables in lower
case.
substitution stringThis is the string substituted for the macro name anywhere it
appears in the source program.
IMAGE Solutions V8.3 14-5
IMAGE Base Language: Test Program Structure: Header
Table of Contents Index Home Master Index Search Help
For example, the following macro substitutes 1024 wherever MAXSIZE appears:
#define MAXSIZE 1024
A test programming example using a #define directive is:
double stuff[MAXSIZE];
.
.
for(i=0;i<MAXSIZE;i++)
stuff[i]=1.75;
You can also specify macros with parameters. For example, the following macro calculates
the remainder when dividing two integers:
#define REM(a,b) ((a) - (a)/(b) * (b))
NOTE
Changing a macro in debug causes the entire file to recompile.
Conditional Compile Directives
The define compile directive #ifdef allows you to include conditional compiler directives in
a test program. You can include a series of statements that instructs the compiler to compile
a program in a number of ways depending on the symbols it finds. The format is:
#ifdef [symbol] #else #endif
The following example can be used to decide whether to compile a section of code:
#ifdef [symbol] /*If symbol defined, compile enclosed
... code. Otherwise, ignore enclosed code.*/
A more complex example would be:
#ifdef [symbol] /*If symbol defined, compile sect. 1 and */
sect1 /*ignore sect. 2. Otherwise, compile */
#else /*sect. 2 and ignore sect. 1. */
sect2
#endif
IMAGE places restrictions on conditional compiling. See “Differences Between ITL and C”
on page 13-9, “Loading for Conditional Compiling” on page 5-18, and the discussion of the
-define and -O options to the itlc command in “Standalone IMAGE Compiler” on page
7-38.
Pinmap
One of the first steps in writing a test program is assigning tester resources to device pins
by creating a pinmap. This allows you to program tester instruments by referencing pin
numbers of the device under test (DUT). The pinmap tells IMAGE which instruments and
IMAGE Solutions V8.3 14-6
IMAGE Base Language: Test Program Structure: Header
Table of Contents Index Home Master Index Search Help
channels are used by each pin of the DUT. (This can also be done using DIBView. See
“DIBView” on page 2-1 in the IMAGE Software Tools Manual.)
Usually, each pinmap line specifies a DUT pin. This pin specification includes:
• Pin number (or the word dib)
• Pin name
• Tester channel type and channel number
• Any tester ac instruments used for that pin
An example pinmap for a mixed-signal test system would be as follows:
pinmap = {
/*DUT pin number pin name channel resource*/
1 "VIN" analog:2A (lfsrc_hi),
2 "VOUT" analog:4A (lfdig_hi),
dib "DIB" analog:2B (lfsrc_gnd),
24 "VCC" dutsrc:1,
};
Test systems that use a configuration board in the test head (such as advanced mixed-
signal testers) use a slightly different form of pinmap. The following is an advanced linear
pinmap:
pinmap = {
3 "VEE" dib:27a1 dutsrc,
6 "MCLAMP" dib:1a2 dc_matrix (src:2),
};
A pin name is mapped to the corresponding pin number by a macro, a mechanism in C that
allows for text substitution. If a pinmap specifies 1 "ABC", the compiler creates a macro that
defines ABC as 1. From then on, the compiler replaces ABC with 1. This works well for
statements such as:
set pin = ABC dutsrc: v = 5v;
However, error messages result from something like:
MyFunction()
{
int ABC;
ABC = 7;
return ABC;
}
because the compiler changes this into:
MyFunction()
{
int 1;
1 = 7;
return 1;
}
IMAGE Solutions V8.3 14-7
IMAGE Base Language: Test Program Structure: Header
Table of Contents Index Home Master Index Search Help
Because of this side effect, choose unique pinnames, ones not used elsewhere in the test
program. Also, avoid using reserved words in pinnames.
The pinmap can also specify stored databits, field specifications for groups of pins or
databits, and additional tester resources not specified elsewhere.
Declare the pinmap in the header section of the test program file before the first function in
the file and before any statements referring to DUT pins. If a program uses multiple source
files, the pinmap must be included in every program file. To avoid having multiple copies of
the pinmap, put it in a .h file and use a #include directive in each file used by the test
program. See the instrumentation manual for your tester for information on pinmap
statement syntax.
You can also create test program modules without a pinmap. See “Creating Test Program
Modules Without a Pinmap” on page 14-26.
IMAGE Solutions V8.3 14-8
IMAGE Base Language: Test Program Structure: main() Function
Table of Contents Index Home Master Index Search Help
main() Function
Each test program must contain one function called main(). A program always begins
execution with main(). This function is used to globally set up and reset, query the operator
if necessary, and then call several functions to perform testing. One or more of these
functions is a sequencer function.
In the following main function, a sequencer function that determines a bin number is called
and executed. This bin number is used to sort the device with the sort bin statement. (See
“Testing and Classifying Devices” on page 15-1 on sort bin and other statements.)
main()
{
setup_all_digital(5.0v,0.4v); /*High level setup function*/
printf("Ready to begin testing...\n"); /*Message*/
seq1(); /*execute the SEQUENCER seq1 and assign bin number*/
sort bin; /*perform a sort on the bin number result*/
}
IMAGE Solutions V8.3 14-9
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
Sequencer and Tests
Sequencer Functions
A sequencer function is an ITL specialized function. It contains sequencer statements that
specify a set of tests to be performed, the order of their execution, the test limits, and the
binning strategy. A test program can have more than one sequencer.
A sequencer function is usually called from the program’s main() function to execute a set
of test functions and determine a bin number. It must begin with SEQUENCER in upper case
followed by the function name. The syntax is:
SEQUENCER sname()
{
.
<sequencer statements>
.
}
Figure 14-2 shows that sequencer functions contain sequencer statements which, in turn,
call test functions that contain test statements. A sequencer function returns the bin value
following its execution (see “Test Parameter List” on page 14-13). Although a sequencer
function typically contains only sequencer statements, other statements are allowed.
A sequencer function returns an undefined value. Do not use it in a sort bin statement.
Using a sequencer return value in a sort bin statement may cause devices to be
incorrectly binned. See “The sort bin Statement” on page 15-14.
IMAGE Solutions V8.3 14-10
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
main()
{
<call sequencer function>
}
Sequencer Function
SEQUENCER<name of sequencer
function>()
{
<sequencer statement>
<sequencer statement>
}
Sequencer Statement
• Defines: Test limits
Datalog number
Datalog label
Datalog format Test Function
• Calls test function
• Receives pass or fail result TESTF<name of test function>()
• Takes pass or fail action {
<test statement>
<test statement>
}
Test Statement
• Determines pass or fail
(Limit comparison, for example)
• Datalogs result, if enabled
Figure 14-2. Sequencer and Test Structure in a Test Program
Sequencer Statements
You specify a sequencer statement within a sequencer function. This statement calls a
test function and takes a pass or fail action based on one or more test results determined
by the test function. An example would be:
/*test name test # test limits test label binning*/
seq icc() $2 >20ma <25ma "supply i" f(2);
A sequencer statement has the following effects:
• It calls the specified test function.
IMAGE Solutions V8.3 14-11
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
• Inside the test function, a test statement must be called to make a pass/fail decision on
each test.
• After the test function returns the test result, the sequencer statement evaluates each
result in order and executes the specified pass/fail action.
A sequencer statement includes the name of a test function to be called and a test
parameter list for each test to be performed inside the test function. Each test parameter list
can contain the following information:
• Test limits
• Test number
• Datalog label
• Datalog result format
• Pass action
• Fail action
• Test conditions
• Binning information
All fields are optional. Many fields have defaults if they are not specified.
Sequencer Syntax
A sequencer statement has two forms, simple and compound. The simple form of the
sequencer statement specifies a single test parameter list. It always begins with seq. The
syntax is:
seq <test function> <test parameter list>;
where:
<test function> A specified test function (TESTF) that performs one or more tests
and calls the appropriate test statements internally to determine
pass or fail for each test result and to perform datalogging. A test
function call includes the name of the test function and optional
parameters to the function in parenthesis, as in ileak() or
icc(pnum). See “Test Functions” on page 14-18 and “Test
Statements” on page 14-18.
<test parameter list>
A series of fields that specify test limits, identifying information
and pass or fail information. A test function can have more than
one test parameter list.
A compound sequencer statement specifies a test parameter list for each test and requires
braces ({}) around multiple test parameter lists. The syntax is:
seq <test function>
{ <test parameter list>;
<test parameter list>;
IMAGE Solutions V8.3 14-12
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
<test parameter list>;
}
Test Parameter List
The complete syntax for the test parameter list is as follows:
<test parameter list>:==[<limit spec>] [$<test number>]
[repeat = <repeat val>] ["<datalog label>"]
["%<datalog format>"] [p(<expression>)]
[pa(<statement>)] [f(<expression>)]
[fa(<statement>)]
<limit spec>:==<limit set> | <variable limit set>
| <condition limit spec>
| <close bins limit spec>
<limit set>:==[><lowlim> | >=<lowlim>] [<<highlim> | <=<highlim>]
| [==<limit>] | nolimits
<variable limit set>:==[>(<expr>) | >=(<expr>)]
[<(<expr>) | <=(<expr>)] | [==(<expr>)]
<condition limit set>:==<condition>:<limit set>
<condition>:<limit set>
.
.
[default:<limit set>]
<condition>:==
<condition defined in test_conditions statement>
<close bins limit spec>:==
<limit set> | <condition limit spec> c(<bin list>)
<limit set> | <condition limit spec> c(<bin list>)
.
.
<bin list>:==
<close bin num> | <close bin num> to <close bin num>
| <bin list>, <bin list>
<close bin num>:==<constant in range 1 to 32>
<repeat val>:== <constant in range 2 to 65535>
where:
<limit spec> A value or series of values or series of variable expressions that
specifies the limits a device must meet to pass the test. Limit
specifications can include test conditions and close bin
specifications for disqualify binning.
<test number> The symbol $ followed by an integer constant, as in $1 or $325,
or a variable with the variable name inside parenthesis, as in
$(tnum). A test number uniquely identifies a datalogged result
IMAGE Solutions V8.3 14-13
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
on a printout for data analysis and for user selection. Give all
tests in a program a unique test number. This test number
should not change between separate runs in the same lot. If you
are using more than one sequencer function, explicitly set the
number of the first test in each sequencer so the numbers do not
overlap.
The compiler also has an automatic numbering capacity. If you
do not specify the test number, the compiler automatically uses
the last test number incremented by one. By default, the
compiler starts numbering at 1 at the beginning of each
sequencer function. To set the starting number for a sequencer
or a group of tests, number the first test in the group and the
compiler assigns test numbers for the remaining tests in the
group. For example, to number a sequencer containing 50 tests
starting at 200, specify $200 as the test number for the first. The
compiler assigns numbers to the other tests, resulting in 50 tests
numbered 200 to 249.
repeat=> This field contains a constant between 2 and 65535. See
“Repeated Test Limits” on page 14-17.
"<datalog label>" A quoted string constant of up to 18 characters, such as "supply
i". This character string labels the result on a datalog printout. If
you do not specify a datalog label, IMAGE uses the test function
name specified in the <test function> field as a default.
"<datalog format>" A quoted string constant beginning with the character %. It
specifies the test result format in a datalog printout using
printf-style formats such as %5.2f. (See “Input and Output
Functions” on page 16-1 for an explanation of formatted I/O
functions.) You can optionally place a units string of up to five
characters after the format of the result. For example, "5.2f uA"
uses the string uA for the units. If you do not specify a datalog
format, the compiler uses the format specified in the <limit
spec> field. If you do not specify limits, the compiler uses a fixed
point format with two digits to the right of the decimal point.
When you set the format string of a test, the datalog format
specifier in the STDF file is set as specified. However, the
datalog formatters provided with IMAGE interpret the standard
ASCII formats, e, f, g, c, and s as f (fixed decimal floating point)
and formats u and i as d (decimal integer).
NOTE
The datalogger is limited to 24 bits. High and low test limits cannot exceed this limit.
IMAGE Solutions V8.3 14-14
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
p(<expression>) Specifies an action to be taken if a test passes. If the test passes,
the value of the expression is remembered as a bin number. The
expression can be a bin number or any legal expression. The
expression is always executed, even if the test fails.
pa(<statement>) Specifies an action to be taken if a test passes. If the test passes,
the specified statement is executed. In any case, testing of the
device continues. The statement in pa(<statement>) is only
called if the test passes. This statement can be a function call, a
goto statement, or any other C language statement. It cannot
be an instrument statement.
NOTE
Use of pa() is discouraged. Most test programs that require this syntax can use disqualify
binning. (See “Assigning Bin Numbers Using Disqualify Binning” on page 15-8.)
f(<expression>) Specifies an action if a test fails. If the test fails, the value of the
expression is remembered as a bin number. The expression can
be a bin number or any legal expression. If in stop on fail mode
(the default) and the test fails, the device is “disabled” and no
further testing takes place on the device. If in continue on fail
mode, testing continues. The expression in f(<expression>) is
always executed.
fa(<statement>) Specifies an action if a test fails. If the test fails, the specified
statement or statements are executed. The statement in
fa(<statement>) is only called if the test fails. The statement
cannot be an instrument statement.
NOTE
Use of fa() is discouraged. Most test programs that require this syntax can use disqualify
binning. (See “Assigning Bin Numbers Using Disqualify Binning” on page 15-8.)
limit set Indicates the test limit values for a test, either the low or the high
limits or both or an exact value or no limits.
lowlim The lower test limit is the symbol > or >= followed by a floating
point constant or variable, as in >=4.5mv, >-20db, or >(low).
The test result must be greater than or equal to the specified
value for the test to pass.
highlim The high test limit is the symbol < or <= followed by a floating
point constant or variable, as in <8.4mv, <5db, or <=(high). The
test result must be less than or equal to the specified value for
the test to pass.
IMAGE Solutions V8.3 14-15
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
limit The symbol == followed by an integer constant or variable, as in
==0x564 or ==1. The test result must exactly equal the specified
value to pass. The equality operator is only supported for integer
values, not floating point, and is used with a single integer test
limit. The compiler flags an error if you specify more than one
limit and one or both use the equality operator.
condition A test condition declared in the test program. Typically, test
conditions are used to specify testing under hot, cold, or room
temperature conditions. (See “Test Conditions” on page 15-27.)
condition limit set
Specifies different test limits depending on the current test
conditions for a test result. (See “Test Conditions” on page
15-27.)
close bins limit set
A set of limits that includes bins to close for disqualify binning.
Limit sets can also include test conditions. (See “Assigning Bin
Numbers Using Disqualify Binning” on page 15-8.)
c(<bin list>) Indicates which bin or bins to close if a test fails. The close bin
list can be a single bin number, several bin numbers separated
by commas, or a range of bins separated by the word to. Bin
numbers can be from 1 to 32.
Sequencer Statement Examples
• A simple sequencer statement with one result, a test number, a high and a low limit, and
a fail bin:
seq in_leak() $10 >-10ua <10ua f(0);
• Statement above with a pass bin added:
seq in_leak() $10 >-10ua <10ua f(0) p(1);
• Statement above with datalog label added but no pass bin:
seq in_leak() $10 "input leak pin 14" >-10ua <10ua f(0);
• Statement above with a datalog format added:
seq in_leak() $10 "input leak pin 14" "%4.2f ua" >-10ua <10ua f(0);
• A compound sequencer using multiple results:
seq codec(3db)
{ $20 "receive gain 3db" > -.25db < .25db f(2);
$21 "receive sign 3db" > 37 f(2);
$22 "transmit gain 3db" > -.25db < .25db f(3);
$23 "transmit sign 3db" > 37 f(3);
}
IMAGE Solutions V8.3 14-16
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
See “Disqualify Binning Syntax” on page 15-8 and “Test Conditions in a Sequencer” on page
15-28 for additional sequencer examples using disqualify binning and test conditions
statements.
Repeated Test Limits
Test statements must be mapped one-to-one to the test parameter lists in sequencer
statements. Simple sequencer statements specify only one test parameter list, and the test
function must contain one test statement. In compound sequencer statements, the test
function must call one test statement for each test being performed. The first call to the test
statement should correspond to the first test parameter list specified in the sequencer
statement. The second call to the test statement should correspond to the second test
parameter list, and so on.
In some cases, especially in test programs used to characterize device performance, you
must compare many values to a single set of limits. An example would be the 4096 output
values obtained from a 12-bit DAC by applying each of the possible input codes. The test
may require that the error between the ideal value and the measured value for each code
be compared to a set of limits. Instead of repeating these limits 4096 times in a compound
sequencer statement, you can specify a repeat value in the sequencer statement. For
example:
seq dac_error() "bit error" $10000 repeat=4096 >-1.22mv <1.22mv f(3);
In this example, the test function dac_error calls a test statement 4096 times using a for
statement in the test function. Each of these 4096 values is compared to the set of limits
specified on this one sequencer line because of the repeat=4096 clause. The device fails
in bin 3 if any of the 4096 values is outside the limits. If datalogging is turned on for this test,
all 4096 values are datalogged. The test number of the first result is 10000, the second is
10001, and so on up to test number 14095.
This option can create a large amount of datalog information. If this is undesirable, use the
following statement to turn off data collection for these tests:
set testf_cond:datalog:disable
See “Changing the Default Behavior of a Test Statement” on page 14-21.
Note that the repeat option does not work correctly when the test number is specified as a
variable.
Changing Test Labels When Using Repeat
If you use repeat in the sequencer line, subsequent tests use the same label on all tests.
IMAGE includes a function, tl_write_label(), that allows you to change the label string
on all tests. (This is the default behavior for this function in V5.7 and later. See
“tl_write_label” on page 26-511.)
Before V5.7, tl_write_label() changes the label only on the first test. (Subsequent tests
use the same label.) You will continue to get this behavior in programs compiled under
IMAGE V5.6 and earlier versions. You can also continue to get this behavior in programs
IMAGE Solutions V8.3 14-17
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
compiled under V5.7 and later by using the variable_labels_in_repeat IMAGE
Behavior Chooser. See the Behavior Chooser section of IMAGE Help and “Using the
IMAGE Behavior Chooser” on page 5-12 for more information.)
Test Functions
A test function is a specialized function called from a sequencer statement to perform one
or more tests. Inside a test function, you can:
• Set up tester instrumentation to provide an input stimulus to a device
• Measure or capture device output
• Analyze the results to obtain one or more test results
• Call a test statement with each test result to make a pass/fail determination and to
datalog the result
• Include other ITL and C statements to modify the behavior of test statements
A test function must be called by a sequencer statement. It must begin with the word TESTF
in upper case preceding the function name in a function definition. The syntax of the test
function is:
TESTF tname()
{
<ITL language statements>
.
.
<test statement>
.
}
Test Statements
A test statement performs two main operations:
• It determines pass or fail on a test result you specify.
• It datalogs the result if datalogging is enabled.
A pass or fail determination can be made in different ways depending on the type of test
statement. For a simple analog parametric test, the test result is compared with the test
limits specified in the corresponding test parameter list in a sequencer statement.
The test statement and sequencer statement work together. The sequencer statement
stores the test limits and datalogging information for each test result. The test statement
accesses this information and uses it to make a pass or fail decision and to perform
datalogging. The test statement stores the pass or fail decision so that the sequencer
statement can use it to take a pass or fail action.
A test statement can have several forms. The basic form of a parametric test statement
allows you to specify a numerical result calculated or measured inside a test function. The
syntax is:
IMAGE Solutions V8.3 14-18
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
test <result> [pass | fail];
where:
result Is any arbitrary expression that evaluates to a number. The test
statement compares this result to the limits specified in the
corresponding test parameter list.
pass Force the test to pass. The limit comparison is ignored and the
test passes unconditionally. If the test statement includes a
result, it is datalogged as the result of the test. If the test
statement does not specify a result, only a pass is datalogged.
fail Force the test to fail. The limit comparison is ignored and the test
fails unconditionally. If the test statement includes a result, it is
datalogged as the result of the test. If the test statement does not
specify a result, only a fail is datalogged.
The following simple test statement uses the variable myresult to specify the result:
test myresult;
The next example uses the value returned from the read_meter function:
test read_meter();
In the following example, the result is the value of an expression which is the read_meter
result multiplied by 0.75:
test read_meter() * .75;
Test statements must be mapped one-to-one to the test parameter lists in sequencer
statements. In a simple sequencer statement, only one test parameter list is specified, and
the test function must contain one test statement. For example:
SEQUENCER seq1()
{ /*beginning of sequencer*/
/*
test function test test limits test binning
name # low/high label fail/pass*/
seq contin() $1 >0 <.7v "continuity" f(0);
seq icc() $2 >20ma <25ma "supply i" f(2);
seq ac() $3 >1.55v <1.62v "amplitude" f(3) p(1);
} /*end of sequencer*/
TESTF icc()
{ /*beginning of test function*/
double supply_i; /*declare local variable*/
set pin=VCC dutsrc:v=5.125v; /*set up dc source*/
set meter input:pin=VCC dutsrc:i; /*set up dc meter*/
set power on: dc; /*turn power on*/
wait 10ms; /*wait for device to settle*/
supply_i=read_meter(); /*read dc voltmeter*/
test supply_i; /*test the result against limits*/
} /*end of test function*/
IMAGE Solutions V8.3 14-19
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
This example, shows the sequencer and icc test from a test program. The test sources a
voltage to the DUT and reads the result. In this test function, the test statement test
supply_i is used to test the result against the limits for the test. The value of supply_i is
obtained from the read_meter function. This value is compared against the limit in the seq
icc() line in the sequencer.
In a compound sequencer statement, the test function must call one test statement for each
test being performed. The first call to the test statement should correspond to the first test
parameter list specified in the sequencer statement. The second call to the test statement
should correspond to the second test parameter list specified, and so on.
This type of test statement uses a software limit comparison to determine pass or fail. The
datalogger is called to log the result if datalogging is enabled. The datalogger is passed the
test result, the pass or fail decision, and the test number, label, and format specified in the
test parameter list for this test. The test statement stores the pass or fail decision so that the
sequencer statement can access it later to determine whether to take a pass or fail action.
You can add the reserved words pass or fail to the end of a test statement to force pass
or force fail. If you specify a result, it is datalogged as the result of the test. If you do not
specify a result, no value is datalogged, only the fact that the test passed or failed. Examples
are:
test myresult pass; /*force pass, datalog myresult*/
test myresult fail; /*force fail, datalog myresult*/
test pass; /*force pass, no value datalogged*/
test fail; /*force fail, no value datalogged*/
Reading the Status of a Test
After a test statement executes, you can call a function to determine the status of the test.
The function read_test_status() returns the following:
PASSED(1) Test passed.
FAILED(2) Test failed.
(PASSED | FAILED)(3)
Using disqualify binning and the test failed one set of limits but
passed an alternate set of limits.
(-1) No tests have executed.
These uppercase keywords are built-in macros in ITL. Here is an example of how you can
use this function:
test read_meter();
if (read_test_status() == FAILED)
printf("print important failure information here\n")
You can use this function anywhere in a test program. It returns the status of the last test
executed, or -1 if no tests have executed.
IMAGE Solutions V8.3 14-20
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
Use the function, read_test_status_alarm() to determine if an alarm occurred. This
function returns TRUE(1) if an alarm occurred on the last test and FALSE(0) if it did not.
Changing the Default Behavior of a Test Statement
By default, a test statement used inside a test function exhibits certain behavior. It datalogs
unconditionally if datalogging is turned on. There is a one-to-one correspondence between
test statements and test parameter lists appearing in the sequencer statement that the test
function is called from. Under certain circumstances you may want to override these
defaults.
You may want to perform several tests internally but not datalog at all, even if datalogging
is turned on. Or you may want to loop on a single test calling the test statement many times
with the same limits. In this case you do not want each call to the test statement to
automatically use a new test parameter list.
Use the following set statement in a test function to override the default behavior of a test
statement inside a test function. (testf_cond stands for “test function conditions.”)
set testf_cond: datalog: enable | disable
test_params: incr | hold
test_params: index= <n | var>;
where:
datalog: enable | disable
enable (the default condition) means datalog if datalogging is
turned on. disable means do not datalog any tests in this test
function even if datalogging is turned on.
test_params: incr | hold
Specifies which set of limits in a compound sequencer statement
to use with the next test statement. incr (the default condition)
means increment to the next test parameter list after each test
statement so that the next test statement executed uses the
information from a new test parameter list. hold means do not
increment to the next test parameter list after each test
statement. While hold is on, each test statement called uses the
information (such as limits) from the same test parameter list.
NOTE
If you use this statement to override the default test function conditions inside a test
function, the changes are only valid for that test function. At the beginning of each test
function, the conditions are automatically reset to their default state.
test_params: index= <n | var>
Specifies the order of test parameters in a compound sequencer.
By default, each test statement executed in a test function uses
IMAGE Solutions V8.3 14-21
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
the next test parameter list in the sequencer. The index can be a
constant or a variable and specifies which test parameter list to
use. 0 specifies the first test parameter list, 1 the second, and so
on.
The index option is useful when a test is conditionally skipped. Take, for example, the
following sequencer:
seq offset_gain()
{ $100 "ac offset" >-2.1v <2.1v f(4);
"ac offset drift" >-0.3v <0.3v f(5);
"ac gain" >3.95v <4.05v f(4);
}
In test function offset_gain you could set up the following test condition:
test ac_offset; /* "ac offset" test result */
if (read_test_condition() == HOT) /* Do "ac offset drift" only */
test calc_offset_drift(); /* if test condition is HOT */
set testf_cond: test_params: index = 2;/* Make sure last limits are */
test ac_gain; /* used for "ac gain" test */
NOTE
If any tester statements affecting a test are executed, for example tl_write_lowlim() or
tl_write_label(), the set testf_cond: test_params: index= statement must be
executed before these statements. In other words, these statements must appear between
the set testf_cond: statement and the test statement.
Executing Statements After a Test Statement
The structure of a TESTF allows you to include ITL and C statements after test statements.
If such statements are executed after a test statement and the test passes, everything
executes as you would expect.
If, however, a test fails, the ITL or C statements will not reprogram the instruments unless
the test mode is set to cont_on_fail. At this point, the test failure terminates the TESTF.
Disabling and Enabling Device Testing
When a test program begins executing, the device under test is “enabled” and tested using
the statements in the test program. This continues until the end of the test program unless
all of the following happen:
• The device fails a test
• The test was called from a sequencer statement that specified a fail bin number (such
as f(2))
• The program is running in stop on fail mode (the default)
IMAGE Solutions V8.3 14-22
IMAGE Base Language: Test Program Structure: Sequencer and Tests
Table of Contents Index Home Master Index Search Help
In this case, the device is “disabled” and no further testing is performed. If you use disqualify
binning and the program is running in stop on fail, the device is disabled when all pass
bins are closed.
Disabling the device under test means that no additional instrument programming takes
place and that no additional test or sequencer functions are called. This effectively
terminates testing on the device.
However, noninstrument statements in the test function following the failed test and
statements between sequencer statements following the failed sequencer statement
continue to execute. You can use the statement tl_site_active() to avoid executing
these statements. For example:
sequencer1()
{
seq test1() $1 >5ma <10ma f(2); /* If the device fails this test */
if (tl_site_active())
printf("About to do test2.\n"); /* Then this is not executed */
seq test2() $2 >0v <2.7v f(2);
}
You can re-enable testing on a device using the statement:
set site_enable_all;
You can use this statement to continue testing a device after it fails. Use it, for example, to
grade devices. After a device fails in one sequencer with tight limits, the set
site_enable_all statement can be used to allow a second sequencer to be called with
looser limits.
IMAGE Solutions V8.3 14-23
IMAGE Base Language: Test Program Structure: Datalog and Summary Statements
Table of Contents Index Home Master Index Search Help
Datalog and Summary Statements
As described in “Test Statements” on page 14-18, test statements automatically perform
datalogging for tests called from the sequencer function. You may need to datalog a
program variable value that is not a test result mentioned in a sequencer statement. You
may also need to write arbitrary text (such as carriage returns and header lines) to the
datalog stream to format datalog output.
Datalogging Program Variable Values
To datalog program variable values, use the syntax:
datalog <value> $<number> ["<datalog label>"] ["%<dataformat>"];
where:
<value> The value to be datalogged (either a constant or an expression).
<number> The test number (an integer expression) identifies the data value
on the datalog report. Examples are: $1, $10, and $325. This
number is for user selection and for data analysis. You can also
use a variable by placing the variable name inside parentheses,
as in $(tnum). Use a variable to increment the test number in a
loop. The test number is required.
"<datalog label>" A character string of up to 18 characters enclosed in double
quotes, such as "input leak pin 12". This string labels the
value that appears in a datalog report. If you do not specify a
label, the name of the variable specified in the <value> field is
used as a default.
"%<dataformat>" A format string that specifies how the value will be printed, such
as "%5.2f db". This string is in printf format and includes a
units field of up to six characters. (See“Additional Methods of
Controlling Datalog From a Test Program” on page 6-75
and“printf()” on page 16-4.)
Examples of datalog statements are:
datalog iresult $100 "program variable" "%3.1f ua";
datalog ivalue $(index) "interesting value" "%4.2f mv";
Writing Text to a Datalog Report
The lprintf() function allows you to write a formatted string of characters to a datalog
report. lprintf operates in the same way as printf except that the output is sent to the
datalog stream. The syntax for using lprintf is:
lprintf("%<format>", var1, var2, ...);
where:
IMAGE Solutions V8.3 14-24
IMAGE Base Language: Test Program Structure: Datalog and Summary Statements
Table of Contents Index Home Master Index Search Help
<format> Is a string of up to 256 characters that can include format
specifiers for variables. (Longer strings are truncated.) lprintf
converts the format of the variable values and creates a string of
ASCII characters that is sent to the datalog stream.
Examples of lprintf statements are:
lprintf("**** continuity tests ****\n");
lprintf("Pin %d failed leakage\n", pinlist[j]);
The string appears in the datalog stream immediately after the last test result, intermediate
value, or string that has been recorded. Be sure to place the lprintf statement so that the
output appears where you want it on the datalog report.
The text string is printed on the datalog report if the test in which it is generated is
datalogged. If the lprintf() call is not in a test, a string for that test only appears on the
report if all tests are selected to be datalogged.
Two additional functions allow you to write a formatted string of characters to a datalog
report:
Lprintf() Print a formatted string to the datalog report regardless of
datalog mode.
Mprintf() Print a formatted string to the datalog report regardless of
datalog mode or binning status.
The format for these functions is the same as for the lprintf function.
Writing to a Summary Report
The smprintf() function allows you to write a formatted string of characters to a summary
report. smprintf operates in the same way as printf, except that the output is sent to a
summary report. The syntax is:
smprintf("%<format>", var1, var2, ...);
where:
<format> Is a string of up to 256 characters that can include format
specifiers for variables. (Longer strings are truncated.) smprintf
converts the format of the variable values and packages a string
of ASCII characters that are sent to the summary report. You
must specify the complete string in one smprintf call. A second
call to smprintf overwrites the first one.
The text string appears in the summary report immediately following the header information
and before the bin counts. This allows you to customize summary reports with your own
header information. For example, the following would create columns for mean and
standard deviation values:
smprintf("Mean= %5.2f; Standard Deviation= %5.2f\n", mean, stddev);
IMAGE Solutions V8.3 14-25
IMAGE Base Language: Test Program Structure: Creating Test Program Modules Without a Pinmap
Table of Contents Index Home Master Index Search Help
Creating Test Program Modules Without a Pinmap
Any IMAGE test program that uses pin programming must use a pinmap or a DIBView
schematic. At times, however, you may wish to create test program modules without a
pinmap (pinmapless). This allows you to write generic main() functions or other test
program modules that you can use in a number of test programs.
Creating a test program using modules without a pinmap requires creating:
• A pinmap file
• Pin name or pin field declarations
Creating a Pin Map File
Use the keyword TL_PINMAP to declare a pin map. This keyword is required for pinmapless
programming. If you use it, it must appear in a .tl file before the first function in the file and
after the pinmap statement. A simple example of a file pinmap.tl would be:
pinmap = {
1 "VCC" dib:27a1 dutsrc,
};
TL_PINMAP;
Using TL_PINMAP causes two things to happen:
• The compiler defines a global variable for each pin name in the pinmap.
• The data structure containing pinmap information is created at this point in the program,
instead of being associated with the main() function.
Since a set of global variables is defined for the pin names, a reference to one of these
names in a module compiled without a pinmap points to the global variable.
Declaring Pin Names and Fields
Pin names and pin fields (groups of pins) must be declared in each file that includes pin
programming syntax if the file does not include a pinmap. The syntax for these declarations
is
extern TL_PINNAME <pinname>;
Defines a pin name.
extern TL_PINFIELD <fieldname>;
Defines a field (group of pins).
For example, the declaration for a pin named VCC would be:
extern TL_PINNAME VCC;
You can declare pin names and fields by including a separate header file with the
declarations. Declaring extra names in this file is not harmful, so you can create a large
header file with all commonly-used pin names.
IMAGE Solutions V8.3 14-26
IMAGE Base Language: Test Program Structure: Creating Test Program Modules Without a Pinmap
Table of Contents Index Home Master Index Search Help
You can also declare pin names and fields by declaring them at the top of each file. This
means that each file would include declarations for the pin names used in that file.
One file cannot include both the pinmap and the declarations for pin names and fields. One
file should contain either the pinmap or the declarations.
Lists of pins are not supported but field notation is allowed. For example, you cannot use:
set pin = (DBUS1, DBUS2) ...
But you can define these pins as a field in the pinmap. For example:
set pin = (FIELD1) ...
Debug displays will work for any declared pins. If all pin names in the pinmap are not
declared in a file, however, a display cannot manipulate any undeclared pins.
Test Program Example
The following shows a test program written with the pinmap in the same file as the
sequencer and test function code. This example illustrates separating the test program into
modules with each module including the full pinmap.
/* Pinmap file - "pinmap.h" */
pinmap = {
1 "VCC" dib:27a1 dutsrc,
};
/* File "a.tl" */
#include <stdio.h>
#include <math.h>
#include <image.h>
#include "pinmap.h"
main()
{
seq1();
sort bin;
}
SEQUENCER seq1()
{
seq test1() < 1ma f(2) p(1);
}
/* File "b.tl" */
#include <stdio.h>
#include <math.h>
#include <image.h>
#include "pinmap.h"
TESTF test1()
{
set pin = VCC dutsrc: v = 5.0v;
set meter input: pin = VCC dutsrc: i;
IMAGE Solutions V8.3 14-27
IMAGE Base Language: Test Program Structure: Creating Test Program Modules Without a Pinmap
Table of Contents Index Home Master Index Search Help
test read_meter();
}
The following shows the same test program rewritten to place the pinmap in a separate file
from the sequencer and test function code and to organize the program code into multiple
files (modules):
/* Pinmap file - "pinmap.tl" - This is now a ".tl" file. */
#include <image.h>
pinmap = {
1 "VCC" dib:27a1 dutsrc,
};
TL_PINMAP;
/* Pin name file - "pinnames.h" */
extern TL_PINNAME VCC;
/* File "a.tl" */
/* This file is now generic. It does not need the pinmap or "pinname.h". */
#include <stdio.h>
#include <math.h>
#include <image.h>
main()
{
seq1();
sort bin;
}
SEQUENCER seq1()
{
seq test1() < 1ma f(2) p(1);
}
/* File "b.tl" */
#include <stdio.h>
#include <math.h>
#include <image.h>
#include "pinnames.h" /* This file needs "pinnames.h" */
TESTF test1()
{
set pin = VCC dutsrc: v = 5.0v;
set meter input: pin = VCC dutsrc: i;
test read_meter();
}
Creating Modules That Use the TMS
Compiling a program without a pinmap that includes the Time Measurement Subsystem
(TMS) has an additional requirement. The compiler generates test head specific code for
some TMS statements. When compiling such statements, the compiler must know the test
head type being targeted. It usually gets the head type from the pinmap. When a pinmap is
IMAGE Solutions V8.3 14-28
IMAGE Base Language: Test Program Structure: Creating Test Program Modules Without a Pinmap
Table of Contents Index Home Master Index Search Help
not included, the compiler gets the type from other statements in the program. When such
statements do not precede a TMS statement, an error results.
Therefore, to create modules without a pinmap that include the TMS, use the following
macros:
TL_TSTHD_MS Defines a mixed-signal test head (A540).
TL_TSTHD_AMS Defines an advanced mixed-signal test head (A580).
These macros are defined in the IMAGE header file image.h and will produce a hardware
programming statement which will identify the test head type to the compiler. Each function
using the TMS should include this macro before the TMS statement. The macro definitions
include a conditional statement so that the hardware statements are not executed at run
time. The definitions look like this:
#define TL_TSTHD_AMS \
{static int dummy=0; if (dummy)
<AMS specific statement>;}
IMAGE Solutions V8.3 14-29
IMAGE Base Language: Testing and Classifying Devices
Table of Contents Index Home Master Index Search Help
15 TESTING AND CLASSIFYING DEVICES
This section describes ITL statements that allow you to set and control tester functions and
to read parameters from within a test program. These tester-specific statements relate to
programmed waits, assigning bin numbers, run-time errors, and accessing system
information.
This section includes the following topics:
• “Testing Functions” on page 15-2
• “Assigning Bin Numbers” on page 15-6
• “Assigning Bin Numbers Using Disqualify Binning” on page 15-8
• “Monitoring Maximum Consecutive Failures” on page 15-16
• “The Input Adjust Function” on page 15-20
• “Test Conditions” on page 15-27
• “Controlling Run-Time Errors” on page 15-31
IMAGE Solutions V8.3 15-1
IMAGE Base Language: Testing and Classifying Devices: Testing Functions
Table of Contents Index Home Master Index Search Help
Testing Functions
The following subsections describe programming statements you can use in a test program
during testing.
Wait Statement
The wait statement causes a program to wait for a specified amount of time. Syntax for the
wait statement is:
wait <expression>;
where:
<expression> Must evaluate to a floating point number that represents the
number of seconds to wait.
The test program waits for the specified amount of time, then continues at the next
statement. The minimum wait is 10µs and the resolution is 10µs.
Rdelay Function
After relays are opened or closed, a hardware settling time delay is required before starting
a measurement. Since ITL statements that open and close relays return without waiting for
this delay, you must provide the delay to be sure hardware has settled. The following
function executes the necessary delay:
rdelay();
Certain language statements, such as set power on and all read_meter() functions, do
perform an rdelay.
Test Program Timing and CPU Speed
IMAGE test programs can be structured to make their timing rely on the speed of the test
computer CPU. This is called “implicit timing.” This method of programming is undesirable
because it causes test programs to malfunction when they are executed on a tester with a
faster test computer CPU.
An example of implicit timing is:
TESTF slewtest() {
double result1, result2;
set src= 1 vrng= 5v v=0.1v;
set meter input:src= 1:v wmd= 10us;
set power on:dc;
result1= read_meter();
test result1;
IMAGE Solutions V8.3 15-2
IMAGE Base Language: Testing and Classifying Devices: Testing Functions
Table of Contents Index Home Master Index Search Help
set src= 1 vrng= 5v v= 4.9v slew:slow;
/* 940 us needed for slew to complete */
/* setup sine array for next test while waiting */
calc_simple_sinedata();
/* wait for src to slew */
wait 0.18ms;
result2 = read_meter();
test result2;
set power off:dc;
}
The above code was written to be as efficient as possible. When optimizing the program,
the test engineer realized that some future setup or calculation could be performed while
waiting for the slew of the DC source to complete. Once the call to
calc_simple_sinedata() was added before the wait, the wait was reduced to the
minimum wait time required for the slew to complete. The total wait is now the implicit time
it takes for calc_simple_sinedata(), plus the explicit wait of 180 µs.
When this code is executed on a tester with a faster test computer CPU, the total wait time
is now less than 940 µs. This occurs because it now takes less time to execute
calc_simple_sinedata().
The optimization of executing calc_simple_sinedata() while waiting for the DC source
to slew is a good one. However, the method of implementing the required wait causes the
program to become nonportable.
IMAGE utility functions exist to handle this situation. The following code contains the same
optimization and is entirely portable:
TESTF slewtest() {
double result1, result2;
set src = 1 vrng=5v v=0.1v;
set meter input:src=1:v wmd=10us;
set power on:dc;
result1 = read_meter();
test result1;
set src = 1 vrng=5v v=4.9v slew:slow;
/* 940 us needed for slew to complete */
tl_set_wait(940us);
/* setup sine array for next test while waiting */
calc_simple_sinedata();
/* wait for src to slew */
tl_wait_wait();
result2 = read_meter();
test result2;
IMAGE Solutions V8.3 15-3
IMAGE Base Language: Testing and Classifying Devices: Testing Functions
Table of Contents Index Home Master Index Search Help
set power off:dc;
}
In the example the statement tl_set_wait(940us); is used to indicate that an event was
just started that requires 940 µs to complete. The function tl_wait_wait() indicates that
an event is about to take place that depends on a previous event having completed. If
940 µs have passed since the tl_set_wait() function, tl_wait_wait() does nothing. If
940 µs have not yet passed, tl_wait_wait() waits until the specified wait interval
completes.
Set/wait wait functions cannot be nested. However, multiple set_wait statements can
occur before a tl_wait_wait(). In this case each set_wait function sets the interval timer
to its wait time if and only if that time is longer than the time remaining on the timer from a
previous tl_set_wait() call. For example:
tl_set_wait(1ms); /* sets wait interval timer to 1ms */
tl_set_wait(0.5ms); /* does nothing since there is already more than
0.5ms on the timer */
wait 2ms; /* timer expires */
tl_wait_wait(); /* does nothing since timer already expired */
tl_set_wait(.5ms); /* sets wait interval timer to .5ms */
tl_set_wait(1ms); /* sets wait interval timer to 1ms */
tl_wait_wait(); /* waits for wait interval timer to expire */
Correct use of the set/wait wait functions can remove many portability problems which can
occur when moving a test program to a tester using a test computer with a faster CPU. The
wait functions used in the examples are explained in the following sections.
tl_set_wait
NAME tl_set_wait—Set a retriggerable wait time.
SYNOPSIS void tl_set_wait(delay_time)
double delay_time;
DESCRIPTION Set up a timer to wait at least delay_time. The timer is set to
delay_time and then starts to count down to zero. If a new
delay_time is sent while the timer is still running, the counter is
increased if the new time is longer than time remaining. This
allows concurrence of overlapping settle waits.
The precision of the timer is 1 µs. All delay times are rounded up
to the next 1 µs.
Note that delay times have no upper bound, but a two minute
timeout period is built in to the tl_wait_wait() function.
ARGUMENTS double delay_time—The time to wait in seconds (will be
rounded to next highest 1 µs)
RETURN VALUE None
IMAGE Solutions V8.3 15-4
IMAGE Base Language: Testing and Classifying Devices: Testing Functions
Table of Contents Index Home Master Index Search Help
tl_wait_wait
NAME tl_wait_wait—Start Terabus settling delay timer
SYNOPSIS void tl_wait_wait();
DESCRIPTION Wait for wait timer done. In case of timer hardware problems,
there is a two minute timeout on the wait. If the remaining wait
period will be legitimately longer than two minutes,
tl_set_wait() and tl_wait_wait() are not recommended.
ARGUMENTS None
RETURN VALUE None
IMAGE Solutions V8.3 15-5
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers
Table of Contents Index Home Master Index Search Help
Assigning Bin Numbers
As outlined in “Test Program Structure” on page 14-1, each test program contains a series
of tests and binning instructions for the devices tested. Testing of a device usually continues
until a bin number is determined for the device. This bin, called a software bin, may be a
pass bin for a good device or a fail bin for a bad device. In normal production, testing stops
as soon as a proper bin number for a device is determined. For characterization, however,
testing may continue until all tests are executed.
Usually, the next step is to a assign final bin number called a handler bin or hardware bin
number. This is the number sent to a handler that determines how the devices are
separated into categories. The software bin number and the handler bin number may or
may not be the same. (See “The device_bins Declaration” on page 15-13.)
The way in which a given test affects binning is specified in sequencer statements used in
the sequencer function. The current binning status can also be used to affect the flow
through the test program.
IMAGE supports two methods of specifying binning for a test:
• Direct binning
• Disqualify binning (see “Assigning Bin Numbers Using Disqualify Binning” on page 15-8)
NOTE
Use either direct binning or disqualify binning in a test program, but not both. If you mix the
two types of binning, the direct assignment of a bin always takes precedence.
Direct Binning
Direct binning uses simple sequencer statements to assign a bin number to a device, as in:
seq cal() $100 "ac offset" >-2.1v <2.1v f(4);
In a simple test program, testing proceeds sequentially through each test until a test fails.
At this point, a bin number is assigned and testing usually stops. If the device passes all
tests, the last test generally assigns the device to a pass bin (such as bin 1). IMAGE
supports binning for bins 0 to 255.
You can program more complex binning strategies using multiple sequencer functions or
fail and pass actions. For example, a program can include several sequencers with each
sequencer determining a bin number. A final bin number can then be calculated based on
the bin numbers from the individual sequencers.
Pass Actions
A pass action, written as p(<expression>) or pa(<statement>) or both, specifies an
action to be taken if the test passes. If you use p(<expression>) and the test result
passes, the value of the expression is remembered as a bin number. Any legal expression
IMAGE Solutions V8.3 15-6
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers
Table of Contents Index Home Master Index Search Help
is allowed, although typically a constant bin value is used. You can also call a function to
achieve some side effects, as in p(getbin()).
If you use pa(<statement>) and the test result passes, the specified statement or
statements are executed. In either case, testing of the device continues. This statement can
be a function call, a goto statement, or any other C language statement. It cannot be an
instrument statement such as a set, reset, start, stop, or move. At this point, a goto
statement is often used to change the flow of the sequencer.
The expression in p(<expression>) is always executed. If, for example, the expression is
a function call such as p(calc_bin_number()), this function is called to determine the pass
bin number even if the test fails. The bin number is only used if the test passes. The
statement in pa(<statement>) is only called if the test passes.
Fail Actions
A fail action, written as f(<expression> or fa(<statement>) or both, specifies an action
if the test fails. If you use f(<expression>) and the test fails, the value of the expression
is remembered as a bin number. Any legal expression is allowed, although typically a
constant bin value is used. If in stop on fail mode (the default) and the test fails, the device
is “disabled” and no further testing takes place on the device. If in continue on fail mode,
testing continues. If you use fa(<statement>) and the test result fails, the specified
statement or statements are executed and testing of the device continues. The statement
in fa(<statement>) cannot be an instrument statement such as set, reset, start, stop,
or move.
The expression in f(<expression>) is always executed. If, for example, the expression is
a function call such as f(calc_bin_number()), this function is called to determine the fail
bin number even if the test passes. The bin number is only used if the test fails. The
statement in fa(<statement>) is only called if the test fails.
NOTE
The use of fa() and pa() is discouraged. Most test programs using these constructs can
use disqualify binning instead.
IMAGE Solutions V8.3 15-7
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers Using Disqualify Binning
Table of Contents Index Home Master Index Search Help
Assigning Bin Numbers Using Disqualify Binning
Although direct binning can be used for complex binning strategies, disqualify binning
provides additional flexibility. Disqualify binning allows you to specify a set of bins as “open”
before testing a device. You can declare each bin as a pass or a fail bin using a
device_bins declaration. Each failed test may disqualify or “close” one or more bins. In
normal production testing, testing stops before the end of the test program if all pass bins
are closed. The part is binned in the lowest numbered open bin.
Disqualify binning simplifies construction of a binning strategy for grading devices. For
example, bins 1, 2, and 3 may all be pass bins, but top grade devices need to be binned in
bin 1, second grade devices in bin 2, and third grade devices in bin 3. A failed test may
disqualify a device from bin 1 by closing bin 1, but leave bins 2 and 3 open. For
characterization, you can use additional bin numbers to categorize different failure modes.
Disqualify binning is supported for bins 1 through 32.
Disqualify binning also allows you to associate more than one set of test limits with a single
test. For example, if bins 1, 2, and 3 are all pass bins, one set of tight limits can be specified
for bin 1, a looser set of limits for bin 2, and a still looser set of limits for bin 3. If the test then
passes the tightest limits, no bins are closed. If it fails the bin 1 limits, bin 1 is closed. If it
also fails the bin 2 limits, bin 2 is closed, and so on.
For maximum throughput, a test result is not compared to each set of limits specified.
Instead it is compared to the first set of limits that can affect binning. If none of the limits can
affect binning, it is compared to the last set of limits.
For example, bin 1 may have a tight set of limits and bin 2 a looser set of limits. If when
executing this test bin 1 is already closed, the test result is only compared to the bin 2 limits.
If these fail and another set of limits were specified for bin 3, then the test result is also
compared to the bin 3 limits to see if the test passes this alternate set of limits.
In this way a test result is compared to each set of limits that can affect binning until it passes
a set of limits. This algorithm results in most test results in a test program being compared
to only one set of limits and provides maximum throughput for a test program used to grade
devices.
Disqualify Binning Syntax
Specify disqualify binning using a close bin limit specification in a sequencer statement. The
syntax is either of the following:
<limit set> c(<bin list>)
<condition limit spec> c(<bin list>)
where:
limit set Indicates the test limit values for a test, either the low or the high
limits or both or an exact value or no limits.
c(<bin list>) Indicates which bin or bins to close if a test fails. The close bin
list can be a single bin number, several bin numbers separated
IMAGE Solutions V8.3 15-8
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers Using Disqualify Binning
Table of Contents Index Home Master Index Search Help
by commas, or a range of bins separated by the word to. Bin
numbers can be from 1 to 32.
condition limit set
Specifies different test limits depending on the current test
conditions for a test result (see “Test Conditions” on page 15-27).
The following is an example of a simple sequencer statement using disqualify binning:
seq leakage() <50ua >100ua c(3);
In the following example, bin 1 and bins 3 through 5 will close if the device does not pass
the leakage test:
seq leakage() <150ua c(1, 3 to 5);
The following example uses disqualify binning to grade devices into three categories:
seq cal() $100 "ac offset" >-1.2v <1.2v c(1)
>-1.8v <1.8v c(2)
>-2.1v <2.1v c(3);
The following example uses both disqualify binning and test conditions (see “Test
Conditions” on page 15-27):
seq gain() HOT: >-2.7v <2.7v
COLD: >-2.0v <2.0v c(2);
The following example uses disqualify binning:
device_bins =
{
1 "GRADE_1" pass,
2 "GRADE_2" pass,
3 "GRADE_3" pass,
4 "BAD_DEVICE" fail,
};
main()
{
setup();
test_device();
sort bin;
}
SEQUENCER test_device()
{
seq leakage() <100ua c(1 to 3);
seq distortion() >60.0dB c(1)
>55.0dB c(2)
>50.0dB c(3);
seq gain() >4.995 <5.005 c(1)
>4.950 <5.050 c(2, 3);
IMAGE Solutions V8.3 15-9
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers Using Disqualify Binning
Table of Contents Index Home Master Index Search Help
}
In this program, bins 1, 2, and 3 are all pass bins, but for different grades of the device. The
limits for the leakage test are the same for all grades, so all three bins are closed if this test
fails. The distortion test uses separate limits for each grade. The gain test uses one set of
limits for bin 1 and another set for bins 2 and 3. A device is binned in bin 1, 2, 3, or 4
depending on which limits it passes. If the device fails the leakage test, testing stops
immediately since all pass bins are closed. If running in the continue on fail mode, however,
testing continues until the end of the test program.
Restrictions on Limit Values
When you use disqualify binning for a test and specify more than one set of limits, there are
some restrictions on the limits specified. You must specify the tightest limits first, and each
set of limits must be equal to or looser than the previous set. In other words, the low limits
must decrease in value and the high limits must increase in value. This is the case in almost
all testing situations.
In a few situations you cannot write limits in this pyramid fashion. In situations where the
limits cannot be written as progressively looser limits, use a compound sequencer
statement with the limits specified as separate test parameter lists. For example:
seq bias() { $100 >179mv <185mv c(1);
>180mv <187mv c(2);
>182mv <190mv c(3);
}
In the bias test function the programming would be
vbias = read_meter();
test vbias;
test vbias;
test vbias;
}
In this example, the test limits cannot be written in pyramid form since the low limits are
increasing, not decreasing. Using a compound sequencer statement and returning the
same result three times guarantees a comparison to each set of limits.
Datalogging When Using Disqualify Binning
A datalog report shows the test result and limits for each selected test if you select the full
format mode. (See “Datalog Reports” on page 6-13.) Failing test results are marked with an
(F). A test called from a sequencer statement using disqualify binning is considered to have
failed if it fails the last set of limits (the loosest) and to have passed otherwise.
When using disqualify binning, passed tests are further categorized depending on whether
or not they affect binning. If a test causes one or more bins to be closed, but passes an
alternate set of limits, this fact is recorded in the datalog output. In datalog text files, test
IMAGE Solutions V8.3 15-10
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers Using Disqualify Binning
Table of Contents Index Home Master Index Search Help
results which caused bins to be closed, but passed an alternate set of limits, are marked
with a (C). In STDF files, bit 5 in the PARM_FLG of the Parametric Test Result Record
(PTR) is set to indicate a test passed an alternate set of limits. (See “Parametric Test Record
(PTR)” on page 24-24.)
Disqualify binning allows you to specify multiple limits for a test. The datalog output will show
the limits against which the test result was compared. If a test result fails a set of limits and
is compared to more than one set of limits, the last set of limits used are shown in the
datalog report. This case is identified by (C) (since bins were closed) if it passed the last
set of limits or (F) if it failed all limits.
For example, in the example in “Disqualify Binning Syntax” on page 15-8, if the leakage test
result is 50 µA, the distortion test result is 53 dB, and the gain test result is 5.5, the following
datalog output will be generated when datalogging all tests:
1 leakage leakage 50 ua < 100 ua
2 distortion distortion 50.0 dB < 53.0 dB (C)
3 gain gain 4.950 < 5.500 (F) < 5.050
Additional Statements Used With Disqualify Binning
In addition to test results in a sequencer function, bins can be closed or opened using the
following test program statements:
set bins close = <bin_list>;
set bins open = <bin_list>;
where <bin_list> is a constant, a variable, a comma separated list of constant bin
numbers in parenthesis, or a range of bin numbers separated by the word to. Examples are
set bins close = 3;
set bins open = last_bin;
set bins open = (1, 2, 4, 7, 9);
set bins open = (1 to 32) close = (2, 4, 8 to 10);
set bins open and set bins close act only on sites which are currently active. In a
multisite test program this means that any disqualified sites are not affected by these
statements. In a single site test program, if the part has failed or been disqualified, it is not
affected by these statements. If you want to open a bin for a disqualified site to continue
testing on that site, you must precede the set bins open statement with a set
site_enable statement. (See “Enabling, Disabling, and Sleeping a Site” on page 17-22.)
Accessing Bin Status and Bin Numbers
You can access the status of bins in a test program using several test program function
calls:
read_lowest_open_bin()
Returns the lowest open bin number. This is the bin number into
which the device would be binned if a sort bin statement was
executed at this point in the test program. If all bins are closed, it
IMAGE Solutions V8.3 15-11
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers Using Disqualify Binning
Table of Contents Index Home Master Index Search Help
returns NO_BINNING (-1). (See “read_lowest_open_bin” on
page 26-70.)
read_bin_is_open(<bin_number>)
Returns TRUE (1) if the specified bin is currently open. It returns
FALSE (0) if the bin is closed. (See “read_bin_is_open” on page
26-49.)
read_bin_is_pass(<bin_number>)
Returns TRUE (1) if the specified bin was declared as a pass bin.
It returns FALSE (0) if the bin was declared as a fail bin. (See
“read_bin_is_pass” on page 26-49.)
tl_get_last_seq_bin();
Returns the bin assignment in the last sequencer by either a fail
or pass clause (f() or p()). If called from within a sequencer, it
returns the bin assignment from that sequencer. The value
returned is not affected by the test results from any previously
called sequencers. If there are bin assignments in a sequencer,
the returned value will be the bin number of the first assignment.
In a multisite test program, only call this function from inside a
serial block. (See “tl_get_last_seq_bin” on page 26-213.)
tl_get_seq_bin(); Returns the bin number assigned in a sequencer function by
f(<expression>) or p(<expression>). This is the number
used by the sort bin statement. If no bin number was assigned
in a sequencer, NO_BINNING is returned. (See
“tl_get_last_seq_bin” on page 26-213.)
tl_get_sort_bin(); Returns the software bin number assigned by the sort bin
statement or NO_BINNING if no bin number was assigned. (See
“tl_get_sort_bin” on page 26-219.)
tl_get_sort_hbin();
Returns the handler bin number assigned by the sort bin
statement or NO_BINNING if no bin number was assigned. (See
“tl_get_sort_bin” on page 26-219.)
These functions allow you to manipulate bins to handle more complex testing situations.
They also allow you to change the flow of control through a test program depending on the
status of bins. Certain tests can be skipped altogether, for example, if a bin has been closed.
The binstatus command can also be used to access the current status of binning. This
command is most useful in debug to determine the status of binning while stopped at a
breaktrap. The command can also be used after executing a test program to examine the
resulting binning.
The syntax for the binstatus command is:
binstatus [-site #] [-station #]
IMAGE Solutions V8.3 15-12
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers Using Disqualify Binning
Table of Contents Index Home Master Index Search Help
The command prints out information on whether or not the part has been binned and the
current bin numbers, both software bin and handler bin, assigned to the part. When using
disqualify binning, the current open or close status of each bin is also shown.
The device_bins Declaration
Use a device_bins declaration to specify which bins are pass bins and which bins are fail
bins. By default, bin 1 is a pass bin and all other bins are fail bins. You can also use a
device_bins declaration to map software bin numbers to handler bin numbers.
All binning in a test program refers to software bin numbers. Device handlers, however, are
often limited to a small set of bin numbers. You can use a device_bins declaration to
specify the handler bin number to be used for each software bin number. The device_bins
declaration also allows you to specify a bin name for each software and handler bin.
The following is the syntax for the device_bins declaration:
device_bins =
{
<bin_num> ["<bin_name>"][hbin = <hbin_num> ["<hbin_name>"]]
[pass | fail | error],
.
.
};
An example is:
device_bins =
{
1 "GRADE_1" hbin = 1 "GRADE_1" pass,
2 "GRADE_2" hbin = 2 "GRADE_2" pass,
3 "GRADE_3" hbin = 3 "GRADE_3" pass,
4 "FAIL_LEAKAGE" hbin = 9 "FAIL_BIN" fail,
5 "FAIL_DISTORTION" hbin = 9 fail,
6 "FAIL_GAIN" hbin = 9 fail,
99 "RUN_TIME_ERROR" hbin = 9 error,
};
If you do not specify a handler bin number, the handler bin number is assumed to be the
same as the software bin number. If you do not specify pass or fail, bin 1 is assumed to be
a pass bin and all other bins are fail bins.
Bin names are defined as macros and can be referenced anywhere in a test program. The
bin names are also included in summary reports and are available in STDF datalog files.
You can also specify the error bin number in a device_bins declaration. The default bin
number for binning devices that encounter a run-time error is bin 0. You can change this bin
number using the error option in the device_bins statement. The error bin is assumed to
be a fail bin.
Hardware bin assignments have the following restrictions:
• You cannot assign one bin name to any one hardware bin.
IMAGE Solutions V8.3 15-13
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers Using Disqualify Binning
Table of Contents Index Home Master Index Search Help
• You cannot assign any one hardware bin to more than one bin type (pass, fail, error).
For example, the following statement violates both these restrictions:
device_bins =
{
/* SW_Bin SW_Bin_Name HW_Bin HW_Bin Name P/F/E */
1 "SW_Pass_1" 1 "HW_Pass_1" pass,
2 "SW_Fail_2" 1 "HW_Fail_2" fail
}
The sort bin Statement
Use the sort bin statement to assign the final bin number to a device. You can do this
explicitly by saying sort bin=<bin_number>. However, the preferred way to use the sort
bin statement is to not specify a bin number and let IMAGE automatically use the bin
number determined in a sequencer.
If a pass or fail bin number was assigned in a sequencer by f(<bin>) or p(<bin>), this bin
number is used. If a pass or fail bin number was not assigned and disqualify binning is used
in the program, then the lowest open bin number is used. If no bins remain open, the bin
result is NO_BINNING.
A sequencer function returns an undefined value. Do not use it in a sort bin statement.
NOTE
Do not assume that the return value of a sequencer function is a valid bin number. Using a
sequencer return value in a sort bin statement may cause devices to be incorrectly
binned.
For example, in STOP_ON_FAIL mode, if a failure occurs in a previous sequencer, a
NO_BINNING value is returned. Since the value is not a valid bin number, it cannot be used
in a sort bin statement.
To access the bin assigned to a site by a sequencer function, use either tl_get_seq_bin()
or tl_get_last_seq_bin(). See “Accessing Bin Status and Bin Numbers” on page 15-11.
Mapping Bin Numbers to Handler Bin Numbers
You can map software bin numbers to hardware bin numbers using the set handler_bin
statement. The sort bin statement then automatically maps the software bin number to a
handler bin number which is then sent to the handler or prober. The statement has the
following syntax:
set handler_bin bin = <expression> hbin = <expression>
IMAGE Solutions V8.3 15-14
IMAGE Base Language: Testing and Classifying Devices: Assigning Bin Numbers Using Disqualify Binning
Table of Contents Index Home Master Index Search Help
NOTE
The set handler_bin statement is obsolete. Although IMAGE supports this syntax, you
should use the device_bins syntax. (See “The device_bins Declaration” on page 15-13.)
You can use a list of these statements to map all relevant software bin numbers to the
corresponding handler bin numbers. Any bin number not mentioned continues to map to the
same number. Only execute these statements once after loading the test program. This is
best done by including them in the tl_init function. For example:
tl_init()
{
set handler_bin bin = 99 hbin = 9;
set handler_bin bin = 0 hbin = 10;
}
In this example, the handler does not support bin numbers 99 and 0. These are mapped to
other values. If the sort bin statement gets a bin number of 99 or 0, bin number 9 or 10 is
sent to the handler. If the sort bin statement gets any other bin number, that number is
sent to the handler.
You can use the set handler_bin statement to define a real handler bin number for the
software bin value NO_BINNING as shown in this example:
set handler_bin bin = NO_BINNING hbin = 0;
After executing this statement, if a sort bin statement is executed without first having
assigned a bin number, a bin number of 0 is sent to the handler.
IMAGE Solutions V8.3 15-15
IMAGE Base Language: Testing and Classifying Devices: Monitoring Maximum Consecutive Failures
Table of Contents Index Home Master Index Search Help
Monitoring Maximum Consecutive Failures
During production testing it is useful to monitor the maximum number of consecutive
failures. This may indicate a handler with a jammed part or a contact failure in wafer probing
at a particular site. In such cases, operators must be alerted that such a condition exists,
and allowed to take immediate action. This can mean fixing the problem or disabling the site,
in multisite testing, on the handler or prober.
The IMAGE Maximum Consecutive Failing Device (MCFD) monitoring feature provides:
• IMAGE functions, which can be called from the test program
• A command processor to allow user control of MCFD
• Ability to initialize the maximum consecutive failures counter either for individual sites or
all sites
• Ability to reset the max consecutive failure counter for individual sites or all sites
• Ability to turn MCFD monitoring on or off
• Ability to query the state of MCFD (on or off)
• Ability for a user function to be called whenever a MCFD failure is triggered for a
particular site
• Display of an error message to alert the operator whenever the maximum consecutive
failures is triggered on a particular site. The error message uses the tl_error()
mechanism. IMAGE does not disable a particular site, since this must be done from the
handler or prober.
General Operation of Maximum Consecutive Failures
The MCFD feature requires you to have the device_bins statement in your test program
header or to have designated passing and failing bins using appropriate IMAGE function
calls. If this requirement has not been met, MCFD will not work and the operator is alerted
by a run-time error when any MCFD function is invoked. (See “The device_bins Declaration”
on page 15-13.)
You can set MCFD counters separately for individual sites by calling initialization functions
from within a serial loop, or you can assign one value for all sites. Therefore, each counter
may potentially have a different value or some sites may not have been set at all. If you
specify sites individually, only those sites for which the counter has been set are monitored
for MCFD.
Whenever a failure is detected at a site, the counter corresponding to that site is
incremented. It is cleared whenever a device at that site passes. At the end of every run of
the test program, IMAGE examines the counters to see if the counts have reached (or
exceeded) user specified levels and will invoke the user defined function if the counts have
been reached or exceeded. Additionally, IMAGE, using tl_error(), logs an error
message. IMAGE provides a dummy user function if you do not define one.
IMAGE Solutions V8.3 15-16
IMAGE Base Language: Testing and Classifying Devices: Monitoring Maximum Consecutive Failures
Table of Contents Index Home Master Index Search Help
IMAGE Test Program Functions
IMAGE includes a number of functions to allow you to control MCFD monitoring from a test
program.
Initializing Sites
To initialize sites for MCFD use the function:
int tl_mcfd_init(unsigned count)
You must call this function once for each site you wish to initialize, from within a serial loop
for a multisite test program. Otherwise, all sites’ counters are set to count. This function
returns the count.
The following example shows how to use this function to select some sites out of the total
number of sites supported by a test program:
serial {
switch (tl_site) {
case 0: tl_mcfd_init(count);
case 1: tl_mcfd_init(count);
}
}
Where count has previously been initialized to some value.
MCFD monitoring is only performed for initialized sites. This allows you to perform MCFD
on all sites supported by the test program or only on some subset.
This function does not initialize if MCFD monitoring is on. MCFD must be first turned off (or
never have been turned on). You can change the sites monitored using this function if you
follow this restriction.
Turning MCFD Monitoring On and Off
To turn on MCFD monitoring use the function:
Bool tl_mcfd_switch_on(void)
When called, this function returns the current state of MCFD monitoring. If this function is
called before you have called the tl_mcfd_init() function, this function returns 0 (MCFD
monitoring off) and prints an error informing you that MCFD must first be initialized. Monitor
return from this function.
If the state of MCFD is transitioning from off to on, the MCF counters are cleared. Otherwise,
the function simply returns without any action, since MCFD monitoring is already on.
To turn off MCFD monitoring use the function:
Bool tl_mcfd_switch_off(void)
This function returns the current state of MCFD monitoring, which should normally should
be off and generally can be ignored.
IMAGE Solutions V8.3 15-17
IMAGE Base Language: Testing and Classifying Devices: Monitoring Maximum Consecutive Failures
Table of Contents Index Home Master Index Search Help
To return the state of MCFD monitoring use the function:
int tl_mcfd_monitoring_on()
This function returns 1 (on) or 0 (off).
Controlling Sites
To disable sites use the function:
int tl_mcfd_disable_site()
This function disables a particular site if called from within a serial loop or all sites if not. If
sites are already disabled, it returns FALSE (0).
To reset the MCFD counter for a particular site or all sites use the function:
int tl_mcfd_clear_counter()
For individual sites this function must be called from within a serial loop. MCFD monitoring
need not be turned off for the counters to be reset.
Monitoring Software and Hardware Bins
You can have MCFD monitor either software or hardware bins. (The default is hardware
bins.) To have MCFD monitor software bins and not hardware bins use the function:
tl_mcfd_monitor_sbin()
To have MCFD monitor hardware bins and not software bins use the function:
tl_mcfd_monitor_hbin()
To use either of these functions, MCFD must have been initialized.
User Function
The prototype user function for MCFD is:
int tl_user_mcfd_handler(int site, unsigned count)
This function is called whenever the MCFD count is reached on any site. It is called once
per site if multiple sites reach the MCFD count on any one run.
Starting MCFD From a Station Window
You can call the MCFD from a station window using the command:
max_consec_fail_dev [-on | -off] [-reset_counter [-site <site spec>]]
[-init # [-site <site spec>]] [-bin hbin | sbin]
where:
-on Turns the MCFD on. If you do not specify a site number, all sites
are monitored.
IMAGE Solutions V8.3 15-18
IMAGE Base Language: Testing and Classifying Devices: Monitoring Maximum Consecutive Failures
Table of Contents Index Home Master Index Search Help
-off Turns the MCFD off.
-reset_counter Resets the counter for the specified site or sites. If you do not
specify a site number, all sites are reset. If this option is used with
-on, -off, or -bin, it is ignored. (These options perform a reset.)
-site <site spec> Specifies the site or sites. This can be a site number or all for
all sites.
-init # Initializes the MCFD counter. If you do not specify a site number,
all sites are initialized. If used with -on, the MCFD is initialized
first. If used with -off, the MCFD is turned off first before being
initialized.
-bin Specifies whether to monitor hardware (hbin) or software (sbin)
bins. The default is hbin.
You can combine some options of this command. If one operation in the command does not
succeed, however, none of the operations will work. For example, you enter:
max_consec_fail_dev -init 5 -on -bin hbin
If initialization fails (the MCFD is already on, for example), -on and -bin are not processed.
IMAGE Solutions V8.3 15-19
IMAGE Base Language: Testing and Classifying Devices: The Input Adjust Function
Table of Contents Index Home Master Index Search Help
The Input Adjust Function
Under certain testing conditions, you must adjust a driving input or source function until a
measured output function has reached a specific value. For example, suppose the gain of
an audio amplifier is specified at a particular output voltage. By adjusting the input voltage
of the amplifier until the output voltage reaches the desired level, the gain can be calculated.
The tl_input_adjust functions provide this input adjustment capability.
The input adjuster works by trying successive approximations to the input. After each
approximation, the program looks at the output to see if it is more positive or more negative
than the desired value. It then determines whether the next input approximation should be
more positive or more negative. It keeps adjusting until two successive approximations to
the input are within resolution or the input fails to converge on an input within the established
limits.
The adjust_func() is a function you write to test an input and return a new output. The
function is called by tl_input_adjust repeatedly to test for the desired result, input. The
syntax is as follows:
tl_input_adjust() - Determine an 'input' value for a given 'output'
int tl_input_adjust(adjust_func, lo_limit, hi_limit, output,
resolution, polarity, max_loop_count, input);
double (*adjust_func)();/* user written test function (see below) */
/* to test 'input' */
double lo_limit; /* low limit for input search */
double hi_limit; /* high limit for input search */
double output; /* the target output */
double resolution; /* the search resolution - when the */
/* difference between successive tests on */
/* the input is less than this value the */
/* search ends */
int polarity; /* flag indicating search direction */
/* IA_POSITIVE_POLAR -input and output */
/* expected to be proportional */
/* IA_NEGATIVE_POLAR - input and output */
/* expected to be inversely proportional*/
/* IA_AUTO_POLAR - polarity will be chosen*/
/* by software based on trend of first two
/* tries */
int max_loop_count; /*max number of iterations to find 'input'*/
double *input; /* 'input': the answer */
where:
<input> When tl_input_adjust completes execution, this variable
contains the final value of the input. Must be a variable.
<lo_lim> This is the lower limit of the input values. tl_input_adjust will
not try more negative input values. Must be a constant or a
variable.
IMAGE Solutions V8.3 15-20
IMAGE Base Language: Testing and Classifying Devices: The Input Adjust Function
Table of Contents Index Home Master Index Search Help
<hi_lim> This is the upper limit of the input values. tl_input_adjust will
not try more positive input values. Must be a constant or a
variable.
<output> This expression is compared with the desired output value after
each adjustment step. The results of this comparison are used to
determine the direction of the next adjustment to the input. Can
be any expression.
<resolution> Search continues until the difference between successive tries is
less than this number.
<polarity> Direction of search. Software determines direction based on first
two tries.
<max_loop_count> Maximum number of iterations to find input.
The adjust_func() function you supply should look like this:
double adjust_func(input)
double input;
{
double result_of_device_test;
...
...
test the device based on 'input'
...
return(result_of_device_test);
}
The return value from tl_input_adjust indicates exit status as follows:
IA_INVALID_ARGUMENT= -1
Bad argument: hi_limit less than lo_limit or invalid polarity.
IA_RETURN_OK=0 A solution was found. It will be returned in input.
IA_RETURN_NO_RESOLUTION=1
Function has iterated max_loop_count and has failed to
converge on an input value to the specified resolution. input
contains zero.
IA_RETURN_INPUT_TOO_LOW=2
The input value lies below the lower limit. input contains the
lower limit lo_limit.
IA_RETURN_INPUT_TOO_HIGH=3
The input value lies above the upper limit. input contains the
upper limit hi_limit.
tl_input_adjust Test Example
The following is an example using the tl_input_adjust routine.
IMAGE Solutions V8.3 15-21
IMAGE Base Language: Testing and Classifying Devices: The Input Adjust Function
Table of Contents Index Home Master Index Search Help
#include <image.h>
#define MAX_LOOPS 1000
pinmap = {
1 “VREG” dib:1a2 dc_matrix (apu,src:1),
2 “SFST” dib:1b2 dc_matrix (src:2),
3 “PSEN” dib:1c2 dc_matrix (apu,src:3),
};
main() {
seq1();
sort bin;
}
SEQUENCER
seq1()
{
seq vpsen() >-10.0v <10.0v f(2) p(1);
}
TESTF
vpsen()
{
double psen_v,adj_psen();
enum Ia_returns status;
set pin=(VREG)
apu:v=0v
force:v
gate:off
disconnect;
set pin=(SFST)
src: v=0.0v;
set pin=(SFST) disconnect:src;
rdelay();
set pin=(VREG) connect:dcgnd;
set pin=(SFST) connect:dcvm1;
set pin=(PSEN)
apu:v=0.8v
force:v
vrng=5v
irng=30ma
gate:on
connect;
set meter
input: vm1
vrng=20v
filter:on;
set pin=(PSEN) apu:v=(2.1v - 0.8v)/2; /* get it started*/
wait 27ms;
status= tl_input_adjust(adj_psen, /* adjust function */
0.8v, /* search lo_limit */
2.1v, /* search hi_limit */
IMAGE Solutions V8.3 15-22
IMAGE Base Language: Testing and Classifying Devices: The Input Adjust Function
Table of Contents Index Home Master Index Search Help
6.0v, /* expected output */
0.01v, /* resolution */
IA_POSITIVE_POLAR, /* polarity 0=auto, 1=pos, 2=neg */
MAX_LOOPS, /* max_loop_count */
&psen_v), /* addr(&) of forcing function */
if (status != IA_RETURN_OK){ /* RETURN_ok 0 */
test psen_v fail; /* RETURN_NO_RESOLUTION 1 */
} else {
test psen_v; /* RETURN_INPUT_TO_HIGH 3 */
}
}
/**********************************************************/
/*************** PSEN adjust function ***************/
/**********************************************************/
double adj_psen(input) /* routine to adjust PSEN */
double input;
{double output;
set pin = (PSEN) apu:v=input;
wait 30ms;
output = read_meter();
return output;
}
Note that tl_input_adjust() also works with digital returns that evaluate to either 0 (pass)
or 1 (fail). The following is an example using tl_input_adjust() for digital testing.
/* Functional Adjust function ; returns 0.0 when passing. */
double adj_func(x)
double x;
{ PIN_LEVELS tlevel,plevel;
int failed;
char abuf[80];
double limit = 2.5v;
tlevel = static_adj.cmos;
switch(static_adj.what) {
case ADJ_CLK:
if (x < 250mv) x = 250mv ; /* Superclock spec... */
plevel.vih = 2.0 + x;
plevel.vil = 2.0 - x;
set supclk =1
vil = plevel.vil
vih = plevel.vih;
pat_power(1);
run_pat("vec.pat", "coarse", RUN_SYNC_SCL); /* Super Clock sync */
printf("\nIs there a pulse at %5.3fmv (y/n) ? ",x*1000);
gets(abuf);
pat_power(0);
failed = abuf[0] != 'y';
return (double) ! failed;
/*break;*/
case ADJ_VIL:
IMAGE Solutions V8.3 15-23
IMAGE Base Language: Testing and Classifying Devices: The Input Adjust Function
Table of Contents Index Home Master Index Search Help
tlevel.vil = x;
failed = (x < limit);
break;
case ADJ_VIH:
tlevel.vih = x;
failed = (x < limit);
break;
case ADJ_VOL:
tlevel.vol = x;
failed = (x > limit);
tlevel.vcp = (tlevel.vol+tlevel.voh)/2;
break;
case ADJ_VOH:
tlevel.voh = x;
failed = (x < limit);
tlevel.vcp = (tlevel.vol+tlevel.voh)/2;
break;
case ADJ_IOL:
tlevel.iol = x;
failed = ( x > 4ma);
break;
case ADJ_IOH:
tlevel.ioh = x;
failed = ( x < -4ma);
break;
}
func_setup(static_adj.vdd, &tlevel, &static_adj.pecl);
pat_power(1);
run_pat("simple.pat", NULL, RUN_FREE_SCL); /* Super Clock NO sync */
wait_until_h50_halt();
pat_power(0);
failed = read_hsd50_results(NULL) !=0 ;
#ifdef ADJ_DEBUG
printf("Adjusting %d, value %f, result %f ABS=%f\n",
static_adj.what, x, (double)failed,fabs(x));
#endif
return (double)!failed;
}
/* Datalog IOL and IOH values */
TESTF
log_pad(avdd, acmos, apecl, amin, amax, astep, adirn, awhat)
double avdd;
PIN_LEVELS *acmos, *apecl;
double amin, amax, astep;
enum Ia_adjust_polar_values adirn;
ADJ_WHAT awhat;
{ enum Ia_returns status;
double answer;
static char *stat_map[] = { "Badarg", "Ok", "MaxLoops", "Too Low", "Too High"};
/* save args to adj func */
static_adj.vdd = avdd;
static_adj.cmos = *acmos;
IMAGE Solutions V8.3 15-24
IMAGE Base Language: Testing and Classifying Devices: The Input Adjust Function
Table of Contents Index Home Master Index Search Help
static_adj.pecl = *apecl;
static_adj.what = awhat;
/* Note: adj_func returns 0.0 for fail, and 1.0 for pass.
* the DESIRED value is 0.5 (not 0.0) to prevent degenerate behavior, since
* tl_input_adjust checks for actual >= desired in POSITIVE case,
* and 1.0 (and 0.0) are both >= 0.0 */
status = tl_input_adjust(adj_func, amin, amax, 0.5, astep,adirn, 100, &answer);
#ifdef ADJ_DEBUG
printf("Status %s, answer %f\n", stat_map[status+1], answer);
#endif
if (status == IA_RETURN_OK)
test answer;
else
test answer fail;
}
The tl_input_adjust Algorithm
The tl_input_adjust function’s purpose is to modify an input value which produces the
specified output. It does this using a binary search technique. The first input value selected
is halfway between the specified high and low limits. The output value produced by this first
input is compared against the desired output.
In each loop, a new input value is chosen, narrowing the input range between the high and
low limits. Each loop cuts the input range in half. Thus, the difference between the new input
approximation and the last input approximation gets smaller and smaller. The algorithm
stops when two successive input values differ by less than the resolution.
Note that the stopping condition for the tl_input_adjust function is the resolution of the
input. The algorithm will recognize that an output is too high or too low and adjust the input
accordingly, but it will not try to attain the exact desired output value. If the desired output is
attained, the algorithm considers this a case of input too high.
Although the tl_input_adjust function’s goal is to find an input value which produces a
specified output value, in most instances the output value will not equal the desired value.
Even if it were possible to reach the output exactly, the input required to do so might be more
precise than necessary. It would not be useful to have the tl_input_adjust function run
extra loops and waste test time trying to adjust to an output which is effectively unreachable.
For these reasons, the tl_input_adjust function is controlled by the value of the input.
The tl_input_adjust function has two other types of stopping conditions. First, since the
tl_input_adjust function does not try input values outside of the specified high and low
limits, if the tl_input_adjust function reaches one of these limits and the next
approximation is outside the limit, the function stops. Second, the tl_input_adjust
function only loops the maximum loop count, which is set using the max_loop_count
parameter. The limits and maximum loop count allow you to control the looping process and
stop it in cases where it may be impossible to converge on an input value.
The adjust algorithm has an error-correcting feature which provides a degree of immunity
from initial transients, noise, and other instabilities which can occur when measuring signals
IMAGE Solutions V8.3 15-25
IMAGE Base Language: Testing and Classifying Devices: The Input Adjust Function
Table of Contents Index Home Master Index Search Help
in real time. If during the adjustment process, the input value is adjusted higher (or lower)
three times in a row, the algorithm temporarily stops its binary search and continues linearly
until the input becomes high (or low) enough so that it must be adjusted lower (or higher)
again. Linear search means that instead of successive input values coming closer and
closer together, the algorithm keeps the difference between the inputs the same and keeps
taking steps in that direction of that same size. Once the input becomes high (or low)
enough, the algorithm reverts to its regular binary search method.
The input may, for example, be drawn higher and higher by an output which is drifting lower.
The input must be moved much higher so that it can get the output to move higher again.
The binary search keeps changing the input by smaller and smaller increments. These
smaller and smaller changes would not stop the drifting, because the input would never get
high enough. The temporary linear search gets the process back on course.
IMAGE Solutions V8.3 15-26
IMAGE Base Language: Testing and Classifying Devices: Test Conditions
Table of Contents Index Home Master Index Search Help
Test Conditions
IMAGE includes test program syntax that allows you to test and classify devices using test
conditions. Typically, test conditions are used to specify the conditions under which the
device is being tested, for example, the temperature, such as hot, cold, or room
temperature. Test conditions can also be used to include special tests or to specify different
test limits that are only used in some circumstances, such as testing a lot of devices to a set
of specifications for a particular customer.
Test conditions can also be used to influence the testing of a device by having the test limit
values depend on the active test condition and, if necessary, changing the flow of the test
program depending on the active test condition.
Declaring Test Conditions
You can specify a test condition used while testing a lot of devices using the Lot Setup
Manager (see “Using the Lot Setup Manager to Set Up Lots” on page 6-5) or using the
startlot or testcond commands (see “Setting Test Conditions Using the testcond
Command” on page 6-10). Test conditions supported in a test program are declared using
a test_conditions declaration.
Test conditions are declared in a header file or in the header section of the test program.
The recommended place for the test condition declaration is adjacent to the pinmap. You
can declare up to 250 test conditions.
The syntax for declaring test conditions is
test_conditions = {[<cond_number>] "<test_cond>",
[<cond_number>] "<test_cond>",
...
};
Test condition names are defined as macros and can be referenced in the test program. An
example of a declaration would be:
test_conditions = { "ROOM", "HOT", "COLD" };
This statement declares three test conditions. You can now specify one of these conditions
in the Lot Setup Manager or using a startlot or a testcond command. You can also use
these names in sequencer statements to specify different limits for each test condition.
Each test condition is automatically assigned a numerical value by the compiler. Normally,
these values are unimportant and are only used internally by the tester. You can explicitly
specify a numerical value for a test condition in a test_conditions declaration by
preceding the test condition name with a value between 1 and 250.
IMAGE Solutions V8.3 15-27
IMAGE Base Language: Testing and Classifying Devices: Test Conditions
Table of Contents Index Home Master Index Search Help
Test Conditions in a Sequencer
The test limits specified in a sequencer statement can depend on the test condition. This
allows you to use a single sequencer statement for multiple test conditions. An example
would be:
seq cal() $100 "ac offset" ROOM: >-2.1v <2.1v
HOT: >-2.7v <2.7v
COLD: >-2.0v <2.0v f(4);
The limits used for this offset test depend on the test condition selected. This example
includes three test conditions corresponding to testing the device at room temperature, at a
hot temperature, or at a cold temperature. If the limits were the same for HOT and COLD, you
could write it as:
seq cal() $100 "ac offset" ROOM: >-2.1v <2.1v
HOT:
COLD: >-2.0v <2.0v f(4);
The syntax is similar to the syntax for the C switch statement. That is, you can use more
than one label for one set of limits. Another way to write this statement would be:
seq cal() $100 "ac offset" ROOM: >-2.1v <2.1v
default: >-2.0v <2.0v f(4);
Use the default test condition if the selected test condition is not one of the test conditions
enumerated or if no test condition is selected. If instead of using the same limits for HOT and
COLD, HOT has no limits, you could use:
seq cal() $100 "ac offset" ROOM: >-2.1v <2.1v
HOT: nolimits
COLD: >-2.0v <2.0v f(4);
If HOT was followed by nothing, the limits for COLD would be used as in one of the previous
examples. Therefore, to specify no limits for HOT, use the word nolimits. If HOT was left out
altogether, a run time error would be reported when executing this statement if the HOT test
condition had been selected.
A more complex example would be a sequencer statement to grade devices at three
temperatures:
seq cal() $100 "ac offset" ROOM: >-1.2v <1.2v
HOT: >-2.0v <2.0v
COLD: >-1.1v <1.1v c(1)
ROOM: >-1.8v <1.8v
HOT: >-2.5v <2.5v
COLD: >-1.7v <1.7v c(2)
ROOM: >-2.1v <2.1v
HOT: >-2.7v <2.7v
COLD: >-2.0v <2.0v c(3);
This example could also be written as:
seq cal() $100 "ac offset"
ROOM: >-1.2v <1.2v HOT: >-2.0v <2.0v COLD: >-1.1v <1.1v c(1)
IMAGE Solutions V8.3 15-28
IMAGE Base Language: Testing and Classifying Devices: Test Conditions
Table of Contents Index Home Master Index Search Help
ROOM: >-1.8v <1.8v HOT: >-2.5v <2.5v COLD: >-1.7v <1.7v c(2)
ROOM: >-2.1v <2.1v HOT: >-2.7v <2.7v COLD: >-2.0v <2.0v c(3);
An example of a compound sequencer statement for grading devices at different
temperatures would be:
seq cal() {
$100 "ac ref" >9.998 <10.002 f(10);
$101 "ac offset" ROOM: >-1.2v <1.2v
HOT: >-2.0v <2.0v
COLD: >-1.1v <1.1v c(1, 2)
ROOM: >-1.8v <1.8v
HOT: >-2.5v <2.5v
COLD: >-1.7v <1.7v c(3)
ROOM: >-2.1v <2.1v
HOT: nolimits
COLD: >-2.0v <2.0v c(4);
$102 "ac gain" ROOM: >4.95v <5.05v
HOT:
COLD: >4.94v <5.06v c(1)
ROOM: >4.90v <5.10v
default:>4.85v <5.15v c(2, 3)
>4.80v <5.20v c(4);
}
Setting and Interrogating Test Conditions
You can set a test condition from the test program, but only at the beginning of the program
before calling the first sequencer and only during the first run of a test program after starting
a new lot. To set a test condition from the test program use:
tl_set_test_condition(<test_condition>);
For example:
tl_set_test_condition(HOT);
You can use test conditions to alter the flow of a test program. Use the following function to
obtain the currently selected test condition:
read_test_condition();
This can be used to conditionally execute code. For example:
switch (read_test_condition()) {
case HOT: ...
case COLD: ...
default: ...
}
or:
int current_test_cond = read_test_condition();
.
IMAGE Solutions V8.3 15-29
IMAGE Base Language: Testing and Classifying Devices: Test Conditions
Table of Contents Index Home Master Index Search Help
if (current_test_cond == COLD)
{ ...
}
You can get the name of the currently selected test condition using:
read_test_condition_name();
This function returns a pointer to a string (char *) which contains the name. For example:
Lprintf( "Current test condition is: %s\n", read_test_condition_name() );
The test condition used to test a lot of devices is recorded in STDF datalog files. The test
condition name is stored in the TEST_COD field of the Master Information Record (MIR). (If
you are using STDF V3, test condition names can be up to three characters. STDF V4 has
no such limitation.)
IMAGE Solutions V8.3 15-30
IMAGE Base Language: Testing and Classifying Devices: Controlling Run-Time Errors
Table of Contents Index Home Master Index Search Help
Controlling Run-Time Errors
ITL provides several methods to control run-time errors from a test program. These
capabilities are described in this section.
Specifying the Error Bin
The ITL statement set error bin allows you to define an error bin from inside a test
program. The syntax is:
set error bin= <exp> hbin= <exp>;
The initial value for software and hardware error bins is bin 0. The preferred way of handling
error bins, however, is using a device_bins declaration.
Changing the Default Action for an Error
When IMAGE encounters a run-time error in a test program, it either ignores the error and
continues running or terminates the test program and bins the device in an error bin. (In
debug mode, IMAGE halts the program at the error and does not bin the device.)
Which action it performs depends on the default action code assigned to the error. (See
IMAGE Quick Help for a list of run-time error codes.) The default action code can be of type
ERROR_IGNORE, in which case IMAGE ignores the error. It can also be of type
ERROR_FORCE_BIN or ERROR_FORCE_HALT, in which case IMAGE terminates the test
program and bins the device. (If you are in debug, ERROR_FORCE_BIN also puts the trap
arrow on the error.) Even if the ERROR_FORCE_BIN occurs before executing any of the
sequencers, the bin number will appear in the datalog and the Station Monitor.
You can change the default action for all run-time errors, except those with action codes of
type ERROR_FORCE_HALT. The ERROR_FORCE_HALT action is reserved for run-time errors that
may produce dangerous conditions and for safety violations. Therefore, you cannot
continue executing past an ERROR_FORCE_HALT error.
If an IMAGE default action is inappropriate, use set error statements to explicitly set up
the action IMAGE will take when a run-time error is detected. Use the error numbers listed
in the IMAGE Quick Help to identify each run-time error. Examples are as follows:
set error ignore= 14;
Set the action for error #14 to ignore.
set error force_fail= (22, 76, 100);
Set the action for errors #22, #76, and #100 to force fail.
When the action is set to force failure, IMAGE forces the
currently-executing test to fail if the error is detected. This
overrides any limit comparisons which would take place.
set error force_bin= (35, 50 to 70);
Set error #35 and errors #50 through #70 to force bin. When
the action is set to force binning, IMAGE bins the device in the
IMAGE Solutions V8.3 15-31
IMAGE Base Language: Testing and Classifying Devices: Controlling Run-Time Errors
Table of Contents Index Home Master Index Search Help
error bin and immediately terminates the test program on
detection of the error. This is the same as the default action for
most run time errors.
set error default= all;
Set the actions for all errors back to their default state using the
keyword all.
Intercepting Errors in a Test Program
You can intercept errors inside a test program and take your own action either before or
instead of the action IMAGE will take. You do this by writing your own error handling function
and telling IMAGE to call this function when an error occurs. (IMAGE will not call your error
function for an error of type ERROR_FORCE_HALT or if you have used set error ignore to
ignore the error.)
Inside this error handling function, you can find out which error just occurred. If you are not
interested in the error, you can return from the error handling function and IMAGE will take
its default action as usual. If you are interested in the error, you can take your own action
and then either exit from the test program or return from the error handling function
instructing IMAGE what action to take.
To tell IMAGE which function to call when an error occurs, use the following statement:
set error handler = <function name>;
<function name> is a pointer to the error handler function you have defined.
When an error occurs, the error handler function is called with the number of the error as a
parameter. (Error numbers are listed in IMAGE Quick Help.) The error handler function can
look at the error number passed to it, determine what action to take, and perform that action.
For instance, assume your error handler function is called myhandler and run-time error
number 4 occurs. If your test program includes the statement:
set error handler = myhandler;
the number 4 is passed to the myhandler function. Having intercepted the error, myhandler
can now respond to error number 4. It can perform a series of actions and then exit from the
test program, it can force IMAGE to take a different action instead of its default action, or it
can let IMAGE take its default action.
Which action IMAGE takes depends on which error action code your error handler function
returns to IMAGE. The possibilities are:
ERROR_FORCE_BIN Bin the device in the error bin.
ERROR_FORCE_FAIL Force the current test to fail.
ERROR_IGNORE Ignore this error.
ERROR_PRESET Allow IMAGE to respond to this error as usual (default action).
IMAGE Solutions V8.3 15-32
IMAGE Base Language: Testing and Classifying Devices: Controlling Run-Time Errors
Table of Contents Index Home Master Index Search Help
These error action codes are defined in a header file named tlerror.h located in the
$IMAGEBIN/itlh directory. Before you can use these error action codes as return values,
you must include tlerror.h in your test program. To include it, insert the following
statement after the standard header files in your test program:
#include <itlh/tlerror.h>
Omitting this statement results in undefined error action codes.
The following is a sample error handling function:
/* Standard header files */
...
#include <itlh/tlerror.h> /* Required for ERROR action codes */
main()
{
...
set error handler = myhandler;
...
}
/* ERROR HANDLING FUNCTION */
int myhandler(error)
int error;
{
switch(error){
/* CLEAN UP BEFORE RESPONDING TO ERROR 16: "segmentation fault" */
case 16:
printf("\nERROR %d: Segmentation fault in test program!\n",error);
cleanup();
return(ERROR_PRESET); /* default action */
break;
/* MY RESPONSE TO ERROR 304: "SAM full" */
case 304:
printf("\nERROR %d: Sequential Access Memory is full.\n",error);
printf("Need to install Pattern RAM before next run.\n");
return(ERROR_FORCE_BIN);
break;
/* IGNORE ERROR 1506: "No rdelay() since last relay was programmed" */
case 1506:
printf("\nERROR %d: rdelay() required!!\n",error);
printf("rdelay() has been executed for you.\n");
rdelay();
return(ERROR_IGNORE);
break;
/* FOR ANY OTHER ERROR, LET IMAGE RESPOND TO THE ERROR. */
default: return(ERROR_PRESET);
} /* end switch*/
IMAGE Solutions V8.3 15-33
IMAGE Base Language: Testing and Classifying Devices: Controlling Run-Time Errors
Table of Contents Index Home Master Index Search Help
} /* end myhandler */
cleanup()
{
printf("Clean up in progress...\n");
...
}
Defining Your Own Errors
You can also define your own errors and call an error routine from a test program. This has
the same effect as if IMAGE were handling a predefined run-time error. To do this, use the
function:
tl_error_user(umess, acode)
char *umess;
int acode;
where:
umess Is a pointer to an error message you have defined
acode Is an error action code indicating which action to take.
The error action codes are:
ERROR_FORCE_BIN Bin the device in the error bin.
ERROR_FORCE_FAIL Force the current test to fail.
ERROR_IGNORE Ignore this error.
They are defined $IMAGEBIN/itlh/tlerror.h. When using error action codes, you must
include <itlh/tlerror.h> in your test program.
When tl_error_user is executed, the specified error message appears in the station
window and the specified action is taken. The following example demonstrates how the
tl_error_user function works:
/* Standard header files */
...
#include <itlh/tlerror.h> /* Required for ERROR action codes */
#define GRISLY_ERROR 1
#define STRANGE_ERROR 2
#define WARNING 3
main() {
myerror_routine(WARNING);
myerror_routine(STRANGE_ERROR);
myerror_routine(1123);
myerror_routine(GRISLY_ERROR);
}
IMAGE Solutions V8.3 15-34
IMAGE Base Language: Testing and Classifying Devices: Controlling Run-Time Errors
Table of Contents Index Home Master Index Search Help
/* THIS IS THE ERROR HANDLING FUNCTION */
void myerror_routine(error)
int error;
{
switch(error){
case WARNING:
printf("This is just a warning.\n");
tl_error_user("Nothing printed out", ERROR_IGNORE);
break;
case STRANGE_ERROR:
tl_error_user("What a strange error!", ERROR_FORCE_FAIL);
break;
case GRISLY_ERROR:
tl_error_user("What a grisly error!", ERROR_FORCE_BIN);
break;
default:
printf("ERROR %d not defined!\n", error);
tl_error_user("Nothing printed out.", ERROR_IGNORE);
break;
} /* end switch*/
} /* end myerror_routine */
Running this program produces the following output:
% run
This is just a warning.
ERROR #0 - What a strange error!
ERROR 1123 not defined!
ERROR #0 - What a grisly error!
Program stopped for in myerror_routine at line 29
Notice that the function tl_error_user identifies all errors as ERROR #0.
Debugging a Test Program Containing Run-Time Errors
The error handling methods described so far are primarily designed for production when
testing devices. Debugging a test program, however, requires additional control. At times,
you need the ability to ignore errors temporarily. You also need tools to help you isolate and
fix run-time errors quickly when you encounter them.
Using Continue on Error Mode
One valuable tool is the continue on error termination mode that allows you to ignore errors
temporarily. This mode forces IMAGE to continue to run past all run time errors, except
IMAGE Solutions V8.3 15-35
IMAGE Base Language: Testing and Classifying Devices: Controlling Run-Time Errors
Table of Contents Index Home Master Index Search Help
those of type ERROR_FORCE_HALT. You can, for instance, continue to run a test program
beyond a failing test to another test. The error messages for any errors continue to appear,
however, so that you know the errors are occurring.
Use this function by typing:
tmode -cont_on_error
Or you can set this mode with the mouse using the SET TERMINATION MODE item on the RUN
pull-right menu or by accessing this tmode switch from within a test program. (See “Setting
Program Termination Modes” on page 5-24.) Turn off this mode by selecting another testing
mode (either -cont_on_fail or -stop_on_fail).
Using set error as an Immediate Command
Another useful debugging tool is the set error statement used as an immediate command
(see “Changing the Default Action for an Error” on page 15-31). This gives you fine control
over individual errors. For instance, you may want to temporarily ignore a specific error to
aid in debugging a section of code. This method may be preferable at times to using the
continue on error mode.
IMAGE Solutions V8.3 15-36
IMAGE Base Language: Input and Output Functions
Table of Contents Index Home Master Index Search Help
16 INPUT AND OUTPUT FUNCTIONS
ITL includes input and output functions that allow input from the terminal keyboard to a
program, output from a program to the terminal screen, and program input and output to disk
files.
This section includes the following topics:
• “Using Input and Output Functions” on page 16-2
• “Input To and Output From the Terminal” on page 16-4
• “Input To and Output From a File” on page 16-10
• “Input To and Output From Strings and Characters” on page 16-14
• “Special I/O Functions” on page 16-15
IMAGE Solutions V8.3 16-1
IMAGE Base Language: Input and Output Functions: Using Input and Output Functions
Table of Contents Index Home Master Index Search Help
Using Input and Output Functions
These functions are part of the standard C library included in every test program. They are
called by the line:
#include <stdio.h>
You need not add this line yourself. When you create an ITL source file, this header file for
standard I/O library functions (along with header files for standard C math library functions
and the library of Teradyne tester functions) automatically appears in the header section of
your test program.
As described in “Header” on page 14-4, the header section includes:
/*Standard header files*/
#include <stdio.h>
#include <math.h>
#include <image.h>
Table 16-1 lists the major functions provided in the standard I/O library. These functions are
discussed in this section. For more information on I/O functions, see section 3, “Introduction
to User-Level Library Functions,” in the Solaris Reference Manual.
Table 16-1. Standard I/O Library Functions
Function Description
Read and Write to Terminal
printf() Put characters to the terminal (standard output) using user-specified
format conversion
putchar() Put a character to the terminal
getchar() Get a character from the keyboard (standard input)
scanf() Get characters from the keyboard using user-specified format
conversion
Read and Write to Files
fopen() Open a named file for read, write, or append
fclose() Close a file opened using fopen()
fprintf() Put output on the named output stream
fscanf() Get input from the named input stream
putc() Put a character into the named file
getc() Get a character from the named file
Read and Write to Strings
IMAGE Solutions V8.3 16-2
IMAGE Base Language: Input and Output Functions: Using Input and Output Functions
Table of Contents Index Home Master Index Search Help
Table 16-1. Standard I/O Library Functions (Continued)
Function Description
sprintf() Put output in a specified string of characters
sscanf() Get input from a specified string of characters
IMAGE Solutions V8.3 16-3
IMAGE Base Language: Input and Output Functions: Input To and Output From the Terminal
Table of Contents Index Home Master Index Search Help
Input To and Output From the Terminal
printf() and putchar() allow you to write characters and numerical values (or a single
character) to the terminal. getchar() and scanf() allow you to read a single character or
characters and numerical values from the terminal.
Input and output is accomplished by reading or writing characters or bytes. The operating
system sets up three standard devices that are attached to programs:
stdin standard input from a terminal
stdout standard output to a terminal
stderr standard error to a terminal
Thus, as shown in table 16-1, printf() places output on the standard output stream
stdout and scanf() reads from the standard input stream stdin.
printf()
printf() converts characters and numerical values stored in variables in a program to an
output string and prints the string to the terminal.
NOTE
ITL test programs are run in a high priority mode under UNIX and Solaris to eliminate
interrupts and ensure measurement repeatability. This technique may delay the
appearance of printf strings. If the time when a printf statement appears on the screen
is important, use the fflush function (see “fflush()” on page 16-15) to force the printf
statement to the screen at a certain time.
printf() has two parts—a control (or format) string and a list of variables. The syntax is:
printf("control string", var, var,...);
Within the control string are two kinds of data: characters printed literally to the output
stream, and conversion specifications. The figure 16-1 shows the parts of a printf()
statement.
Control string
Conversion specification
printf("The value of pi is %f.\n", PI);
Literal characters
Figure 16-1. Parts of a printf() Statement
IMAGE Solutions V8.3 16-4
IMAGE Base Language: Input and Output Functions: Input To and Output From the Terminal
Table of Contents Index Home Master Index Search Help
Conversion Specifications
A conversion specification converts and prints the next successive variable after printf().
Each variable listed after a control string must have a conversion specification. All
conversion specifications begin with the % character and end with a conversion character.
Additional modifiers can be used to control format. The syntax is:
%[<conversion modifiers>]<conversion character>
Table 16-2 lists printf conversion characters. Table 16-3 lists printf conversion
modifiers.
Table 16-2. printf() Conversion Characters
Character1 Output
%d Integer variable is converted to decimal.
%o Integer variable is converted to octal.
%x Integer variable is converted to hexadecimal.
%u Unsigned integer variable is converted to decimal. (Result is in the range
0–4294967295.)
%c Character variable is printed.
%s Variable is taken to be a string (character pointer) and characters from the
string are printed until a null character or until the number of characters
indicated by the precision specified is reached. Default precision is all
characters up to a null.
%e Float or double variable is converted to scientific notation. One digit is
before the decimal point and the number after is equal to the precision
specified. (Default = 6 digits.) Prints IEEE indeterminate values (infinity or
not-a-number) as Infinity or Nan respectively.
%f Float or double variable is converted to decimal. Number of characters
after the decimal point is the precision. The default precision is 6 digits. If
the precision is explicitly 0, no digits and no decimal point are printed.
Prints IEEE indeterminate values (infinity or not-a-number) as Infinity or
Nan respectively.
%g Float or double variable is printed in %d, %e, or %f format, whichever gives
full precision in minimum space. Prints IEEE indeterminate values (infinity
or not-a-number) as Infinity or Nan respectively.
1. Since printf() uses the % character to identify a conversion specification, you must use %% to
produce a % character in your output.
IMAGE Solutions V8.3 16-5
IMAGE Base Language: Input and Output Functions: Input To and Output From the Terminal
Table of Contents Index Home Master Index Search Help
Table 16-3. Modifiers Used in printf() Conversion Specification
Modifier1 Output
- (minus sign) Converted value is printed beginning at the left of its field width (left
justified).
+ (plus sign) If positive, the reverse value is printed with a + at the beginning.
Field Width Specifies the minimum width of the field. If converted value has
fewer characters than the field width, output is padded on the left (or
right, if the left-adjustment indicator has been given) to make up the
field width. If the field width begins with a zero, zero-padding is
used; if not, blank padding is used.
. (period) Separates the field width from the next digit string. The decimal
point counts as one space in the output.
Precision Specifies maximum number of characters printed from a string or
number of digits printed to the right of the decimal point of a float
or double.
l (letter ell) Specifies that the corresponding data item is long rather than int.
Conversion A character that indicates type of conversion to be applied (see
Character table 16-2).
1. If used, modifiers must appear in the order listed in this table.
Field Width
Most conversion modifiers affect field width. To better understand how these modifiers
change field width, you must look at the parts of the conversion format. For example:
precision
% .
field width type (d o x f e g)
Now, fill in some values:
printf("%16.5f", value);
16 is the field width.
5 is the precision (digits to the right of the decimal).
f tells you that the variable is formatted as a float or double and converted to decimal.
Another way to visualize this field is:
IMAGE Solutions V8.3 16-6
IMAGE Base Language: Input and Output Functions: Input To and Output From the Terminal
Table of Contents Index Home Master Index Search Help
precision = 5
field width = 16
In no case does a nonexistent or small field width cause truncation of a field. Padding takes
place only if the specified field width exceeds the actual width.
To produce output formatted the way you want it, and to get the most out of printf(), be
sure to use a sufficiently large field width. You cannot, however, print fields of more than
128 characters.
For example, using:
printf("%9d %9d %9d\n", val1, val2, val3);
produces:
12 234 1222
4 5 23
22334 2322 10001
putchar()
The putchar() function puts a single character to the terminal. putchar() always takes an
argument. You must place the character you want printed between the parentheses. This
argument can be a single character, a variable, or a function whose value is a single
character. The syntax is
putchar('s');
putchar('\n');
putchar('345');
putchar(getchar());
NOTE
Single quotes (') are used for character constants.
getchar()
getchar() gets one character from the keyboard. It has no argument. The syntax is:
var = getchar()
Since getchar() has no argument, it simply gets the next character and gives itself the
value of that character. For example:
char ch;
ch = getchar();
putchar(ch);
IMAGE Solutions V8.3 16-7
IMAGE Base Language: Input and Output Functions: Input To and Output From the Terminal
Table of Contents Index Home Master Index Search Help
scanf()
scanf() takes characters and numerical values from the keyboard (standard input),
interprets those characters and numerical values using conversion specification, and stores
the results in its variables.
Like printf(), scanf() uses a control string followed by a list of variables. However, each
variable must be a pointer, indicating where the converted input is to be stored. The syntax
is:
scanf("control string", var, var,...);
When using scanf() with numeric values, always precede the variable name with an &
character. (See “Data Types and Constants” on page 13-11.) To read in a value for a string
variable, do not use an &. For example:
scanf(input, "%d", &value);
The control string can contain:
• “White space” characters (blanks, tabs, or newlines), which are ignored.
• Ordinary characters (except %) that must match the next nonwhite space character of
the input stream.
• Conversion specifications used to direct interpretation and conversion of the input field.
As with printf(), the conversion specification begins with the % character and ends with a
conversion character and a number that specifies field width.
An input field is defined as a string of nonwhite space characters. It extends to the next white
space character, or until the field width, if specified, is exhausted. scanf() uses white space
when dividing input into separate fields. Consecutive conversion specifications are matched
with consecutive fields, leaving white space in between. The only exception to this is %c,
which reads the next character, even if it is white space.
Table 16-4 lists conversion characters used with scanf(). The conversion characters d, o,
and x can be capitalized or preceded by l (the letter ell) to indicate that a pointer to long
rather than to int is in the argument list. Similarly, the conversion characters e and f can
be capitalized or preceded by l to indicate a pointer to double rather than to float. The
conversion characters d, o, and x can be preceded by h to indicate a pointer to short rather
than to int.
Table 16-4. scanf() Conversion Characters
Character Input
%d, %D, %hd A decimal integer is expected; the corresponding variable should
be an integer pointer.
%o, %O, %ho An octal integer is expected; the corresponding variable should be
an integer pointer.
%x, %hx A hexadecimal integer is expected; the corresponding variable
should be an integer pointer.
IMAGE Solutions V8.3 16-8
IMAGE Base Language: Input and Output Functions: Input To and Output From the Terminal
Table of Contents Index Home Master Index Search Help
Table 16-4. scanf() Conversion Characters (Continued)
Character Input
%c A character is expected; the corresponding variable should be a
character pointer. The normal skip over white space characters is
suppressed in this case. If a field width is given, the corresponding
variable should refer to a character array and the indicated number
of characters is read.
%s A character string is expected; the corresponding variable should
be a character pointer to an array of characters large enough to
accept the string and a terminating \0, which will be added. The
input field is terminated by a space character or a newline.
%e, %E, %f, %F A floating point number is expected; the next field is converted
accordingly and stored through the corresponding variable, which
should be a pointer to a float. The input format for floating point
numbers is an optionally signed string of digits possibly containing
a decimal point, followed by an optional exponent field consisting
of an E or e followed by an optionally signed integer.
% A single % is expected in the input at this point; no assignment is
done.
scanf() functions return the number of successfully matched and assigned input items.
This can be used to decide how many input items were found. The constant EOF is returned
at end of input. Note that this is different from 0, which means that no conversion was done;
if conversion was intended, the input must contain an inappropriate character. scanf()
does not provide a way to convert a number in any arbitrary base (decimal, hex, or octal)
based on the traditional C conventions (leading 0 or 0x).
IMAGE Solutions V8.3 16-9
IMAGE Base Language: Input and Output Functions: Input To and Output From a File
Table of Contents Index Home Master Index Search Help
Input To and Output From a File
fopen()
fopen() opens a specified file, associates a stream with it, and returns a pointer to be used
to identify the stream in subsequent operations. The syntax is:
fopen(filename, type);
To use fopen(), you must assign a type designation that describes the use to be made of
the file. This type designation is a character string having one of the following values:
r Open for reading.
w Create for writing.
a Append: open for writing at end of file, or create for writing.
fopen() returns the pointer NULL if the filename cannot be accessed.
An example using both fopen() and fclose() is in “fclose()” on page 16-10.
fclose()
fclose() empties any buffers for the named stream and closes the file. Buffers allocated
by the standard input/output system are freed. fclose() is normally used to close a file
being written to. The syntax is:
fclose(stream); Terminal
stream
File
An example that illustrates the use of fopen() and fclose() is as follows:
/* This function opens a file, reads the first line, prints it,
and closes the file.*/
prline()
{
char input_buffer[80]; /* buffer for storing characters read in */
char filename[256]; /* put the name of the file to open here */
FILE *fp; /* file pointer */
/* Open the file, storing the result of the "fopen()" call in the file
descriptor 'fp'. If the open fails, print a warning and return. */
strcpy(filename, "myfile");
fp = fopen(filename,"r"); /* first param is filename */
/* second param is "r" for read only mode */
if (fp == NULL) {
printf("I can't open the file %s.\n", filename);
return;
}
IMAGE Solutions V8.3 16-10
IMAGE Base Language: Input and Output Functions: Input To and Output From a File
Table of Contents Index Home Master Index Search Help
/* Use fgets to get the first line in the file. */
fgets(input_buffer, /* name of buffer to put input in */
80, /* maximum number of characters to read */
fp); /* stream descriptor to read from */
printf("%s", input_buffer); /* Print out the line using printf */
fclose(fp); /* Close the file. This is important. */
}
fprintf()
fprintf() puts output to a file. The syntax is:
fprintf(pointer, "control string", var, var,...);
This function is identical to printf() but requires an additional variable. This variable is a
pointer to a file and must be the first variable in your variable list. For example:
/* Print some values at the terminal and also print the same text
into a file. Assume the file has already been opened for
writing and the descriptor for the file is named "outfp". */
double result_a = 1.0, result_b = 2.9;
int rtime = 1000;
printf("Result: %f %f %d\n", result_a, result_b, rtime);
fprintf(outfp, /* output file descriptor */
"Result: %f %f %d", /* output format specification */
result_a, result_b, /* two floating point numbers */
rtime); /* one integer */
scanf()
fscanf() gets output from a file. The syntax is:
fscanf(pointer, "control string", var, var,...);
This function is identical to scanf() but requires an additional variable. This variable is a
pointer to a file and must be the first variable in your variable list. For example:
/* Read two floating point numbers and an integer from a file. The first
line of the file looks something like "0.1 10.0 44". Assume the file is
already opened for reading, and the descriptor for the file is named
"outfp". */
double result_a = 1.0, result_b = 2.9;
int rtime = 1000;
fscanf(infp, /* input file descriptor */
"%f %f %d\n", /* input conversion format specification */
IMAGE Solutions V8.3 16-11
IMAGE Base Language: Input and Output Functions: Input To and Output From a File
Table of Contents Index Home Master Index Search Help
&result_a, &result_b,/* addresses of two floating point variables */
&rtime); /* addresses of one integer */
putc() and fputc()
putc() puts a character to the named output stream and returns the character written. The
output stream can be the terminal (standard output) or a file, in which case the variable is a
pointer to that file. The syntax is:
putc(c, stream); Terminal
stream
File
This function returns the constant EOF on error.
A variation, fputc(), behaves like putc() but is a genuine function rather than a macro.
The syntax is:
fputc(c, stream)
An example using putc() and fputc() is:
/* Use the functions putc() and fputc() in a loop to print out all the
characters in a specified string to a file and to the terminal. This example
essentially has the same effect as calling fputs() for each of the strings.
Assume "outfp" is the file descriptor for the file we are writing to. */
int loop;
char outstring[256];
strcpy(outstring, "This is a string.");
for (loop = 0; /* start the loop at 0 */
outstring[loop] != '\0';/* run until a null character */
loop++) { /* increment loop after every iteration */
fputc(outstring[loop], /* put the current character */
outfp); /* to the file using function fputc */
putc(outstring[loop], /* put the current character */
stdout); /* to the terminal using macro putc */
}
/* Send "newline" characters to get carriage-return linefeed. */
putc('\n', outfp);
fputc('\n', stdout);
getc() and fgetc()
getc() returns the next character from the named input stream. The input stream can be
from the keyboard (standard input) or from a file, in which case the variable is a pointer to
that file. The syntax is:
getc(stream);
KEYBOARD
stream
FILE
IMAGE Solutions V8.3 16-12
IMAGE Base Language: Input and Output Functions: Input To and Output From a File
Table of Contents Index Home Master Index Search Help
An example using the getc() function is:
/* Use the getc() function to get a line of text from the terminal,
substituting the character "_" for the character ".". The dedicated stream
descriptor "stdin" refers to terminal input. */
int loop;
char instring[256];
loop = 0;
instring[loop] = getc(stdin);
while(instring[loop] != '\n' && instring[loop] != EOF)
{
if (instring[loop] == '.')/* Convert the character if necessary. */
instring[loop] = '_';
loop++; /*Increment count and get another character.*/
instring[loop] = getc(stdin);
}
instring[loop] = '\0'; /* terminate string, just to be sure */
printf("%s\n", instring); /* print the string, for good measure */
If getc() encounters the end of the file being read, or if an error occurs, such as trying to
read from a file that was not opened for reading by fopen(), getc() returns the constant
EOF.
A variation, fgetc(), works like getc(). It can be used to save object text. The syntax is:
fgetc(stream)
NOTE
A carriage return is not a legal character.
IMAGE Solutions V8.3 16-13
IMAGE Base Language: Input and Output Functions: Input To and Output From Strings and Characters
Table of Contents Index Home Master Index Search Help
Input To and Output From Strings and Characters
sprintf()
sprintf() places output in a specified character string. The syntax is:
sprintf(string, "control string", var, var,...);
An example using the sprintf() function is:
/* Create a string containing selected information using the function
sprintf(), then print it out with printf(). */
char operator[80];
char mystring[256];
extern int tl_lotnum;
strcpy(operator, "Fred");
sprintf(mystring, "Operator: %s Lot number: %d", operator, tl_lotnum);
printf("%s\n", mystring);
sprintf() formats variables as printf() does but places the result in string. Therefore,
be sure that string is big enough to receive the result.
If you are using Solaris 2, be aware that operation of sprintf() is different. Under Solaris
2, this function returns the number of characters transmitted. When switching between
platforms, be careful that functions written using sprintf() still work as intended.
sscanf() and Sscanf()
sscanf() gets input from a specified character string. The syntax is:
sscanf(string, "control string", var, var,...);
An example using the sscanf() function is:
/* Using the function sscanf(), convert an ASCII string containing three
decimal constants and store the results in three integer variables, then
print the results. */
int in1, in2, in3;
char *examplestring = "1010 4095 -1";
sscanf(examplestring, "%d %d %d", &in1, &in2, &in3);
printf("In1 = %d, in2 = %d, in3 = %d\n", in1, in2, in3);
Sscanf() scans the string just like scanf() and places the resulting values in variables.
These variables must be pointers.
IMAGE Solutions V8.3 16-14
IMAGE Base Language: Input and Output Functions: Special I/O Functions
Table of Contents Index Home Master Index Search Help
Special I/O Functions
In addition to the standard library of I/O functions provided by ITL, there are five special I/O
functions. Table 16-5 lists these functions.
Table 16-5. Special I/O Functions
Function Description
fflush() Flush the stdio buffer (called stdout) used by
printf()
tl_fflush_nowait Flush the stdio buffer without resetting nowait
tl_read_char Get a single character without a carriage return, but do
not echo
tl_read_char_nowait Get a single character, if one was typed
tl_read_enable_nowait Turn on tl_read_char_nowait
tl_read_disable_nowait Turn off tl_read_char_nowait
fflush()
When using printf(), the \n put at the end of the string flushes the stdio buffer, causing
the string to appear at the terminal and moves the cursor to the next line. The fflush()
function flushes the stdio buffer used by printf() without requiring a \n in the string.
This allows you to put a string to the terminal without a carriage return at the end, leaving
the cursor on the same line as the string. You can use this to prompt the user and accept
the user’s input on the same line as the prompt.
The syntax is:
fflush(stdout);
You might use fflush() in the following way:
printf("prompt string:"); /*Stores string in the stdout buffer.*/
fflush(stdout) /*Flushes buffer contents to terminal,
retaining cursor at end of the string.*/
scanf(); /*Receives keyboard input.*/
There is no \n inside the printf parentheses since you do not want a carriage return.
Another function of fflush is to put strings to the terminal at the exact time you want them
to appear. This is sometimes useful because IMAGE test programs run in a high priority
mode under UNIX/Solaris. This mode eliminates interrupts and may delay the appearance
of printf strings. Use fflush after a printf statement to ensure that the string appears
where you want it.
IMAGE Solutions V8.3 16-15
IMAGE Base Language: Input and Output Functions: Special I/O Functions
Table of Contents Index Home Master Index Search Help
fflush, however, resets nowait if it is set. In such cases use the function
tl_fflush_nowait(). This function does not reset nowait. It is particularly useful in loops
waiting for a character strike. An example would be:
int count=0;
tl_read_enable_nowait();
while (!tl_read_char_nowait())
{
printf("count is %d\r", ++count);
tl_fflush_nowait(stdout);
wait 1;
}
tl_read_disable_nowait();
tl_read_char()
The tl_read_char() function allows you to get a single character from the keyboard
without echoing it to the screen or requiring a carriage return to be typed after the character.
It can be used for “type any number to continue” routines. The syntax is:
tl_read_char();
You might use tl_read_char() in the following way:
char ch;
printf("type a letter ==>\n");
ch = tl_read_char();
Additional tl_read Functions
Three I/O functions are used together for polling the keyboard and controlling loops. They
allow you to get a character at a point in the program if one was typed.
For instance, if you have a loop and you want to set up a condition where you can say “type
any key to stop loop,” you can use these functions. They protect against an infinite loop,
allowing you to control the loop over a period of time. You can, therefore, run a loop until
you want it to stop.
Their syntax is:
tl_read_enable_nowait();
tl_read_char_nowait();
tl_read_disable_nowait();
Here is an example of their use:
tl_read_enable_nowait();
for(<parameters of for loop>)
{
.
.
if (tl_read_char_nowait() !=0) break;
IMAGE Solutions V8.3 16-16
IMAGE Base Language: Input and Output Functions: Special I/O Functions
Table of Contents Index Home Master Index Search Help
}
tl_read_disable_nowait();
NOTE
tl_read_char_nowait can cause a problem during debugging. If you are stopped in a trap
and use the step command to step into this function, you will lose IMAGE and have to
reboot.
IMAGE Solutions V8.3 16-17
IMAGE Base Language: Multisite Testing
Table of Contents Index Home Master Index Search Help
17 MULTISITE TESTING
IMAGE supports testing of several identical devices in multiple sites on a single test head.
Multisite testing of devices increases throughput by testing two or more devices
simultaneously1. Multisite testing can be used with test head multiplexing to mask the
handler or prober indexing time on testers with more than one test head. A single test
program is loaded in a station used for multisite testing. This program then controls the
testing of all devices being tested at all sites.
This section includes the following topics:
• “Multisite Testing in IMAGE” on page 17-2
• “Multisite Test Pinmap” on page 17-3
• “Channel Assignments in a Pinmap” on page 17-5
• “Sequencer Functions and Binning” on page 17-6
• “Test Functions” on page 17-8
• “Global Variables in Multisite Test Programs” on page 17-17
• “Site Selection” on page 17-19
• “Loading a Multisite Test Program” on page 17-20
• “Manipulating Sites in a Test Program” on page 17-21
• “Assigning and Accessing Bin Numbers” on page 17-27
• “System Variables” on page 17-28
• “Digital Signal Processing” on page 17-29
1. See also “Parallel Test on A500 Family Test Systems” on page G7-1.
IMAGE Solutions V8.3 17-1
IMAGE Base Language: Multisite Testing: Multisite Testing in IMAGE
Table of Contents Index Home Master Index Search Help
Multisite Testing in IMAGE
A test program written to perform multisite testing is slightly different from a program which
only tests one device. A program, once written to support multisite test, can be used to test
any number of devices from a single device up to the maximum number of devices
supported by the pinmap (eight devices maximum) or a DIBView schematic.
For multisite test, a device interface board (DIB) is wired to accept two or more devices. The
pinmap in the test program describes the wiring used on the DIB. The pinmap, therefore,
also defines the maximum number of devices that can be tested in parallel. The only test
program change required to change this maximum is a modification to the pinmap to show
the connections used on a different DIB supporting a different number of devices.
Multisite test capability is fully integrated into IMAGE. IMAGE statements used to program
the tester instrumentation in a multisite test program are identical to statements used in a
single device test program.
IMAGE instrument statements allow instrument programming by referencing device pins.
The tester channels used are specified only in the pinmap, not in individual instrument
statements. A reference to a device pin in a multisite test program is a reference to that
device pin on all the devices being tested. Therefore, a single set pin or set dpin
statement in a multisite test program programs all tester channels used for that device pin
or list of device pins by all devices being tested.
If one device fails, further testing is automatically suspended on that device. Testing
continues on the remaining good devices. Instrument statements now program only the
channels still in use on the good devices, not the channels used on the failed device.
IMAGE features such as binning, datalog, and summary reports are fully supported under
multisite test. A separate datalog record is generated for each device tested.
IMAGE Solutions V8.3 17-2
IMAGE Base Language: Multisite Testing: Multisite Test Pinmap
Table of Contents Index Home Master Index Search Help
Multisite Test Pinmap
The pinmap for a multisite test program is similar to the pinmap for a single device program.
Instead of specifying a single tester channel for a device pin, however, it specifies a list of
tester channels, one per device site. The pinmap also specifies the maximum number of
sites supported. Here are two examples of a dual site pinmap. The first is for a Catalyst test
system and the second is the same example but for an A580 test system.
Catalyst Example:
pinmap (2 sites) = {
/* Pin Pin Name Channel Instrument Description
site0 site 1 */
1 "BCK" hsd_drv_rcv: (9, 105),
2 "SDATA" hsd_drv_rcv (10, 106),
6 "MPCK" hsd_drv_rcv: (13, 109),
12 "AD0" hsd_drv_rcv: (1, 97) (dig_src:(1,4), dig_cap:(1,4)),
13 "AD1" hsd_drv_rcv: (2, 98) (dig_src:(1,4), dig_cap:(1,4)),
14 "AD2" hsd_drv_rcv (3, 99) (dig_src:(1,4), dig_cap:(1,4)),
73 "TRCLOSE" hsd_drv_rcv: (25, 121) (dig_src:(2,5), dig_cap:(2,5)),
74 "TROPEN" hsd_drv_rcv: (26, 122) (dig_src:(2,5), dig_cap:(2,5)),
75 "TRAYOUT_" hsd_drv_rcv (27, 123) (dig_src:(2,5), dig_cap:(2,5)),
131 "SCO_A" dib:(1a11,24f11) dc_matrix,
231 "PLFD_1" dib:(2a1,8a1) plfdig_hi, /* plfdig_hi 1,3 */
135 "RFIS_A" dib:(10a1,14a1) vhfawg_dir_hi (dc_matrix),
5 "DVDD" dib:(1f1,24a1) dutsrc,
150 "REXT_HSD" hsd_drv:(1,41) (hcu:(4,5)), /* Changed to digital */
44 "AM6" dib:(1f19,1f25) thads_mux dc_matrix (hcu:(4,5)),
344 "AM6_SRC" dib:(1f19,1f25) thads_mux dc_matrix (src:3),
400 "PLFSHI" dib:(3a1,15a1) plfsrc_hi (hcu:(4,5)),
405 "HFDGHI" dib:16a1 hfdig_hi,
};
In this example, the term (2 sites) specifies that the device interface hardware and these
test programs support testing of up to two devices.
The digital drive and receive channels are wired independently to each site. For instance,
pin 1 "BCK" is wired to digital channel 9 for site 0 and is wired to digital channel 105 for site 1.
Pins AD0 through AD2 are wired not only to digital channels but also to both dig_src and
dig_cap instruments. Site 0 is wired to dig_src 1 and dig_cap 1 while site 1 is wired to
dig_src 4 and dig_cap 4.
Each site has separate dc_matrix pins, as shown by pin 131 "SCO_A". Each site has
separate PLFDIG pins, as shown by pin 231 "PLFD_1". Analog instruments are typically
assigned on a per site basis. However, if a singular instrument must be shared between
IMAGE Solutions V8.3 17-3
IMAGE Base Language: Multisite Testing: Multisite Test Pinmap
Table of Contents Index Home Master Index Search Help
both sites, such as the HFDIG in the above examples, then only declare one instrument in
your pinmap, as in pin 405 "HFDGHI".
Each site must have its own power supply (device pin 5).
You can declare thadsmux resources in a multisite pinmap and can place various resources
behind those pins (device pins 44 and 344).
IMAGE Solutions V8.3 17-4
IMAGE Base Language: Multisite Testing: Channel Assignments in a Pinmap
Table of Contents Index Home Master Index Search Help
Channel Assignments in a Pinmap
NOTE
This section does not apply to Catalyst test systems.
Analog channels can be assigned to device pins and sites in a pinmap without restrictions.
Assign digital channels into which patterns are loaded according to the following set of rules:
• Group digital tester channels in groups of eight, as in: 1-8, 9-16, and 17-24.
• Assign all channels in a group to one site. For example, do not assign channel 1 to site
0 and channel 8 to site 1.
• After assigning a group of eight tester channels to eight device pins on site 0, assign
other groups of eight channels each to each of the other sites in the same order. For
example, if on site 0 channels 1 to 8 are assigned to device pins 1 to 8 in that order, site
1 may have channels 9 to 16 assigned to device pins 1 to 8 in that order. But do not
assign channel 9 to pin 1 and then channel 16 to pin 2. Use the same ordering on each
site.
In the A580 pinmap example in “Multisite Test Pinmap” on page 17-3, digital channel
assignments follow these rules. These rules need not be followed for digital channels into
which patterns will not be loaded (for example, channels connected to a digital signal
capture memory). This is the so-called “Mod-8” rule, and the compiler checks the digital
channel assignments and issues an error if the rules are not followed.
IMAGE Solutions V8.3 17-5
IMAGE Base Language: Multisite Testing: Sequencer Functions and Binning
Table of Contents Index Home Master Index Search Help
Sequencer Functions and Binning
A typical test program contains one or more sequencer functions. These are usually called
from a high level function such as main(). After executing the sequencer functions the
device is usually binned. A typical top level function looks like this:
main()
{
seq1();
seq2();
sort bin;
}
The first sequencer function is always executed. The second sequencer is executed unless
all devices fail in the first sequencer function. The sort bin statement bins the devices in
the bins assigned during execution of the sequencer functions. A separate bin number is
assigned for each device.
Once a bin number is assigned by a sort bin statement to a site it cannot be changed. If
more than one sort bin statement is executed, only the first will have an effect.
The sequencer function in a multisite test program is similar to a sequencer function used
to test a single device. It usually consists of sequencer statements that specify a set of tests
to be performed, the test limits, and the binning strategy. Each test listed applies to all
devices being tested. Separate test results are generated for each device and compared to
the test limits.
If a device fails a test in the sequencer function and a bin number is specified, that bin
number is remembered for that device. For example, if a sequencer includes the statement
f(2) and site 1 fails, the bin number (2) is remembered for site 1 and if in stop on fail
mode (the default), site 1 is disqualified. This means that no further testing takes place on
the device. Since other device sites probably still contain good parts, execution of the
sequencer continues.
Sequencer statement syntax includes the ability to specify a fail action (fa) or pass action
(pa). This is a statement or group of statements to be executed if a device fails or passes,
either instead of assigning a bin number or in addition to assigning a bin number.
A typical fail action (or pass action) consists of a call to a function. This is only executed if
the device fails (or passes). It is executed once for each failing (or passing) device. A global
variable, tl_site, indicates which site it is being called for. An example of a fail action
would be:
seq test1() > 10ma < 15ma fa(printf("Site %d failed.\n", tl_site););
If site 1 fails the test the following line is printed:
Site 1 failed.
If both site 0 and 2 fail, two lines are printed:
Site 0 failed.
Site 2 failed.
IMAGE Solutions V8.3 17-6
IMAGE Base Language: Multisite Testing: Sequencer Functions and Binning
Table of Contents Index Home Master Index Search Help
Do not use the goto statement in a multisite test program, especially not as a fail or pass
action. This is because after one device fails execution should not be altered for the still
active devices.
IMAGE Solutions V8.3 17-7
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
Test Functions
Test functions are called from sequencer functions by sequencer statements. A test function
contains the statements necessary to set up the tester hardware or to take measurements.
In a multisite test program, a test function is called only once to test all the active sites.
A test function includes one or more test statements to determine pass or fail. A separate
pass or fail must be determined for each device. A serial block is used to specify a separate
result for each device.
Shared Tester Resources in Serial Blocks
To test multiple devices in parallel the tester must include enough resources (enough
channels for example) to drive several devices at once. If each device contains a 16 bit bus,
for example, the tester will need 16 digital channels for each device (that is, 32 channels for
two devices, 48 channels for three devices, and so on). Likewise, if a device requires one
ac input, normally the tester should contain one ac source per device being tested.
This is impossible in some situations. For example, a linear test system can have only one
Precision Time Measurement Subsystem and only one DC meter. These instruments must
be shared among the devices being tested in parallel.
Resources which must be used on one device at a time are supported by a serial block
which defines a group of statements that must be executed sequentially first for one device,
then the next, and so on. A set pin statement, when inside a serial block, programs only
the single device being tested during this pass through the serial block. This allows a test
program, for example, to perform most tests in parallel, but to make a time measurement
on one pin, one device at a time.
A serial block begins with the word serial followed by a statement or group of statements
in braces:
serial {
<statement>;
<statement>;
...
}
An example would be:
TESTF dctest()
{
set pin = VCC
dutsrc: v = 5.2v; /* Set voltage on each source */
serial {
set meter input: pin = VCC dutsrc:i; /* Connect meter to one source */
test read_meter(); /* Read and compare to limits */
}
}
IMAGE Solutions V8.3 17-8
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
In this example the supplies are programmed in parallel, but the meter is sequentially
connected to each device and read. The test statement must be used inside a serial block.
The test statement accepts the test result which in this example is the result returned by the
read_meter statement.
If two devices are being tested in the above example, the first statement sets the voltage on
each supply to 5.2V. Then the meter is connected to the supply for the first device, read,
and the result compared to the limits specified in the sequencer function. Then the meter is
connected to the supply for the second device, read again, and the result for the second
device is compared to the same limits in the sequencer function.
Serial blocks are generally used in test functions or in lower level functions called from test
functions. They are usually not used in sequencer functions.
The code in a serial block is executed once for each active site. If running in stop on fail
mode (the default) the code is not executed for any sites that have failed.
In some cases, devices at all sites can be driven from a single signal source. For example,
it may be necessary to drive all devices from a single ac source. Isolating buffers are
generally required on the DIB to avoid device interference. You can specify a shared
resource of this type in the pinmap. The instrument statements used to program the device
pin to which this ac source is connected then know that only one tester channel is used for
all devices instead of a separate channel per device.
The following additional serial blocks are available:
serial_sleep { ... }
serial_disabled { ... }
serial_all { ... }
serial_failed_sequencer { ... }
serial_max_sites { ... }
For information on these serial blocks, see “Serial Blocks Used in Site Manipulation” on
page 17-24.
HSD Test Statements
Most test statements must be included in a serial block to specify a separate result for each
device.
High speed digital test statements can be used either outside or inside a serial block.
Normally, they are used outside a serial block so that the test is performed on devices at all
sites. If used inside a serial block, a high speed digital test statement tests each device
separately. That is, a pass is made through the serial block for each device. When the high
speed digital test statement is encountered, only the device being tested on this pass
through the serial block is tested. Testing all devices in parallel is much faster, of course.
Available test statements include the following:
test <result> must be used inside a serial block
test fail must be used inside a serial block
test pass must be used inside a serial block
IMAGE Solutions V8.3 17-9
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
test <result> fail must be used inside a serial block
test <result> pass must be used inside a serial block
test ac_functional normally used outside a serial block
test acstate normally used outside a serial block
test open_short normally used outside a serial block
test parallel_leak normally used outside a serial block
test hs_current_scan normally used outside a serial block
High Speed Digital Pattern Loading
High speed digital patterns for a multisite test program are identical to the patterns used for
a single device test program. A digital pattern is written for only one device. When a pattern
is loaded in a multisite test program, the pattern is automatically loaded into the tester
channels for all devices being tested.
Multisite Testing on Catalyst Test Systems
The following sections explain multisite testing using Catalyst testers.
High Speed Digital Pattern Loading
On Catalyst test systems, you can use the no_parallel parameter with the load command
to load patterns into tester channels for a single site only. (See “Loading Patterns” on page
35-3 in the Catalyst Instrumentation Manual.) That is, you can prevent loading the pattern
automatically across all test sites. The pattern is then loaded into the channels or pins
specified in the pattern. If a parallel pin is specified, the pattern is loaded into the channel
assigned to site 0.
When you do this, the compiler no longer checks the channel assignments as described in
“Channel Assignments in a Pinmap” on page 17-5. The purpose of this feature is to prevent
the compiler from issuing errors when you want to use a multisite test pinmap and at the
same time disable the use of parallel digital vectors.
This is useful when you do not have enough resources in the test system to do real multisite
testing using digital patterns. You can accomplish the same result using pinmap
assignments. For example, under certain circumstances you can use the same driver
channel to drive multiple sites, while using separate channels for the receive side of the site.
This allows you to use tester channels more effectively but has the drawback of leaving the
burden of duplicating the vectors in multiple sites up to you. Avoid using this technique.
Do not place patterns loaded using no_parallel in a serial loop. The pattern loader only
supports loading of site 0 or all sites, so a no_parallel pattern in a serial loop would load
exactly the same way each time through the loop. PACS instrumentation, however, might
change, thus yielding undesired results.
For the test system to load multisite patterns successfully, the multisite pinmap must follow
the Mod 8 rule (see “Channel Assignments in a Pinmap” on page 17-5). This rule is checked
IMAGE Solutions V8.3 17-10
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
by the compiler at the load hsd pattern statement if the load hsd pattern statement
does not specify no_parallel.
The compiler can only check the Mod 8 rules if a pinmap is used. That is, you can get around
this restriction by putting the load statement in a file that does not include the pinmap.
Having a parallel pattern that does not follow the Mod 8 rule can cause problems that are
difficult to find. To ensure that these problems do not occur, another Mod 8 rule check is
performed at run time for patterns that do not specify no_parallel.
Multisite Testing Without Match Mode Loops
This section describes multisite testing using patterns that do not branch based on a site-
specific condition, that is, patterns without match mode. (A typical situation requiring a site-
specific condition is a loop that branches when a device pin goes high. This must be
performed on each device separately.)
For example, a counted loop does not branch because it executes exactly the number of
times defined by the count. However, a counted and conditional loop branches because the
loop executes either until the loop count is met or the condition in any site becomes true,
whichever occurs first. A condition for all sites (that is, if(cpu)) is considered to be
nonbranching.
Given that a multisite pinmap is defined and the load hsd pattern statement does not
specify no_parallel, the pattern loading process performs the following functions:
• The compiler checks the pinmap for the Mod 8 rules.
• The pattern duplicates the site 0 pattern into sites 1-n, where n equals max-sites defined
by the pinmap.
When the pattern is run, the start hsd pattern statement tells the SCM to execute the
pattern on all sites simultaneously.
You need to set ignore_halt-on-fail to prevent the SCM fail flag from stopping the
pattern. (See “Catalyst Pattern Generator and HRAM Setup” on page 33-57 in the Catalyst
Instrumentation Manual.) This would cause one bad device to fail all devices. Instead, the
test_ac_functional statement runs the pattern, then checks to see if any sites failed. If
needed, it then examines each channel fail flag to determine which pins on which sites
failed.
Figure 17-1 is an example of a memory map with three patterns.
IMAGE Solutions V8.3 17-11
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
pinmap (3 sites) = Site 0 Site 1 Site 2
{
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
1 clock drv:(1, 9, 17),
2 data3 drv_rcv: (2, 10, 18),
... PATTERN1 PATTERN1 PATTERN1
};
SCM
PATTERN3 PATTERN2 PATTERN2 PATTERN2
PATTERN2
PATTERN1 PATTERN3 PATTERN3 PATTERN3
CLOCK DATA3
0 H
SVM & LVM Memory
1 L
. .
Figure 17-1. Pattern Testing Without Match Mode
Multisite Testing With Match Mode Loops
Most digital tests need to put the device under test (DUT) in an initial state. Sometimes, the
vectors needed for DUT initialization vary. That is, the number of clocks or vectors needed
to initialize the device varies from device to device and possibly from run to run. The solution
is to use conditional vector branching, commonly referred to as match mode. This technique
applies a sequence of vectors and checks if the DUT is in the desired state. If it is not, the
pattern loops again until the condition is met.
Multisite testing makes this more complex. In a multisite test the SCM applies a vector
address to the digital channels. This address is applied to channels of all sites. If a
conditional branch is performed, the branch must apply to all sites, which is not correct.
You cannot use conditional branching in a multisite test pattern because all sites must be
executing the same vectors at all times, thus preventing any match mode vectors from being
applied. On Catalyst test systems, you can use conditional loops in a multisite test program,
by selectively defining patterns as parallel or no_parallel, where patterns using match
mode are defined as no_parallel.
As explained in the previous section, parallel patterns are written for site 0, and IMAGE
automatically duplicates them across the multiple sites. Patterns defined as no_parallel
are not duplicated by IMAGE. Then how are the match mode patterns executed on the other
sites? Multisite test patterns without no_parallel set must be written in a certain way. You
must duplicate the site 0 match mode pattern for each site. You must also create new
patterns to keep the initialized devices in the desired state while the next site is being
initialized.
When duplicating a pattern use the following procedure:
1. Create one pattern that is the site 0 pattern size times the number of sites.
2. Start the site 0 pattern at virtual address 0 and continue for site 0 pattern size.
IMAGE Solutions V8.3 17-12
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
3. Set sites 1-n channels to x. At this time, site 0 has been initialized.
4. Write vectors to keep site 0 in the initialized state and to pad the remaining vectors in
this pattern. At this time, site 1 pattern starts at site 0 pattern size plus 1 and continues
for site 0 pattern size.
5. Set sites 2-n channels to x. Now site 2 is initialized.
6. Write vectors to keep site initialized. Note that these may or may not be the same as site
0 vectors. This varies from device type to device type.
7. Keep repeating the above steps until all sites are initialized.
The pattern resulting from this process includes n copies of the site 0 initialization pattern
with each pattern residing in unique pattern address space. This allows each vector to
sequence freely. You must keep a site that was previously initialized in the initialized state
while initializing the other sites. You must also keep all sites in the initialized state when
moving from the match mode pattern to the parallel pattern.
In some cases, however, this delay is prohibitive. In these cases, you can jump from the
match mode pattern to the parallel pattern. The limitation is that the simulator and the history
RAM cannot deal with patterns in the same burst that have different pin lists.
Another variation on this technique is to use only no_parallel patterns throughout your
test program. In this case, you are responsible for duplicating the channel data across all
sites. IMAGE, however, still interprets the results at runtime. Even though a pattern may be
loaded using no_parallel, the test statement still tests the results on a per site basis. This
allows you to develop the patterns as desired without losing the benefits of having a multisite
test program.
The last vector in a no_parallel pattern should verify that the device is still in the desired
state (see VERIFY in figure 17-2). Any site failing this vector implies that the device did not
hold its initialized state. This failure mechanism is useful for binning, but even more useful
for developing these vectors and debugging them. Figure 17-2 shows a no_parallel
pattern.
IMAGE Solutions V8.3 17-13
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
pinmap (3 sites) =
{ Site 0 Site 1 Site 2
SEQ
1 clock drv:(1, 9, 17), 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
2 data3 drv_rcv: (2, 10, 18), tset sequence
...
};
Initialization Pattern
Initialization Pattern
Chans 1 2 9 10 17 18
0 H X X X X
1 L X X X X PATTERN1 PATTERN1 PATTERN1
1 L X X X X
1 X 0 H X X
1 X 1 L X X PATTERN2 PATTERN2 PATTERN2
1 X 1 L X X
1 X 1 X 0 H
1 X 1 X 1 L PATTERN3 PATTERN3 PATTERN3
1 X 1 X 1 L
VERIFY 1 L 1 L 1 L
SVM & LVM Memory
PATTERN3
PATTERN2
PATTERN1
CLOCK DATA3
0 H
1 L
. .
Figure 17-2. Multisite Testing With a no_parallel Pattern
Multisite Testing With Digital Signal Source and Capture
Digital source (dig_src) and digital capture (dig_cap) instruments are used in digital
testing to either represent analog signals digitally or to extend digital memory (SVM and
LVM). Multisite testing on Catalyst test systems supports the use of dig_src and dig_cap
in digital testing. To use dig_src and dig_cap in multisite testing, the dig_src and
dig_cap hardware setup must be present on all the sites and the dig_src and dig_cap
microcode must be duplicated across all the sites during pattern load. Unlike pattern data,
duplication of dig_src and dig_cap microcode during pattern load requires “scrambling” of
the microcode data for each vector.
When a multisite test pinmap exists and multiple dig_src and dig_cap instruments are
available, the compiler creates multisite pin lists that enable the hardware setup routines to
set up the dig_src and dig_cap hardware for each multisite pin across all sites.
If a digital pattern is loaded parallel and that pattern contains dig_src and dig_cap
microcode, the pattern loader must duplicate the dig_src and dig_cap microcode for each
instrument, unless the instrument is defined as a shared resource.
IMAGE Solutions V8.3 17-14
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
Any digital pin using a dig_src or dig_cap instrument must define a list of channels needed
for multisite testing in the pinmap. It must also specify the list of dig_src and dig_cap
instruments needed for each channel. This information is used by the compiler to create pin
lists for the hardware setup routines of instruments and digital channels and by the loader
to see if microcode needs to be duplicated.
Multisite Testing With PACS
Precision AC Subsystem (PACS) instruments are used in digital testing to either source or
capture analog waveforms while the pattern is running. This is done using Catalyst
microcode that is programmed from within the pattern. This microcode allows a digital
pattern to either start or stop analog waveforms from the pattern. This permits
synchronization of the digital pattern and the PACS waveform source or capture.
Multisite testing on an Catalyst test system supports the use of PACS in digital testing.
Support of PACS during multisite testing requires that the PACS hardware setup be
duplicated across all sites. In addition, the Catalyst microcode must be duplicated during
pattern load.
When a multisite test pinmap exists and multiple PACS instruments are available, the
compiler creates multisite pin lists. These pin lists enable the hardware setup routines to set
up the PACS hardware for each multisite pin across all sites.
If a digital pattern is loaded parallel and that pattern contains Catalyst microcode, then the
pattern loader must duplicate the Catalyst microcode for each instrument, unless the
instrument is defined as a shared resource.
Any digital pin using a PACS instrument must define a list of channels needed for multisite
testing in the pinmap. It must also specify the list of PACS instruments needed for each
channel. This information is used by the compiler to create pin lists for the hardware setup
routines of instruments and digital channels.
Shared Resources in Parallel Patterns
To test multiple devices in parallel, the tester must have enough resources to drive several
devices at once. If 32 digital channels are needed to test each device, then two sites need
64 digital channels. Likewise, if a device requires one AC input, then two sites require two
AC inputs, one for each site.
In some situations, a dedicated resource is not available for each site, usually for hardware
or economic reasons. Most resources can be shared with the exception of digital channels.
Shared resources must be programmed in a serial block which defines a group of
statements that must be executed sequentially for each device in turn.
Using shared resources in a parallel pattern requires special consideration. Pattern loading
must appear outside the serial loop, since all sites are loaded in parallel. The serial loop
contains the site specific setup statements for the shared resource, in addition to the pattern
start statement.
The special consideration here is that the start pattern statement runs all sites in parallel
regardless of the site number. The test statement, however, only looks at failing channels
IMAGE Solutions V8.3 17-15
IMAGE Base Language: Multisite Testing: Test Functions
Table of Contents Index Home Master Index Search Help
from the current site. This consideration implies that any pattern used in this fashion should
be self initializing. That is, the pattern should not make any assumption about the state of
the device at pattern start. Also no other pattern should depend on the state of the device
at the end of this pattern since that can not be guaranteed either.
Testing Restrictions
Observe the following restrictions when doing multisite testing on an Catalyst tester:
• Conditional branching on a per site basis is not allowed in a parallel pattern. That is,
“match mode” vectors usually apply to a specific condition on a site. Thus, the condition
coming true on any site alters the execution on all sites.
• Digital pattern load statements appearing inside a serial loop cause the pattern to be
loaded on the first pass through the loop. All subsequent passes do nothing.
• Jumps between no_parallel patterns and parallel patterns are not recommended.
• All channels in a single DMF cage that use dig_srcs are restricted to using the
dig_srcs in the same cage.
• Channels from different DMF cages that use dig_cap cannot be connected to the same
slice.
• You can load patterns into either site 0 or all sites. You cannot select any other sites for
pattern loads.
• Parallel test patterns must be run with ignore-halt-on-fail set. Without this flag set,
a failure on one site can cause the pattern to halt prematurely, possibly passing bad
devices on other sites which could have failed had the pattern continued.
IMAGE Solutions V8.3 17-16
IMAGE Base Language: Multisite Testing: Global Variables in Multisite Test Programs
Table of Contents Index Home Master Index Search Help
Global Variables in Multisite Test Programs
Global variables are sometimes used to store values shared among tests. For example, a
test may measure the dc offset on a pin and save the offset in a global variable. Subsequent
tests then subtract this offset from their measured values.
save and retrieve Statements
In a multisite test program this offset is different for each device, so separate values must
be saved for each device. Declaring a separate variable for each device is inconvenient.
Instead, use a save statement at the point where the offsets are calculated and a retrieve
statement when the values are needed. These statements allow global variables which
must store different values for each device to be handled without writing the test program
for a fixed number of sites and without being concerned about which device you are working
on.
The save and retrieve statements have the following syntax:
save idata = <integer_variable>;
save ddata = <double_variable>;
save adata = <float_array> size = <number_of_elements>;
retrieve idata = <integer_variable>;
retrieve ddata = <double_variable>;
retrieve adata = <float_array>;
save stores the current value of the integer, double, or array variable for the site being
tested during this pass through the serial block. retrieve writes the values for the site
being tested during this pass through the serial block back into the variable. Always use
these statements inside a serial block. For example:
double offset; /* 'offset' is a global variable */
...
serial {
...
offset = read_meter(); /* Determine offset for one device */
save ddata = offset; /* Save the offset */
}
...
serial {
...
retrieve ddata = offset; /* Retrieve the offset for one site */
test read_meter() - offset; /* Use the offset in a calculation */
}
IMAGE Solutions V8.3 17-17
IMAGE Base Language: Multisite Testing: Global Variables in Multisite Test Programs
Table of Contents Index Home Master Index Search Help
Retrieve Functions
Two functions are available for retrieving an integer or double value directly without first
writing it into the variable:
tl_retrieve_i("<integer_variable_name>");
tl_retrieve_d("<double_variable_name>");
The last serial block in the example above can alternatively be written as:
serial {
...
test read_meter() - tl_retrieve_d("offset");
}
NOTE
In save and retrieve statements the variable names do not use quotes. The tl_retrieve
functions in the preceding example, however, require quotes around the variable name.
These functions are useful for getting a value in a calculation. They can be used outside a
serial block as part of a set statement as shown in this example:
set acsrc: audio1
freq= 4khz
amp= tl_retrieve_d("gain") * 0.5
set acsrc: output1
offset= tl_retrieve_d("dc_offset");
A different value of gain and dc_offset will be used in calculating the amplitude and DC
base for each low frequency source.
IMAGE Solutions V8.3 17-18
IMAGE Base Language: Multisite Testing: Site Selection
Table of Contents Index Home Master Index Search Help
Site Selection
Executing the run command by default causes testing on all the sites supported by the test
program. You can change this default using the sites command which has the following
syntax:
sites [# # ... | -all] [-debug #] [-station #] [-auto on | off]
where:
sites # Enable a site or sites for test program execution. Enter the
command with one or more numbers (0–3) to enable specific
sites. Default is site 0. For example, the following command
enables sites 0, 2, and 3:
sites 0 2 3
run commands will now test devices on these sites only.
Enter the command with no parameters to display what sites are
currently enabled. If used at a breaktrap while debugging, sites
displays both the sites enabled at the start of the test program
and what sites are still enabled (that is, sites that have not failed).
-all Enable all the sites supported by the test program or specified in
the load command.
-debug # Enable site # in all debug displays. When debugging a multisite
test program, debug displays (such as the tester setup display)
show the information for only one site at a time. This option
refreshes the display and shows the site specified. For example,
the following command causes the debug displays to refresh
showing the information for site 1:
sites -debug 1
-station # Enable sites in station #. For example, the following command
enables all sites for the program loaded in station 3:
sites -all -station 3
-auto on causes debug displays to automatically track the current site
being tested.
The easiest way to debug most test programs is to enable one site (using sites 0 for
example). Most debugging is unaffected by the number of devices being tested. Then, to
debug problems relating to multisite test, enable two or more sites using the sites
command. Determine the current status of each site at a breaktrap using sites with no
parameters. Use the -debug option to see the current setting of the instrumentation for one
site at a time.
When using a handler or prober in production testing, the handler or prober is interrogated
to determine the active sites. Active sites may change between each run of the program. If
one site on a handler is jammed, for example, testing may continue on the other sites.
IMAGE Solutions V8.3 17-19
IMAGE Base Language: Multisite Testing: Loading a Multisite Test Program
Table of Contents Index Home Master Index Search Help
Loading a Multisite Test Program
When a test program is loaded, IMAGE performs a configuration check to determine that
the tester configuration has the resources required to execute the test program. When
loading a multisite test program, IMAGE assumes, by default, that testing will be done on
all sites supported by the test program and requires the tester to include the resources to
test on all sites. If the tester lacks some instruments needed to test on all sites, errors are
reported.
In some situations, you may write a multisite test program for use on any one of several
testers with different configurations. For example, one tester may have enough resources
to test two devices in parallel, but another tester can only test one device at a time. You can
specify the active sites when you load the test program. If you do this, the configuration
check only requires that the tester include the resources needed to test on the sites
specified, thus avoiding configuration error messages.
To specify, at load time, which sites will be used, use the -sites option to the load
command. For example:
load px100 -sites 0 1
This would load px100 (a test program supporting up to four devices) and test on sites 0 and
1 only. It would not report errors for any missing instrumentation used on sites 2 and 3.
You can specify the -sites option either on the command line (as shown in the example)
or in a .load file.
Use the sites command after loading the test program to change the active sites, either
eliminating sites or enabling additional sites. If additional sites are enabled, the tester
configuration is rechecked to verify compatibility with the sites now enabled.
IMAGE Solutions V8.3 17-20
IMAGE Base Language: Multisite Testing: Manipulating Sites in a Test Program
Table of Contents Index Home Master Index Search Help
Manipulating Sites in a Test Program
Normally, each site in the test program, both in multisite test and single site testing, is either
enabled or disabled. Sites start out at the beginning of a program as enabled. If testing in
the stop_on_fail mode, a site is disabled if it fails a test or if the set site_disable
statement is executed. The site stays disabled until the end of the test program unless it is
re-enabled by the set site_enable statement. If testing in continue_on_fail mode,
sites are never disabled. IMAGE includes a number of commands and functions that allow
you to manipulate sites. These are described in the following sections.
Using the Sleep State
The sleep state for sites (available in V6.2 and later) helps you address the needs of
multisite test. The sleep state allows a site to be in one of three states: enabled, disabled,
or sleeping. The sleep state allows a site to be put aside while operating on other sites, and
later awakened, or enabled, to continue testing on that site. While a site can be disabled
and then re-enabled to achieve the same result, the sleep state has several advantages in
a multisite test program.
When running in the continue_on_fail mode, a site cannot be disabled. It is, therefore,
not possible to put a site aside without first altering the mode to stop_on_fail. The sleep
state can be used to put a site aside whether or not the test mode is stop_on_fail.
When a disabled site is re-enabled, assigning a new fail bin is allowed. This means that the
device may not end up being binned in the first fail bin, unless code is included to save the
bin number and the device is explicitly binned using the sort bin statement. By using the
sleep state and then waking the site instead of enabling it, binning is unaffected. By default,
the device is binned in the first fail bin.
Each time a site is disabled, tl_site_shutdown() is called. This function is useful to
perform some action required after all testing is finished on a device, such as powering
down or disconnecting instruments. This generally means that it is desirable to have this
function execute only once per site when totally done with the site. When using the sleep
state to put aside a site, tl_site_shutdown() is not called. When all testing is complete
on a failed site, the site can be disabled and tl_site_shutdown() is called.
tl_site_shutdown() is called at the end of a test program for any sites still active or in the
sleep state. The function, therefore, ends up being called once and only once for each site
during the run of the program.
Two actions may cause a site to change from one state to another:
• Executing a statement to explicitly move one or more sites to a new state
• A failing test
You can also enable and disable all sites or specific sites during program debugging using
the Tester Setup display.
IMAGE Solutions V8.3 17-21
IMAGE Base Language: Multisite Testing: Manipulating Sites in a Test Program
Table of Contents Index Home Master Index Search Help
Enabling, Disabling, and Sleeping a Site
ITL language statements are provided to change the state of site. The following syntax is
supported:
set site_enable = <site>
Enable the specified site.
set site_enable_all
Enable all sites.
set site_disable = <site>
Disable the specified site.
set site_disable_all
Disable all sites.
set site_sleep = <site>
Put the specified site to sleep.
set site_sleep_all Put all enabled sites to sleep.
set site_wake = <site>
Wake (enable) the specified site.
set site_wake_all Wake all sleeping sites.
set site_swap_sleep
Swap the sleeping and the enabled sites.
(Sleep ⇒ enabled. Enabled ⇒ sleep).
These statements move sites between the enabled, sleep, and disabled states. Table 17-1
defines the behavior in more detail.
Table 17-1. Moving Sites Between Enabled, Sleeping, and Disabled
Effect on sites that are:
Statement
Enabled Sleeping Disabled
set site_enable = <site> Binning Binning Binning
set site_enable_all affected1 affected1 affected1
Enabled Enabled
set site_disable = <site> Disabled Disabled None
set site_disable_all
(Test mode =
stop_on_fail)
set site_disable = <site> None None None
set site_disable_all
(Test mode =
continue_on_fail)
IMAGE Solutions V8.3 17-22
IMAGE Base Language: Multisite Testing: Manipulating Sites in a Test Program
Table of Contents Index Home Master Index Search Help
Table 17-1. Moving Sites Between Enabled, Sleeping, and Disabled (Continued)
Effect on sites that are:
Statement
Enabled Sleeping Disabled
set site_sleep_all Sleeping None None
set site_sleep = <site> Sleeping None Error
set site_wake_all None Enabled None
set site_wake = <site> None Enabled Error
set site_swap_sleep Sleeping Enabled None
1. Binning is affected by the set site_enable statements. After executing this statement, binning
is reset such that the next failure will record a new bin number. This may cause the sort bin
statement to record a bin number other than the first failure in a test program.
Altering the Action on Test Failures
The action taken when a test fails depends on the test mode, stop_on_fail or
continue_on_fail, and the binning specified: fail bin number, f(bin), or close binning,
c(bin). By default, when a test fails for a site in the stop_on_fail mode and is assigned
to a bin, the site is automatically disabled to prevent further testing on that site. You can
choose to alter this default action and instead use the sleep mode by using the following
statement:
set sleep_mode: off | on;
where:
off The sleep mode is only entered if one of the following statements
are used explicitly: set site_sleep=<site>, set
site_sleep_all, or set site_swap_sleep. The default.
on A site enters the sleep mode when a test fails.
This statement can be used once at the beginning of a program to set the desired action for
the test program, or it can be used multiple times during execution of the program to achieve
different behavior in some sequencers or in certain parts of the program. The mode is reset
to off before each run of the test program.
Behavior of this statement is summarized in table 17-2 below. The default action in the table
is the behavior of all test programs before IMAGE V6.2.
IMAGE Solutions V8.3 17-23
IMAGE Base Language: Multisite Testing: Manipulating Sites in a Test Program
Table of Contents Index Home Master Index Search Help
Table 17-2. Summary of Actions After a Test Failure
Action set
sleep_mode:
Test Bin
Test Result Bin Result
Mode Specifier
off;
on;
(default)
stop on fail None Test fails None Site put to
sleep
f(2) Test fails 2 Site Site put to
disabled sleep
c(1)1, Test fails first set of Bin 1 None None
c(2)1 limits closed
c(1)1, Test fails both sets of Bins 1,2 Site Site put to
c(2)1 limits closed disabled sleep
continue None Test fails None Site put to
on fail sleep
f(2) Test fails 2 None Site put to
sleep
c(1)1, Test fails first set of Bin 1 None None
c(2)1 limits closed
c(1)1, Test fails both sets of Bins 1,2 None Site put to
c(2)1 limits closed sleep
1. Assumes bin 1 and bin 2 are pass bins. Other bins are fail bins.
Note that with sleep_mode on, a failing test causes a site to be put to sleep independent of
the test mode. Note also that even if no fail bin number is specified on the sequencer for a
test, if the test fails and sleep_mode is on, the site is put to sleep. This behavior differs from
the default behavior where a device is not disabled if neither a fail bin number nor close
binning is specified.
Serial Blocks Used in Site Manipulation
Several variations on the serial block are available. The standard serial block looks like this:
serial {
... /*Do this for each enabled site.*/
}
In addition to the standard serial block the following are available:
IMAGE Solutions V8.3 17-24
IMAGE Base Language: Multisite Testing: Manipulating Sites in a Test Program
Table of Contents Index Home Master Index Search Help
serial_sleep { ... }
Do for each sleeping site. For information regarding the sleep
state, see “Using the Sleep State” on page 17-21.
serial_disabled { ... }
Do for each disabled site.
serial_all { ... } Do for each site, regardless of the state.
serial_failed_sequencer { ... }
Do for each site that failed the last sequencer. This provides a
convenient way of determining which sites failed a sequencer.
This can be used after returning from a sequencer to perform an
operation on each site that failed the sequencer. The code in the
serial block is executed once for each failed site. If used inside a
sequencer, the code in the serial block is executed once for each
site that has failed that sequencer so far.
serial_max_sites { ... }
Do for each site supported by the test program. Normally, you
use serial_all instead of serial_max_sites. Both types of
serial blocks behave identically if all sites supported by a test
program are used. They behave differently if a program is run
using only a subset of the sites specified in the pinmap. This is
the case if the -sites option is specified when the program is
loaded, if the -sitemask option is used when the program is run,
or if the start command issued from a handler or prober
specifies not running all sites. In these cases, serial_all goes
through only the sites used for that run, but serial_max_sites
goes through all the sites supported by the test program as
specified in the pinmap.
When you use serial_max_sites you cannot datalog to the
sites that were not enabled at the start of the test program run.
Only use serial_max_sites in special circumstances, such as
performing spot calibration on all sites during the execution of a
test program.
Inside each serial block, read_current_site() can be used to determine which site is
being tested during a pass through the serial block. For more information on serial blocks,
see “Shared Tester Resources in Serial Blocks” on page 17-8.
Using Site Masks
In a multisite test program with a complicated flow, you can manipulate sites using a site
mask. A site mask is an integer word with a single bit assigned to each site. The least
significant bit is site 0, the next bit, site 1, and so on.
IMAGE Solutions V8.3 17-25
IMAGE Base Language: Multisite Testing: Manipulating Sites in a Test Program
Table of Contents Index Home Master Index Search Help
For example, you have a four site program. In this program sites 1 and 2 are enabled and
sites 0 and 3 are disabled. The site mask of all the enabled sites would contain 0...0110
in binary or 0x6 in hexadecimal.
The following functions allow you to obtain site masks for all the sites in the enabled,
disabled, or sleep state:
read_sitemask_enabled();
Returns a site mask for all enabled sites.
read_sitemask_disabled();
Returns a site mask for all disabled sites.
read_sitemask_sleep();
Returns a site mask for all sleeping sites.
read_sitemask_all();
Returns a site mask for all sites being tested. This is the
equivalent of ORing the 3 first site masks.
In addition, the following function obtains a site mask for all sites that failed the last
sequencer:
read_sitemask_failed_sequencer();
Returns a site mask of all sites failing a sequencer. If called from
within a sequencer, the site mask returned identifies the sites
that failed that sequencer so far.
IMAGE Solutions V8.3 17-26
IMAGE Base Language: Multisite Testing: Assigning and Accessing Bin Numbers
Table of Contents Index Home Master Index Search Help
Assigning and Accessing Bin Numbers
Bin numbers in a multisite test program are assigned and accessed using the same
statements and routines used in a single device program. Some statements, however, must
be used inside serial blocks in a multisite test program. Use the following inside a serial
block:
sort bin= <bin_number>;
tl_get_last_seq_bin();
tl_get_seq_bin();
tl_get_sort_bin();
tl_get_sort_hbin();
An example would be:
int bin_number;
...
set site_enable_all;
serial {
... /* Determine a bin number for a site */
sort bin= bin_number;
}
Here, the final bin number is calculated rather than being set directly in a sequencer
statement so the sort bin= version of the statement is used. Since serial blocks execute
only for still active devices, to bin all devices, the set site_enable_all statement is used
before the serial block.
NOTE
A sort bin statement (without the equal sign) is usually not used in a serial block, although
it is legal to do so. It is usually used to bin all devices at once.
IMAGE Solutions V8.3 17-27
IMAGE Base Language: Multisite Testing: System Variables
Table of Contents Index Home Master Index Search Help
System Variables
The function read_current_site() is available inside a serial block to determine which
site is being tested during a pass through the serial block. You usually do not need to know
this. This function may be called, however, if you must take different actions based on the
site or index an array based on the site number. The function returns the site being tested
on this pass through the serial block. For example:
serial {
switch (read_current_site()) {
case 0: /* Do this for site 0 */ break;
case 1: /* Do this for site 1 */ break;
default:/* Do this for other sites */ break;
}
}
Calling this function outside of a serial block has no meaning, and it will return a negative
number.
Alternatively, for backwards compatibility, you can access the system variable tl_site
directly. This variable is normally set to the site being tested on a pass through the serial
block. However, in some cases, such as after a failing test statement, it is set to a negative
value. Use read_current_site() instead of accessing tl_site directly.
You can call tl_site_active() to determine if a site or any sites are still active. The
function returns TRUE if the site is active or FALSE if it is not. Inside a serial block it returns
TRUE if the site tested on this pass through the serial block is still active. It returns FALSE if
the device has been disabled (failed). Outside a serial block the function returns TRUE if any
devices are still active. It returns FALSE if all devices have failed.
Example (in a sequencer function):
seq test1() > 10.0ma < 15.0ma f(2);
if (tl_site_active()) printf("About to call test2\n");
seq test2() > 4.8v < 5.2v f(3);
The message About to call test2 is printed only if at least one device is still being
tested.
IMAGE Solutions V8.3 17-28
IMAGE Base Language: Multisite Testing: Digital Signal Processing
Table of Contents Index Home Master Index Search Help
Digital Signal Processing
Testers can contain one array processor for digital signal processing. This must be shared
among all devices being tested. (Tiger, Catalyst, and some A580 testers do not use a
separate array processor for DSP. See “Digital Signal Processing” on page 18-1.) Array
processor calculations are, therefore, typically included in a serial block as in this example:
a. #define SAMPLE_SIZE 2048
TESTF distortion()
{
start pattern= "x1000"; /* Start digital pattern */
set dpin= DOUT0 /* Enable capture */
lfdig: sample_size= SAMPLE_SIZE enable_capture;
b. set pin= AIN /* Gen input sine wave */
lfsrc: lpfilt= 4khz amp= tl_retrieve_d("gain") * 0.5;
start pin= AIN
lfsrc: segment= sine_f1k;
c. wait 2ms;
resume pattern; /* Synchronize */
d. serial {
set dpin= DOUT0 digcap: enable_read;/* Enable rd for 1 site */
move digcap: size= SAMPLE_SIZE /* Move data to DSP */
to: dsp_data= capture_data;
test analyze_spec(); /* Use DSP to analyze */
}
}
In this example, data is captured in parallel on all devices. This is the time consuming part
of the test. Then the data is analyzed separately for each device by moving the data for one
device into the array processor. The function analyze_spec performs the actual analysis in
the array processor and returns a value. analyze_spec is written to process the data from
only one device. The value returned from the function is passed to the test statement for
comparison against the test limits in the calling sequencer statement.
IMAGE Solutions V8.3 17-29
IMAGE Base Language: Digital Signal Processing
Table of Contents Index Home Master Index Search Help
18 DIGITAL SIGNAL PROCESSING
Digital Signal Processing (DSP) for mixed-signal device testing is a key capability of the
Tiger, Catalyst, and A5xx PowerPort test systems.
DSP-based test methods use waveform synthesizers and digitizers, instead of analog
source and measurement instruments, to stimulate and measure devices. With DSP-based
testing, analog hardware instrument functions are replaced by algorithms executing on
computers. One major advantage is reduced test time. A significant cost has been the time
and expertise needed to develop DSP-based test programs.
DSP-capable systems have an architecture that supports high throughput DSP-based
testing. Test language features, in particular a feature set named FlexDSP, are designed to
simplify test program development and reduce the programming effort and expertise
needed.
This section includes the following topics:
• “Basic Features and Specifications” on page 18-2
• “Background: DSP-based Testing” on page 18-3
• “DSP-enhanced Tester Architecture” on page 18-6
• “Overview of FlexDSP” on page 18-7
• “Output Parameter for Capture Instruments” on page 18-10
• “Data Arrays” on page 18-12
• “Compute Blocks” on page 18-16
• “Signal Processing Operations on Data Arrays” on page 18-21
• “Other Operations on Data Arrays” on page 18-22
• “Programming With FlexDSP” on page 18-23
• “Running and Debugging FlexDSP Programs” on page 18-30
• “FlexDSP Operation” on page 18-31
• “Creating Custom Block Algorithms” on page 18-32
IMAGE Solutions V8.3 18-1
IMAGE Base Language: Digital Signal Processing: Basic Features and Specifications
Table of Contents Index Home Master Index Search Help
Basic Features and Specifications
DSP-enhanced test systems include these features:
• DSP architecture - A “parallel” tester architecture for decreased test execution time
– A high bandwidth control bus and four high bandwidth data busses: Maximum data
rate for each data bus: 25 Mbytes/second
– A multiprocessor test computer and a threaded operating system:
1 or 2 UltraSPARC processors running Solaris 2.5.1, or later versions
– Capture instruments with “banked” memory
• FlexDSP - A software feature set for decreased program development time
– Software-based DSP - DSP operations are function calls
– A library of high level, test and measurement functions - Test programs can use
simple equations
– A set of C extensions in IMAGE Test Language (ITL) constructs - Code to be
executed in parallel can be simply identified and programmed
IMAGE Solutions V8.3 18-2
IMAGE Base Language: Digital Signal Processing: Background: DSP-based Testing
Table of Contents Index Home Master Index Search Help
Background: DSP-based Testing
The DSP-enhanced tester architecture and the IMAGE FlexDSP feature set were designed
for DSP-based testing. The following summary of DSP-based test methods will help you
understand and use these test systems.
DUT Stimulus, Response, and Measurement
DSP-based testing uses source instruments, capture instruments, and a computer
processor to calculate the value of one or more measured device characteristics.
DSP test algorithms usually include the following steps:
1. Stimulate a device-under-test (DUT).
2. Capture the DUT response to the stimulus.
3. Move captured data to the computer (if processor is not local to the instrument, as is the
case for Catalyst and A5 test systems).
4. Compute one or more measurement results, using the captured data.
5. Make a test decision by comparing the computed results to limits.
The test time used for stimulating the DUT can be reduced by:
• Using the optimal test method and signals for stimulus
• Configuring the tester with enough source instrument outputs to allow all DUT inputs to
be stimulated “in parallel” (that is, at the same time)
The test time taken by stimulus tasks is usually less dependent on tester architecture than
the test time taken by measurement tasks.
Measurement of the response of the DUT to the stimulus involves three programmed
operations (see figure 18-1):
• Capture of the device response data by an instrument
• Movement of the captured data to the processor
• Execution of analysis computations on the processor
Relative duration of the three operations will vary depending on the DUT, the characteristics
and parameters tested, and the test methods and instrumentation used.
S Measurement
S e
t t M T
Instrument a t Device response/ o e
r l v Compute s
setup data capture
••• t e e t •••
Program Execution Sequence - Measurement for a Single Test
Figure 18-1. Measurement Operations for a DSP-based Test
IMAGE Solutions V8.3 18-3
IMAGE Base Language: Digital Signal Processing: Background: DSP-based Testing
Table of Contents Index Home Master Index Search Help
In the simplest case, each of the measurement tasks are executed serially, that is, in
sequence, one after another. The whole sequence is repeated for each test. Since the test
computer is idle during data capture and the DUT is idle during computations, this simple
approach is inefficient, especially in a program with many tests.
Test Time Reduction Techniques: Pipelining and Multisite Testing
Two approaches are commonly used to reduce inefficiency and test time: pipelining and
multisite testing.
Pipelining
During a series of measurements, data captures can be programmed to overlap with
computations. This technique is known as “pipelining.” Pipelining speeds up execution by
reducing the time the test computer and the DUT are idle.
The term pipeline is used to describe a program structure that allows two or more
sequences of tasks to be overlapped and synchronized with each other. An overlapped
sequence is a “pipeline.” See figure 18-2.
Programs that incorporate pipelines are complex. Expertise is required to write and debug
programs using pipelines.
Pipeline setup Compute pipeline
Compute Compute Compute Compute
Capture Capture Capture Capture
Test Program Execution Flow
Figure 18-2. Example: Execution Flow of Pipelined Compute Tasks
Multisite Testing
A test “site” is a location on the device interface (test fixture) for one device under test.
Multisite testing occurs when the separate devices at multiple sites are stimulated
simultaneously so they can all respond at the same time, in parallel. See figure 18-3.
IMAGE Solutions V8.3 18-4
IMAGE Base Language: Digital Signal Processing: Background: DSP-based Testing
Table of Contents Index Home Master Index Search Help
Source Site 1
Capture
Site 2
Capture
Source Site 3
Capture Site 4
Capture
Device Interface
Tester Instruments (Fixture)
Figure 18-3. Elements of Multisite Testing
Capability for parallel measurement depends on the test system architecture, the instrument
resources and test programming features available.
For more information, see “Multisite Testing” on page 17-1.
Tester Architecture Requirements for DSP
Ideally, a test system would be able to test the results of computations on the captured data
immediately. Test time would then be limited to stimulus time plus device response time.
This ideal does not exist.
Practically, the maximum reduction in test time is provided by a test system that can:
• Capture the responses of all devices simultaneously and continuously
• Move all the captured data to the computer in much less time than the typical device
response time
• Process the data into measurement results in much less time than the typical device
response time
DSP-capable tester architectures address these requirements for DSP-based testing.
IMAGE Solutions V8.3 18-5
IMAGE Base Language: Digital Signal Processing: DSP-enhanced Tester Architecture
Table of Contents Index Home Master Index Search Help
DSP-enhanced Tester Architecture
The architecture of testers designed for DSP-based testing is shown in figure 18-4.
Features for DSP-based testing include:
• Multiple high-bandwidth data busses allow large captured data sets to be quickly and
simultaneously transferred to the computer from multiple capture instruments
• A test computer with operating system support for multiple “threads” of computation
allows parallel execution of data moves and computations. A thread is single sequential
flow of control, with a beginning, execution sequence, and end, within a program.
Multiple threads in a program can all run at the same time and perform different tasks.
Threads are the software mechanism for the concurrent and parallel task execution
needed to take advantage of the DSP-enhanced architecture.
• Optional second processor, allowing true parallel computations
• Capture instruments with “banked” memories allow simultaneous capture and data
movement, or almost continuous data capture
High-Speed
Digital
DSP-Capable Test Computer
Subsystem
Bus I/F
Control
CPU 1 Source
Data1
Data2 Capture
CPU 2*
Data3 Device
Precision Source Under
Data4
AC Test
Data Subsystem Capture
Busses
Source
Capture
²
²
²
* Note: CPU 2 is optional
Figure 18-4. Diagram of DSP-enhanced Architecture
IMAGE Solutions V8.3 18-6
IMAGE Base Language: Digital Signal Processing: Overview of FlexDSP
Table of Contents Index Home Master Index Search Help
Overview of FlexDSP
ITL for Tiger, Catalyst, and A5xx with PowerPort has a set of programming features called
FlexDSP, designed to simplify writing DSP-based test programs and allow you to take
advantage of the DSP-enhanced architecture.
At a high level, to develop a high throughput DSP-based test program, you must:
1. Write and debug code to perform the computations on the captured data that are
required by your test method.
2. Create threads and control their execution on one or, optionally two, test computer
processors.
3. Manage testing and test result processing of multiple device sites.
FlexDSP provides features to support these tasks:
• Three C language extensions as part of ITL:
– Compute block - A statement that identifies code that can be autopipelined:
automatically pipelined and executed in parallel, for all measurements and device
sites. Compute blocks are the programming interface for autopipelining. Test result
processing is managed for all test sites.
– DARRAY - A variable type referring to an internal structure, called a data array, that
manages the data used by code that is automatically pipelined and executed in
parallel, inside a compute block.
– Capture instrument output parameter - A parameter in the set statement for
capture instruments that allows automatic background movement of the captured
data into a data array for processing inside a compute block.
• A library of measurement routines - These functions, called block algorithms, return
values for common device measurements. The routines are called block algorithms
because each one replaces a sequence of basic, lower level vector processor
operations. In the C language, “block” is another term for compound statement. Block
algorithms are the “compound statements” of DSP.
• A library of “thread-safe” basic DSP algorithms, similar to A5 algorithms. These basic
routines can be used for data analysis requirements not met by the library of block
algorithms.
The DSP architecture does not include special digital signal processor hardware. Because
of this, there are no special syntax or data buffers corresponding to the signal processor
instrument. DSP computations are programmed using function calls on variables you
declare as a special type (DARRAY), described below.
The captured data flow through the FlexDSP feature set is shown in figure 18-5.
IMAGE Solutions V8.3 18-7
IMAGE Base Language: Digital Signal Processing: Overview of FlexDSP
Table of Contents Index Home Master Index Search Help
Capture Data Computation Basic routines
instrument(s) structure structure ROUTINES
DSP analysis
output Data compute routines
BLOCK
parameter array block ALGORITHMS
Block
algorithms
Device response(s) Measurement result(s)
Figure 18-5. Captured Data Flow Through the FlexDSP Feature Set
When used in a multisite program, multiple capture instruments can capture multiple
responses of a single device, or multiple device responses, and the sample data for each
response is analyzed separately. IMAGE manages the separate processing of test results
for all devices.
FlexDSP does not support programming threads explicitly using low level calls to the
operating system. All thread programming is done at a high level using compute blocks.
An ITL programming example using FlexDSP features is in figure 18-6.
IMAGE Solutions V8.3 18-8
IMAGE Base Language: Digital Signal Processing: Overview of FlexDSP
Table of Contents Index Home Master Index Search Help
TESTF example()
{ • DARRAY - Data will be
DARRAY cap_samples=DA_NULL;
managed by IMAGE
set pin= AOUT plfdig: output= &cap_samples
enable_capture;
da_set_Fs(cap_samples, 64.0e3);
start pin= AOUT plfdig; • output parameter - data
will be automatically
compute(cap_samples)
moved in the background
DARRAY cap_samples;
{
DARRAY real_samples= DA_NULL;
DARRAY fft_freq= DA_NULL; • Compute block - Data
DARRAY power_spec= DA_NULL; moves and computations
double fund, harm3, power_ratio; will be automatically
pipelined, in parallel
real_samples=da_frac_to_real(cap_samples);
fft_freq=da_fftb(real_samples);
power_spec=da_power_spectrum(fft_freq, DA_REAL);
fund= da_amplitude(power_spec, 1.0k);
harm3= da_amplitude(power_spec, 3.0k);
power_ratio= da_dB(harm3/fund);
• Block algorithms -
test fund;
test oriented
test harm3;
test power_ratio; analysis functions
}
}
Figure 18-6. Example: FlexDSP Program Code
IMAGE Solutions V8.3 18-9
IMAGE Base Language: Digital Signal Processing: Output Parameter for Capture Instruments
Table of Contents Index Home Master Index Search Help
Output Parameter for Capture Instruments
The output parameter in the set statement of some capture instruments is the ITL syntax
feature that allows them to work with FlexDSP.
Capture instruments on DSP-capable systems may have an output parameter in the set
statement. The output parameter allows you to specify a variable of type DARRAY as the
destination for the samples captured. If you pass the destination DARRAY name into a
compute block, captured data will be moved implicitly, that is, without any other statement
specifically causing data to be moved.
The following set syntax is common to all of the capture instruments that support FlexDSP:
set pin = <pin_spec> <capture_inst>:
output=<data_array_address>;
where:
<pin_spec> Is the specified pin for the capture instrument in the pinmap.
<capture_inst> Is the capture instrument that will move data to the destination
data array.
<data_array_address>
Is the address of the data array, declared as type DARRAY, in the
form &<darray_name>.
NOTE
You must specify the value of the data array address for the output parameter using the
operator &.
Descriptions of other capture instrument syntax related to data movement, such as vector
size and data type, and procedures for use, are contained in the individual capture
instrument sections. See “Supported Capture Instruments” on page 18-11.
Automatic Background Move
The implicit movement of data described above is called an automatic background move. It
is automatic because you do not have to explicitly program data movement. The move will
be in the background because the compute block can assign a separate thread to the data
move so it may occur concurrently with other operations (setups, captures, moves and
computations) during autopipelining.
If you program an automatic background move, you do not have to use a move statement
to move data. When execution enters the compute block, as soon as data capture is
complete, the captured data will be moved into the destination data array.
IMAGE Solutions V8.3 18-10
IMAGE Base Language: Digital Signal Processing: Output Parameter for Capture Instruments
Table of Contents Index Home Master Index Search Help
If you use the output parameter to assign a destination data array and do not operate on
the data array inside a compute block, the parameter and the data array are ignored during
execution.
For more information on using the output parameter, see “Programming an Automatic
Background Move” on page 18-23.
Supported Capture Instruments
The following capture instruments support the output parameter and FlexDSP automatic
background move. See the individual instrument sections for details.
• Precision Low Frequency Digitizer (plfdig)
See “Using the Output Parameter for an Automatic Background Move” on page 17-30
in the Catalyst Instrumentation Manual.
• Low Frequency AC Digitizer (lfacdig)
See “Using the Output Parameter for an Automatic Background Move” on page 14-35
in the Catalyst Instrumentation Manual or “Using the Output Parameter for an Automatic
Background Move” on page 20-33 in the Catalyst Tiger Instrumentation Manual.
• Very High Frequency Digitizer (vhfdig)
See “Automatic Background Move” on page 30-36 in the Catalyst Instrumentation
Manual.
• DSIO Digital Capture (dig_cap)
See “Using the Output Parameter for an Automatic Background Move” on page 41-66
in the Catalyst Instrumentation Manual or “Using the Output Parameter for Automatic
Background Moves” on page 41-22 in the Catalyst Tiger Instrumentation Manual.
• 1GHz Very High Frequency Digitizer (1gvhfd)
See “Automatic Background Move” on page 30-36 in the Catalyst Instrumentation
Manual or “Automatic Background Move” on page 14-34 in the Catalyst Tiger
Instrumentation Manual.
• Time-Jitter Analyzer (tja)
See “Moving Time Stamp Data” on page 50-34 in the Catalyst Tiger Instrumentation
Manual.
• Gazelle Digital (ghsd)
See “Moving Captured Data” on page 43-51 in the Catalyst Instrumentation Manual.
• GigaDig (gigadig)
See “Automatic Background Move” on page 31-22 in the Catalyst Instrumentation
Manual or “Automatic Background Move” on page 15-22 in the Catalyst Tiger
Instrumentation Manual.
IMAGE Solutions V8.3 18-11
IMAGE Base Language: Digital Signal Processing: Data Arrays
Table of Contents Index Home Master Index Search Help
Data Arrays
A data array is an IMAGE structure that holds sample data from a capture instrument for up
to eight test sites, plus other site-independent data. In addition you can use as many data
arrays as you need for data processing. The data array allows IMAGE to manage the
sample data during parallel execution of autopipelined data moves and computations inside
compute blocks.
Type DARRAY
To refer to the data in a data array, you must declare and use a variable of type DARRAY.
The DARRAY type is a C extension within ITL.
The syntax for the DARRAY declaration is:
DARRAY <data_array_name> = DA_NULL;
where:
<data_array_name> Is the variable name you choose to declare for the data array.
Data Array Initialization
Always initialize the value of the DARRAY you declare by assigning it the value DA_NULL. This
avoids possible erroneous results due to the newly declared DARRAY being set to an internal
handle value that already in use, that is, that already references a data array that has data.
Example:
DARRAY captured_samples = DA_NULL;/* captured_samples can accept
instrument output and be used
in a compute block */
A reference to a data array can be described in several ways. See “Data Array Name vs.
Handle”.
A data array is often associated with a capture instrument. A data array is created
automatically if the output parameter for a capture instrument is used. By default, a data
array and its data stay (persist) in memory until the end of the TESTF that contains the
compute block where the data is used. You can set other values for how long data arrays
persist. See “Lifetime” on page 18-15.
If necessary, you can create a data array to hold data that you need for analysis
computations inside a compute block. See “Moving Sample Data Explicitly” on page 18-23.
Data Array Name vs. Handle
In this manual, data array and DARRAY are used interchangeably to refer to the structure
holding the sample data. Strictly speaking, the data array is the internal IMAGE structure
IMAGE Solutions V8.3 18-12
IMAGE Base Language: Digital Signal Processing: Data Arrays
Table of Contents Index Home Master Index Search Help
that contains the data and the DARRAY is the type of the variable used to refer to the data
array.
In addition, the term handle is sometimes used to refer to variables of type DARRAY.
In summary, functions that operate on data arrays may specify inputs as one of:
• The data array name
• The data array handle
• The DARRAY name
• The DARRAY handle
Data Array Contents: Sample and Attribute Data
Data arrays contain two categories of user-accessible data:
• Sample data: vectors of captured data, one vector per site
• Information about sample data (attribute data)
Sample Data
Sample data from a capture instrument is the primary content of a data array. The data array
structure allows IMAGE to multiplex and demultiplex the sample data for individual sites,
maintaining a separate sample data set for each site.
Attribute Data
In addition to sample data, the data array also contains information about (attributes of) the
sample data. The values of the attributes are common to all test sites.
Information about sample data (attribute data), includes:
• “Data Type” - numeric type of all samples, for all sites
• “Size of Sampled Data” - length of sample data vectors, for all sites
• “Sample Frequency” - sample frequency of data samples, for all sites
• “Test Frequency” - fundamental frequency of data samples, for all sites
• “Lifetime” - time of persistence of a data array and its data in memory
You can read, write and print the attribute data in data arrays. See “Other Operations on
Data Arrays” on page 18-22.
Data Type
FlexDSP supports the following data types:
DA_REAL Single precision floating point
DA_DREAL Double precision floating point
DA_INT 32-bit signed integer
IMAGE Solutions V8.3 18-13
IMAGE Base Language: Digital Signal Processing: Data Arrays
Table of Contents Index Home Master Index Search Help
DA_FRACT2 Fixed point fraction, in range of -1 to 1
DA_CMPLX Single precision complex
DA_DCMPLX Double precision complex
Nonconforming Data Type Symbols
The above symbols replaced a similar set that did not have the prefix DA_ in IMAGE
V6.2.ct4. To run programs written and compiled before V6.2.ct4, you must either change
the symbols to the updated data type symbols above or place the following line in your
.load file:
-define DA_USE_NONCONFORMING_TYPE_NAMES
Type Conversion
Block algorithms support automatic data type conversion, or promotion. The conversions
are ordered as shown in figure 18-7. When an operation is performed on data with different
types, all data is converted to the type next higher in the diagram.
For example, if an operation is performed with DA_INT and DA_FRACT2 data, the operands
are converted to DA_REAL.
DA_DCMPLX
DA_CMPLX DA_DREAL
DA_REAL
DA_INT DA_FRACT2
Figure 18-7. Automatic Data Conversion Ordering
Sample Frequency
The sample frequency is the sampling rate associated with a sample set. If an analysis
function requires it, you must specify the sample frequency since it is not passed from the
capture instrument.
IMAGE Solutions V8.3 18-14
IMAGE Base Language: Digital Signal Processing: Data Arrays
Table of Contents Index Home Master Index Search Help
Size of Sampled Data
The size attribute of the data array holds the number of elements (length) of the sampled
data set.
Test Frequency
The test frequency is a frequency specification used by some block algorithms. If the
function requires it, you must specify the sample frequency.
Lifetime
The lifetime of a data array is how long the structure and its data persists in memory. A data
array is a structure with allocated memory.
To conserve allocated memory, IMAGE sets the default lifetime of a data array to be until
the end of the TESTF in which it is declared or defined. You can set the lifetime to be until
the run is completed, or until the test program is unloaded.
IMAGE Solutions V8.3 18-15
IMAGE Base Language: Digital Signal Processing: Compute Blocks
Table of Contents Index Home Master Index Search Help
Compute Blocks
A compute block is a program construct that identifies code that can be autopipelined
(automatically pipelined and executed in parallel). A compute block is implemented as the
compute statement, a C extension within ITL.
Autopipelined program tasks include data movement, computations on data, and test result
processing for all test sites.
Compute blocks provide a high level mechanism and simple syntax for creating and
controlling parallel threads of execution on one or more test computers. IMAGE does not
support programming threads explicitly using low level calls to the operating system.
Threads are programmed only by using compute blocks.
Syntax for the compute statement is:
compute( <parameter(s)> )
<parameter declaration>;
{
<ITL statement(s)>
}
where:
parameter A sequence of simple expressions used to transfer data into
computations spawned by compute block. The list of
expressions accepted is restricted. See “Syntax Rules” on page
18-17.
parameter declaration
Declarations for the names used in the compute block. Each
parameter must be declared separately. See “Syntax Rules” on
page 18-17.
ITL statement(s) Any sequence of allowable ITL statements. See “Restrictions on
ITL Statements” on page 18-19.
Aspects of Programming With Compute Blocks
To write programs using compute blocks, become familiar with the following aspects of
using them:
• Differences between a compute block and a C function. The compute block is an
extension to C, within ITL. It is similar to a function, but with important differences. See
“Compute Blocks and C Functions” on page 18-17.
• Syntax rules. See “Syntax Rules” on page 18-17.
• Scoping rules. Because of the way IMAGE implements control of parallel processing,
the scope of variables may initially be confusing. See “Scope Rules” on page 18-18.
• ITL statements allowable in compute blocks. As the control interface for parallel
processing, compute blocks cannot execute some ITL statements. See “Restrictions on
ITL Statements” on page 18-19.
IMAGE Solutions V8.3 18-16
IMAGE Base Language: Digital Signal Processing: Compute Blocks
Table of Contents Index Home Master Index Search Help
• Guidelines for structuring programs using compute blocks. When you use compute
blocks, you must structure your test program in specific ways to ensure autopipelining
operates correctly and your program structure does not negate the advantages of using
compute blocks. See “IMAGE Program Structure and Compute Blocks” on page 18-26.
• Test result processing and data logging.
• Compute blocks and multisite test. Compute blocks extend IMAGE multi-site (also
referred to as parallel test) capabilities to allow pipelining and parallel processing of data
analysis computations.
Compute Blocks and C Functions
Although similar in appearance, compute blocks are not C functions. Areas of difference are
the following:
• Expression types accepted. A limited number of simple expression types can be passed
into a compute block.
• Parameter declaration syntax required. Syntax for parameter declarations requires that
each variable be declared separately.
• Parameter types accepted. A limited number of parameter types can be passed into a
compute block.
• Scope of variables. Variables in a function that includes the compute block are not within
the scope of the compute block and must be passed in to be used.
• Nesting constraint. Nesting (placing a compute block inside a compute block) is
prohibited. A compute block cannot be placed inside a compute block, either directly or
indirectly (by calling a function that contains a compute block).
For details, see “Syntax Rules” on page 18-17.
Syntax Rules
The following syntax rules apply to the compute statement:
• Expressions that may be passed into a compute block include
– variables of form name
– pointers of form *name
– addresses of form &name
Other expression forms result in compile errors.
• Parameter declarations must be done individually, each as a separate statement.
Examples:
Correct - This will compile:
compute (input1, input2)
int input1; /*CORRECT: Each variable */
int input2; /* declared in separate */
{ /* statement. */
<statements>
}
IMAGE Solutions V8.3 18-17
IMAGE Base Language: Digital Signal Processing: Compute Blocks
Table of Contents Index Home Master Index Search Help
Incorrect - This will not compile:
compute (input1, input2)
int input1, input2; /*ERROR: Two variables */
{ /* declared in same */
<statements> /* statement. */
}
• Types of parameters that can be passed into a compute block include
– char - signed and unsigned
– int - long, native, and short
– float and double
– pointers and addresses
A DARRAY name or handle is type int.
• The sequence of statements has special scope rules. See “Scope Rules”.
• You cannot place a compute block inside a compute block. This is called “nesting.” In
addition, a function called from inside a compute block cannot include a compute block.
The reason for the nesting restrictions is that a compute block creates a thread of
execution different from the main thread of execution. Compute blocks cannot be
created by a thread other than the main thread. Therefore, a compute block cannot
directly or indirectly (by function) contain another compute block.
• The tester cannot be programmed inside a compute block. Statements that program
tester hardware, such as set and move, cause compiler errors.
The reason for this restriction is that IMAGE manages captured data movement,
computations, and test results processing during parallel execution of separate threads.
Management of tester hardware resources and control data in a multithreaded
environment is prohibitively complex.
Scope Rules
An important difference between a compute block and a C function is the scope of variables.
The scope of a variable determines where a variable is available to be used. A compute
block appears to be the same as a function, but the implementation of the compute block
makes it behave differently from a function. For implementation details, see “How the ITL
Compiler Processes a Compute Block” on page 18-31.
For a variable to be available for use in a compute block, it must be one of the following:
• Global to the function (often a TESTF) that includes the compute block
• Local within the compute block
A compute block cannot reference a variable in the surrounding TESTF (or other function
which contains it). Surrounding variables must be passed in as parameters.
See examples in figure 18-8.
IMAGE Solutions V8.3 18-18
IMAGE Base Language: Digital Signal Processing: Compute Blocks
Table of Contents Index Home Master Index Search Help
Incorrect: Correct:
Variable from surrounding scope Variable from surrounding scope
used in compute block. passed into compute block before use.
TESTF t1() TESTF t2()
{ {
int var_in_t1_scope; int var_in_t2_scope;
compute() compute(var_in_scope_t2)
{ int var_in_scope_t2;
int result = var_in_t1_scope {
} int result = var_in_t2_scope;
} /* end of t1 */ }
} /* end of t2 */
Compile error:
undefined symbol: var_in_tl_scope
Figure 18-8. Example: Compute block variables and surrounding scope
Restrictions on ITL Statements
Not all ITL statements are allowed in the body of a compute statement.
This section uses the term “side thread.” This refers to threads of execution spawned during
execution of compute blocks.
The following statements are not allowed:
• Instrument set statements and move statements
These statements will cause a compiler error. They are not allowed because threaded
management of instrument hardware, with the exception of automatic background data
movement, is not supported by IMAGE.
• The compute statement
This statement will cause an error from the compiler. The compute statement creates a
side thread when executed. IMAGE does not allow a side thread to create another side
thread.
• A call to a function that contains a compute statement
This will cause a runtime error. A compute statement in a function called from a compute
block will result in a side thread trying to create another side thread. IMAGE prohibits
this.
• A SEQUENCER statement
This will cause a runtime error. Compute blocks create side threads. A SEQUENCER
statement must be in the main thread.
• A TESTF statement
This will cause a runtime error. All compute blocks must be inside a TESTF to ensure
proper test processing. Therefore, a TESTF is prohibited from being in a compute block.
IMAGE Solutions V8.3 18-19
IMAGE Base Language: Digital Signal Processing: Compute Blocks
Table of Contents Index Home Master Index Search Help
The following statement category is allowed, because it will not create a compiler or runtime
error, but is not recommended:
• Statements that write to shared data between compute blocks
Threads are independent and contend for execution: it is impossible to control or predict
the order of execution. If multiple threads are executing and writing to shared data, it is
very likely the data will be corrupted.
Although you can read shared data in compute blocks, do so only if you know the data
is not going to change value while the compute block is executing.
You cannot move compute blocks containing shared resources (see “Shared Resources
in Parallel Patterns” on page 17-15).
Data arrays are “thread safe.” That is, captured data is completely managed for
automatic background moves, computations using da_ DSP routines, and test result
processing in SEQUENCER statements.
IMAGE Solutions V8.3 18-20
IMAGE Base Language: Digital Signal Processing: Signal Processing Operations on Data Arrays
Table of Contents Index Home Master Index Search Help
Signal Processing Operations on Data Arrays
IMAGE provides a library of functions for analyzing captured sample data in data arrays.
You can safely use all functions with the prefix da_ in compute blocks. Several groups of
functions are available.
For complete descriptions of all FlexDSP functions, see “FlexDSP Programmer’s
Reference” on page 27-1.
Block Algorithms
Block algorithms are used to analyze sample data. They are high-level, test and
measurement functions that replace sequences of basic algorithms. For detailed
information on writing custom block algorithms, see “Creating Custom Block Algorithms” on
page 18-32.
For example, da_snr computes the signal-to-noise ratio of a sample data set.
Utility Functions
Utility functions provide simple operations on samples and block algorithm results.
For example, da_amplitude returns the amplitude (magnitude) of a frequency in a
spectrum.
Data Window Parameters
Data window parameters are data windowing algorithm types passed into block algorithms.
For example, da_hanning_window filters the sample data with the Hanning data windowing
function.
Basic Algorithms
Basic vector operations are also used to analyze sample data. The operations are similar
to the A5 DSP algorithms, but usable (thread-safe) in the FlexDSP environment.
IMAGE Solutions V8.3 18-21
IMAGE Base Language: Digital Signal Processing: Other Operations on Data Arrays
Table of Contents Index Home Master Index Search Help
Other Operations on Data Arrays
IMAGE provides a set of functions to allow you to create data arrays and to read, write, and
print data contents other than the sample data.
Creating Data Arrays
• Define (Create) a new data array
Reading Data
• Get the location of the sample data
• Get the type of the sample data
• Get the size allocated for sample data
• Get the sample frequency
• Get the test frequency
Writing Data
• Set the sample frequency
• Set the test frequency
• Set the lifetime of the data array
Printing Data
For debugging purposes, you may want to print out the contents of a data array:
• Print the contents of the data array
IMAGE Solutions V8.3 18-22
IMAGE Base Language: Digital Signal Processing: Programming With FlexDSP
Table of Contents Index Home Master Index Search Help
Programming With FlexDSP
Programming an Automatic Background Move
To program an automatic background move, you must perform the following steps:
1. Declare the destination data array, using the data type DARRAY, before the set
statement for the capture instrument. See “Data Arrays” on page 18-12.
2. Include the output= parameter in the set statement for the capture instrument. The set
statement cannot be in a compute block. See “Output Parameter for Capture
Instruments” on page 18-10.
3. Pass the data array into a compute block where you have programmed the analysis of
the captured data. See “Compute Blocks” on page 18-16.
See “Example: FlexDSP Program Code” on page 18-9.
Moving Sample Data Explicitly
In IMAGE V6.4 and later, you can use DARRAYs in a move statement. The DARRAY is specified
by the keyword data_array.
To move data from a DARRAY:
move data_array = <darray handle>
size = <integer size>
to:
<destination>
error = <int variable> /* optional */
A valid destination can be any of the following:
• A DSPBUFFER
• A file
• An array
• A DARRAY
To move data to a DARRAY:
move
<source>
to:
data_array = <darray handle>
error = <int variable> /* optional */
timeout = <time> /* optional */
A valid source can be any of the following:
• An instrument (such as PLFDIG or HFDIG)
• A DSPBUFFER
• A file
IMAGE Solutions V8.3 18-23
IMAGE Base Language: Digital Signal Processing: Programming With FlexDSP
Table of Contents Index Home Master Index Search Help
• An array
• A DARRAY
When a DARRAY is the destination and the DARRAY handle is invalid, the move statement
automatically creates a new DARRAY. For example:
DARRAY DA_filedata = DA_NULL;
move
file = "datafile"
size = 1024
to:
data_array = DA_filedata;
This creates a handle DA_filedata to a DARRAY which contains 1024 elements from
datafile.
When a DARRAY is the destination and the DARRAY handle refers to a valid DARRAY, the data
is converted from the source data type to the DARRAY’s data type as necessary. For
example, assume that the file fract2.data contains 1024 elements of type DA_FRACT2.
The following move statement will convert the data from DA_FRACT2 to DA_REAL and store it
in DA_realdata:
DARRAY DA_realdata = da_define(DA_NULL, DA_REAL, 1024);
move
file = "frac2.data"
size = 1024
to:
DA_realdata;
Table 18-1 shows legal data movement as a function of data type when moving data from a
DARRAY.
Table 18-1. Moving Data From a DARRAY
To DSPBUFFER To File To CPU
Data
Type D D D
I R D C F I R D C I R D C
C C C
Fract2 m c m c c
Integer m c m m c
Real c m c m c m c
Double c m m c m
Complex m c m m c
Double c m m c m
Complex
IMAGE Solutions V8.3 18-24
IMAGE Base Language: Digital Signal Processing: Programming With FlexDSP
Table of Contents Index Home Master Index Search Help
Table 18-2 shows legal data movement as a function of data type when moving to a DARRAY
from any source, provided that the source supports the given data type. For example, a CPU
source cannot be type Fract2.
Table 18-2. Moving Data to a DARRAY
To DARRAY
Data Type
F I R D C DC
Fract2 m c c
Integer m c
Real c c m c
Double c c m
Complex m c
Double Complex c m
Column labels are: F= fract2, I= integer, R= real, D= double, C= complex, DC= double
complex.
m indicates a data move only (no conversion is performed).
c indicates data type conversion is performed on moved data.
Blank spaces indicate no legal move.
When you use a DARRAY in a move statement, data is only moved for one site, based on the
value of tl_site. Therefore, in a multisite program the move must be in a serial loop.
(Single-site programs do not have that restriction.)
When using an instrument source and a DARRAY destination in a move statement, note that
the set statement for the instrument does not need the output= parameter which is needed
for automatic background moves with compute blocks.
In IMAGE V6.4, you can use a move statement to directly move data in and out of a data
array. You can also use the procedure below.
When developing a multisite program, you must use the da_ functions inside either a serial
loop or a compute block. Also, if you define data arrays and use them, you must program
management of multiple sites.
To move data to a data array:
1. Declare a variable of type DARRAY for the data array you want to create.
2. Define (create) and initialize the data array using the da_define function.
3. Get a pointer to the data vector of the data array.
4. Use a for loop to move the data from the C array to the data array.
IMAGE Solutions V8.3 18-25
IMAGE Base Language: Digital Signal Processing: Programming With FlexDSP
Table of Contents Index Home Master Index Search Help
The following example uses integer data:
int values[32], *intptr, i;
DARRAY inl_data = DA_NULL;
/* Define the DARRAY. Specify a size 32 integer array. */
inl_data = da_define(0, DA_INT, 32);
/* Get a pointer to the integer array. */
intptr = (int *)da_get_vector(inl_data);
...
<other code>
...
/* Move the data from the C integer array to the DARRAY. */
for (i=0; i<32; i++)
intptr[i] = values[i];
An alternate procedure, with a different step 4 and a programming example in a more
compact style:
1. Declare a variable of type DARRAY for the data array you want to create.
2. Define (create) the data array using the da_define function.
3. Get a pointer to the data vector of the data array.
4. Using the pointer as an array address, move the data from the C array to the data array.
Example:
DARRAY d_filter = da_define(DA_NULL, DA_INT, 32);
move aidata=values size=32 to:
adata=da_get_vector(d_filter);
To move data out of a data array, use the same set of steps, but reverse the direction of
data movement in the last step.
For example, the last line in the for loop of the example above for moving data to a data
array can be changed to move data out:
for (i=0; i<32; i++)
values[i] = intptr[i];
IMAGE Program Structure and Compute Blocks
IMAGE test programs have a basic structure that is determined by:
• The C programming language on which ITL is based
• The language extensions within ITL that support tester applications
For a complete description and discussion of ITL program structure, see “Test Program
Structure” on page 14-1.
In addition, test developers structure their programs in specific ways for various purposes.
For example:
IMAGE Solutions V8.3 18-26
IMAGE Base Language: Digital Signal Processing: Programming With FlexDSP
Table of Contents Index Home Master Index Search Help
• A company may have a standard for modular programming that specifies how many
sequencer statements are in a SEQUENCER function.
• A test developer may program pipelines for reduced test time.
There are many other reasons for particular program structures.
Compute blocks and the operation of threaded programs restrict the ways that programs
can be structured. These restrictions interact with the program structures listed above, and
many others not listed.
For ITL programs using compute blocks to operate efficiently, programs need to be
structured in the recommended way. Some programming styles and techniques are
incompatible with compute block operations and should be avoided.
Recommended Program Structure
To ensure correct and efficient execution of programs using compute blocks, structure your
test program using these guidelines:
• Place all data analysis inside compute blocks.
In addition to allowing the use of the thread-safe and efficient library of DSP routines,
analysis calculations in compute blocks allow you to avoid serial loops for multisite
testing.
• Place all test statement(s) inside, and at the end of compute blocks.
The test statement must be in the compute block to allow result processing for multiple
sites. The test statement begins synchronizing threads for result processing. Impact on
concurrent and parallel execution is minimized by putting the test statements last.
• Place all compute blocks inside a TESTF.
This allows autopipelining and test result processing to operate efficiently. You can also
place compute blocks between TESTFs, inside a SEQUENCER statement.
• Place all, or as many as possible, TESTFs in one SEQUENCER statement.
This allows maximum concurrency or parallelism during execution. To correctly process
test results, the thread are synchronized at both the beginning and end of the
SEQUENCER statement. If TESTFs with compute blocks are in different SEQUENCER
statements, autopipelining cannot take place across all TESTFs.
You can pass multiple data arrays into a compute block.
• Use only data arrays, referenced by variables of type DARRAY, to pass data from a
compute block to a function.
Because data arrays are thread-safe, data will not be corrupted during concurrent or
parallel processing.
• Use only “thread-safe” DSP routines in a compute block.
The library of DSP routines (da_<name>) work correctly with data arrays to multiplex and
demultiplex sample data. If you create your own routines, they must be safe.
• If your program relies on the results of compute block computations, use the thread
synchronization function tl_compute_sync.
The tl_compute_sync function forces the main thread of execution to wait for the
completion of all side thread execution.
IMAGE Solutions V8.3 18-27
IMAGE Base Language: Digital Signal Processing: Programming With FlexDSP
Table of Contents Index Home Master Index Search Help
Use this function with caution. If the main thread of execution could have continued,
synchronization defeats parallel execution.
Generally, programs with the recommended structure do not need additional calls to the
synchronization function.
A diagram of the recommended ITL program structure for programs using compute blocks
is in figure 18-9.
Programming Styles and Techniques to Avoid
Avoid the following styles and techniques:
• Manual pipelining - not needed; autopipelining is provided by IMAGE.
• Sequencer per TESTF - conflicts with FlexDSP architecture.
• Changing the move attributes of a given DARRAY between compute blocks without
enabling a new capture - conflicts with FlexDSP architecture.
IMAGE Solutions V8.3 18-28
IMAGE Base Language: Digital Signal Processing: Programming With FlexDSP
Table of Contents Index Home Master Index Search Help
main()
{
<call sequencer function> Use minimum number of
} sequencers (1 is ideal) for all
test functions with compute
blocks
Sequencer Function
SEQUENCER<name of sequencer function>()
{
<sequencer statement> Synchronization Points -
<sequencer statement> Implicit tl_compute_sync
}
Sequencer Statement
• Defines: Test Limits
Datalog Number
Datalog Label
Datalog Format
• Calls test function
• Receives pass or fail result
• Takes pass or fail action
FlexDSP FEATURES
Test Function Compute Statement (Block)
TESTF <name of test function>() • Data analysis using DA_
{ functions on data arrays,
DARRAY <darray name> passed in as type darray
<...> • Can call other functions
<...> • test statement(s) at end
<compute statement> compute(<parameters>)
parameter declaration;
<...> parameter declaration;
} {
<...>
<test statement>
Test Statement <test statement>
}
• Determines pass or fail
(limit comparison, for example)
• Datalogs result, if enabled
Figure 18-9. Recommended Structure for Test Programs with Compute Blocks
IMAGE Solutions V8.3 18-29
IMAGE Base Language: Digital Signal Processing: Running and Debugging FlexDSP Programs
Table of Contents Index Home Master Index Search Help
Running and Debugging FlexDSP Programs
Test programs using compute blocks execute multi-threaded. In engineering mode, you can
run programs either multi-threaded or single-threaded. See “Choosing Multi-threaded or
Single-threaded Program Execution” on page 5-24.
The IMAGE debugger does not support running to breaktraps during multi-threaded
execution. The debugger will run programs single-threaded if you use one or more
breaktraps and run to trap.
IMAGE Solutions V8.3 18-30
IMAGE Base Language: Digital Signal Processing: FlexDSP Operation
Table of Contents Index Home Master Index Search Help
FlexDSP Operation
IMAGE and Solaris Threads
How the ITL Compiler Processes a Compute Block
Outside of IMAGE, if you program threads manually using the Solaris operating system, you
call a library function to create a thread. The thread creation function accepts a pointer to a
user defined function. During program execution, a thread is created and it executes the
user function code.
IMAGE does not allow you to directly program threads using calls to Solaris. FlexDSP
provides the compute statement to identify program code you want to execute in parallel.
The ITL compiler produces executable code that incorporates thread creation.
During the processing of a compute block, the ITL compiler (see figure 18-10):
1. Creates a new function. This function is external, and outside the scope of the function
that contains the compute block.
2. Moves the ITL statements inside the compute block into the new function.
3. Replaces the statements with a call to the new function that contains them.
4. Adds an operating system function call to create a thread. The argument passed to the
thread creation function is the address of the new function.
User ITL Code Compiled Code IMAGE tl_compute Function
void myfunc() void myfunc() void tl_compute
{ { (functionPointer)
compute() 3 extern void tl_compute_1a();
void *functionPointer;
{
float result; 4 tl_compute(tl_compute_1a); {
result= 1 + 1; return; Solaris_Thread_Create
test(result); } (functionPointer);
}
void tl_compute_1a() }
return; 1
} {
float result;
2 result = 1 + 1;
test(result);
}
Figure 18-10. Example: ITL Compilation of Compute Block (Pseudocode)
IMAGE Solutions V8.3 18-31
IMAGE Base Language: Digital Signal Processing: Creating Custom Block Algorithms
Table of Contents Index Home Master Index Search Help
Creating Custom Block Algorithms
This section describes the process of writing custom block algorithms for DSP using the
DARRAY data structure. A high level design overview used in IMAGE block algorithms is
given and the different sections of those algorithms are explained. Also addressed is the
internal DARRAY structure and functions used to access their data. Additionally, some
attention is given to multithreading concerns.
DARRAY Data Structure
This section explains the DARRAY data structure. It describes some functions and techniques
useful in the effective manipulation of DARRAYs.
Creating a DARRAY
New DARRAYs can be created using the function da_define. An example using da_define
is as follows:
DARRAY new_darray;
new_darray = da_define(DA_NULL, DA_REAL, 128);
In this example, new_darray is assigned to a DARRAY handle, which describes the location
of the internals of the new DARRAY. The da_define parameters specify information about
the new DARRAY.
DA_NULL tells IMAGE to allocate a new handle for the new DARRAY. If an existing DARRAY
handle is used in place of DA_NULL, IMAGE reuses the handle for the new DARRAY. In most
cases, DA_NULL is sufficient.
DA_REAL is the datatype of the new DARRAY. It means that new_darray expects to be filled
with values of C type float. Other options for this parameter include the following:
DA_DREAL C type double
DA_INT C type int
DA_CMPLX C type COMPLEX
DA_DCMPLX C type D_COMPLEX
The complex types contain special structures as their elements. See “Use of Complex
Types” for details on handling this data type.
The 128 passed to da_define in the above example tells IMAGE to create a vector big
enough for 128 data points. One vector is created for each site in the test program.
Therefore, an eight site test program with a DARRAY size of 128 has eight vectors, each with
room for 128 data points.
IMAGE Solutions V8.3 18-32
IMAGE Base Language: Digital Signal Processing: Creating Custom Block Algorithms
Table of Contents Index Home Master Index Search Help
Use of Complex Types
COMPLEX data types are best illustrated by example. The following example shows how to
declare and access the parts of a COMPLEX variable:
COMPLEX *cptr = complex_data;
float rpart, cpart;
rpart = cptr->real;
cpart = cptr->imag;
In this example, the float variables rpart and cpart are set to the real and imaginary
parts of the COMPLEX variable complex_data. This is done using C syntax for manipulating
fields of structures. The type D_COMPLEX is analogous, using double variables rather than
float variables.
Accessing DARRAY Data
Accessing information stored in a DARRAY is essential when writing a block algorithm. This
section presents functions that give that access and explains each one briefly.
void *da_get_vector(DARRAY handle)
The most fundamental of the accessor functions, da_get_vector, provides a pointer to the
vector of data for the current site. This pointer can then be treated as a regular C array. For
example, the following code will change the third element of the current site into a zero:
DARRAY handle;
int *data_ptr;
handle = da_define(DA_NULL, DA_INT, 128);
data_ptr = (int*)da_get_vector(handle);
data_ptr[2] = 0;
Note several things here. First, on the fourth line, the value returned by da_get_vector is
cast as (int*). This allows the return type of da_get_vector, usually (void*), to match
the type of data_ptr. Second, on the fifth line, the third element of data is indexed as 2.
The indices of the data_ptr array begin at 0 and continue to 127, to access the 128th
element of data.
int da_get_type(DARRAY handle)
int da_get_size(DARRAY handle)
double da_get_Fs(DARRAY handle)
double da_get_Ft(DARRAY handle)
These functions return information stored in the DARRAY internal structure. The information
returned by these functions describes characteristics of the waveforms that they contain,
including:
Type Datatype of the elements. An example type is DA_REAL.
Size Number of elements of data, per site, the DARRAY contains.
Fs Sampling frequency which is the frequency at which the data
points are sampled. With an Fs of 1 kHz, for instance, samples
would be 1 ms apart.
IMAGE Solutions V8.3 18-33
IMAGE Base Language: Digital Signal Processing: Creating Custom Block Algorithms
Table of Contents Index Home Master Index Search Help
Ft Test frequency, which applies to periodic data and represents
the frequency of the waveform contained in the vector.
void da_set_Fs(DARRAY handle, double Fs)
void da_set_Ft(DARRAY handle, double Ft)
These functions allow information storage in the internal DARRAY structure. When given a
valid DARRAY handle and a value to store, they set the appropriate field in the internal
structure of the handle. The value can later be retrieved using a corresponding da_get_*()
function.
Structure of IMAGE Block Algorithms
IMAGE block algorithms are divided into two main parts, or layers:
• The error handling layer strips information out of the DARRAY, presents it in a form
convenient to the next layer, and verifies the user parameters.
• The computation layer computes the actual result.
Typically, these two layers are implemented in two separate functions. The error handling
function is user-callable and the computation function is called by the error handling layer.
A naming convention distinguishes computation functions from error handling functions.
This section discusses these layers, explaining techniques they use to get their tasks done.
An extended example is shown, a fictional algorithm called volts_per_second. This
algorithm calculates the time-average of the voltage level in its waveform for the current site.
Error Handling Layer
The purpose of the error handling layer is to simplify using block algorithms for both users
and programmers. This layer has two main tasks. First, it reads information you provide and
packages it for the computation layer. Second, it verifies that the provided information is
error-free. If any errors are detected, this layer takes the appropriate action.
The first task of the error layer is to translate information you provide into information useful
to the computation layer. Users typically provide information either as C parameters or as
information stored in the DARRAY structure. It is important to decide how you can most
conveniently give information to the algorithm.
The example algorithm (see “Example Error Handling Layer Function” on page 18-36) uses
both C parameters and the internal DARRAY structure to translate information. The vital
pieces of information this algorithm uses are the sampling frequency, the size of the vector,
and the vector itself. The prototype of the algorithm is as follows:
double volts_per_second(DARRAY handle, double Fs);
In this prototype you see that the sampling frequency Fs is a C parameter. The remaining
information, the size and the vector, is stored internally in the DARRAY. To get this
information, the algorithm could do something like the following:
int data_size;
double *data_vector;
IMAGE Solutions V8.3 18-34
IMAGE Base Language: Digital Signal Processing: Creating Custom Block Algorithms
Table of Contents Index Home Master Index Search Help
data_size = da_get_size(handle);
data_vector = (double*)da_get_vector(handle);
The task of translation is not completed by accessing the correct information. The final piece
is to package the information in a manner convenient to the computation layer. Most
typically this involves just passing the information as C parameters, as in the following call:
volts_per_second_computation(data_vector, data_size, Fs);
Sometimes, it makes sense to do some preliminary work on the information to make it more
palatable to the computation layer. While this is a stylistic point, it can make a big difference
in the simplicity and reusability of the computation layer. The key question to ask is, from
the computation standpoint, what information is fundamental to finding the right answer? In
this case, it may be natural to ask for the duration in time of the vector, as well as the vector
itself, and the size of the vector, in elements. In that case, the error layer may perform the
following:
double data_duration;
data_duration = data_size / Fs;
volts_per_second_computation(data_vector, data_size, data_duration);
The task of translation is to provide convenience to both the user of the algorithm and the
programmer. By examining key information from both perspectives, the error layer can
provide a simple and convenient interface between those two entities.
One other important task remains for the error layer, finding errors. User data is not always
correct and it is easier to handle errors when they are found up front.
You first need to understand the assumptions being made by the computation layer. Then
you must consider how user data could possibly break those assumptions.
For example, the computation layer may assume that the data_duration will be positive.
A user may break that assumption by passing a zero or a negative value for Fs. A simple
check in the error layer can rule out this possibility, as in:
if (Fs <= 0.0) { /* error code here */ };
Similar checks can be made for other failure conditions on user data. Calls to
da_get_vector(), for instance, will return NULL pointers if they encounter an error
condition. Checking for this NULL condition can save the trouble of debugging a
segmentation violation later on in the development cycle. The documentation on individual
da_get_*() functions (see “FlexDSP Programmer’s Reference” on page 27-1) explains the
error conditions and how they may occur.
Note that graceful error handling can be difficult in a language like ITL or C. Once an error
is detected, you must decide what to do, usually on an individual basis. You can, for
example, print an error to the screen, return a reserved error value, flag a global error
variable, or perform some combination of these. The action taken should allow easy
detection and correction of errors. Any such scheme would be satisfactory.
IMAGE Solutions V8.3 18-35
IMAGE Base Language: Digital Signal Processing: Creating Custom Block Algorithms
Table of Contents Index Home Master Index Search Help
Example Error Handling Layer Function
The following is an almost fully complete template for the example used in the previous
section. Some details on error handling have been omitted. It is intended to show what a full
error handling layer might look like.
a. double volts_per_second (handle, Fs)
DARRAY handle;
double fs;
b. { int data_size;
double data_duration;
double *data_vector;
c. /* Check for error - negative sampling frequency */
if (Fs <= 0.0)
{
printf ("An error has occurred\n");
return (TL_DA_ERROR);
}
d. /* Gather information */
data_size = da_get_size(handle);
data_vector = da_get_vector(handle);
data_duration = data_size / Fs;
e. /* Check for more errors */
if (data_vector == NULL)
{
printf ("An error has occurred\n");
return (TL_DA_ERROR);
}
f. if (data_size == TL_DA_ERROR)
{
printf ("An error has occurred\n");
return (TL_DA_ERROR);
}
g. /* Pass the information on to the computation layer.*/
answer =
volts_per_second_computation(data_vector,data_size,data_duration);
return (answer);
}
Computation Layer
The purpose of the computation layer is to produce an answer from the relevant information.
A well-designed computation layer should be able to stand on its own as a logical tool for
doing a given calculation. IMAGE computation layer functions are designed to have minimal
overhead while computing their result. The error handling layer should buffer these
functions from user errors and other conditions that would complicate their implementation.
In other words, the computation layer should get right to the point.
IMAGE Solutions V8.3 18-36
IMAGE Base Language: Digital Signal Processing: Creating Custom Block Algorithms
Table of Contents Index Home Master Index Search Help
Here is the example computation layer for the voltage average calculation:
double volts_per_second_computation(data_vector,data_size, data_duration)
double *data_vector;
int data_size;
double data_duration;
{ double result;
double total_voltage = 0;
int i;
for (i=0;i<data_size;i++)
total_voltage += data_vector[i];
result = total_voltage / data_duration;
return result; }
Notice how this routine contains nothing not directly related to calculating the final answer.
The error handling layer takes care of the context, while this layer does only the “real” work.
Multithreading Concerns
Typically, a block algorithm is called from inside a compute block in a multithreaded
program. This means that the program must account for the possibility that it will be run
concurrently or in parallel with other algorithms, possibly all accessing the same data. This
section looks at issues arising from multithreading.
The most common error in a multithreaded program is known as a data race condition and
occurs when two or more threads try to access the same piece of data at the same time.
Consider the case of a bank’s computer updating the balance in your savings account. One
thread may be adding 1% interest to your account, while another may be processing a
deposit of $100 you make at an ATM machine at the same time.
Thread 1:
temp = balance;
temp = temp * (1.01);
balance = temp;
Thread 2:
balance = balance + 100;
Assuming an initial balance of $100, you might expect the final balance to be either $201 or
$202, depending on whether the deposit is processed before the interest. However, if the
deposit is processed in the middle of thread 1, it is possible to find a final balance of $101.
Assume thread 1 assigns the variable temp and then multiplies by 1.01 to compute $101.
At the same time, thread 2 updates balance to $200. But, the value of temp is $101, and
then thread 1 finishes by clobbering the changes thread 2 made and writing $101 in the
balance. Your deposit is lost.
You can avoid such a problem by identifying data shared among the different threads
running the algorithm. This global data can take many forms, and it is often hard to identify.
Most generally, whenever two or more threads have a pointer to the same address, the data
at that address is global. Fields of the DARRAY structure are global data, with the exception
IMAGE Solutions V8.3 18-37
IMAGE Base Language: Digital Signal Processing: Creating Custom Block Algorithms
Table of Contents Index Home Master Index Search Help
of the data vector returned by da_get_vector(), which is site-specific. Any values that the
algorithm accepts by pointer are global data, unless the addresses passed through that
pointer are different for the different sites. Static variables declared in the algorithm are
global data. Global program variables are, of course, global data. Finding all the global data
in such an algorithm is difficult, but those are the most common instances.
Once global data is identified, it must be treated with care. The rules for handling global data
can be boiled down into two cases. If no thread will be modifying the data, no race condition
exists. If any thread will be modifying the data, synchronization techniques must be used.
These techniques are beyond the scope of this section. If possible, try to avoid writing to
global data in any algorithm that will be called from a compute block. If writing to this data
is unavoidable, refer to any multithreading reference for information on synchronization.
Sometimes, it may be your responsibility to manage multithreading concerns. For instance,
an algorithm that returns two values must write to pointers you supply. It would be wrong to
give the same addresses to different sites to supply their return values. It is also possible
that your program may try to manipulate a global variable at the same time as the algorithm.
In such cases, it’s up to you to eliminate any race conditions. You must supply different
output pointers to different sites and wait until the algorithm is finished manipulating global
variables to access that data. Of course, explicitly documenting such pitfalls is the
responsibility of the writer of the algorithm.
The key point to remember about multithreaded programming is to be careful about how you
treat global data. Avoiding race conditions by treating this data with care is a major step in
writing correct multithreaded programs.
IMAGE Solutions V8.3 18-38
IMAGE Base Language: Checkers
Table of Contents Index Home Master Index Search Help
19 CHECKERS
IMAGE includes a set of checker software programs designed to verify that the tester
hardware is functioning correctly. The two basic types of checker programs are:
• Self-test
• Maintenance and installation
Self-test checkers are designed to run on the test system without requiring you to remove
your device testing setup. They are the focus of this section.
This section covers the fundamentals of using the IMAGE checker programs, including the
following:
• “Understanding IMAGE Checkers” on page 19-2
• “Overview: Loading and Running IMAGE Checkers” on page 19-5
• “Loading Checkers” on page 19-6
• “Running Checkers” on page 19-12
• “Running Checkers Automatically” on page 19-22
• “Creating Custom Checker Runs” on page 19-34
• “Creating a Static Configuration” on page 19-43
For information on specific IMAGE checkers, see the Checker Description Manual that
corresponds to your tester.
For information on running Device Focussed Checkers, see “Device Focussed Checkers”
on page 20-1.
NOTE
The A500F, A510F, A520F, A530F, A535, A540F, A545, A550F, A555, A560, A565, A570,
and A580 test systems are not supported in IMAGE V8.0. That means V8.0 is not tested on
those systems. While the software may operate properly, Teradyne will not fix bugs in V8.0
that involve those testers only.
IMAGE Solutions V8.3 19-1
IMAGE Base Language: Checkers: Understanding IMAGE Checkers
Table of Contents Index Home Master Index Search Help
Understanding IMAGE Checkers
The IMAGE checker environment is a system of self-test checkers with a single user
interface. Using the interface, you can load a single checker at a time or a group of checkers
to test the entire tester. This enables you to change the focus of testing from specific to
general.
Checker Structure
A checker program can include the following functions:
• Initialization—this section (not included in all checkers) allows you to provide
information to set up the checker.
• Brief check—this section of a checker program includes functions to verify as quickly as
possible that the instrument is present and working.
• Full check—this section of a checker program includes additional functions, including
performance and verification tests such as memory checks and high and low speed
tests, to determine the full functionality of the instrument.
The results of each checker run are returned to IMAGE by the values CK_PASS, CK_FAIL, or
CK_INVALID.
Each checker is composed of the following files:
<checker_name>_table.tl
This is the table of the checker_name checker program and
contains all the entry points to the checker functions. It includes
files to be included (#include), name declarations, and the
checker table structures. This file also specifies the checker’s
name, default loop execution count, and execution mode.
<checker_name>.tl The source code file contains all the checker’s executable code,
such as sequencers, test functions, and support routines. Some
checkers may have more than one .tl file.
<checker_name>.load
The .load file for the checker_name checker program. This file
includes the names of the modules and libraries to be loaded
using the load command.
In addition, some checkers may load HSD patterns, wave files, and additional source code
files. These are listed in the .load file for each checker.
For example, the DC Subsystem checker .load file (dcst.load) includes the following
files:
dcst.tl
dcst_ubvi.tl
dcst_table.tl
IMAGE Solutions V8.3 19-2
IMAGE Base Language: Checkers: Understanding IMAGE Checkers
Table of Contents Index Home Master Index Search Help
Checker Types
Although IMAGE checkers are used to test a wide variety of test system functions, they are
grouped in two broad categories.
Self-test checkers are standalone checker programs that can be run at any time without
additional equipment or test system preparation.
Maintenance and installation checkers include a variety of programs used to test
functionality, for calibration, and other purposes. Some of these programs require external
hardware, such as a device interface board (DIB) or cable. Some maintenance and
installation checkers include an _mi suffix.
Minimum Hardware Configuration
The minimum hardware configuration that can be assumed to be available for checker use
is as follows:
• 3 DC V/I sources (matrixed sources src1 and src2 and dutsrc1)
• all 48 matrix pins
• 1 DC Voltmeter
• 48 stored data bits
• Terabus timer
• station multitimer
• Time Measurement Subsystem
How Checkers are Organized
The A500 family of testers is quite diverse. Some hardware, such as the data distribution
system, is common to all testers. Other hardware is specific to a tester or test head.
Checker Groups
To allow you to load the correct checkers on your tester, checker programs are organized
in groups. Checkers are grouped first by test-head type (advanced mixed signal, and
Catalyst Tiger), and then divided into mainframe and test-head groups. Common tester
hardware is included in a separate group. IMAGE checker groups include the following:
• Common Frame
• Advanced Mixed Frame
• Advanced Mixed Head
•
• Tiger Digital
• Tiger Analog
IMAGE Solutions V8.3 19-3
IMAGE Base Language: Checkers: Understanding IMAGE Checkers
Table of Contents Index Home Master Index Search Help
Grouping IMAGE checkers minimizes memory use by loading only relevant checkers into a
tester. This method also avoids using incompatible syntax in a checker in the wrong test
head.
Location of Checkers
Checker releases occur at the same time as IMAGE releases, and you may have more than
one version of checkers installed. IMAGE loads the version of checkers specified by the
/image/checkers link. To see which version of checkers is loaded, type the following in a
station window:
ls -l /image/checkers
You should see a listing such as:
checkers -> ckr_bin.6.3
In this example, the link is to checkers 6.3, so IMAGE reads the menu files in ckr_bin.6.3
and loads V6.3 checkers.
IMAGE reads the checker menu files from the path specified in the CKRBIN environment
variable. If the environment variable in CKRBIN is not set, IMAGE looks in /image/checkers
for the link and reads that menu file. You can set the CKRBIN environment variable to a
checker version by typing the following command in a station window before clicking on the
CHECKERS button:
setenv CKRBIN /image/ckr_bin.<version number>
Where <version number> is the checker version you want to load.
For example, to set the pathname to ckr_bin.6.3 and load V6.3 checkers use:
setenv CKRBIN /image/ckr_bin.6.3
The environment variable is read only once after you click on the CHECKERS button in the
station window. To change to another version of checkers, bring up another station window,
set the environmental variable to the new version of checkers that you want to load, and
click on the CHECKERS button.
NOTE
IMAGE V4.3 and later does not work with older versions of checkers. Newer IMAGE
versions use calibration information that is in the corresponding version of checkers.
IMAGE Solutions V8.3 19-4
IMAGE Base Language: Checkers: Overview: Loading and Running IMAGE Checkers
Table of Contents Index Home Master Index Search Help
Overview: Loading and Running IMAGE Checkers
The general procedure for loading and running IMAGE checkers is as follows:
1. Open a station window. You open either a tester-specific or an auxiliary station window,
depending on the type of checkers you wish to run. (See “Loading Checkers” on page
19-6.)
2. cd to a directory where you have write privileges.
3. Press RIGHT on the CHECKERS button in the station window and select the checkers to
load. This can be one of the standard selections or a custom selection you have set up.
(See “Loading Checkers” on page 19-6.) The checkers load.
4. Click LEFT on the RUN button. The Checker Supervisor menu appears. (See “Running
Checkers” on page 19-12.)
5. Select RUN CHECKER SEQUENCE from the menu. The checkers run.
IMAGE Solutions V8.3 19-5
IMAGE Base Language: Checkers: Loading Checkers
Table of Contents Index Home Master Index Search Help
Loading Checkers
The first task in running IMAGE checkers is loading the checker programs into a station
window. You can use any station, although tester-specific stations only allow you to load the
checkers and checker groups appropriate for the test head at that station. Auxiliary stations,
on the other hand, allow additional options, including loading System Checkers.
Auxiliary stations are:
• 3 to 10 on advanced mixed-signal testers
• 2 to 10 on A565/PATH II testers
• 3 to 10 on Catalyst testers
• 2 to 10 on Catalyst Tiger testers
You can load checkers using the CHECKERS button menu in the station window (figure 19-
1). All load selections in the CHECKERS button menu have command line equivalents that use
the load command. For more information on the load command, see “Loading Using the
load Command” on page 5-4.
Figure 19-1. Checkers Menu and System Check Pull-Right Menu.
The following sections describe the IMAGE options for loading checkers. They include:
• Checker groups. Loads selected checker programs in groups. Also includes the option
to automatically bring up the IMAGE debugger. See “Loading Checker Groups” on page
19-10.
• Fast-load checkers. Loads groups of checker programs faster than all other options.
See “Loading Checker Groups” on page 19-10.
IMAGE Solutions V8.3 19-6
IMAGE Base Language: Checkers: Loading Checkers
Table of Contents Index Home Master Index Search Help
• Individual checkers. Loads an individual checker program. Also includes the option to
automatically bring up the IMAGE debugger. See “Loading Individual Checkers” on
page 19-11.
• System checker. The system checker loads all available checker programs and
automatically checks all test heads in the tester. This selection appears only in an
auxiliary station. See “Loading the System Checker” on page 19-7.
• Custom checkers. Loads any custom checker groups you have saved. See “Creating
Custom Checker Runs” on page 19-34.
• Static Configure. Allows you to create and view checker groups for specific hardware
configurations. This selection appears only in an auxiliary station. See “Creating a Static
Configuration” on page 19-43.
Loading the System Checker
The IMAGE system checker allows you to automate execution of stand-alone checkers on
the test system. The system checker automatically checks all test heads present and loads
the checkers in several groups, as opposed to one checker at a time. IMAGE determines
which hardware is present by reading a hardware map and loads the associated checker
groups. You must execute the system checker from an auxiliary station.
At the end of a system checker run, three files are created to provide results of the system
checker execution:
• A merged summary file (ck_loop_summary_) displays a list of the checkers executed
and whether each checker failed or not.
• The ck_log_merged_ file stores the output printed to the screen during the system
checker execution.
• The datalog file (checker_datalog_) records the values of the tests that executed in
the checker. You can record all tests or failing tests only. The default is failed tests only.
You can run the system checker once or in a continual loop. You can also select daily,
weekly, or monthly automatic checker execution modes (after they have been saved) and
datalog modes or you can alter the checker execution and datalog modes. This option does
not allow use of the IMAGE debugger.
Using the checkers Button Menu
The SYSTEM CHECK menu item has a pull-right menu (figure 19-1) with the following options
to load and run checkers:
SYSTEM CHECK Loads and runs test system checkers once.
SYSTEM CHECK -BRIEF Loads and runs tester checkers once in brief mode.
SYSTEM CHECK -DAILY -LOOP
-WEEKLY -LOOP
-MONTHLY -LOOP
These modes load the system checkers and run a user-definable
subset of checkers or run selected checkers in full or brief mode.
IMAGE Solutions V8.3 19-7
IMAGE Base Language: Checkers: Loading Checkers
Table of Contents Index Home Master Index Search Help
Selected checkers can be disabled from running in any of these
modes. Any configuration that you can set up using SYSTEM
CHECK -CUSTOM can be run daily, weekly, or monthly.
Set up this feature using either SYSTEM CHECK -CUSTOM or the
ckr_setup_menu program to configure the checkers. Enter your
configuration for any checkers and groups and save this setup.
When you save the setup to disk, you are prompted for a prefix.
Use the prefix listed below which corresponds to the switch you
are using:
Prefix Mode
DAILY -DAILY
WEEKLY -WEEKLY
MONTHLY -MONTHLY
SYSTEM CHECK -CUSTOM
Displays a menu in the station window that allows you to change
the number of times the checker is run or to change checker data
collection and termination mode. You can also store modes to a
file or restore saved modes from a file. See “Creating Custom
Checker Runs” on page 19-34.
SYSTEM CHECK -LOOP Loads and runs test system checkers in a continual loop.
SYSTEM CHECK -LOOP -BRIEF
Loads and runs test system checkers in a continual loop in brief
mode.
SYSTEM CHECK -CUSTOM -LOOP
Sets hardware in loop mode and displays a menu in the station
window. This menu allows you to change the number of times
the checker is run or to change checker data collection and
termination mode. You can also store modes to a file or restore
saved modes from a file. See “Creating Custom Checker Runs”
on page 19-34.
SYSTEM CHECK -TRAP_ON_FAIL
Loads and runs test system checkers in debug mode. When the
checkers are loaded, a settrap -failedtest command is
issued before running the checkers. Use this option to debug a
failing test.
SYSTEM CHECK -TRAP_ON_ALARM
Loads and runs test system checkers in debug mode. When the
checkers are loaded, a settrap -alarm command is issued
before running the checkers. Use this option to debug a failing
test.
In brief mode the hardware is functionally checked in typical conditions in which it will be
used by customers, with the emphasis on reduced execution time. In some cases brief
mode executes fewer tests, but that is not necessarily the rule.
IMAGE Solutions V8.3 19-8
IMAGE Base Language: Checkers: Loading Checkers
Table of Contents Index Home Master Index Search Help
In full mode the hardware is functionally tested in all known possible conditions. In this
mode, coverage is emphasized over execution time.
Using the sys_check Command
You can also load the IMAGE system checker using the sys_check command line in an
auxiliary station window. It has the following syntax:
/image/checkers/sys_check [[-h0 -h1 -h2 -h3 -h4] [-loop] [-brief] [-daily]
[-weekly] [-monthly] [-trap_on_fail]
[-trap_on_alarm]] | [[-custom] | [-saved <file>]]
where:
-h0 Checks mainframe hardware.
-h1 Checks test head 1 hardware.
-h2 Checks test head 2 hardware.
-h3 Checks test head 3 hardware.
-h4 Checks test head 4 hardware.
-loop Loads and runs test system checkers in a continual loop.
-brief Loads and runs tester checkers once in brief mode.
-daily/-weekly/-monthly
These modes load the system checkers and run a user-definable
subset of checkers or run selected checkers in full or brief mode.
Selected checkers can be disabled from running in any of these
modes. Any configuration that you can set up using sys_check
-custom can be run daily, weekly, or monthly.
-trap_on_fail Loads and runs test system checkers in debug mode. When the
checkers are loaded, a settrap -failedtest command is
issued before running the checkers. Use this option to debug a
failing test.
-trap_on_alarm Loads and runs test system checkers in debug mode. When the
checkers are loaded, a settrap -alarm command is issued
before running the checkers. Use this option to debug a failing
test.
-custom Displays a menu in the station window that allows you to change
the number of times the checker is run or to change checker data
collection and termination mode. You can also store modes to a
file or restore saved modes from a file. See “Creating Custom
Checker Runs” on page 19-34.
-saved <file> Starts the auto checkers using a custom setup obtained from
<file>.
IMAGE Solutions V8.3 19-9
IMAGE Base Language: Checkers: Loading Checkers
Table of Contents Index Home Master Index Search Help
If you do not specify any parameters, the checkers test all the hardware present once.
Hardware switches can be combined, as in:
/image/checkers/sys_check -custom -loop
If the test system checkers are run using the -loop switch, you must stop them using
Control-C or the ABORT button.
Loading Checker Groups
The CHECKER GROUPS selection in the CHECKERS button menu allows you to load checker
programs in groups. The checker groups run on the tester without user intervention. Only
self-test programs (checkers ending in st) are loaded in checker groups.
This selection has a pull-right menu that includes the following groups: COMMON FRAME,
ADVANCED MIXSIG HEAD, ADVANCED MIXSIG FRAME, CATALYST HEAD, TIGER DIGITAL, and
TIGER ANALOG. For a listing of checkers loaded in each group, see IMAGE Quick Help.
Additional checkers appear in the individual checker menus.
This selection allows you to use the debugger. You can also select -debug to enter the
debugger automatically.
Using the load Command
You can load checker groups from the command line using the following load commands:
load [-debug] /image/checkers/Common_frame_ck
load [-debug] /image/checkers/Advmixsig_head_ck
load [-debug] /image/checkers/Advmixsig_frame_ck
load [-debug] /image/checkers/Catalyst_head_ck
load [-debug] /image/checkers/Tiger_analog_ck
load [-debug] /image/checkers/Tiger_digital_ck
NOTE
When loading a test program into an auxiliary station, use the following switches to specify
the test head type associated with that station:
load <program> -head adv_mixsig
-head catalyst
-head tiger
If you try to load a program into a station with a mismatched test head, the program is not
loaded and an error message appears.
Fast-Load Groups
Fast-load checkers are prelinked, binary checker groups that perform identically to checkers
loaded without this option. When you fast-load checkers, you cannot use the IMAGE
debugger. You cannot fast-load maintenance and installation programs.
IMAGE Solutions V8.3 19-10
IMAGE Base Language: Checkers: Loading Checkers
Table of Contents Index Home Master Index Search Help
When each version of checkers is released, you must run the system checker once to create
fast-load groups. The procedure is as follows:
1. At the root prompt, log in as checkers and start IMAGE.
# login checkers
password: xxxxxxx
% image
2. Select NEW STATION from the IMAGE Workspace menu or click on the STATIONS button
in the IMAGE Control window to open an auxiliary station window.
3. Using the CHECKERS button on the station window select SYSTEM CHECK to run the
system checker. You can also run the system checker using the command:
/image/checkers/sys_check
This procedure takes about 15 minutes. When done, a fast version of checkers is created,
allowing checkers to load in seconds instead of minutes.
Before starting to test or build the fast-load file, IMAGE looks for a file called
disable_fastload in the CKR_BIN directory. If this file is present, no testing is done, and
the group is loaded in the standard mode. If you place this file in the CKR_BIN directory, you
can use the same CKR_BIN for multiple systems with different configurations.
Loading Individual Checkers
The INDIVIDUAL selection in the CHECKERS button menu allows you to select and load
individual checker programs for any of the major test system groups. Depending on the test
station and tester you are using, the menu shows individual checkers for advanced mixed-
signal, Catalyst, or Catalyst Tiger. The menu also includes -debug selections for each
group to allow you to enable the debugger when loading individual checkers.
When you pull right on any group in the INDIVIDUAL menu, you can select to display the menu
of either self-test or maintenance and installation checkers.
The individual checker menus change for each release as new checker programs are
added. The complete list of individual checkers is in the Checkers section of IMAGE Quick
Help.
You can also load individual checkers from the command line using the load command.
Use the following command to load a checker program:
load [-d] /image/checkers/<checker_name>
-head <adv_mixsig|catalyst|tiger>
IMAGE Solutions V8.3 19-11
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
Running Checkers
Once a checker program is loaded, you can run it using the RUN button or the run command.
If the checker option permits, you can access the debugger using the DEBUG button or the
debug command. To datalog checker results, use the DATA SETUP button or any of the data
collection commands (see “Datalog Reports” on page 6-13).
The default for all self-test checkers is tmode -cont_on_error. To reset the program
termination mode, use the tmode command (see “Setting Program Termination Modes” on
page 5-24).
All errors are logged to a trace file. The trace file is named:
<system-checker-date>.data
This file is stored in the directory from which the checker was started.
NOTE
If you use the xlock command to lock the screen, you must use an argument, such as
-allowaccess. The xlock command by itself locks the screen but it also shuts down the X
server, causing the checkers to hang up the first time sys_check deletes a checker group.
Another way to lock the screen is to use the LOCK SCREEN selection in the IMAGE
Workspace Utilities menu. This selection does not shut down the X server.
Displaying the Main Menu
To run checkers, click LEFT on the station window’s RUN button or enter the run command.
IMAGE responds with its main checker menu:
MAIN MENU
---------
1 - Display Configuration
2 - Display Execution Data
3 - Change Execution Data
4 - Change Output Setup
5 - Initialize Checkers
6 - Run Checker Sequence
7 - Loop Checker Sequence
8 - Checker Execution Summary
9 - FAIL Message Storage
10 - Exit this menu level
Selection >>
where:
Display Configuration
Displays the current hardware configuration. This option is no
longer supported.
IMAGE Solutions V8.3 19-12
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
Display Execution Data
Change Execution Data
Displays or changes the current execution modes of all checkers
in the group. By default, all checkers are run once in brief mode.
See “Displaying and Changing the Execution Setup” on page
19-14.
Change Output Setup
Allows you to change the output setup for any or all checkers in
the group. By default, all checker messages are sent to the
station window. See “Changing the Output Setup” on page
19-15.
Initialize Checkers
Allows you to initialize any or all checkers in the group. See
“Initializing Checkers” on page 19-17.
Run Checker Sequence
Loop Checker Sequence
Runs or loops the checkers. See “Running and Looping
Checkers” on page 19-18.
Checker Execution Summary
Produces a summary of checker values. See “Producing a
Checker Summary” on page 19-18.
FAIL Message Storage
Allows you to store failure messages. See “Storing Failure
Messages” on page 19-19.
Exit this menu level
Exits the Checker menu.
In addition to the menu choices, you can enter several text commands at the Selection>
prompt at any menu level. The commands are as follows:
run Run the checker sequence.
loop Loop the checker sequence.
exit or x Exit this menu level (return to the next higher menu level). If you
are at the main menu, this quits the checker menu.
summary Produce a snapshot summary report of the checker results.
quit Quit the checker menu and return to the station window prompt.
0 Redraw the current menu. This is useful if the menu has scrolled
off the screen.
IMAGE Solutions V8.3 19-13
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
Displaying and Changing the Execution Setup
The Display Execution Data menu selection displays a table of the current execution
setup, then returns to the main menu. This includes the checkers to be executed, the load
board, the count (number of times to execute each checker), and the mode (brief or full).
The following is the execution setup for the Tiger Analog group.
Checker Number Load Bd. Count Mode
-------------------- ------ -------- ----- ------
PACSII_AMS_ST 00001 0 1 Brief
HEADST 00002 0 1 Brief
VHFCWST 00003 0 1 Brief
VHFST 00004 0 1 Brief
VHF_AMS_ST 00005 0 1 Brief
GIGADIGST 00006 0 1 Brief
UHFCWST 00007 0 1 Brief
LFACST 00008 0 1 Brief
LFAC_AMS_ST 00009 0 1 Brief
RDC24ST 00010 0 1 Brief
VREGST 00011 0 1 Brief
OVIDCCST 00012 0 1 Full
LCAST 00013 0 1 Brief
TRGST 00014 0 1 Brief
TJAST 00015 0 1 Brief
QVSDCCST 00016 0 1 Full
QVSST 00017 0 1 Brief
UBASYST 00018 0 1 Brief
UWST 00019 0 1 Brief
MODSRCST 00020 0 1 Brief
BBACST 00021 0 1 Brief
---------------------------------------------------------
The Change Execution Data selection first displays a table of the current execution setup
and then displays a menu. The following shows an example setup (with the dcst checker
loaded) and the menu:
Checker Number Load Bd. Count Mode
-------------------- ------ -------- ----- ------
DCST 00002 0 1 Brief
---------------------------------------------------------
EXECUTION SETUP MENU
--------------------
1 - Specify Execution count
2 - Specify Execution mode
3 - Clear All Execution counts
4 - Set All Execution counts to 1
5 - Set All Execution modes to 'Brief'
6 - Set All Execution modes to 'Full'
7 - Save Execution & Output Setup
8 - Restore Execution & Output Setup
9 - Exit this menu level
IMAGE Solutions V8.3 19-14
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
where:
Specify Execution count
Specifies the number of times each individual checker is to be
executed. (The default is once.) This selection prompts you to
enter a checker name. To turn off (not execute) an individual
checker, specify an execution count of 0 for it.
Specify Execution mode
Specifies the execution mode (full or brief) for each checker.
(The default is once.) This selection prompts you to enter a
checker name.
Clear All Execution counts
Set execution counts for all checkers in the group to 0.
Set All Execution counts to 1
Set execution counts for all checkers in the group to 1.
Set All Execution modes to 'Brief'
Set execution mode for all checkers in the group to brief.
Set All Execution modes to 'Full'
Set execution mode for all checkers in the group to full.
Save Execution & Output Setup
Save (on disk) the current setup for the configuration, execution
counts and mode, and I/O selections. The setup is always saved
to the file ck_setup.<suffix>. You are prompted for the
suffix extension.
Restore Execution & Output Setup
Restore the current setup for the configuration, execution counts
and mode, and I/O selections. The setup is always reloaded from
the file ck_setup.<suffix>. You are prompted for the suffix
extension.
Exit this menu level
Returns you to the main checker menu.
Changing the Output Setup
The Change Output Setup menu allows you to select the destination and verbosity of
messages from the checkers. When you select this option, you see the current message
output and a menu to change it as follows:
Current Output setup: ALL messages to Station Window Only.
-----------------------------------------------------------
OUTPUT SETUP MENU
-------------------
1 - Send Output to Station Window Only
IMAGE Solutions V8.3 19-15
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
2 - Send Output to Trace File Only
3 - Send Output to Station Window and Trace File
4 - Display ALL Messages
5 - Only Display FAIL Messages
6 - Don't Display ANY Messages
7 - Save Execution & Output Setup
8 - Restore Execution & Output Setup
9 - Exit this menu level
where:
Send Output to Station Window Only
Send Output to Trace File Only
Send Output to Station Window and Trace File
These selections allow you to send checker messages to the
station window, a trace file, or both. (The default is the station
window.) The name of the trace file on disk is determined from
the time and date when the checker supervisor was loaded. For
example
ck_log_<datestamp>
where <datestamp> = mmddyy:hh:mm . For example,
072586:09:45
Display ALL Messages
Only Display FAIL Messages
Don't Display ANY Messages
As the checkers are run, IMAGE announces each checker with
the message
Running Checker <checkername>
and its version number. Following each checker, a final status
message (that is, checker Passed/Failed) is issued. These
selections allow you to display all messages, only fail messages,
or no messages. (The default is all messages.)
Save Execution & Output Setup
Restore Execution & Output Setup
These selections allow you to save (on disk) and restore the
current setup for the configuration, execution counts and mode,
and I/O selections. The setup is saved in the directory from
which the checkers were started. It is always saved to and
reloaded from the file ck_setup.<suffix>. You are prompted
for the suffix extension on both save and restore.
Exit this menu level
Returns you to the main checker menu.
IMAGE Solutions V8.3 19-16
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
Initializing Checkers
Selecting Initialize Checkers generates the following menu that allows you set,
change, or restore initialization:
INITIALIZATION MENU
---------------------
1 - Step through initialization questions
2 - Initialize checker to default values
3 - Save checker initialization values
4 - Restore saved initialization values
5 - Exit this menu level
where:
Step through initialization questions
Allows you to select a checker and to examine and change all
possible setting for the checker.
Initialize checker to default values
Changes all checker values to default.
Save checker initialization values
Restore saved initialization values
These selections allow you to save (on disk) and restore the
current checker setup. The setup is saved in the directory from
which the checkers were started. It is always saved to and
reloaded from the file ck_setup.<suffix>. You are prompted
for the suffix extension on both save and restore.
Exit this menu level
Returns you to the main checker menu.
When you choose to initialize, a menu of all checkers in the current group appears and
allows you to select a checker. For example, if you have the dcst checker loaded you would
see the following menu:
SELECT CHECKER TO INITIALIZE
----------------------------
1 - DCST
2 - Exit this menu level
The checker’s routine then prompts you for answers to its questions. You answer all
questions by pressing Return to select the default value. For example, the following is an
example sequence for the dcst checker:
DCST MENU
---------
1 - Check DC Source
2 - Check DC Measurement System
3 - Check DC Source & Measurement System
4 - Exit this menu level
Selection >> 1
IMAGE Solutions V8.3 19-17
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
DC SOURCE MENU
--------------
1 - Check V Forcing Accuracy
2 - Check I Forcing Accuracy
3 - Check V & I Forcing Accuracy
4 - Exit this menu level
Selection >> 1
Enter Source number to check.
To check DUTSRC's 1-4, enter 6-9 respectively (1-9, 0 = all)-->0
DCST initialization complete
When the initialization routine returns, the menu of checkers is redisplayed, allowing you to
initialize other checkers.
Running and Looping Checkers
Two commands in the main checker menu execute the checkers: Run Checker Sequence
(option 6) and Loop Checker Sequence (option 7). Run Checker Sequence executes a
single pass through the checker sequence. (You can execute individual checkers more than
once using the Specify Execution Count selection in the Execution Setup Menu. See
“Displaying and Changing the Execution Setup” on page 19-14.)
The Loop command prompts you for the number of times to loop. You can also specify
continuous looping. To prematurely terminate looping, type Control-C. However, Control-C
also causes exit back to the Unix system command level.
Producing a Checker Summary
Each checker returns a single pass or fail value. These values, along with execution counts,
are maintained by IMAGE. The Checker Execution Summary selection (option 8 in the
main checker menu) allows you to request this information and clear it. Checker summary
reports are always sent to the station window and to a disk file (ck_summary_<datestamp>
where <datestamp> is mmddyy:hh:mm). The following is an example checker summary for
the Tiger Analog group:
Selection >> 1
CHECKER SUMMARY VERSION: V8.0 012003
Tue Jan 21 16:13:50 2003
IMAGE VERSION: IMAGE V8.0 012103 SunOS 5.6
Tester: margin Operator: buckley
Station: 1 Test Head: 1
-------------------------------------------------------------------------------
Checker Channels Executions Passes Fails % %
Name Brief Full Total Pass Fail
-------------------------------------------------------------------------------
PACSII_AMS_ST N/A 0 0 0 0 0 0.00 0.00
HEADST N/A 0 0 0 0 0 0.00 0.00
IMAGE Solutions V8.3 19-18
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
VHFCWST N/A 0 0 0 0 0 0.00 0.00
VHFST N/A 0 0 0 0 0 0.00 0.00
VHF_AMS_ST N/A 0 0 0 0 0 0.00 0.00
GIGADIGST N/A 0 0 0 0 0 0.00 0.00
UHFCWST N/A 0 0 0 0 0 0.00 0.00
LFACST N/A 0 0 0 0 0 0.00 0.00
LFAC_AMS_ST N/A 0 0 0 0 0 0.00 0.00
RDC24ST N/A 0 0 0 0 0 0.00 0.00
VREGST N/A 0 0 0 0 0 0.00 0.00
OVIDCCST N/A 0 0 0 0 0 0.00 0.00
LCAST N/A 0 0 0 0 0 0.00 0.00
TRGST N/A 0 0 0 0 0 0.00 0.00
TJAST N/A 0 0 0 0 0 0.00 0.00
QVSDCCST N/A 0 0 0 0 0 0.00 0.00
QVSST N/A 0 0 0 0 0 0.00 0.00
UBASYST N/A 0 0 0 0 0 0.00 0.00
UWST N/A 0 0 0 0 0 0.00 0.00
MODSRCST N/A 0 0 0 0 0 0.00 0.00
BBACST N/A 0 0 0 0 0 0.00 0.00
-------------------------------------------------------------------------------
CHECKER SUMMARY MENU SELECTIONS
-------------------------------
1 - Display Checker Summary (Snapshot)
2 - Final Checker Summary (to disk)
3 - Reset All Checker Summary Counts
4 - Reset a Single Checker Summary
5 - Exit this menu level
The menu selections are as follows:
Display Checker Summary (Snapshot)
Displays a current summary in the station window.
Final Checker Summary (to disk)
Sends a final summary to a disk file.
Reset All Checker Summary Counts
Reset a Single Checker Summary
Resets summary counters for all checkers or for one checker.
Exit this menu level
Returns you to the main checker menu.
Storing Failure Messages
You can store checker failure messages using the FAIL Message Storage selection. This
menu item gives you the following menu:
FAIL MESSAGE STORAGE MENU SELECTIONS
------------------------------------
1 - Display Stored FAIL Messages
2 - Clear stored FAIL Messages
IMAGE Solutions V8.3 19-19
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
3 - Set stored FAIL Message limit
4 - Exit this menu level
where:
Display Stored FAIL Messages
Displays any fail messages you have stored.
Clear stored FAIL Messages
Clears all stored fail messages.
Set stored FAIL Message limit
Sets a limit on stored fail messages.
Exit this menu level
Returns you to the main checker menu.
Autocalibration for Checker Runs
Autocalibration is used with checkers. Autocalibration automatically calibrates the DC
Subsystem, the Time Measurement, and other test system hardware. See “Calibration
Theory of Operation” on page 21-3 for details.
Self-test checkers enable autocalibration by default. You can disable autocalibration when
you load the test program or after you load the test program using any of the following
methods:
• Enter the -noautocal switch on the load command line. For example, to load the test
program dcst, you would type: load dcst -noautocal
• Include the -noautocal switch in the .load file for the test program.
• Enter the calibrate -noautocal command at the station window prompt.
• Set switch variable 1 to be nonzero by typing the following command at the station
window prompt:
switchvar 1=1
• Set switch variable 1 to be nonzero in the test program by including the following
statement in the .load file:
-switchvar 1 1
You can enable autocalibration by:
• Entering the calibrate -autocal command at the station window prompt
• Resetting switch variable 1 to be zero by deleting the test program or by typing the
following command at the station window prompt:
switchvar 1=0
If autocalibration is enabled, the test system checks the time since last calibration, and
calibrates at the beginning of the program if any of the following are true:
• The instrument has not been calibrated since IMAGE started
• The instrument has not been calibrated since the last time test system power was cycled
or if the initialize command was used
IMAGE Solutions V8.3 19-20
IMAGE Base Language: Checkers: Running Checkers
Table of Contents Index Home Master Index Search Help
• More than four hours has elapsed since the last calibration
Autocalibration always calibrates the DC Subsystem at the start of the test program and
after every four hours and whenever the test system is powered up.
TMS calibration and TMS deskew occur at the beginning of the test program and after every
four hours only if TMS statements occur in the test program.
Autocalibration deskews the advanced mixed-signal High Speed Digital Subsystem.
IMAGE repeats the calibration whenever the temperature changes more than three degrees
Centigrade or whenever test-head power supply levels change more than the specified limit.
Autocalibration calibrates only the test head in use during TMS and HSD calibration. For
example, a test program loaded into station 2 with the -autocal switch calibrates the TMS
for test head 2 only and deskews the TMS and HSD for test head 2 only.
Calibration results are sent to a trace file in the same directory as the test program. The
calibration output is directed to the checker output stream when checkers are run with the
-autocal switch. See “Changing the Output Setup” on page 19-15 for more information on
directing the output of checker programs (and thereby the autocal messages that occur
while checkers are run with -autocal turned on).
If calibration fails during a checker run, the test system checkers ignore calibration errors.
The test system checkers program the instrument with nominal values and run to the end
of the checker by default.
IMAGE Solutions V8.3 19-21
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Running Checkers Automatically
The Automatic Checker Run utility allows you to schedule test system checker runs on a
weekly basis for any day or days of the week at one specified time. You can schedule or
start test system checker runs:
• On the test system itself
• From another test system
• From a remote workstation
• From a remote VT100 style terminal over a modem
• From a shell tool over Ethernet
Installing the Auto Checker Utility
To use Auto Checker Run, you must have both IMAGE and checkers installed on the tester
and you must install the Auto Checker utility. Installation involves running an installation
script, setting a path, and modifying an IMAGE file. This procedure requires root privilege.
You must run the installation script, install_auto.csh, on the NIS (Network Information
Service) master. NIS is Sun’s network database service, and it is enabled by default when
IMAGE is installed. The NIS master is the computer that contains network database
information such as passwords, hosts, and networks. To determine the name of the NIS
master for your tester type the command:
ypwhich -m passwd
The name of the NIS master is printed on the screen after you press Return.
Run the installation script, install_auto.csh on the NIS master as follows:
1. Log in to the NIS master as root.
2. cd to /image/checkers/auto.
3. Run the installation script file by typing:
install_auto.csh<cr>
4. Exit the root account.
5. In the account that will run the checkers add the following to the .login file:
set path = ( $path /image/checkers/auto )
6. The System Administrator must specify which test systems, remote workstations, or
remote terminals can configure, schedule, and start checker runs on the tester. This is
done by listing the name of the test system, remote workstation, or remote terminal in
the file
/image/tester/<hostname>/.rauto
The system administrator must enter the name of the test system, remote workstation, or
remote terminal exactly as the name appears in the /etc/hosts file. For example, the
/etc/hosts file for a test system might contain the following entries:
IMAGE Solutions V8.3 19-22
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
135.123.254.1 neutron
135.123.254.2 proton_s
135.123.254.3 proton_t
135.123.254.4 alpha
135.123.254.5 beta
135.123.254.6 gamma
The .rauto file for this test system might look like the following:
proton_s
alpha
In this example, proton_s and alpha could configure, schedule, and start checker runs on
the test system.
The system administrator can enter the + character in the .rauto file to allow any tester,
workstation, or terminal to configure, schedule, or start the auto run. In the above example,
the /image/tester/<hostname>/.rauto file would contain only the + character; no other
entries would be required.
Running Auto Checkers Under Solaris 2
To run auto checkers on a Solaris 2.x tester, you must edit the file /etc/logindevperm to
make the console, mouse and keyboard mode 666. Change the following lines in the
/etc/logindevperm file:
/dev/console 0600 /dev/mouse:/dev/kbd
/dev/console 0600 /dev/sound/* # audio devices
/dev/console 0600 /dev/fbs/* # frame buffers
They should look as follows after modification:
/dev/console 0666 /dev/mouse:/dev/kbd
/dev/console 0666 /dev/sound/* # audio devices
/dev/console 0666 /dev/fbs/* # frame buffers
NOTE
Auto checkers will not run if the Common Desktop Environment (CDE) has been installed
and the graphical login screen is enabled. The graphical login screen starts before anyone
logs in to the test system. This prevents auto checkers from running. See “Installing IMAGE
on a Test System Using CD ROM” on page 3-3 of the IMAGE V7.x/8.x Software Installation
Guide for Testers.
Invoking the Checker Setup Display
The Checker Setup Display (figure 19-2) allows you to select the checkers to be run, the
number of times each checker is to be run, the datalog mode, and the start time and day.
IMAGE Solutions V8.3 19-23
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Figure 19-2. Checker Setup Display
To begin to use the auto run utility, type:
/image/checkers/auto/checkerdisp
in any window of the tester except station 5 or any window of a remote tester or workstation.
This brings up the Checker Setup display. You cannot open or use station 5 on the tester
since the test system checkers run in station 5.
Specifying the Tester for Auto Run
The SET HOST button on the Checker Setup display specifies the tester for the auto run. You
must select a tester or click SELECT on the SET HOST button to select the local host. To
select a tester:
1. Type in the name of the tester to the right of the HOSTNAME: prompt and press Return.
2. Enter the tester name exactly as the name appears in the local host’s /etc/hosts file.
Your workstation or tester name must be in the remote tester file
/image/tester/<hostname>/.rauto as described in “Installing the Auto Checker
Utility” on page 19-22.
If you do not enter a host name and you click on the SET HOST button, the local host is
selected. After the host is selected, the STATUS button changes to ENABLE AUTO RUN. The
Checker Setup display reads the remote (or local) hosts’s defaults file,
/image/checkers/Defaults.dat.<hostname> and fills the display with the information. If
the defaults file is missing, one is created and filled with default values. Figure 19-3 shows
the Checker Setup display with the default values.
Figure 19-3. Set Host Button
IMAGE Solutions V8.3 19-24
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Checker Versions
The CHECKER VERSION item of the Checker Setup display shows the major release number
of the checkers installed on the test system and the release revision (as a date).
Start Time
The START TIME item on the Checker Setup display is the time that the auto run starts. Enter
a start time value and press Return to validate the entry. The start time must be in 24 hour
format. No AM or PM notation is permitted. The Checker Setup display attempts to interpret
any abbreviations entered in the Start Time field. For example, if you enter 12, the Checker
Setup display shows 12:00 after you press Return.
Only one time entry is permitted. If the auto run is scheduled to run more than one night, it
does so at the same time each night. If you enter an invalid START TIME entry, an error
message appears at the bottom of the display. The default start time is 23:00 hours (11:00
PM).
Datalog Mode
The DATALOG MODE item on the Checker Setup display selects the test results to be
recorded. Select FAILED TESTS or ALL TESTS by clicking SELECT on the corresponding
boxes. Results are stored in export /home/<hostname>/auto. Take care when selecting
ALL TESTS since overnight runs can generate enough data to fill the hard disk partition. The
default is FAILED TESTS.
Auto Run Day(s)
The AUTO RUN DAY(S) item on the Checker Setup display selects the days of the week the
checkers run. Select from 1 to 7 days by clicking SELECT on the box corresponding to the
day of the week (figure 19-4). The auto run starts at the same time on each day. The default
is the current day of the week.
Figure 19-4. Auto Run Day Selection
IMAGE Solutions V8.3 19-25
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Set Modes
The SET MODES item on the Checker Setup display brings up a pop-up window with all the
individual checker attributes. Display this Checker Attributes window by clicking SELECT
on the SET MODES button. The pop-up window (figure 19-5) displays all the checkers in the
present group of checkers selected, the execution mode, and the loop count for each
checker. As the default, all checkers run one pass in full mode and only failed tests are
datalogged to a trace file in /home/<hostname>/auto and to the console window.
Figure 19-5. Set Modes Selection
Checker Groups
You can view and select checker groups by pressing MENU on the GROUPS button and
selecting from this menu (figure 19-6). The checkers in each group are the same as the
ones shown when you press MENU on the CHECKERS button in a test station control panel.
See “Loading Individual Checkers” on page 19-11 for a list of the checkers in each group.
IMAGE Solutions V8.3 19-26
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Figure 19-6. Checker Groups
Execution Mode
You can change the execution mode from FULL to BRIEF by clicking SELECT on the
abbreviated menu button next to EXECUTION MODE for each checker (figure 19-7).
The buttons at the top of the Checker Groups display, ALL MODES FULL and ALL MODES
BRIEF, allow you to set the execution mode of all checkers in the Checker Group displayed
to FULL MODE or BRIEF MODE by clicking one button. You can see the choices for execution
mode by pressing MENU on the abbreviated menu button next to each EXECUTION MODE.
A menu appears with the choices BRIEF and FULL.
Loop Count
The LOOP COUNT is the number of times the checker will be executed. You can change the
LOOP COUNT for each checker by pressing MENU on the abbreviated menu button next to
LOOP COUNT for each checker (figure 19-7). The menu shows the loop count choices. Select
1, 2, 4, 8, 16, or 100.
IMAGE Solutions V8.3 19-27
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Figure 19-7. Execution Mode and Loop Count
Output Mode
You can select the checker results to be saved by pressing MENU on the box next to
OUTPUT MODE. The choices are FAILED TESTS, ALL TESTS, and NO TESTS (figure 19-8).
You can send the checker results to a trace file or to the screen by clicking SELECT on the
boxes for TRACE FILE or CONSOLE. A trace file is a file in /home/<hostname>/auto
containing all auto run test results and messages. If you select CONSOLE, the test results
and messages are sent to the station 5 tester window. The default settings are FAILED TESTS
to a TRACE FILE and CONSOLE (figure 19-8).
IMAGE Solutions V8.3 19-28
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Figure 19-8. Output Mode Selection
Saving Checker Attributes
You must save your changes to checker attributes before exiting the Checker Attributes
display by clicking SELECT on the SAVE button and then clicking SELECT on the DONE
button. To exit without saving the changes, click on the DONE button and confirm that you
do not want to save the changes. The Checker Attributes display window is replaced by the
Checker Setup Display (figure 19-9).
Saving Auto Run Defaults
The SAVE button on the Checker Setup Display saves changes made to the auto-run
defaults. If you made changes to the HOSTNAME, START TIME, DATALOG MODE, or AUTO RUN
DAYS, you must save them by clicking on the SAVE button (figure 19-9).
Figure 19-9. Checker Setup Display
IMAGE Solutions V8.3 19-29
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Reboot_Always
The IMAGE Properties window includes an option, REBOOT ALWAYS, that allows you to
reboot the remote tester before the start of the auto run. Rebooting is useful if the remote
tester is not running IMAGE (for example, OpenWindows) or if station 5 is in use on the
tester. (For more information on IMAGE Properties, see “Setting IMAGE Properties” on
page 3-34.)
To enable this option:
1. Log in to the test system as root.
2. su to auto.
3. Bring up IMAGE.
4. Select PROPERTIES>IMAGE PROPERTIES from the IMAGE Workspace menu.
5. Select the AUTO CHECKER RUN OPTIONS menu.
6. Press MENU on the abbreviated menu button for REBOOT ALWAYS and select TRUE.
7. Save this change by clicking SELECT on the APPLY button (figure 19-10).
8. Quit the IMAGE Properties window.
Figure 19-10. Reboot Always Selection
NOTE
Changes made to the IMAGE Properties window are recognized by auto run only if the
changes are saved and the ENABLE/DISABLE AUTO RUN button is toggled. To toggle this
button, click on the DISABLE AUTO START button in the Checker Setup Display (the button
changes to ENABLE AUTO START) and then click on the ENABLE AUTO START button (the
button changes back to DISABLE AUTO START).
IMAGE Solutions V8.3 19-30
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
Enable Auto Start
The ENABLE AUTO START button on the Checker Setup Display starts the auto run. You must
have already saved changes made to the checker attributes in the Set Modes display as
well as changes made to the auto-run defaults as described in “Saving Checker Attributes”
on page 19-29 and “Saving Auto Run Defaults” on page 19-29. If you do not save changes,
auto run uses the old or default values. When you click on the ENABLE AUTO START button,
the button changes to DISABLE AUTO START and the countdown begins (figure 19-11).
Figure 19-11. Start of Auto Run
A message appears on the tester console window that auto run is enabled. If the start time
is within 12 hours, countdown messages appear in the tester console window announcing
the auto run. Countdown messages appear in the windows of any terminals logged into the
tester.
Four hours before start time, the warning messages become more frequent, and the ABORT
AUTO icon appears on the tester screen if the tester is running IMAGE. To stop the auto run,
click on the ABORT AUTO icon at any time before the auto run starts.
Once the auto run starts, the tester reboots itself if you set REBOOT_ALWAYS to TRUE in the
Auto checker runs menu, and then the tester starts the checker run in station 5. After the
checker run starts, you can stop it by clicking on the ABORT button or by typing CONTROL-C
in station 5. When the checker run is stopped, user “auto” remains logged in until IMAGE is
manually exited and user “auto” is manually logged out.
If REBOOT_ALWAYS was not enabled, the tester must be running IMAGE and station 5 must
not be in use. When running in the no-reboot mode, auto run starts in station 5 at the
specified time if no devices are being tested, or as soon as the device being tested is
binned.
IMAGE Solutions V8.3 19-31
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
For the ABORT icon to appear on the user computer in the four hours before the start of an
auto-checker run, any user on the console must allow outside connections to the X server.
Do this using the command:
xhost +
in the user’s .login file.
Terminal Interface
The Terminal Interface allows you to schedule and start auto run from a remote VT100 style
terminal over a modem or from a Shelltool through the Ethernet. The workstation must be
in the tester’s /image/tester/<hostname>/.rauto file as described in “Installing the Auto
Checker Utility” on page 19-22. The same warnings and ability to stop the auto run occur on
the remote tester. The Terminal Interface cannot change the checker attributes or the
REBOOT_ALWAYS selection in the IMAGE Properties window. To change the checker
attributes and the REBOOT_ALWAYS selection, you must be logged in to the tester itself as
described in “Installing the Auto Checker Utility” on page 19-22.
To schedule or start the auto run from a VT100 type terminal or shell tool:
1. Log onto the VT100 style terminal or shell tool.
2. Type either of the following:
checkerdisp -nographics<cr>
ckrsetup<cr>
The VT100 or Shelltool prompts you for the name of the test system on which you want
to schedule auto run.
3. Press RETURN to enter the name of the test system that you remotely logged in to, or
type in the name of the test system for the auto run and press RETURN.
4. The Checker Setup for the selected test system appears on the VT100 screen or shell
tool. If no changes have been made, the default settings are:
– Auto Run enabled for current day of the week
– Datalog mode is FAILED TESTS
– Scheduled start time is 23:00 (24 hour format)
– Auto Run Feature is DISABLED
5. The Configuration Menu appears on the VT100 screen shell tool with the following
selections:
1 Edit Start Time
2 Edit Day of Week
3 Edit Datalog Mode
4 Toggle enable/disable Auto Run
5 Save Changes
6 Exit this menu level
6. To change the start time, type 1 and enter the start time in 24 hour format.
7. To change the day or days of the week for auto run, type 2 and type y or n after the days
of the week.
IMAGE Solutions V8.3 19-32
IMAGE Base Language: Checkers: Running Checkers Automatically
Table of Contents Index Home Master Index Search Help
8. To change the datalog mode, type 3 followed by A for All Tests or F for Failed Tests.
9. To save changes, type 5. You must save any changes before you can enable or disable
the auto run in the next step.
10. To start the auto run, type 4. The Checker Setup indicates AUTO RUN FEATURE IS
ENABLED.
11. To exit the menu, type 6.
The auto run countdown now begins with the same warning messages to users logged on
to the tester. You can stop the auto run from the VT100 style terminal or Shelltool only if
auto run has not started. To stop auto run, type 4. Checker Setup indicates AUTO RUN
FEATURE IS DISABLED. Once the auto run begins, you can stop auto run only by aborting
the auto run on the tester itself.
IMAGE Solutions V8.3 19-33
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
Creating Custom Checker Runs
IMAGE allows you to customize parameters of the system check checker run. This feature
allows you to modify which checkers in a group to run and, from that list, what modes to run
the checkers in. It also allows you to save the output mode of a checker group.
Files used for custom setups are stored in either of the following files:
$HOME/.checker_setups
/image/tester/<testername>/.checker_setups
For example, if you set up a custom checker run, select the dcst checker to run in brief
mode, and save this setup to the file dccheck, this creates one file per checker group plus
an additional file that stores the data output mode. The files would be called:
dccheck.ck_exo_setup.<group_name>
where dccheck is the name you defined.
You can start sys_check using a -saved <file> argument to start the auto checkers using
the custom setup.
If you save the setups as site setups, they are listed in the Custom Checkers menu, which
is the first item in the CHECKERS button menu in any auxiliary station. This item includes a
button menu with all the site or global custom checker runs, allowing these custom setups
to be started using the button menu.
If you save the setups as personal setups, they are stored in a menu called
$HOME/.checker_setups/.custom_menu. This file is not included in the Custom Checkers
menu. You can, however, modify the .usermenu (under the USER button) to include private
custom runs. To add a personal custom run menu to your user menu, create a
$HOME/.usermenu which includes the following:
"Custom Checker Menu" MENU ${HOME}/.checker_setups/.custom_menu
Both the tester menu and the private menu are recreated based on the existing custom
checker files each time the custom checkers are run.
NOTE
If the checker group has changed, IMAGE gives a warning about a “stale” saved file. The
checker run is then aborted.
NOTE
If you statically configure a test system, you must recreate any saved custom checker files.
See “Creating a Static Configuration” on page 19-44.
You can also move stored custom setups forward when a new version of checkers is
installed on a tester (provided the checkers in the group have not changed). IMAGE
IMAGE Solutions V8.3 19-34
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
includes a search path for the custom files. When looking for a set of saved files, IMAGE
looks in the following directories in this order:
$HOME/.checker_setups
/image/tester/<nodename>/.checker_setups
This allows a two-tier approach which provides for a tester-specific set of customizations
and a user-specific set of customizations.
You can also use the ckr_setup_menu command. The syntax is as follows:
/image/checkers/ckr_setup_menu [-init] | [-file <restore file>]
where:
-init Initializes all exo tables to their default values without interactive
operation. The default values are:
io = fail messages to station window and trace file
checker execution mode is FULL
checker execution count is 1
-file File name of setup file to restore.
Invoking the Custom Setup Menu
Custom setup of system checkers is completely menu driven. To begin custom setup, either
select SYSTEM CHECK>SYSTEM CHECK -CUSTOM in the CHECKERS button menu or enter the
command:
sys_check -custom
The Checker Setup menu is displayed in the station window as follows:
Enter 'X' to exit; <CR> to refresh menu.
(0) To start checkers
(1) Mixed_frame_ck
(2) Linear_frame_ck
(3) Common_frame_ck
(4) Mixed_head_ck
(5) Linear_head_ck
(6) Advmixsig_frame_ck
(7) Advmixsig_head_ck
(8) Synchronous_power_ck
(9) Image_sensor_ck
(10) Tiger_digital_ck
(11) Tiger_analog_ck
(12) Catalyst_head_ck
(13) For global commands menu
Selection =>
IMAGE Solutions V8.3 19-35
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
Selection 0 allows you to start the current system checker. Selections 1 through 10 allow
you to customize each checker group. Selection 11 includes global commands that affect
all groups in the system checker.
Customizing Checkers by Groups
To customize System Check you must customize each checker by selecting a Checker
Group for that checker. Options 1 through 12 in the Checker Setup menu are the valid
checker groups. If you select a Checker Group, a menu similar to the following appears:
*** Tiger_analog_ck ***
-----------------------
(0) To return to main menu
(1) Change execution modes
(2) Change output modes
(3) Change resource list
(4) Display execution and output for Advmixsig_frame_ck
(5) Display resource list for Advmixsig_frame_ck
(6) Set display options
Please enter selection =>
Selection 0 returns you to the main menu. The remaining selections are described in the
following sections.
Changing Execution Modes
Selection 1 in the group menu displays the current settings for the group and a menu that
allows you to change execution counts and modes. The following is an example:
Tiger_analog_ck
Checker Mode Count ID
----------------------------------------------
pacsII_ams_st full 1 1
headst full 1 2
vhfcwst full 1 3
vhfst full 1 4
vhf_ams_st full 1 5
gigadigst full 1 6
uhfcwst full 1 7
lfacst full 1 8
lfac_ams_st full 1 9
rdc24st full 1 10
vregst full 1 11
ovidccst full 1 12
lcast full 1 13
trgst full 1 14
tjast full 1 15
qvsdccst full 1 16
qvsst full 1 17
ubasyst full 1 18
IMAGE Solutions V8.3 19-36
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
uwst full 1 19
modsrcst full 1 20
bbacst full 1 21
Trace file output: ENABLED.
Station window output: ENABLED.
Trace file will log FAIL MESSAGES.
(0) To exit menu
(1) Specify execution count and mode
(2) Set all counts to zero
(3) Set all counts to one
(4) Set all modes to brief
(5) Set all modes to full
Please enter selection =>
In this menu, option 0 returns to the previous menu structure. Option 1 allows you to specify
the mode of execution for a particular checker, as well as the number of times the checker
is to be executed. Options 2 through 5 set all checkers in the group to a fixed setting.
Changing Output Modes
Selection 2 in the group menu displays the current settings for the group and a menu that
allows you to change output modes. The following is an example:
Tiger_analog_ck
Checker Mode Count ID
----------------------------------------------
pacsII_ams_st full 1 1
headst full 1 2
vhfcwst full 1 3
vhfst full 1 4
vhf_ams_st full 1 5
gigadigst full 1 6
uhfcwst full 1 7
lfacst full 1 8
lfac_ams_st full 1 9
rdc24st full 1 10
vregst full 1 11
ovidccst full 1 12
lcast full 1 13
trgst full 1 14
tjast full 1 15
qvsdccst full 1 16
qvsst full 1 17
ubasyst full 1 18
uwst full 1 19
modsrcst full 1 20
bbacst full 1 21
Trace file output: ENABLED.
IMAGE Solutions V8.3 19-37
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
Station window output: ENABLED.
Trace file will log FAIL MESSAGES.
(0) To exit menu
(1) Send output to Station Window only
(2) Send Output to Trace File Only
(3) Send Output to Station Window and Trace File
(4) Display ALL Messages
(5) Only Display FAIL Messages
(6) Don't Display ANY Messages
Please enter selection =>
In this menu, option 0 returns to the previous menu. Options 1 through 3 allow you to control
the checker output by sending it to the station window (screen), a trace file (ck_log file), or
both. Options 4 through 6 allow you to control whether messages are displayed or not.
Changing the Resource List
Some checkers have been modified to allow you to select specific resources for the
checkers to test. These checkers also have an associated help file to help you in selecting
the resources.
Note that the specific custom configuration only applies to checkers in the context of a
custom run. This information is not available from the standard checker menus once a
checker or group is loaded.
The ability to select a specific resource list can greatly reduce the time necessary to run
checkers. It also allows you to set up checker runs such that you test only the resources
required for testing a specific device.
By default, all resources are tested.
You can use some metacharacters to make definition of a set of channels to run easier. The
menu format for selecting resources also aids in this.
The following menu selections are available for setting the desired resources:
* Select all resources (=all)
* Clear all resources (=none)
* Set resources to run (=)
* Unset resources to run (XOR)
* Add resources to run (OR)
The menus Select all and Clear all do not query for input.
Channel input can be one of:
• An integer number preceded by +/- to set or reset
• A special menu selection to set all resources
• A special menu selection to reset all resources
• A comma- or space-separated list of resource numbers "1,3,5" or "1 3 5"
• A range of resource numbers "1-5"
IMAGE Solutions V8.3 19-38
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
Precede the list input by + or - to mark the channels listed for set or reset. If neither is
specified, the resources listed are toggled from the present state.
Since a resource can mean different things to different checkers, checkers include a help
file to describe the resource nomenclature. You can view the help files using the resource
menus in the custom checker utility.
Selection 3 in the group menu displays the resource settings for the group and a menu that
allows you to set and view resources. The following is an example:
Tiger_analog_ck
Checker ID Type Resource Data (1 to 160)
-------------------------------------------------------------------------
pacsII_ams_st 1 1 all resources selected
headst 2 1 all resources selected
vhfcwst 3 1 all resources selected
vhfst 4 1 all resources selected
vhf_ams_st 5 1 all resources selected
gigadigst 6 1 all resources selected
uhfcwst 7 1 all resources selected
lfacst 8 1 all resources selected
lfac_ams_st 9 1 all resources selected
rdc24st 10 1 all resources selected
vregst 11 1 all resources selected
ovidccst 12 1 all resources selected
lcast 13 1 all resources selected
trgst 14 1 all resources selected
tjast 15 1 all resources selected
qvsdccst 16 1 all resources selected
qvsst 17 1 all resources selected
ubasyst 18 1 all resources selected
uwst 19 1 all resources selected
modsrcst 20 1 all resources selected
bbacst 21 1 all resources selected
(0) To exit menu
(1) Set all resources for a checker
(2) Clear all resources for a checker
(3) Set/Clear one resource for a checker
(4) Set/Clear a range for a checker
(5) View Resource help file for a checker
Please enter selection =>
In this menu, option 0 returns to the previous menu structure. Option 1 sets all resources
within the checker to be tested, and option 2 sets all resources within the checker to not be
tested. Options 3 and 4 allow you to control which resources are tested. Option 5 displays
a help file for a checker which shows how to enter data for choices 3 and 4.
IMAGE Solutions V8.3 19-39
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
NOTE
The resource help file is displayed using the file editor program set by the EDITOR
environment variable. Thus, to have the file displayed using the OpenWindows textedit
program, enter the following in the station window: setenv EDITOR textedit
Displaying and Changing Summaries
Selection 4 in the group menu displays a summary of the execution mode and count for
each checker in the checker group. This selection provides a summary such as the
following:
Tiger_analog_ck
Checker Mode Count ID
----------------------------------------------
pacsII_ams_st full 1 1
headst full 1 2
vhfcwst full 1 3
vhfst full 1 4
vhf_ams_st full 1 5
gigadigst full 1 6
uhfcwst full 1 7
lfacst full 1 8
lfac_ams_st full 1 9
rdc24st full 1 10
vregst full 1 11
ovidccst full 1 12
lcast full 1 13
trgst full 1 14
tjast full 1 15
qvsdccst full 1 16
qvsst full 1 17
ubasyst full 1 18
uwst full 1 19
modsrcst full 1 20
bbacst full 1 21
Trace file output: ENABLED.
Station window output: ENABLED.
Trace file will log FAIL MESSAGES.
Selection 5 in the group menu displays a summary of the resources to be tested within each
of the checkers contained in the checker group. This selection provides a summary such as
the following:
Advmixsig_frame_ck
Checker ID Type Resource Data (1 to 160)
-------------------------------------------------------------------------
scmclk_ams_st 1 1 all resources selected
dmf_ams_st 2 1 FFC00000 00000000 00000000 00000000 00000000
mfs_ams_st 3 1 all resources selected
IMAGE Solutions V8.3 19-40
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
pacs_ams_st 4 1 all resources selected
smem_ams_st 5 1 all resources selected
cmem_ams_st 6 1 all resources selected
apxfer_ams_st 7 1 all resources selected
vbms_ams_st 8 1 all resources selected
In this example, dmf_ams_st has been modified to select channels 1 through 10 for test with
this checker. The resource list displays this in hexadecimal (the default) where each of the
four bits in each hex digit corresponds to a copy of a resource. this means that
F000000 -> would test channels 1 through 4
1000000 -> would test channel 4 only
8000000 -> would test channel 1 only
Selection 6 in the group menu controls how resource customization summaries are
displayed. This selection provides a summary such as the following:
Display resource data in [H]ex or [D]ecimal >> d
Display mode will be DECIMAL
Enter first resource number to display [1 to 1024: 1] >> 1
First resource displayed will be 1
Enter last resource number to display [1 to 1024: 22] >> 22
Last resource displayed will be 22
Enter maximum resource type to display [1 to 4: 1] >> 4
Highest resource type displayed will be 4
For example, the dmf_ams_st example above changed to display in decimal would look as
follows:
Advmixsig_frame_ck
Checker ID Type Resource Data (1 to 160)
-------------------------------------------------------------------------
scmclk_ams_st 1 1 all resources selected
dmf_ams_st 2 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0
mfs_ams_st 3 1 all resources selected
pacs_ams_st 4 1 all resources selected
smem_ams_st 5 1 all resources selected
cmem_ams_st 6 1 all resources selected
apxfer_ams_st 7 1 all resources selected
vbms_ams_st 8 1 all resources selected
Global Commands Menu
Selecting the global command menu, option 13 of the group menu, displays a menu similar
to the following:
** THESE COMMANDS AFFECT ALL CHECKER GROUPS **
(0) To return to main menu
(1) Save custom execution and output modes to file
(2) Restore custom execution and output modes from file
(3) Datalog failed tests to file (default)
(4) Datalog all tests to file
IMAGE Solutions V8.3 19-41
IMAGE Base Language: Checkers: Creating Custom Checker Runs
Table of Contents Index Home Master Index Search Help
Selection =>
Selection 0 returns you to the main menu.
Selection 1 saves the custom setup to a file. When selected, you are asked to enter a prefix.
This is a name you want to give to the custom setup. The names daily, weekly, and
monthly have special meanings. See the “Loading the System Checker” on page 19-7.
Once you enter the prefix, you are asked to enter whether the saved setup should be stored
as [P]rivate or [S]ite. (You can also answer with ? to get help.) Private allows you to
save the setup in your home directory under a directory .checker_setups. Add the
following to your .usermenu file for faster execution of private custom checker setups:
"Custom Checker Menu" MENU ${HOME}/.checker_setups/.custom_menu
If you save the custom setup as Site, the file is saved in
/image/tester/<name>/.tester_setups and appears in the CHECKERS>CUSTOM
CHECKER RUNS button menu.
Selection 2 reloads a saved custom setup. You can do this, as explained above, either from
your customized .usermenu (if private) or from the station window CHECKERS>CUSTOM
CHECKER RUN menu.
Selection 3 calls for datalogging of only failed tests to a file, and selection 4 calls for
datalogging of all tests to a file.
IMAGE Solutions V8.3 19-42
IMAGE Base Language: Checkers: Creating a Static Configuration
Table of Contents Index Home Master Index Search Help
Creating a Static Configuration
The IMAGE System Check option allows you to load multiple checker groups quickly and
easily. Given the large number of IMAGE checker programs, however, this may be less than
ideal.
One problem is that System Check may load checkers for hardware you do not have in your
tester. This wastes valuable time and memory. It also means that when you look at the
checker menus you see a long list of checkers, some of which are unnecessary.
A second problem is more subtle. After a checker run, some checkers may return INVALID.
This does not imply a problem. INVALID in this context only means that the hardware
needed for the checker to run was not present. Since you have loaded checkers for
hardware you do not have, this is what you would expect.
However, an INVALID can be deceiving. A board may not be seated properly and its
checker will not return FAIL but INVALID. Looking at all the checker results you may not see
a problem which can affect tester yield.
The static configuration feature allows you to customize checker groups to a specific
hardware configuration. It allows you to reduce checker execution time based on test
system configuration.
This feature rebuilds the Checker Groups based on the tester hardware configuration at the
time of execution. It reads the configuration file and chooses checkers valid for the tester.
After completion, only valid checkers appear in the CHECKERS>INDIVIDUAL>STAND ALONE
CHECKERS menu. If, for example, a test system has no VHF instruments, the VHF checkers
would not be loaded and would not appear in any checker menus.
You need not rerun static configuration on a statically configured tester unless the hardware
changes (that is, an instrument is added or removed).
Static configuration also changes the definition of INVALID for a test system. For a
preconfigured system, if a checker is INVALID, System Check instead reports the checker
as a FAIL. If, therefore, hardware is removed from the test system without notice, a failure
flag signals a potential problem.
Checkers INVALID for a test system are not deleted from the checkers directory. However,
you can only execute these checkers using the standard command line load command or
selecting the unconfigure option to restore the checker groups and menus.
NOTE
If a new hardware option is added to the test system, or an existing option is removed,
perform an Unconfigure operation then perform another Static Configure operation. This
updates the checker groups and menus.
Static configuration is a CONFIGURE selection in the CHECKERS button menu in an auxiliary
station window. The CONFIGURE menu has three options:
IMAGE Solutions V8.3 19-43
IMAGE Base Language: Checkers: Creating a Static Configuration
Table of Contents Index Home Master Index Search Help
STATIC CONFIGURE Creates a static configuration for a test system.
UNCONFIGURE Restores checker groups and menus to their original state.
VIEW CONFIGURATION Displays checkers currently part of checker groups.
How Static Configure Chooses Files
Static configuration works by comparing the checkers with the test system hardware
configuration. A tester configuration is determined in the following way. Each checker has
a config file in $CKRBIN/conf. The config file for any checker is called <name>.cf, where
<name> is the checker name.
When you select STATIC CONFIGURE from the CHECKERS menu, the config file for each
checker is compared to the file:
/image/tester/<tester>/system_config
This file is created by sys_check.
If the required hardware is present, the checker is included in the checker group. If any
hardware specified in the checker config file is missing from the system_config file, the
checker is not included in any checker group.
If any checker does not have a config file ($CKRBIN/conf/<name>.cf), the checker is
included in the checker group by default.
If you change the hardware configuration on a tester that has been configured, you must
rerun static configure. The static configure option takes about 10 to 15 minutes to configure
a tester.
If the tester configuration does change, you are warned; sys_check compares a stored
system configuration file to the present system configuration.
Creating a Static Configuration
To create a static configuration for a test system:
1. Open an auxiliary station window.
2. Select CHECKERS>CONFIGURE>STATIC CONFIGURE or enter the command
/image/checkers/configure.
The Checker Groups are rebuilt based on the hardware configuration in the test system at
the time of execution. It takes about 10 to 15 minutes.
If a new hardware option is added to the test system, or an existing option is removed,
update the static configuration as follows:
1. Open an auxiliary station window.
2. Select CHECKERS>CONFIGURE>UNCONFIGURE or enter the command
/image/checkers/unconfigure. The unconfigure operation takes about 10 to 15
minutes.
IMAGE Solutions V8.3 19-44
IMAGE Base Language: Checkers: Creating a Static Configuration
Table of Contents Index Home Master Index Search Help
3. When the unconfigure operation finishes, select CHECKERS>CONFIGURE>STATIC
CONFIGURE or enter the command /image/checkers/configure.
This updates the checker groups and menus.
NOTE
Once you statically configure a test system, you must recreate any saved custom checker
files. These files are stored in your directory
$HOME/.checker_setups
and in the tester-specific location
/image/tester/<tname>/.checker_setups
Unconfiguring a Static Configuration
To unconfigure a static configuration:
1. Open an auxiliary station window.
2. Select CHECKERS>CONFIGURE>UNCONFIGURE or enter the command
/image/checkers/unconfigure.
This restores the checker groups and checker menus to their original state, where all
checkers are viewed under the appropriate menus. It takes about 10 to 15 minutes. The
definition of an INVALID checker is restored, where in the System Check summary it
appears as if the checker were not executed.
Viewing a Static Configuration
To view the current checker configuration:
1. Open an auxiliary station window.
2. Select CHECKERS>CONFIGURE>VIEW CONFIGURATION or enter the command
/image/checkers/view_config.
This selection displays in a textedit window the list of checkers currently part of each
checker group. For example, if a test system has not had Static Configure performed, all
default checkers are listed in the default checker groups. If the test system has had Static
Configure performed, the reduced list of checkers is displayed in the checker groups.
Disabling a Static Configuration
To disable static configuration for a checkers directory, create a file called
disable_fastload in the $CKRBIN directory. This is the same file used to prevent IMAGE
from creating the prelinked fast-load files. Normally, the same criterion will apply for
IMAGE Solutions V8.3 19-45
IMAGE Base Language: Checkers: Creating a Static Configuration
Table of Contents Index Home Master Index Search Help
preventing the static configure option, namely that checker binaries are shared by more
than one tester. (See “Fast-Load Groups” on page 19-10.)
IMAGE Solutions V8.3 19-46
IMAGE Base Language: Device Focussed Checkers
Table of Contents Index Home Master Index Search Help
20 DEVICE FOCUSSED CHECKERS
The Device Focussed Checkers (DFC) feature more tightly integrates test system checkers
into the production environment. It allows you to describe how the tester is being used to
test devices and to include this information in a test program. This information is then used
to test the specified instruments at the operating points being used in the test program
during a production run.
This section includes the following topics:
• “Using Device Focussed Checkers in IMAGE” on page 20-2
• “DFC User Callable Functions and Definitions” on page 20-4
• “DFC User Callable Functions and Definitions” on page 20-4
• “DFC Execution Points” on page 20-5
• “DFC Compiler” on page 20-6
• “PLFSRC Module” on page 20-8
• “PLFDIG Module” on page 20-9
• “HSD50 Module” on page 20-10
• “DC Module” on page 20-12
IMAGE Solutions V8.3 20-1
IMAGE Base Language: Device Focussed Checkers: Using Device Focussed Checkers in IMAGE
Table of Contents Index Home Master Index Search Help
Using Device Focussed Checkers in IMAGE
By successfully running DFC at the start of a lot, the end of a lot, and before any autocal
points during the lot, you can be confident that the test system was operating correctly
during the entire testing of the lot. Further, by only checking the instruments, channels, and
parameter settings actually used to test the devices in the lot, the time required to execute
DFC is significantly less than the time needed to run the system diagnostics (checkers).
The DFC system has three major blocks:
• Input
• Control system
• Test library
The input to the DFC system is a module you write describing the instruments used and the
operating points of those instruments. This input file is compiled using the DFC compiler
called dfccomp which resides in IMAGEBIN. The resulting binary is loaded with the test
program using the test program .load file.
The control system decides when the DFC checkers are executed. Functions are provided
to enable or disable DFC functions from inside the test program. Additional functions allow
you to check the status of a DFC test and to request addition tests.
The test library is where the instrument checkers reside. This library loads co-resident with
the test program when a DFC input module is present in your test program .load file. Only
the checkers corresponding to the instruments described in the input file link with the test
program.
Limitations
The DFC provides no diagnostic output and is designed only to signal the test program if an
instrument used by the test program fails or drifts out of specification (as best as can be
determined by the tester).
If DFC signals the test program to stop testing on a lot of devices, have a technician or field
service person run test system checkers to determine the cause of the fault.
You can determine which instrument failed using the DFC. This requires that you modify
your test program to add calls to the DFC library.
Test Program Modifications
To use the DFC feature, you must modify your test program.
First, you must add a DFC input file to the .load file for the test program. The syntax for this
file and a description on creating this file are described in “DFC Compiler” on page 20-6.
Next, you must enable the DFC system in the tl_init() section of the test program. DFC
must be enabled before the fist run of the test program, which requires it to be enabled in
tl_init().
IMAGE Solutions V8.3 20-2
IMAGE Base Language: Device Focussed Checkers: Using Device Focussed Checkers in IMAGE
Table of Contents Index Home Master Index Search Help
You must also modify the test program to check the return status of DFC and take action on
a failure. The most integrated approach is to write a callback function supported by the DFC
control, which lives in the test program and is called by DFC if any instruments fails a test.
The name of the supported call-back is tl_dfc_fail_action(), and the recommended
action would be to stop testing the lot of devices.
To output additional information, such as which instrument failed, you must include the
header file dfc_instrs.h in the test program. This header defines an enumerated type
called TL_DFC_INST which contains a value for each supported instrument. These values
can be passed sequentially to the function tl_dfc_inst_status() to determine which
instrument failed.
IMAGE Solutions V8.3 20-3
IMAGE Base Language: Device Focussed Checkers: DFC User Callable Functions and Definitions
Table of Contents Index Home Master Index Search Help
DFC User Callable Functions and Definitions
The following functions are included to be used with DFC:
tl_dfc_enable() Called to enable DFC. Call it from tl_init() in the test
program.
tl_dfc_disable() Called to disable DFC.
tl_dfc_request() Called to indicate to IMAGE to run DFC at the next available
point (before testing the next device).
tl_dfc_fail_action()
Called at the end of a DFC execution if any instrument failed.
This is a user-callback which you write. If it does not exist, no
action is taken.
tl_dfc_fail_run() Called to determine if the last DFC execution failed. Returns
nonzero if DFC failed or an error was encountered. Returns 0 if
DFC passed.
tl_dfc_inst_status(inst)
Called to check if a given instrument failed. Return value is an
enumerated type with values: Pass, Fail, Error, and NotRun as
defined in dfc_instrs.h. The passed argument inst is also
defined in this header file.
tl_dfc_preexecute_hook()
Called before running DFCs from the DFC control system. This
is a user-callback which you write. If it does not exist, no action
is taken and processing continues.
tl_dfc_postexecute_hook()
Called after running DFCs from the DFC control system. This is
a user-callback provided by the test program. If it does not exist,
no action is taken and processing continues. The hook is
provided for reloading any patterns or segments the test
program needs.
IMAGE Solutions V8.3 20-4
IMAGE Base Language: Device Focussed Checkers: DFC Execution Points
Table of Contents Index Home Master Index Search Help
DFC Execution Points
The DFC system runs the specified instrument checkers at the following points:
• Immediately after the first autocalibration
• Before any subsequent autocalibration
• Immediately after tl_user_endlot() is called
Additionally, you can call tl_dfc_request() to schedule DFC execution before the start of
testing for the next device.
IMAGE Solutions V8.3 20-5
IMAGE Base Language: Device Focussed Checkers: DFC Compiler
Table of Contents Index Home Master Index Search Help
DFC Compiler
The DFC compiler parses and compiles the instrument description file. The output is a .o
module which is loaded with the test program. The input is a DFC file in a LISP-like syntax
which specifies which instruments are used in the test program and how they are
programmed.
Loading the test program with the DFC module causes the DFC test library to be linked with
the test program. This library (libdfc.a) is where the checker functions for each instrument
exist. When the test program is run, the DFC executive calls, at the appropriate time,
Usage
The DFC compiler is called dfccomp. Unlike other IMAGE tools, it cannot be started by
imagepath in /image/common. This means that to use the tool, you must either add
$IMAGEBIN to your path, or start the compiler with the full path as in:
$IMAGEBIN/dfccomp <foo.dfc>
The usage of the tool is:
dfccomp [-save] <filename>
The -save flag saves a copy of the intermediate .tl file for inspection or debugging
purposes. This intermediate file is compiled using the IMAGE itlc compiler to create the
final DFC module.
Compiling foo.dfc creates the object file foo.o in the same directory.
Compiling foo.dfc with the -save switch creates the intermediate file foo.tl and the
object file foo.o in the same directory.
Parameters and Syntax
The input file syntax is described in detail in the instrument sections. This section provides
a brief overview of the supported syntax.
The DFC input file resembles LISP syntax. An instrument definition is followed by
parameter/value pairs. For example:
(instr1
(param1 value1)
(param2 value2)
(param3 value3)
)
For the PLFSRC instrument, an instrument specification might look as follows:
(plfsrc
(range 1mv)
(freq 100KHz)
IMAGE Solutions V8.3 20-6
IMAGE Base Language: Device Focussed Checkers: DFC Compiler
Table of Contents Index Home Master Index Search Help
(lpfilt 20KHz)
)
You can define multiple setups for an instrument and multiple instruments. You cannot set
the same parameter more than once for an instrument. This requires multiple setups.
Instrument names (such as plfsrc used in the example) are checked against a valid list of
supported instruments at compile time. Parameters and values are not checked by the
compiler. This checking is done in the individual instrument checkers at runtime. For
information about which parameters and values are supported by each instrument checker,
see the documentation for that DFC instrument.
During the development of a DFC input file, closely monitor the output in the station window
at runtime for errors generated from the DFC checkers related to parameters. Any error
causes the test program to terminate execution, and this is the only time the DFC prints any
output to the station window.
Once the DFC input file is debugged, no output should be generated by the DFC.
IMAGE Solutions V8.3 20-7
IMAGE Base Language: Device Focussed Checkers: PLFSRC Module
Table of Contents Index Home Master Index Search Help
PLFSRC Module
The test program plfsrc_dfc() checks the functionality of a Precision Low Frequency
Source. The inputs to the program are values to specify what operating characteristics to
verify the source at and the pin number of the source to be tested. A pin number is also
required to specify some PLFDIG for use in testing the source’s AC capabilities. This other
PLFDIG should be one that is also being tested with a DFC module. Another constraint on
the input for the pin numbers of the instruments is that the pin number must be for the HI
side of the instrument.
The output for the program is a FAIL if the instrument fails to preform correctly or a PASS if
it succeeds. The program takes no more than a minute to test a single source instrument.
Parameters/Syntax
The program is called using the syntax:
plfsrc_dfc(<parameter list>);
where:
src_pin Specific PLFSRC to be tested. It must be a valid pin number.
dig_pin Specific PLFDIG. It must be a valid pin number.
src_lpfilt 2khz | 20khz | 100khz | 500khz (Default is 2khz.)
amp 0.0 -> 10.24 vpk. (Default is 10.0vpk.)
src_dcbase -11.0vpk -> 11.0vpk. (Default is 0.0V.)
freq Highest frequency at which the PLFSRC is being used. (Default
is 1 kHz.)
The parameters must be specified in the order above. If you are not concerned about testing
a specific parameter, it is assigned a default value. Src and dig pin numbers require a valid
pin number which must be supplied. Otherwise, the program fails immediately.
Test Strategy
The program tests the PLFSRC at dc and ac. At DC the inputted values for amp and the
dcbase line are tested by connecting the source to the DC Matrix in the test system. This
allows checking of connection ability and the performance in the ranges you specify. The
AC section involves connecting the source and specified digitizer together across the
THADS bus and sourcing sine waves at, and within, the frequency range specified and with
the appropriate filter and amplitude. The sine waves are checked for noise, amplitude
accuracy, THD, and spurs. These characteristics signify if the source is performing
correctly. At any time that the source is not performing within the expected values, the
program fails and produces an error message.
IMAGE Solutions V8.3 20-8
IMAGE Base Language: Device Focussed Checkers: PLFDIG Module
Table of Contents Index Home Master Index Search Help
PLFDIG Module
The plfdig_dfc() test program checks the functionality of a Precision Low Frequency
Digitizer instrument. The inputs to the program are the values to specify the operating
characteristics to verify the digitizer at and the pin number of the digitizer to be tested. A pin
number is also required to specify a PLFSRC for use in testing the digitizer’s AC capabilities.
This PLFSRC should be one that is also being tested with a DFC module. Another constraint
on the input for the pin numbers of the instruments is that the pin number must be for the HI
side of the instrument.
The output for the program is a FAIL if the instrument fails to preform correctly or a PASS if
it succeeds. The program takes no more than a minute to test a single digitizer instrument.
Parameters/Syntax
The program is called by using the syntax:
plfdig_dfc(<parameter list>);
where:
dig_pin Specific PLFDIG, must be valid pin number.
src_pin Specific PLFSRC, must be valid pin number.
vrange 0.113 -> 11.0 vpk. (Default is 11.0vpk.)
dig_lpfilt 2khz -> 500khz. (Default is 2khz.)
dig_dcbase -11.0 -> 11.0vpk. (Default is 0.0v.)
dig_feq Frequency of waveforms typically captured by dig. (Default is
1khz.)
The parameters must be input in the order above. If you are not testing a specific parameter,
it is assigned a default value. Src and dig pin numbers require valid pin number which must
be supplied. Otherwise, the program fails immediately.
Test Strategy
Test the PLFDIG at dc and then ac. DC tests involve testing connections to the DC Matrix
and the THADS bus, using the ability of the digitizer to capture simple dc levels at specific
ranges. This verifies the basic capture and move ability of the digitizer. AC tests involve
connecting the digitizer and source together across the THADS bus and then using the
digitizer to capture waveforms from the source. This verifies the ability of the source to
capture AC waveforms within its operating specifications and verify its performance in that
range by specifically testing to the frequency inputted with the amplitude and filter
requested. Any time the digitizer is not preforming correctly, the program fails the instrument
and stops testing.
IMAGE Solutions V8.3 20-9
IMAGE Base Language: Device Focussed Checkers: HSD50 Module
Table of Contents Index Home Master Index Search Help
HSD50 Module
The hsd50_dfc module tests the basic functionality of HSD50 channels. If present, the
DSIO subsystem is also tested. Test coverage is designed to exercise the digital channels
at the operating points specified by the device program. Only the channels in the channel
list specified in the .dfc file are tested. To minimize run time, only specify the channel range
used by the device program.
Some testing is performed by looping back each channel’s digital driver to the digital
receiver and bursting a pattern. The loopback connection is made at the test head. Other
testing is performed using the TMS.
Parameters/Syntax
The hsd50_dfc program is called using the syntax:
tl_dfc_hsd50(<parameter list>);
where:
chanlist The range of digital channels to test, from 1 to 192. The format
must be x..y with x as the first and y as the last channel in the
range. This parameter is required.
mclk Master clock frequency from 160 MHz to 200 MHz. (Default is
200 MHz.)
t0_div t0 clock divider from 4 to 32771. (Default is 4.)
vrange Channel driver voltage range: low, middle, or high. (Default is
high.)
calset A valid digital calibration set name. The calset must already have
been defined and started in tl_init() for testing to function
correctly. This parameter is required.
An example is as follows:
tl_dfc_hsd50 (
mclk, 200MHz
t0_div, 4
vrange, high
calset, "valid_calset_name");
HSD Test Coverage
The master clock frequency, t0 clock divider, and vrange specified in the device program
are exercised by the tests. Only the channels within the range specified by the channel list
are tested.
The calset name you provide must represent a cal_set defined and started in the
tl_init() of the device application program. If the cal_set failed calibration, or was not
IMAGE Solutions V8.3 20-10
IMAGE Base Language: Device Focussed Checkers: HSD50 Module
Table of Contents Index Home Master Index Search Help
calibrated before a call to the hsd50_dfc program, the program fails. Also, variables defined
in the .dfc file must match the settings defined in the cal_set defined in the .dfc file. For
example, if the .dfc file looks like:
(hsd
(mclk 200MHz)
(t0_div 4)
(vrange high)
(calset "cal_200_normal")
)
then the cal_set cal_200_normal should include:
set hsd50 cal-set = "cal_200_normal"
m_clk = 200MHz
vrange: high
dchan = (1 to 8);
Variables defined in the .dfc file that do not match the variables in the cal_set can cause
hsd50_dfc to fail. The only operating point that should be considered optional is the t0 clock
divider. All others must be included in the .dfc to ensure correct test execution.
The TMS and DC subsystems are used and, therefore, must also be calibrated.
dfc_hsd50 tests, as with all checker tests, must be run with the DUT relay open to isolate
the tester from the DIB while the self-tests are run. The cal_set passed to dfc_hsd50
through the .dfc file may be defined to calibrate HSD50 with the DUT relay either open or
closed. Therefore, the timing used in the dfc_hsd50 tests is set up to allow for potential
differences between calibration with open or closed DUT relays. Calibration sets run with
the DUT relay closed on long path lengths may result in failure of the dfc_hsd50 tests.
Tests included in dfc_hsd50 are briefly described below:
Rev. prom check Checks HSD ID PROMs.
Calibration Constants Check
Checks that the calibration set is valid.
Format and timing checks
Various patterns are burst, with each channel driver looped back
at the test head and checked by the channel receiver. SCM
microcode, digital modes, formats, patterns, and timing are all
exercised. Failures are determined by reading the accumulated
fail register and SCM flags and comparing to expected values.
Digital channel driver operation is also monitored using the TMS.
Digital Signal Tests (if option exists in system)
A digital signal is burst from SMEM to the CMEM through each
digital channel and looped back at the test head. The results
captured into CMEM are compared to expected values.
IMAGE Solutions V8.3 20-11
IMAGE Base Language: Device Focussed Checkers: DC Module
Table of Contents Index Home Master Index Search Help
DC Module
The test program dc_dfc checks the standard dc sources and the dc system meter. For the
dc sources, you must specify the source number, voltage, and current ranges that the
sources are set to during their test points of interest. For the meter you can specify which
input to test. The program takes no more than 5 seconds per source and 16 seconds for the
system meter to execute a single setup.
Parameters/Syntax
The parameters input by a foo.dfc file are as follows:
DC SOURCES (dc
(src #)
(vrng xxx)
(irng xxx)
)
where:
src # Specified source to test (1-9).
vrng xxx Voltage range of source: 0.5v | 1v | 2v | 5v | 10v |
20v | 50v | 100v | 200v
irng Current range of source: 5ua | 10ua | 20ua | 50ua |
100ua | 200ua| 500ua | 1ma |
2ma | 5ma | 10ma | 20ma |
50ma | 100ma | 200ma
DC METER (dc
(meter xxx)
)
where:
meter xxx Specified input to test: vm1, vm2, vmdiff, all
all tests vm1, vm2, vmdiff, and all in the same test call.
Test Strategy
Using matrix crosspoints 1-3 and the test system reference, the voltage forcing/metering
and the current forcing/metering for the dc sources are verified for the voltage and current
ranges you specify. Some miscellaneous checks are also performed, such as verification of
the delta bus input to the dc source and the maximum compliance tests.
The DC meter tests are done using dc source 1, crosspoints 1-3, and the test system
reference. The metering accuracy is verified per user input (for example, vm1, vm2...) on all
meter ranges. Coverage for sample and difference gain and meter filtering are also
performed. These tests are the same as those found in the DCST self-test checker.
IMAGE Solutions V8.3 20-12
IMAGE Base Language: Calibration
Table of Contents Index Home Master Index Search Help
21 CALIBRATION
Calibrating a test system instrument ensures that it performs according to specifications.
Each test system instrument requiring calibration has a criterion for when its calibration
expires. This is often based on time since the last calibration or on a drift in temperature. If
an instrument’s calibration is not valid, that instrument is no longer guaranteed to be in
specification if used to make measurements.
Over the years, IMAGE has been enhanced to maintain test system calibration with minimal
intervention by users. Since code is frequently copied from one test program to the next,
however, many test programs do not take advantage of the benefits IMAGE offers and run
the risk of testing parts on an uncalibrated test system.
The ISO 9000 requirements have driven some of these changes. It is no longer adequate
simply to calibrate the test system. The calibration schedule must be enforced and
performed according to manufacturer specifications. Otherwise, parts are not considered to
have been tested on a tester calibrated to reference standards. Officially, this means the
parts tested are not ISO 9000 compliant unless the calibration schedule is enforced.
Conversely, the tester can be overcalibrated. If an instrument is guaranteed to be within
specifications for four hours after calibration, for example, calibrating the instrument every
hour wastes potential production time.
This section describes IMAGE calibration routines. It includes:
• “Calibration Theory of Operation” on page 21-3
• “Controlling Calibration” on page 21-17
• “Manual Calibration Using the calibrate Command” on page 21-33
• “Autocal Examples” on page 21-51
• “Overriding Calibration Errors Using an Error Handler” on page 21-57
• “Syntax Summary” on page 21-60
The normal and recommended method of calibrating test system instruments uses the
IMAGE autocalibration utility (autocal). Most descriptions of calibration in this section refer
to autocal. Additional information is provided on “manual” calibration, calibration invoked
using specific commands or test program statements.
Calibration discussions in this section are confined to IMAGE software calibration. For
information on other types of calibration (such as performance verification and calibration
hardware theory of operation) see the Catalyst Instrumentation Manual and the Catalyst
IMAGE Solutions V8.3 21-1
IMAGE Base Language: Calibration:
Table of Contents Index Home Master Index Search Help
Tiger Instrumentation Manual. Sections in these manuals describe specific calibration
procedures for those components.
For those instruments that have microwave analysis capability, a more extensive calibration
procedure is required. Only a few basic calibration steps are included in the autocal utility.
Since the microwave port signals to and from the device are frequency dependent and
signal path dependent, the calibration process must test each path with a series of
standards through a range of frequencies. S-parameters measurement, Noise Figure
determination, calibration of the ENR source, and source linearity may all be necessary
prior to analysis. The user must insert appropriate DIBs and standards at several steps
during the calibration process. The documentation for this is included in the Catalyst and
Catalyst Tiger manuals in the chapters on microwave calibration. These steps are not part
of the autocal utility.
IMAGE Solutions V8.3 21-2
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Calibration Theory of Operation
Calibrate test system instruments whenever they are uncalibrated. (See “Determining When
Calibration is Performed” on page 21-6.) The simplest and recommended way to calibrate
test system instruments during production testing is to let IMAGE do it automatically at
regular time intervals using automatic calibration (autocal). You can enable or disable
autocal for each test program, for each instrument, or in a number of other ways. This
section provides details on how calibration works.
How Autocal Works
When autocal is on, the state of most instruments used in the test program is checked
before each execution of that program. (Some tester instruments are not included in
autocal.) If an instrument’s calibration has expired, that instrument is calibrated before the
test program runs. Normally, all copies of that instrument in the tester are calibrated, not
only those used in that program. (Some instruments can be set to calibrate by copy.)
Autocal works by checking the calibration state of each instrument whose software driver is
linked to the test program before each program execution. Any uncalibrated instruments are
then calibrated by autocal. An instrument driver is linked when programming statements for
that instrument are used in the test program.
Note that only one driver is linked regardless of the number of instruments used in the test
program. Therefore, if you have two PLFDIG’s in your test system but only use one in your
program, both are calibrated by autocal. (You can change this to calibrate only the
instruments used in the test program using the pinmap_only mode of calibration. See
“Pinmap Only Mode” on page 21-29.)
Calibration at Test Program Load
Autocal is called when you load a test program (IMAGE V5.3 D2 and later) before executing
tl_init(). When you load a test program, the following functions are called (figure 21-1):
reset all;
<autocalibration>
tl_init();
The reset_all function is executed before and after each instrument is calibrated either by
autocal, by the calibrate command, or by the function tl_cal_inst().
IMAGE Solutions V8.3 21-3
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Yes Test system out
of calibration?
No
tl_user_pre_autocal()
Autocalibration
tl_user_post_autocal()
tl_init() End
Figure 21-1. Flowchart of Autocalibration at Test Program Load
tl_init() is a null function that you typically overwrite when you define this function in your
program.
Calibration at Test Program Run
After a test program is loaded, any of the following cause IMAGE to check if calibration is
required:
• The run command
• A start signal from an enabled handler or prober
• A start signal from the Start Switch
Each time a test program is run, the following functions are called (figure 21-2):
reset all;
<autocalibration>;
main();
IMAGE Solutions V8.3 21-4
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Yes Test system out
of calibration?
No
tl_user_pre_autocal()
Autocalibration
tl_user_post_autocal()
main() End
Figure 21-2. Flowchart of Autocalibration at Test Program Run
Autocal checks the calibration status of each instrument linked to the test program. If
calibration is necessary, the instrument is calibrated. Calibration is unnecessary if the
instrument is already calibrated and nothing has happened to invalidate this calibration.
(See “Determining When Calibration is Performed” on page 21-6.)
Calibration results are sent to a trace file in the same directory as the test program.
User Autocal Functions
The following functions are called before and after invocation of any calibration from
autocal:
tl_user_preautocal()
Called before any instrument calibration from autocal.
tl_user_postautocal()
Called after any instrument calibration from autocal.
These functions are provided for your use in special situations regarding calibration. They
do nothing unless you define them. The functions are only called when one or more
instruments are out of calibration. They are not called on every test program run. See
“tl_user_preautocal” on page 26-434 and “tl_user_postautocal” on page 26-434 for more
information.
IMAGE Solutions V8.3 21-5
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Determining When Calibration is Performed
The need for calibration is checked for all instruments when a test program is loaded and
before each program run. Calibration is performed if:
• The instrument has not been calibrated since IMAGE was started.
• The instrument has not been calibrated since the last time test system power was cycled
(turned off, then on) or the initialize command was used.
NOTE
Exceptions to this statement are the Analog Pin Unit (APU) and Advanced Analog Pin Unit
(AAPU). These instruments maintain their calibration during initialization and so do not
require calibration afterwards.
• Calibration has expired due a significant variation in temperature. (For some
instruments, calibration depends on time. The calibration default interval for most
instruments is four hours.)
• A tester power supply drifts or the temperature changes significantly (HSD50 and
Catalyst only).
For example, autocal calibrates the DC Subsystem at the following times:
• If four hours has passed since the last DC Subsystem calibration;
• During loading of a test program if the DC Subsystem has not been calibrated since the
last time IMAGE was started;
• Immediately following a power-up of the test system.
Time Measurement Subsystem (TMS) calibration and deskew occur at the beginning of the
test program and after every four hours. Calibration occurs if TMS statements are used in
the test program, or if you are using mixed-signal, advanced mixed-signal, or Catalyst digital
in the program. TMS calibration is a full calibration including deskew and is performed once
for every test head in the test system.
On the Catalyst testers, autocal calibrates and deskews the Digital Subsystem whenever
the temperature changes more than three degrees Centigrade or whenever test head power
supply levels change more than the specified limit. (See “PLFSRC and PLFDIG” on page
21-16.)
Autocal calibrates only the test head in use during TMS and HSD calibration. For example,
a test program loaded into station 2 under autocal calibrates the TMS for test head 2 only
and deskews the TMS and HSD for test head 2 only.
Autocal also calibrates other instruments if those instruments are used in the test program.
These are listed in table 21-1. Instruments not listed are presently not calibrated under
autocalibration.
Table 21-1 shows the calibration characteristics of A5xx Family instruments and any
calibration dependencies. The table has the following headings:
IMAGE Solutions V8.3 21-6
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
• Instrument lists the instrument and its IMAGE syntax abbreviation used in calibration
commands
• Autocal lists whether the instrument is calibrated by autocalibration
• Pinmap Only lists whether the instrument can use the pinmap_only feature. (See
“Pinmap Only Mode” on page 21-29.)
• Calfile lists whether the instrument uses a calibration file to store calibration values
• Force lists whether the instrument can be forced to use its calibration file even if the file
may not be valid
• Default Criteria lists the default time interval used for checking calibration
• Dependencies lists which other instruments must be calibrated for calibration to
succeed for this instrument.
Table 21-1. Instrument Calibration Characteristics
Pinmap Default
Instrument Autocal? Calfile? Force? Dependencies
Only? Criteria
Advanced Analog Pin Unit yes yes no no 4 hours DC
(apu)
Broadband AC (wf) yes yes yes yes 30 days DC
DC Subsystem (dc) yes no no no 4 hours none
GigaDig (gigadig) yes yes yes no 20 min DC
High Curent Power Supply yes yes yes no 10 min DC
(dps)
High Speed Digital yes no yes yes 20 min1 DC, tms
Subsystem, Catalyst (hsd)
High Speed Sampler yes no no no 4 hours DC, tms
(hfsamp)
Low Current Ammeter (lca) yes yes no no 4 hours DC
Microwave Port (uwport) yes yes no no 1 hour DC, uwsrc,
uwrecv
Microwave Receiver yes yes no no 1 hour DC, uwsrc
(uwrecv)
Microwave Source (uwsrc) yes yes no no 1 hour DC
Octal V/I Source (ovi) yes yes yes no 10 min. DC
Precision Low Frequency yes yes no no 4 hours plfsrc
Digitizer (plfdig)
IMAGE Solutions V8.3 21-7
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-1. Instrument Calibration Characteristics (Continued)
Pinmap Default
Instrument Autocal? Calfile? Force? Dependencies
Only? Criteria
Precision Low Frequency yes yes no no 4 hours none
Source (plfsrc)
Precision Multimeter (pmm) no n/a n/a n/a n/a none
Pulse Driver (pulse) yes yes no no 4 hours DC
Quad Voltage Source (dps) yes yes yes no 10 min. DC
Serial Bus channel card yes no no no 30 days DC
(cdig)
Time-Jitter Analyzer (tja) yes no yes yes 1 month DC
Time-Jitter Digitizer (tjd) yes yes yes yes 4 hours DC, tms
Advanced Time yes no no no 4 hours DC
Measurement Subsystem
(tms)
Trigger Walking Delay yes no no no 4 hours DC, tms
Generator (t_delay)
Turbo AC (wf) yes yes yes yes 30 days DC
VHF Arbitrary Waveform yes yes no no 20 min2 DC
Generator (vhfawg)
VHF Continuous Wave yes yes no no 4 DC
Source (vhfcw) hours1
VHF Digitizer (hfdig) yes yes yes no 4 hours none
Voltage Regulation Front yes yes yes no 7 days1 DC
End Channel Card (vreg)
1. If autocalibration is on, the environment is checked within an interval not to exceed 4 hours for a significant
change in temperature.
Table 21-2 shows the required calibration resources for the A500 family instruments. The
table has the following headings:
• Instrument lists the instrument and its IMAGE syntax abbreviation used in calibration
commands
• Resource lists the name of the resource
• Use lists whether the instrument uses the resource.
IMAGE Solutions V8.3 21-8
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-2. Calibration Resources Required by Instruments
Instrument Resource Use
Advanced Analog Pin Unit (apu) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
DC Subsystem (dc) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
High Speed Digital Subsystem, Catalyst (hsd) dig_src not used
dig_cap not used
dsp bufs not used
pat mem 100 PRAM
locations.
hsd state Settings affected by
reset are reset,
settings that are not
(e.g. timing and
levels) are left in
their previous state,
except vrange and
mck which are
programmed to the
value specified in the
calset.
DC used and reset
DUT source 1 (src=1) used and reset
TMS used (if in test
system) and reset
matrix pins 2,46,47,48 used and reset
trigger switchyard, lines 7 used
and 8 to head
IMAGE Solutions V8.3 21-9
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-2. Calibration Resources Required by Instruments (Continued)
Instrument Resource Use
High Speed Sampler (hfsamp) dig_src not used
dig_cap not used
pat mem 1 pattern loaded
dsp bufs not used
Low Current Ammeter (lca) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
Microwave Source (uwsrc) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
measure bus used and reset
meter used and reset
vhfawg (IFMS) used and reset
IMAGE Solutions V8.3 21-10
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-2. Calibration Resources Required by Instruments (Continued)
Instrument Resource Use
Microwave Receiver (uwrecv) Note: calibrate -uwrecv causes UWRECV
calibration data gathered during the first test
program run to be invalidated. Because UWRECV
calibration is relatively slow, this is generally
undesirable.
dig_src not used
dig_cap (128k) calibrate -
uwrecv uses no
DSP. Variables are
only initialized for the
coming run. During a
test program run,
when a new
frequency and
amplitude needs to
be calibrated, a
calibration signal is
measured. This
requires five DSP
buffers totaling 128k
of space.
pat mem not used
dsp bufs (5) calibrate -
uwrecv uses no
DSP. Variables are
only initialized for the
coming run. During a
test program run,
when a new
frequency and
amplitude needs
calibration, a
calibration signal is
measured. This
requires five DSP
buffers totaling 128k
of space.
IMAGE Solutions V8.3 21-11
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-2. Calibration Resources Required by Instruments (Continued)
Instrument Resource Use
Microwave Receiver (uwrecv) hfdig/uwmm/thads The UWRECV must
have an HFDIG
attached to the
UWMM through the
THADS when
calibration occurs.
The aclock assigned
to the UWRECV
may be changed
during calibration,
but it will not affect
the master clock or
other PACS cages
(aclock dividers in
the cage containing
the HFDIG only).
Microwave Port (uwport) Note: UWPORT causes the UWSRC (UHFSRC)
and UWRECV behind it to be calibrated if they are
uncalibrated, so calibrating the UWPORT requires
the resources for calibrating UHFSRC and
UWRECV. Otherwise, UWPORT resource usage
is under user control. Users can provide a routine
to do s-parameter calibration at autocal time or at
runtime. The resources this routine requires are
under user control. The UWPORT requires users
to connect external components (calibration
standards) and measure them to calibrate. Users
can choose to use the array processor for the
computations involved, although the driver
defaults to doing everything in the CPU.
dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
uhfsrc used
uwrecv used
IMAGE Solutions V8.3 21-12
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-2. Calibration Resources Required by Instruments (Continued)
Instrument Resource Use
Octal V/I Source (ovi) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
Precision Low Frequency Digitizer (plfdig) dig_src 110 locations of
PLFSRC; restored
after cal
dig_cap 100000 capture
samples
pat mem not used
dsp bufs 8 DSP temporary
buffers; reset after
cal
Precision Low Frequency Source (plfsrc) dig_src 8292 locations of
dig_src; restored
after cal
dig_cap 81920 captures
samples
pat mem not used
dsp bufs 10 temp bufs; reset
after cal
Precision Multimeter (pmm) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
dig_src not used
NOTE: PMM calibration uses no system
resources. However, the test system must wait for
PMM calibration to finish before continuing.
IMAGE Solutions V8.3 21-13
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-2. Calibration Resources Required by Instruments (Continued)
Instrument Resource Use
Pulse Driver (pulse) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
DC used
TMS used
Quad Voltage Source (dps) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
Serial Bus channel card (cdig) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
DC used
TMS used
system voltmeter used; reset after cal
VI source 1 used; reset after cal
matrix used; reset after cal
NOTE: reset all is executed at the end of cal
Time-Jitter Digitizer (tjd) dig_src not used
dig_cap not used
pat mem 2 vectors
dsp bufs not used
TMS used
TDR (hsd50) used
Calstrobe used
IMAGE Solutions V8.3 21-14
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-2. Calibration Resources Required by Instruments (Continued)
Instrument Resource Use
Time Measurement Subsystem (tms) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
System voltmeter used
Source 1 used
Calstrobe used
THADS used
PTS for mis_sig used
LA302 for lin/adv_lin used
Trigger Walking Delay Generator (t_delay) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
DC used
TMS used
VHF Arbitrary Waveform Generator (vhfawg) dig_src used 24 locations,
but restored after cal
dig_cap not used
pat mem not used
dsp bufs not used
meter used; reset after cal
VHF Continuous Wave Source (vhfcw) dig_src not used
dig_cap not used
pat mem not used
dsp bufs not used
meter used; reset after cal
IMAGE Solutions V8.3 21-15
IMAGE Base Language: Calibration: Calibration Theory of Operation
Table of Contents Index Home Master Index Search Help
Table 21-2. Calibration Resources Required by Instruments (Continued)
Instrument Resource Use
VHF Digitizer (hfdig) dig_src not used
dig_cap used
pat mem not used
dsp bufs 6 DSP temporary
buffers; reset after
cal
Voltage Regulation Front End Channel Card dig_src not used
(vreg)
dig_cap not used
pat mem not used
dsp bufs not used
DC used and reset
PLFSRC and PLFDIG
The Precision Low Frequency Source (PLFSRC) and the Precision Low Frequency Digitizer
(PLFDIG) are calibrated together. The PLFDIG requires the PLFSRC to be calibrated first
due to a calibration dependency. The PLFSRC, however, can be calibrated by itself.
If you load a test program using only the PLFSRC or only the PLFDIG, the other PLF
instrument will also calibrate. If your test program uses the PLFSRC and not the PLFDIG,
you can avoid this in IMAGE V5.6 and later using the pinmap_only feature. (See “Pinmap
Only Mode” on page 21-29.)
VHFAWG
In IMAGE V6.3 and later, the Very High Frequency Arbitrary Waveform Generator
(VHFAWG) has temperature-based calibration. Temperature checks are performed every
20 minutes, and recalibration will not occur unless a significant drift is detected.
The VHFAWG1200/2500/4800 uses a temperature sensor on its channel card to determine
the amount of temperature drift. A 1.75 degree C change will trigger recalibration.
The VHFAWG200 and 400 check for drift using the peak detector and Absolute Level
Reference Oscillator (ALRO) on their channel cards. The ALRO provides a temperature-
stable reference signal. To perform a drift check, this signal is connected to and measured
by the detector. When the voltage measured by the detector changes by 5 mV or more since
the last calibration, recalibration is triggered.
The RF Instrument Setup display shows the time of the last actual calibration. The
command calibrate -report shows the time remaining until the next temperature check.
IMAGE Solutions V8.3 21-16
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
Controlling Calibration
Normally, using autocal simply involves loading a test program under autocal and running
it. In this case, IMAGE does all the work of making sure instruments stay in calibration.
In some situations, such as debug, you may want some flexibility. For example, you may
want to handle calibration of one or more instruments yourself. Autocal includes a number
of functions and parameters that allow you to customize the way autocal operates.
NOTE
When debugging a test program, do not use the Immediate window to alter calibration
between test program runs.
IMAGE also supports “manual” calibration. This is calibration you invoke using the
calibrate command or test program calibration statements. See “Manual Calibration
Using the calibrate Command” on page 21-33 for more information.
Enabling and Disabling Autocalibration
You can enable autocalibration using any of the following methods:
• Check the Autocalibration option in the Load test program window when loading a test
program.
• Include the -autocal switch on the load command line. For example, to load the test
program dcst, you would type load dcst -autocal
• Include the -autocal switch in a .load file for the test program.
• Enter the calibrate -autocal command at the station window prompt.
Autocal is never turned on by default.
You can disable autocalibration after you load a test program by:
• Using the command calibrate -noautocal in a station window;
• Using the function tl_set_autocal_onoff() or tl_cal_set_autocal_mode() in a
test program (see “Enabling and Disabling Autocal” on page 21-22 and “Setting
Calibration Modes for Autocal” on page 21-22);
• Using the calibrate command to disable calibration for specified instruments. (See
“Manual Calibration Using the calibrate Command” on page 21-33.)
Using the Load Window
The Load test program window includes a selection to start autocal. When you bring up the
load window, you can check the following selection:
OPTIONS: AUTOCALIBRATION
Load the selected file and turn on autocalibration.
IMAGE Solutions V8.3 21-17
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
Using load Command Parameters
The load command includes the following calibration-related parameters:
load <progname> [-autocal] [-ignore_cal] [-cal_after] [-nocalfile]
[-pinmap_only] [-frc_calfile] [-<inst> [cal_type] noautocal]
[-<inst> [cal_type] ignore_cal] [-<inst> [cal_type] nocalfile]
[-<inst> [cal_type] frc_calfile]
where:
-autocal Activate autocalibration. The default is noautocal.
-ignore_cal Ignore calibration. Allows you to load a test program without
calibrating any test system instruments. In this mode the test
program executes without run-time errors, but results measured
using test system instruments are inaccurate. Divide by zero
alarms may occur. The default is not to ignore calibration.
NOTE
This parameter allows you to run the test system uncalibrated. This may result in incorrect
testing of some devices. Production testing is disabled in this mode.
-cal_after Calibrate after the test program run. The default is to run
calibration before the test program run.
-nocalfile Do not use the calibration data files for instruments which
support them. (See table 21-1 on page 21-7.)
-pinmap_only Calibrate only those copies used in the current pinmap. This
mode is available only for instruments which support calibration
by instance. See “Pinmap Only Mode” on page 21-29 and table
21-1 on page 21-7.
-frc_calfile Force use of calibration data files even if the calibration file may
not be valid.
NOTE
This parameter allows you to run the test system uncalibrated. This may result in incorrect
testing of some devices. Production testing is disabled in this mode.
-inst Specifies the instrument. Valid instruments are:
-dc DC Subsystem
-tms Time Measurement Subsystem
-apu Analog Pin Unit/Advanced Analog Pin Unit
-asu Analog Sampling Unit
-deskew High Speed Digital Subsystem (mixed)
IMAGE Solutions V8.3 21-18
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
-hsd50 High Speed Digital Subsystem (ams)
-hpvi High Power V/I
-hva High Voltage Ammeter
-fvs Floating Voltage Source
-sps Synchronous Power Subsystem
-cdig Serial Bus Channel Card
-hfsamp High Speed Sampler
-lca Low Current Ammeter
-opamp Opamp channel Card
-plfdig Precision Low Frequency Digitizer
-plfsrc Precision Low Frequency Source
-pulse Pulse Driver
-vhfawg VHF Arbitrary Waveform Generator
-vhfcw VHF Continuous Wave Source
-uhfsrc UHF Source
-t_delay Trigger Walking Delay Generator
-ost Open/Shorts Tester
-ath Array Test Head
-supclk Superclock
-uwrecv Microwave Receiver
-tjd Time-Jitter Digitizer
-uwsrc Microwave Source
-uwport Microwave Port
-hfdig VHF Digitizer
-ovi Octal V/I Source
-vreg Voltage Regulation Front End
-tja Time-Jitter Analyzer
-qvs Quad Voltage Source
-dps Device Power Supply (QVS, HCPS)
-wf Waveform Instrument (BBAC, Turbo AC)
-gigadig GigaDig
NOTE
The HF Digitizer does not require calibration. The VHF Digitizer, which is programmed using
hfdig syntax, does require calibration.
cal_type Specifies the type of calibration for an instrument. Currently, only
the Precision Multimeter supports multiple types of calibration.
The PMM allows the following cal types:
acv dcv ohms
See “Precision Multimeter” on page 21-44.
-<inst> [cal_type] noautocal
Do not activate autocal for instrument inst or for cal_type.
IMAGE Solutions V8.3 21-19
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
When autocal is not enabled, you must handle calibration for that
instrument.
-<inst> [cal_type] ignore_cal
Ignore calibration for instrument inst or calibration type
cal_type. Allows you to load a test program without calibrating
a specified instrument.
NOTE
This parameter allows you to run the test system uncalibrated. This may result in incorrect
testing of some devices. Production testing is disabled in this mode.
-<inst> [cal_type] nocalfile
Do not use the calibration data files for instrument inst or for
cal_type. (See table 21-1 on page 21-7.)
-<inst> [cal_type] frc_calfile
Force use of calibration data files even if the calibration file may
not be valid for instrument inst or for cal_type.
NOTE
This parameter allows you to run the test system uncalibrated. This may result in incorrect
testing of some devices. Production testing is disabled in this mode.
Displaying an Autocal Report
To display a report on the state of calibration use the calibrate -report command. You
can also generate this report from a test program using the function tl_cal_report().
(See “tl_cal_report” on page 26-163 for more information.) Note that this report does not
reflect the state of calibration of all instruments in the test system, only those used in the
current test program.
The Autocal Report shows the following:
Autocal Mode Lists the autocal parameters currently in force for
autocalibration. Parameters include the following:
ON/OFF—Indicates whether autocal is on or off.
IGNORE/!IGNORE—Indicates whether autocal is ignored or not
ignored.
BEFORE/AFTER—Indicates whether autocal is performed before
or after the test program is run.
CALFILE/NOCALFILE—Indicates whether or not autocal uses
calibration files.
ALL/PINMAP_ONLY—Indicates whether autocal calibrates all
IMAGE Solutions V8.3 21-20
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
copies of instruments in the test system or only those used in the
pinmap.
Autocal State Shows the current state of autocal. Possible states include the
following:
CAL/UNCAL/OFF—Indicates whether instruments are calibrated,
uncalibrated, or autocal is off.
THIS_RUN/NOT—Indicates whether calibration was performed on
this run of the test program or not.
Inst_name Lists the instrument name.
Cal_type Lists the type of calibration for the instrument.
Inst Mode Shows autocal parameters currently in force for autocalibration
for the listed instrument. Parameters include the following:
ON/OFF—Indicates whether autocal is on or off for this
instrument.
IGNORE/!IGNORE—Indicates whether autocal is ignored or not
ignored for this instrument.
CALFILE/NOCALFILE—Indicates whether autocal uses
calibration files for this instrument.
FRC_CALFILE/!FRC_CALFILE—Indicates whether use of the cal
file is forced for this instrument.
Inst State Shows the current state of autocal for the listed instrument.
Possible states include the following:
CAL/UNCAL/OFF—Indicates whether the instrument is calibrated,
uncalibrated, or autocal is off.
THIS_RUN—Indicates that calibration was performed for this
instrument on this run of the test program.
Remaining Lists time, in seconds, before next calibration.
An example of an autocal report is as follows:
A U T O C A L R E P O R T
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Inst_name Cal_type Inst Mode Inst State Remaining
_________ ________ _________ __________ _________
dc ON CAL 13971/14400 secs
tms ON CAL 14336/14400 secs
hsd50 ON FRC_CALFILE UNCAL 0/1200 secs
Autocal Mode: ON PINMAP Autocal State: UNCAL
NOTE: Only differences from the default modes are shown. Defaults are:
insts: ON, !IGNORE, CALFILE, !FRC_CALFILE
autocal: ON, !IGNORE, BEFORE, CALFILE, !FRC_CALFILE, ALL
NOTE: HSD50 calibration criteria include temperature drift, power
supply drift, and hardware changes. These criteria are
IMAGE Solutions V8.3 21-21
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
checked at a specified time interval. Only that time
interval is displayed above.
The HSD50 note (which does not appear unless the HSD50 is used in the test program)
indicates that the HSD50 subsystem uses two levels of calibration criteria:
• Time before the next environment check (for temperature and power supply monitoring).
The default interval is 20 minutes.
• Times before calibration files expiring (a separate timer is monitored for each cal file).
The default interval is one year.
Only the first level criterion, time remaining before checking the calibration environment, is
shown in the calibration report.
Setting Calibration Modes
Calibration modes are the methods used by IMAGE to perform calibration. IMAGE includes
a number of functions you can use to set and change calibration modes.
Enabling and Disabling Autocal
To enable or disable the autocal utility from a test program, use the function:
tl_set_autocal_onoff(flag)
where flag can be 0 (off) or 1 (on). For example, to turn on autocal use:
tl_set_autocal_onoff(1)
Remember that when autocal is not enabled, you must handle calibration. (See
“tl_set_autocal_onoff” on page 26-347 for more information.)
To determine if autocal is on or off from a test program use the function:
tl_get_autocal_on()
This function returns TRUE if autocal is on, FALSE if off. (See “tl_get_autocal_on” on page
26-196 for more information.)
Setting Calibration Modes for Autocal
To set the mode for the autocal utility from a test program use the function:
tl_cal_set_autocal_mode(mode)
where mode can be any of the following:
TL_AUTOCAL_OFF/TL_AUTOCAL_ON
Turn autocal off or on. When autocal is not enabled, you must
handle calibration. The default is off.
TL_AUTOCAL_CAL_BEFORE/TL_AUTOCAL_CAL_AFTER
Invoke autocal before or after the test program executes. In
either case, autocal always occurs immediately after the test
IMAGE Solutions V8.3 21-22
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
program load completes (before execution of tl_init()).
Calibrating after execution may useful when using device
handlers or probers with environmental controls. The default is
before.
The flags TL_AUTOCAL_CAL_BEFORE and
TL_AUTOCAL_CAL_AFTER are mutually exclusive. Do not set
them both in the global autocal state.
TL_AUTOCAL_ALL_COPIES/TL_AUTOCAL_PINMAP_ONLY
Calibrate all copies of instruments for each instrument driver
linked into the current test program, or calibrate only those
copies used in the current pinmap. The default is to calibrate all
copies.
NOTE
The pinmap_only mode is available only for instruments which support calibration by
instance (see table 21-1 on page 21-7).
TL_AUTOCAL_CALFILE/TL_AUTOCAL_NO_CALFILE
Use or ignore all existing calibration data files. The default is to
use all cal files.
NOTE
The cal file mode is available only for instruments which support calibration files (see table
21-1 on page 21-7).
TL_AUTOCAL_FRC_CALFILE/TL_AUTOCAL_NO_FRC_CALFILE
Force or do not force use of calibration data files even if they are
not valid under current conditions. The default is to not force use
of cal files.
NOTE
This mode is available only for instruments which support forcing calibration files (see table
21-1 on page 21-7).
NOTE
Test system instrument specifications are not guaranteed when operating with calibration
files forced for any instrument.
IMAGE Solutions V8.3 21-23
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
NOTE
When the autocal utility is set to force calibration files, a warning message is printed to the
station window and to the datalog stream for every program execution. Production testing
is disabled.
TL_AUTOCAL_IGNORED/TL_AUTOCAL_NOT_IGNORED
Ignore calibration for any instruments using autocal, but allow all
instruments to be used as if they were calibrated. (That is, do not
stop the program with run time errors reporting that instruments
are not calibrated.) This is intended for use in engineering
situations and is not appropriate for production testing. The
default is to not ignore autocal.
NOTE
Test system instrument specifications are not guaranteed when operating with calibration
ignored for any instrument.
NOTE
When the autocal utility or any instrument is set to ignore calibration, a warning message is
printed to the station window and to the datalog stream after each program execution.
Production testing is disabled.
See “tl_cal_set_autocal_mode” on page 26-164 for more information.
Determining Autocal Modes for Autocal
To determine the mode for the autocal utility from a test program use the function:
tl_cal_get_autocal_mode()
This function returns the following modes:
TL_AUTOCAL_ON Autocal is on.
TL_AUTOCAL_OFF Autocal is off.
TL_AUTOCAL_IGNORED Error messages will be ignored.
TL_AUTOCAL_NOT_IGNORED
Error messages will not be ignored.
TL_AUTOCAL_CAL_BEFORE
Perform autocal before running test program.
IMAGE Solutions V8.3 21-24
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
TL_AUTOCAL_CAL_AFTER
Perform autocal after running test program.
TL_AUTOCAL_CALFILE Use the calfile.
TL_AUTOCAL_NO_CALFILE
Do not use the calfile.
TL_AUTOCAL_ALL_COPIES
Calibrate every copy of the instrument.
TL_AUTOCAL_PINMAP_ONLY
Calibrate only copies of the instrument defined in pinmap.
See “tl_cal_get_autocal_mode” on page 26-158 for more information.
Enabling and Disabling Autocal for an Instrument
To calibrate a specified instrument from a test program, use the function:
tl_cal_inst(inst, cal_type)
View choices for inst by typing calibrate -usage in the station window.
To force a specified instrument to be uncalibrated use the function:
tl_cal_set_uncal(inst, cal_type, onoff)
See “tl_cal_inst” on page 26-163 and “tl_cal_set_uncal” on page 26-167 for more
information.
In all functions, cal_type is the specific type of calibration for a particular instrument.
Currently, only the Precision Multimeter supports multiple types of calibration. (See
“Precision Multimeter” on page 21-44.) If an instrument has only one type of calibration, use
empty quotes ("") for its cal_type. For example:
tl_cal_inst("hsd50", "");
tl_cal_inst("pmm", "dcv");
Setting Autocal Modes for an Instrument
To set the autocal mode for an instrument from a test program use the function:
tl_cal_set_inst_mode(inst, cal_type, mode)
where mode can be any of the following:
TL_AUTOCAL_OFF/TL_AUTOCAL_ON
Turn autocal off or on for this instrument. When autocal is not
enabled, you must handle calibration for this instrument. The
default is off.
TL_AUTOCAL_CALFILE/TL_AUTOCAL_NO_CALFILE
Use or ignore all existing calibration data files for this instrument.
The default is to use the cal file.
IMAGE Solutions V8.3 21-25
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
TL_AUTOCAL_FRC_CALFILE/TL_AUTOCAL_NO_FRC_CALFILE
Force or do not force use of calibration data files for this
instrument even if they are not valid under current conditions.
The default is to not force use of cal files.
NOTE
This mode is available only for instruments which support forcing calibration files (see table
21-1 on page 21-7).
NOTE
Test system instrument specifications are not guaranteed when operating with calibration
files forced for any instrument.
NOTE
When any instrument is set to force calibration files, a warning message is printed to the
station window and to the datalog stream for every program execution. Production testing
is disabled.
TL_AUTOCAL_IGNORED/TL_AUTOCAL_NOT_IGNORED
Ignore calibration for this instrument using autocal, but allow the
instrument to be used as if it were calibrated. (That is, do not stop
the program with run time errors reporting that the instrument is
not calibrated.) This is intended for use in engineering situations
only and is not appropriate for production testing. The default is
to not ignore autocal.
NOTE
Test system instrument specifications are not guaranteed when operating with calibration
ignored for any instrument.
NOTE
When the autocal utility or any individual instrument is set to ignore calibration, a warning
message is printed to the station window and to the datalog stream for every program
execution. Production testing is disabled.
View choices for inst by typing calibrate -usage in the station window.
IMAGE Solutions V8.3 21-26
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
In all functions, cal_type is the specific type of calibration for a particular instrument.
Currently, only the Precision Multimeter supports multiple types of calibration. (See
“Precision Multimeter” on page 21-44.) If an instrument has only one type of calibration, use
empty quotes ("") for its cal_type. For example:
tl_cal_set_inst_mode("hsd50", "", TL_AUTOCAL_FRC_CALFILE);
See “tl_cal_set_inst_mode” on page 26-166 for more information.
Determining Autocal Modes for an Instrument
To determine the autocal mode for an instrument from a test program use the function:
tl_cal_get_inst_mode(inst, cal_type)
View choices for inst by typing calibrate -usage in the station window.
This function returns the following modes:
TL_AUTOCAL_ON Autocal is on.
TL_AUTOCAL_OFF Autocal is off.
TL_AUTOCAL_IGNORED Error messages will be ignored.
TL_AUTOCAL_NOT_IGNORED
Error messages will not be ignored.
TL_AUTOCAL_CALFILE Use calfile.
TL_AUTOCAL_NO_CALFILE
Do not use calfile.
In all functions, cal_type is the specific type of calibration for a particular instrument.
Currently, only the Precision Multimeter supports multiple types of calibration. (See
“Precision Multimeter” on page 21-44.) If an instrument has only one type of calibration, use
empty quotes ("") for its cal_type. For example:
tl_cal_get_inst_mode("hsd50", "");
See “tl_cal_get_inst_mode” on page 26-160 for more information.
Determining Calibration States
The calibration state is whether the test system, or any instrument, is calibrated or
uncalibrated or calibration is invalid. The calibration state can also tell you if calibration was
performed during the current run of the program.
To determine the state of autocal from a test program use the function:
tl_cal_get_autocal_state()
To determine the calibration state of an instrument from a test program use the function:
tl_cal_get_inst_state(inst, cal_type)
IMAGE Solutions V8.3 21-27
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
Both these functions return the following flags indicating calibration state:
TL_AUTOCAL_CALIBRATED/TL_AUTOCAL_UNCALIBRATED
If calibration has failed or has never been run, the state is
uncalibrated.
TL_AUTOCAL_INVALID If autocal was attempted but the required hardware is not
present, the state of calibration for that instrument is both
uncalibrated and invalid.
NOTE
Global autocal state (that is, autocalibration for all instruments) cannot be invalid.
TL_AUTOCAL_THIS_RUN
For “pre-run” autocalibration (autocal mode is set to
TL_AUTOCAL_CAL_BEFORE), it indicates that calibration occurred
at the beginning of the run.
For “post-run” autocalibration (autocal mode is set to
TL_AUTOCAL_CAL_AFTER), it indicates that calibration occurred
at the end of the last run.
NOTE
For the special case of the first run after a load, TL_AUTOCAL_THIS_RUN is flagged in “post-
run” autocalibration and is not flagged in “pre-run” autocalibration.
Essentially, having TL_AUTOCAL_THIS_RUN flagged means that
when autocalibration last checked to see if calibration was
necessary, a calibration occurred. Not having
TL_AUTOCAL_THIS_RUN flagged means that calibration did not
occur when autocalibration last checked. Autocalibration checks
occur only once per run to update the instrument state.
Both functions to get autocal states (tl_cal_get_autocal_state() and
tl_cal_get_inst_state(inst, cal_type)) return bit vectors. Thus, to test if a condition
TL_AUTOCAL_XXX holds, use a bit-wise AND. For example:
if (tl_cal_get_autocal_state() & TL_AUTOCAL_XXX) {
// do special action when state XXX is detected //
}
In all functions, cal_type is the specific type of calibration for a particular instrument.
Currently, only the Precision Multimeter supports multiple types of calibration. (See
“Precision Multimeter” on page 21-44.) If an instrument has only one type of calibration, use
empty quotes ("") for its cal_type. For example:
tl_cal_get_autocal_state("hsd50", "");
IMAGE Solutions V8.3 21-28
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
See “tl_cal_get_autocal_state” on page 26-159 and “tl_cal_get_inst_state” on page 26-162
for more information.
Setting Calibration Criteria
The following functions allow you to set or determine calibration criteria (time or
temperature) for an instrument:
tl_cal_set_inst_crit(inst, cal_type, crit, units)
Change autocal criteria.
tl_cal_get_inst_crit(inst, cal_type, crit)
Get autocal criteria for instrument.
tl_cal_get_remaining(inst, cal_type)
Get remaining time or temperature until calibration is required.
NOTE
Modifying the default calibration criteria for any test system instrument invalidates the
specifications of that instrument.
View choices for inst by typing calibrate -usage in the station window.
For example, to change the time interval for DC calibration you could use:
tl_cal_set_inst_crit("dc", "", 6*60*60.0, TL_AUTOCAL_TIME)
This function would reset the dc calibration time interval to six hours. TL_AUTOCAL_TIME and
TL_AUTOCAL_TEMP define the type of calibration criteria (time or temperature).
In all functions, cal_type is the specific type of calibration for a particular instrument.
Currently, only the Precision Multimeter supports multiple types of calibration. (See
“Precision Multimeter” on page 21-44.) If an instrument has only one type of calibration, use
empty quotes ("") for its cal_type.
See “tl_cal_set_inst_crit” on page 26-166, “tl_cal_get_inst_crit” on page 26-160, and
“tl_cal_get_remaining” on page 26-163 for more information.
Pinmap Only Mode
If the calibration resource is in pinmap_only mode, only those instances of instruments
referenced in the pinmap are calibrated (where applicable). For example, if a test system
has four PLFDIGs, but a particular program uses only two of the instances and these are
pin programmed, only these two instances would be calibrated by autocal. This distinction
is not possible for all test system instruments (the DC subsystem and the APUs are
examples). See table 21-1 on page 21-7.
IMAGE Solutions V8.3 21-29
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
To use pinmap_only mode effectively, include all instruments used in your test program in
your pinmap, even resources (such as TMS) that may not normally be listed. You can use
dummy pins or the uses pinmap statement to do this.
Note that the PLFDIG requires the PLFSRC to be calibrated. (See the calibration
dependencies in table 21-1 on page 21-7.) Furthermore, if the PLFDIG is used in the pinmap
and the PLFSRC is not, the PLFDIG will not calibrate properly when using pinmap_only
mode. The PLFSRC must be mentioned in the pinmap (even if it is not being used).
Disabling a Handler or Prober
By default, if autocal attempts to calibrate a test system instrument and calibration of that
instrument fails, the test program executes and a run time error is generated when that
uncalibrated test system instrument is used. In production testing, if the calibration of that
instrument were to continuously fail, parts would continue to be binned to the error bin.
Use the following functions to control disabling of handlers and probers when runtime errors
occur:
tl_disable_hp_after_rte_on()
Turn on autodisable of handler or prober on a runtime error.
tl_disable_hp_after_rte_off()
Turn off autodisable of handler or prober.
tl_disable_hp_after_rte_state()
Return the autodisable state of handler or prober.
See “Disabling a Handler or Prober for a Runtime Error” on page 1-45 in the Handler/Prober
Manual for more information.
Setting the Calibration Interval
For added flexibility, you can set the calibration interval from a test programs using one of
the following functions when using autocal:
extern void tl_apu_cal_set_interval();
Sets the calibration interval for Advanced Analog Pin Units.
Default interval is four hours. (See “tl_apu_cal_set_interval” on
page 26-147.)
extern void tl_cdig_set_cal_interval();
Sets the calibration interval for the Serial Bus Channel Card.
Default interval is 30 days. (See “tl_cdig_set_cal_interval” on
page 26-168.)
extern void tl_dc_cal_set_interval();
Sets the calibration interval for the DC Subsystem. Default
interval is four hours. (See “tl_dc_cal_set_interval” on page
26-178.)
IMAGE Solutions V8.3 21-30
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
extern void tl_hfsc_set_ramp_cal_duration();
Sets the calibration interval for the High Speed Sampler. Default
interval is four hours. (See “tl_hfsc_set_ramp_cal_duration” on
page 67-134 in the Catalyst Instrumentation Manual.)
extern void tl_hsd50_set_cal_interval();
Sets the calibration interval for the advanced mixed-signal
Catalyst Digital Subsystem. It can set either the environment
check interval (default = 20 minutes) or the length of time the cal
file will be valid (default = 1 year). This function requires two
parameters passed to it for it to work. See “Catalyst Functions”
on page 67-1 in the Catalyst Instrumentation Manual for more
information.
extern void tl_plfd_cal_interval();
Sets the calibration interval for the Precision Low Frequency
Digitizer. Default interval is four hours. (See “tl_plfd_cal_interval”
on page 26-306.)
extern void tl_plfs_cal_interval();
Sets the calibration interval for the Precision Low Frequency
Source. Default interval is four hours. (See “tl_plfs_cal_interval”
on page 26-306.)
extern void tl_tms_cal_set_interval();
Sets the calibration interval for the Advanced Time
Measurement Subsystem. Default interval is four hours. (See
“tl_tms_cal_set_interval” on page 26-420.)
extern void tl_uhfsrc_cal_interval();
Sets the calibration interval for the Microwave Source. Default
interval is four hours. (See “tl_uhfsrc_cal_interval” on page
26-428.)
extern void tl_uwrecv_cal_interval()
Sets the calibration interval for the Microwave Receiver. Default
interval is one hour.
extern void tl_vhfawg_cal_interval();
Sets the calibration interval for the Very High Frequency
Arbitrary Waveform Generator. The default interval is 20 minutes
(time between temperature checks, not necessarily calibrations).
(See “tl_vhfawg_cal_interval” on page 26-495.)
extern void tl_vhfcw_cal_interval();
Sets the calibration interval for the Very High Frequency
Continuous Wave Source. Default interval is four hours. (See
“tl_vhfcw_cal_interval” on page 26-502.)
To change the recalibration interval from the default to some other time interval (for
example, 24 hours), use the following function:
IMAGE Solutions V8.3 21-31
IMAGE Base Language: Calibration: Controlling Calibration
Table of Contents Index Home Master Index Search Help
extern void tl_wf_cal_time_interval();
Sets the calibration interval for the wf instruments: BBACCAP,
BBACSRC, Turbo AC Source, and Turbo AC Capture. Default
interval is 30 days.
These functions take one parameter—the number of seconds (an integer) of the calibration
interval. For example, to set the interval for DC Subsystem calibration to five hours instead
of four, use:
extern void tl_dc_cal_set_interval();
tl_dc_cal_set_interval(60*60*5);
The exception is tl_hsd50_set_cal_interval() which takes two parameters.
These functions are not required for normal use. Use them only in special circumstances.
NOTE
Calibration interval defaults are set to the maximum recommended time for each
instrument. Increasing this time may violate calibration.
NOTE
Use of cron with calibration commands is not recommended.
IMAGE Solutions V8.3 21-32
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
Manual Calibration Using the calibrate Command
The calibrate command (entered in a station window) allows you to calibrate various
tester subsystems and to control calibration. The calibrate command syntax is as follows:
calibrate [-station #] [-noautocal | -autocal] [-ignore_cal | -noignore_cal]
[-cal_after | -cal_before] [-nocalfile | -calfile]
[-frc_calfile | -nofrc_calfile]
[-all_copies | -pinmap_only] [-report]
calibrate [-station #] -<inst> [cal_type] [autocal | noautocal]
[-station #] -<inst> [cal_type] [ignore_cal | noignore_cal]
[-station #] -<inst> [cal_type] [calfile | nocalfile]
[-station #] -<inst> [cal_type] [frc_calfile | nofrc_calfile]
calibrate [-station #] -dc [file | verbose]
calibrate [-station #] -tms
calibrate [-station #] -apu
calibrate [-station #] -asu [file | verbose]
calibrate [-station #] -pmm dcv acv ohms
calibrate -deskew
calibrate [-station #] -hsd50
calibrate [-station #] -hsd
calibrate [-station #] -hpvi
calibrate [-station #] -hva
calibrate [-station #] -fvs
calibrate [-station #] -sps
calibrate [-station #] -cdig
calibrate [-station #] -hfsamp
calibrate [-station #] -lca [file | verbose]
calibrate [-station #] -opamp [file | verbose]
calibrate [-station #] -plfdig
calibrate [-station #] -plfsrc
calibrate [-station #] -pvmeter
calibrate [-station #] -pvsrc pvsrc1 pvsrc2
calibrate [-station #] -pulse [file | verbose]
calibrate [-station #] -vhfawg
calibrate [-station #] -vhfcw
calibrate [-station #] -uhfsrc
calibrate [-station #] -t_delay
calibrate [-station #] -ost
calibrate [-station #] -ath
calibrate [-station #] -supclk
calibrate [-station #] -uwrecv
calibrate [-station #] -tjd
calibrate [-station #] -uwsrc
calibrate [-station #] -uwport
calibrate [-station #] -hfdig
calibrate [-station #] -diu
calibrate [-station #] -ovi
calibrate [-station #] -vreg
calibrate [-station #] -tja
IMAGE Solutions V8.3 21-33
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
calibrate [-station #] -ecms [file | verbose]
calibrate [-station #] -qvs
calibrate [-station #] -dps
calibrate [-station #] -wf [file | verbose]
calibrate [-station #] -gigadig
NOTE
The HF Digitizer does not require calibration. The VHF Digitizer, which is programmed using
hfdig syntax, does require calibration.
where:
inst Specifies an instrument. Not all instruments are available on all
test systems.
cal_type Specifies the type of calibration for an instrument. Currently, only
the Precision Multimeter supports multiple types of calibration.
The PMM allows the following cal types:
acv dcv ohms
See “Precision Multimeter” on page 21-44.
-noautocal | -autocal
Turn autocal off or on. When autocal is not enabled, you must
handle calibration. The default is off.
-ignore_cal | -noignore_cal
Ignore calibration for this instrument using autocal, but allow the
instrument to be used as if it were calibrated (that is, do not stop
the program with run time errors reporting that the instrument is
not calibrated). This is intended for use in engineering situations
only and is not appropriate for production testing. The default is
to not ignore autocal.
NOTE
Test system instrument specifications are not guaranteed when operating with calibration
ignored for any instrument.
NOTE
When the autocal utility or any individual instrument is set to ignore calibration, a warning
message is printed to the station window and to the datalog stream for every program
execution. Production testing is disabled.
IMAGE Solutions V8.3 21-34
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
-cal_after | -cal_before
Invoke autocal before or after the test program executes. In
either case, autocal always occurs immediately after the test
program load completes. Calibrating after execution may be
useful when using device handlers or probers with
environmental controls and temperatures can be held only for a
limited time. The default is before.
-nocalfile | -calfile
Use or ignore all existing calibration data files. The default is to
ignore all cal files. (See table 21-1 on page 21-7.)
-frc_calfile | -nofrc_calfile
Force or do not force use of calibration data files even if the
calibration file may not be valid. The default is to not force use of
cal files.
NOTE
This parameter allows you to run the test system uncalibrated. This may result in incorrect
testing of some devices. Production testing is disabled in this mode.
-all_copies | -pinmap_only
Calibrate all copies of instruments for each instrument driver
linked into the current test program, or calibrate only those
copies used in the current pinmap. The default is to calibrate all
copies.
NOTE
The pinmap_only mode is available only for instruments which support calibration by
instance (see table 21-1 on page 21-7).
-report Print a report on the state of calibration. (See “Enabling and
Disabling Autocal” on page 21-22.)
station # Specifies a station number.
Once the calibration process starts, calibration status messages and results (passed, failed,
or aborted) are displayed in the current station window (or the station window specified
using the -station # option).
Note that calibration of an instrument can only occur if a statement for that instrument occurs
in a test program. Therefore, a test program containing instrument statements must be
loaded for that instrument to be calibrated.
IMAGE Solutions V8.3 21-35
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
NOTE
If your test program includes any calibration statements, and you load the program under
autocal, IMAGE calibrates the test system or instrument twice.
Advanced Analog Pin Unit
Calibrate Advanced Analog Pin Units (AAPUs) manually using the command:
calibrate [-station #] -apu
where:
-station # Specifies the test station for calibration.
-apu Trigger switch for APU or AAPU calibration.
This command calibrates all APUs or AAPUs in the test system.
You can also calibrate APUs and AAPUs from a test program using the statement:
start apu cal;
The following function returns the number of minutes since the last APU or AAPU
calibration:
int tl_apucal_time()
Broadband AC, Turbo AC
Calibrate BBAC and Turbo AC instruments (BBACCAP, BBACSRC, Turbo AC Capture,
Turbo AC Source) manually using the command:
calibrate <-station #> -wf
where:
-station Specifies the station number.
To calibrate all WF (BBAC, Turbo AC) instruments in the test system, include the following
statement in the test program:
start wf: cal;
To calibrate specific instruments by the slot and slot channel in a test program, use:
start slot= <int_var> schan= <int_var> wf:cal;
To calibrate a specific pin or a pin list use:
start pin= <int_var> wf:cal;
IMAGE Solutions V8.3 21-36
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
Catalyst Digital Subsystem
Catalyst digital calibration adjusts levels and timing to meet test system specifications.
Calibration data for the test system are updated after each calibration. During
autocalibration, the calibration control variables are temporarily set to the values used
during execution of a calibration set (cal_set).
A cal_set specifies conditions under which calibration will occur. You can specify multiple
cal_sets, but only one cal_set can be active at a time. cal_sets are required because
the calibration constants (stored in a calfile in /image/tester/<host_name>/cal/
hsd50_<test program name>_<set name>_h<head>_cal.log.Z) can change depending
on the conditions of the calibration, for example if the power supply range or the levels are
changed. cal_sets also allow you to achieve greater accuracy by specifying calibration
parameters that correspond to your testing conditions. See “The Calibration File” on page
33-12 for more information about the files in which cal_set information is stored.
You must define cal_sets before a calibration can run. At a minimum, a cal_set must
specify a cal_set name and a power supply range. All other parameters have default
values which are used if not specified. The following shows the syntax for a cal_set:
set hsd cal_set = "<setname>"
vrange: <high | middle | low>
[ppmu_vsys = <value>]
dut: open | close
pin = (1 to 384)
dchan = (chanlist)
vih = 2.5v
vil = 0.5
voh = 2.5
vol = 0.5
ioh = -10ma
iol = 25ma
vcp = 2.5v
vcl = <rangelimit>
vch = <rangelimit>
dut: open | close
ppmu_v_force = 0.5
ppmu_v_meter = 0.5
ppmu_i_force_2ma = 2ma
ppmu_i_force_200ua = 200ua
ppmu_i_force_20ua = 20ua
ppmu_i_meter_2ma = 2ma
ppmu_i_meter_200ua = 200ua
ppmu_i_meter_2ua = 2ua
ppmu_i_meter_200na = 200na
target = 50
...;
Note that multiple pins or pin groups can be specified with different parameters in the same
cal_set. Pins not listed are not calibrated.
You can start calibration using the following keyboard command:
IMAGE Solutions V8.3 21-37
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
calibrate -hsd
Typing this command immediately forces calibration of all defined cal_sets. If no cal_sets
are defined, calibration exits without doing anything.
Calibration can be controlled completely by the test program. You can turn off autocal and
use your own set of conditions to determine when to run calibration. These conditions can
include:
• First run of the test program
• Any specified mainframe or test head temperature change
• Any specified power supply change
• Any specified time interval
• Any other condition appropriate for the test program and device under test
When the specified conditions are met, the test program executes a statement which
invalidates the calibration. Like autocal, this does not cause calibration to run. Calibration
begins when the start hsd calibration statement in the test program executes.
See “Calibrating the Digital Subsystem” on page 32-36 in the Catalyst Instrumentation
Manual for more information.
DC Subsystem
Calibrate the DC Subsystem, including all present sources, voltmeter, and DUT sources,
manually using the command:
calibrate [-station #] -dc [file | verbose]
where:
-station # Specifies the test station for calibration.
-dc Switch for DC calibration.
file Sends a detailed summary of the calibration to a log file, date
and time stamped, in the following directory:
/image/tester/<hostname of tester computer>
/dccal_log_<DATE:HR:MN>
verbose Sends a detailed summary of the calibration to the station
window.
This command also calibrates any HCUs in the test system.
As calibration proceeds, messages are displayed on the status of calibration, including:
• Source currently being calibrated
• Reference card serial number
• Date of last calibration of the DC reference
• Result of calibration (passed, failed, or aborted)
IMAGE Solutions V8.3 21-38
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
Messages are shown in the current station window or in the station window specified using
the -station # option. An example of calibration output is:
% calibrate -dc
Starting calibration of the DC sources
Data Retention Verified
Reference serial number 851721
Last reference calibration on Sept. 12, 1989
Calibrating Voltmeter
Calibrating Source 1
Calibrating Source 2
Calibrating Source 3
Calibrating Source 4
Calibrating Source 5
Calibrating Dut Source 1
Calibrating Dut Source 2
Calibrating Dut Source 3
Calibrating Dut Source 4
Calibration complete
DC source calibration complete
Calibration in the Debug Display
The calibration status, including the date and time of the last calibration, is also shown in
the DC Subsystem debug display. If a source failed the last calibration, a double asterisk
(**) appears after the information line for that source in the display.
Calibration Functions
IMAGE includes several functions related to DC Subsystem calibration. One of these,
tl_dccal_subr(0), allows you to initiate calibration from a test program. Additional
functions are as follows:
tl_dc_cal_set_interval()
Sets the autocalibration interval (see “Calibration Theory of
Operation” on page 21-3).
tl_dccal_status(inst)
Returns the calibration status of each DC Subsystem instrument
(see page 26-179).
tl_dccal_time() Reads the time since the last calibration and the calibration
status (see page 26-180).
For additional information on DC Subsystem calibration see the DC Subsystem section of
the instrumentation manual appropriate for your tester.
GigaDig
To calibrate the GigaDig from the command line, use the following command:
IMAGE Solutions V8.3 21-39
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
calibrate [-station #] [-pinmap_only] -gigadig
To calibrate manually from inside a test program use:
start /* calibrate a single GigaDig */
pin= /* pin = <pin_spec> | <slot_spec> | <dib_spec> */
gigadig: cal
;
start /* calibrate all GigaDig instruments */
gigadig: cal
;
High Current Power Supply
Calibrate the High Current Power Supply (HCPS) using the following command:
calibrate -dps
In a test program, you can include:
start pin = <pin_name> dps: cal;
start dps: cal;
High Speed Sampler
You can initiate ramp calibration for the High Speed Sampler using the command:
calibrate [-station #] -hfsamp
where:
-station # Specifies the test station for calibration.
-hva Switch for High Speed Sampler calibration.
NOTE
You must calibrate the Time Measurement Subsystem and the DC Subsystem before
calibrating the High Speed Sampler.
You can also initiate ramp calibration using the function call:
tl_hfsc_ramp_cal();
It takes tl_hfsc_ramp_cal() about seven seconds to finish. To maintain accuracy,
recalibrate the sampler every four hours.
Low Current Ammeter
To calibrate all Low Current Ammeters in the test system manually, use the command:
IMAGE Solutions V8.3 21-40
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
calibrate [-station #] -lca [file | verbose]
where:
-station # Specifies the test station for calibration.
-lca Switch for LCA calibration.
file Sends a detailed summary of the calibration to a log file, date
and time stamped, in the directory:
/image/tester/<hostname of tester computer>
/lca_log_<DATE:HR:MN>
verbose Sends a detailed summary of the calibration to the station
window.
You can also calibrate an LCA from within a test program. To calibrate all LCAs, execute
the following ITL statement:
start lca: cal;
To calibrate a specific LCA, use:
start pin=1 lca: cal;
IMAGE provides the following function to return LCA calibration status:
int slot=14;
int status;
.
.
status = tl_lcacal_status(slot);
Where slot is an integer and is the test head slot number of the LCA. This function returns
the calibration status of the LCA specified as follows:
0 LCA calibration passed.
-1 LCA calibration failed.
5 LCA calibration invalid.
Microwave Port
To calibrate the Microwave Port (UWPORT) in the test system manually, use the command:
calibrate [-station #] -uwport
where:
-station # Specifies the test station for calibration.
-uwport Trigger switch for UWPORT calibration.
IMAGE Solutions V8.3 21-41
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
Microwave Receiver
To calibrate the Microwave Receiver in the test system manually, use the command:
calibrate [-station #] -uwrecv
-station # Specifies the test station for calibration.
-uwrecv Switch for UWRECVV calibration.
You can also calibrate a UWRECV from within a test program. To to calibrate all UWRECVs
in the test system regardless of the last calibration, execute the following ITL statement:
start uwrecv: cal;
To calibrate a specific UWRECV, use:
start pin=<pin_spec> uwrecv: cal;
Microwave Source
To calibrate all Microwave Sources (UWSRCs) in the test system manually, use the
command:
calibrate [-station #] -uwsrc
where:
-station # Specifies the test station for calibration.
-uwsrc Trigger switch for UWSRC calibration.
You can have your test program calibrate the UWSRC using the following statements.
These statements calibrate the UWSRC every time the test program runs.
To calibrate the UWSRC assigned to the pin in <pin ID>, use:
start pin=<pin ID> uwsrc: cal;
The default UWSRC for a pin is the UWSRC assigned to the pin as a channel in the pinmap.
The statement shown above calibrates the specified UWSRC regardless of the last
calibration. To calibrate all UWSRCs in the test system regardless of the last calibration, use
the following statement:
start uwsrc: cal;
Octal VI Source
Use the following syntax to calibrate the OVI Source.
To calibrate every OVI source in the test system, use either of the following:
start ovi cal;
To calibrate each OVI source in OVI_LIST, use:
IMAGE Solutions V8.3 21-42
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
start ovi=<OVI_LIST>cal;
To calibrate the OVI source behind each pin in PIN_LIST, use:
start pin=<PIN_LIST>ovi:cal;
To calibrate OVI sources from the command line, use:
calibrate -ovi
Precision Low Frequency Digitizer
To calibrate the Precision Low Frequency Digitizer (PLFDIG) manually, use the command:
calibrate [-station #] -plfdig
where:
-station # Specifies the test station for calibration.
-plfdig Switch for PLFDIG calibration.
You can also calibrate a PLFDIG from within a test program. To calibrate all PLFDIGs in the
test system, execute the following ITL statement:
start plfdig: cal;
To calibrate a specific PLFDIG, use:
start pin=<pin_spec> plfdig: cal;
Precision Low Frequency Source
To calibrate the Precision Low Frequency Source (PLFSRC) manually, use the command:
calibrate [-station #] -plfsrc
where:
-station # Specifies the test station for calibration.
-plfsrc Switch for PLFSRC calibration.
You can also calibrate the PLFSRC from within a test program. Start calibration using the
following statements:
start <pin ID> plfsrc: cal;
start plfsrc:cal;
where:
<pin ID> Is a constant, a pin number, a pin name, a pin list, a variable, or
a field.
IMAGE Solutions V8.3 21-43
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
Precision Multimeter
To ensure that the Precision Multimeter (PMM) meets its rated accuracy specifications, it
must be calibrated regularly. (See the PMM section of the instrumentation manual
appropriate for your tester.) Calibrate the PMM using:
calibrate [-station #] -pmm dcv acv ohms
where:
-station # Specifies the test station for calibration.
-pmm Perform calibration of all the PMM modes. This calibration takes
12 minutes.
dcv Perform calibration on the DC voltage modes of the PMM. This
calibration takes 2.2 minutes.
acv Perform calibration on the AC voltage modes of the PMM. This
calibration takes 1.1 minutes.
ohms Perform calibration on the resistance modes of the PMM. This
calibration takes 11 minutes.
You can specify more than one flag on the command line.
NOTE
Do not interrupt calibration using Control-C. Interrupting calibration returns control to you,
but the PMM will not be calibrated.
You can also calibrate the PMM from within your test program. Use the set pmm cal_mode
statement to tell the PMM which self-calibration routine or routines to run:
set pmm cal_mode: dc; /* run the DCV routine */
set pmm cal_mode: ac; /* run the ACV routine */
set pmm cal_mode: ohms; /* run the OHMS routine */
set pmm cal_mode: (dc ac); /* run DCV and ACV */
set pmm cal_mode: all; /* run all the routines */
You can specify a combination of routines by enclosing them within parentheses separated
by spaces, as in:
set pmm cal_mode: (dc ac); /* run DCV and ACV */
Then use the set pmm cal statement to tell PMM when to run the self-calibration routines
you selected. The choices are:
set pmm cal:off; Do not run PMM self-calibration routines.
set pmm cal:once; Run PMM self-calibration routines each time a set pmm
statement is executed.
IMAGE Solutions V8.3 21-44
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
set pmm cal:on; Automatically check at the start of each test program run to see
if PMM self-calibration routines are required. (Not currently
supported.)
Normally, PMM self-calibration information is bundled into a single set pmm statement, such
as:
set pmm
cal_mode: all
cal: once;
Calibrate the meter when absolute accuracy is necessary. Calibrate all PMM modes once
every 24 hours. Use the function tl_pmm_dump_cal_times to determine the time of the last
calibration was run for dc, ac, and ohms.
Pulse Driver
To calibrate all Pulse Driver channel cards manually, use the command:
calibrate [-station #] -pulse [file | verbose]
where:
-station # Specifies the test station for calibration.
-pulse Trigger switch for Pulse Driver calibration.
file Sends a detailed summary of the calibration to a log file, date
and time stamped, in the directory:
/image/tester/<hostname of tester computer>
/pulse_log_<DATE:HR:MN>
verbose Sends a detailed summary of the calibration to the station
window.
Pulse Driver calibration occurs immediately after you enter this command.
You can also calibrate the Pulse Driver from within a test program. The statement for
calibrating a specific Pulse Driver channel card is:
start pin=<pin ID> pulse: cal;
The statement for calibrating all Pulse Driver channel cards is:
start pulse: cal;
Quad Voltage Source
To calibrate the QVS from the command window, use:
calibrate -dps
To calibrate every QVS in the test system from a test program, use the statement:
start dps cal;
IMAGE Solutions V8.3 21-45
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
To calibrate the QVS behind each pin in PIN_LIST, use the statement:
start pin=(PIN_LIST) dps:cal;
Serial Bus Channel Card
To calibrate the Serial Bus channel card (SBCC) manually, use the command:
calibrate [-station #] -cdig
where:
-station # Specifies the test station for calibration.
-cdig Trigger switch for SBCC calibration.
You can also use the following statement in your test program or in the Immediate window
to calibrate all SBCCs in the test system:
start cdig: cal;
During calibration, event line channels used to construct the sandcastle waveforms are
calibrated both as event line channels and as sandcastle channels and the calibration
constants stored. When you use the event line channels to construct sandcastle waveforms,
use the sandcastle calibration for those event line channels. The following statement selects
the sandcastle or the event line calibration:
set pin=<pin_spec> cdig:
calibration: sandcastle | event_line ;
where:
pin_spec Is the pin connected to the channel that you want to set.
NOTE
By default, event line channel calibration is used even when the event line channel is used
for sandcastle output unless you specify sandcastle in the calibration statement.
Time Jitter Analyzer
Calibrate the Time Jitter analyzer (TJA) using the following command:
calibrate [-station #] -tja
Time-Jitter Digitizer
The Time-Jitter Digitizer (TJD) is calibrated for:
• Offset between time stamper A and time stamper B
• Interpolator linearity
IMAGE Solutions V8.3 21-46
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
• TJD clock period
To calibrate the TJD manually, use the following command:
calibrate [-station #] -tjd
To calibrate the TJD from a test program use:
start pin = <pin_spec> tjd: cal;
To calibrate all TJDs in the test head from a test program use:
start tjd: cal;
Advanced Time Measurement Subsystem
You must run DC Subsystem calibration before calibrating the Advanced Time
Measurement Subsystem (ATMS). Calibrate the ATMS manually using the command:
calibrate [-station#] -tms
where:
-station # Specifies the test station for calibration.
-tms Trigger switch for ATMS calibration.
This command calibrates:
• The interpolators
• The local clock
• The threshold D/A converters
• The input skew
As the calibration routine executes, messages such as the following are displayed:
Calibrating TMS
Calibration Complete
You can perform full calibration on the ATMS from within a test program using the
statement:
start tms: cal_full;
To calibrate only the interpolators and local clock use:
start tms: cal;
If calibration fails, you must recalibrate or initialize your test system. To initialize your test
system, select INITIALIZE from the IMAGE Workspace menu or type initialize in a station
window. This command returns all ATMS calibration values to their defaults.
Calibration Priority
The mainframe portion of ATMS calibration (interpolators and local clock) uses a set of
priorities to decide when to perform calibration. The mixed-signal test head version of the
IMAGE Solutions V8.3 21-47
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
ATMS mainframe calibration has highest priority, the advanced linear head version has
second priority, and the linear version has lowest priority.
For example, assume a tester is configured such that station 1 is a linear station, station 2
is an advanced linear station, and station 3 is a mixed-signal station. You load a test
program in each station using the -autocal option. You run the program on station 1,
causing TMS mainframe calibration to run completely. You then run the program on stations
2 and 3, and mainframe calibration is executed in each case.
Assume now that the allotted time between calibrations expires. If you run a program, TMS
mainframe calibration is run. Say that program was for the advanced linear head. If you then
run a program on the mixed-signal head, mainframe calibration runs again because the
mixed-signal head has the highest priority. If you run a linear program after the mixed-signal
program, however, and the time interval for autocalibration has not expired, mainframe
calibration will not run. This is because the mixed-signal mainframe calibration just ran, and
it has higher priority.
Overwrite of tsets During Calibration
Note that when ATMS calibration occurs on a mixed-signal tester it overwrites some of tset
1. Therefore, you must reprogram tset timing data after ATMS calibration.
IMAGE V5.4 and later includes the flag tl_tms_cal_has_run(). This function returns a
value of 1 the first time this flag is read after ATMS calibration. Otherwise, the flag is
assigned a value of 0. You can use this flag to conditionally reprogram your timing only
when necessary.
In IMAGE V5.5 and later, this problem is fixed and the tsets are restored.
Trigger Walking Delay Generator
To calibrate the Trigger Walking Delay Generator manually, use the command:
calibrate [-station #] -t_delay
where:
-station # Specifies the test station for calibration.
-t_delay Trigger switch for Trigger Walking Delay Generator calibration.
The following function call calibrates the Trigger Walking Delay Generator:
tl_t_delay_cal_all();
Very High Frequency Arbitrary Waveform Generator
To calibrate all Very High Frequency Arbitrary Waveform Generators (VHFAWGs)
manually, use the command:
calibrate [-station #] -vhfawg
IMAGE Solutions V8.3 21-48
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
where:
-station # Specifies the test station for calibration.
-vhfawg Trigger switch for VHFAWG calibration.
Use the following statement in your test program to calibrate all VHFAWGs in the test
system:
start vhfawg: cal;
Use the following statement in your test program to calibrate a specified VHFAWG in the
test system. pin_spec is the pin connected to the VHFAWG you want to calibrate. The
default VHFAWG for a pin is the VHFAWG assigned to the pin as a channel in the pinmap.
start pin=<pin_spec> vhfawg: cal;
Very High Frequency Continuous Wave Source
To calibrate the Very High Frequency Continuous Wave Source (VHFCW) manually, use
the command:
calibrate [-station #] -vhfcw
where:
-station # Specifies the test station for calibration.
-vhfcw Switch for VHFCW calibration.
(See “Calibrating the VHFCW Source” in the Catalyst Instrumentation Manual.)
You can also calibrate the VHFCW from within a test program. Start calibration using:
start pin = <pin ID> vhfcw: cal;
This statement starts calibration for the default VHFCW source assigned to each pin in the
<pin ID>. The default VHFCW source for a pin is the VHFCW source assigned to the pin
as a channel in the pinmap.
start vhfcw: cal;
This statement starts calibration for all VHFCW sources in the test head.
where:
<pin ID> Is a constant, a pin number, a pin name, a pin list, a variable, or
a field which has the above named channel cards and functional
channel declared behind the pin.
slot Identifies a channel card by identifying the test head slot it
resides in.
schan Identifies a channel for the instrument located in slot=<int>.
Use schan=1 for vhfcw_dir and schan=2 for vhfcw_alt.
IMAGE Solutions V8.3 21-49
IMAGE Base Language: Calibration: Manual Calibration Using the calibrate Command
Table of Contents Index Home Master Index Search Help
Voltage Regulation Front End
To calibrate all VREG channel cards manually, use the command:
calibrate [-station #] -vreg
where:
-station # Specifies the test station for calibration.
-vreg Switch for VREG calibration.
You can also calibrate VREG from within a test program. To calibrate all VREGs, execute
the following ITL statement:
tl_cal_inst("vreg", "");
IMAGE Solutions V8.3 21-50
IMAGE Base Language: Calibration: Autocal Examples
Table of Contents Index Home Master Index Search Help
Autocal Examples
The following are two autocal examples.
Loading With and Without Autocal
To illustrate the effect of using autocal, say you use the following test program called
autocal.tl:
/* Standard header files */
#include <stdio.h>
#include <math.h>
#include <image.h>
tl_init()
{
tl_cal_set_inst_crit("dc", "", 20.0, TL_AUTOCAL_TIME); /* 20 seconds */
}
main()
{
seq1();
sort bin;
}
SEQUENCER seq1()
{
/*
test function test test limits test binning
name # low high label fail pass
_____________ ____ ___________ ___________________ _________*/
seq test_dc() $1 >2.9v <3.1v "test dc meter" f(0) p(1);
}
TESTF test_dc()
{
double reading;
set src=1 vrng=5v v=3.0v force:v;
set meter input: src=1:v vrng=5v;
set power on:dc;
wait 5ms;
reading=read_meter();
set power off:dc;
test reading;
}
If you run autocal.tl without autocal turned on, you get a run time error. The following
would be displayed in your station window:
% load autocal
...Load in progress
...Reading files /u/dcp/progs/autocal.tl and .bin
IMAGE Solutions V8.3 21-51
IMAGE Base Language: Calibration: Autocal Examples
Table of Contents Index Home Master Index Search Help
...Wait (Searching libraries)
...Wait (Loading)
...Load completed.
% run
ERROR #134 - DC subsystem uncalibrated.
Program stopped for run time error in test_dc at line 32
% delete
delete: Test program has been deleted
With autocal turned on, autocal.tl runs successfully:
% load autocal.tl -autocal
...Load in progress
...Reading binary file /u/dcp/progs/autocal.bin
...Wait (Searching libraries)
...Wait (Loading)
...Load completed.
Data Retention Verified.
Reference serial number 0xc5c55
Last reference calibration on Mar. 17, 1994
Calibrating Voltmeter
Calibrating Source 1
Calibrating Source 2
Calibrating DUT Source 1
Calibration Complete
% loop -on
Device #1 Bin #1 Test time = 16.514 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
Device #2 Bin #1 Test time = 0.044 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
:
:
:
Device #18 Bin #1 Test time = 0.042 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
Device #19 Bin #1 Test time = 0.042 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
Data Retention Verified.
Reference serial number 0xc5c55
Last reference calibration on Mar. 17, 1994
Calibrating Voltmeter
Calibrating Source 1
Calibrating Source 2
Calibrating DUT Source 1
Calibration Complete
Device #20 Bin #1 Test time = 16.095 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
IMAGE Solutions V8.3 21-52
IMAGE Base Language: Calibration: Autocal Examples
Table of Contents Index Home Master Index Search Help
Complex Example Using Autocal Parameters
This example is more complex. It includes the tl_user_preautocal() and
tl_user_postautocal() functions. It also sets autocal modes and states. The program
code is as follows:
/* Standard header files */
#include <stdio.h>
#include <math.h>
#include <image.h>
int do_cal=0;
tl_init()
{
printf("in tl_init(): setting DC cal criteria to 10 seconds for demo\n");
tl_cal_set_inst_crit("dc", "", 10.0, TL_AUTOCAL_TIME);
}
tl_user_preautocal()
{
printf("in tl_user_preautocal()\n");
if (do_cal == 0) {
printf("TEST: setting global ignore cal\n");
tl_cal_set_autocal_mode(TL_AUTOCAL_IGNORED);
printf("TEST: setting do_cal flag to 1\n");
do_cal = 1;
}
}
tl_user_postautocal()
{
printf("in tl_user_postautocal()\n");
if (do_cal == 1) {
printf("TEST: unsetting global ignore cal\n");
tl_cal_set_autocal_mode(TL_AUTOCAL_NOT_IGNORED);
}
}
main()
{
printf("entering main()\n");
if (tl_cal_get_autocal_state() & TL_AUTOCAL_UNCALIBRATED) {
printf("TEST: calibration invalid, skipping tests\n");
}
else if (do_cal == 1) {
printf("TEST: calibration ONLY, skipping tests\n");
printf("TEST: setting do_cal to 0\n");
do_cal = 0;
}
else {
printf("TEST: calibration valid, executing tests\n");
seq1();
sort bin;
IMAGE Solutions V8.3 21-53
IMAGE Base Language: Calibration: Autocal Examples
Table of Contents Index Home Master Index Search Help
}
printf("leaving main()\n");
}
SEQUENCER seq1()
{
/*
test function test test limits test binning
name # low high label fail pass
_____________ ____ ___________ ___________________ _________*/
seq test_dc() $1 >2.9v <3.1v "test dc meter" f(0) p(1);
}
TESTF test_dc()
{
double reading;
tl_sba_w1ps_x(01111, 1); /* ground safety */
set src=1 vrng=5v v=3.0v force:v;
set meter input: src=1:v vrng=5v;
set power on:dc;
wait 5ms;
reading=read_meter();
set power off:dc;
test reading;
}
If you loaded and ran this program for some devices with autocal turned on, the following
would be displayed in your station window:
% load /u/program_file/calibration/cal_resource.c -autocal
...Load in progress
...Reading binary file /u/program_file/calibration/test/extra.bin
...Reading binary file /u/program_file/cal_resource.bin
...Wait (Searching libraries)
...Wait (Loading)
...Load completed.
in tl_init(): setting DC cal criteria to 10 seconds for demo
% loop -on
in tl_user_preautocal()
Test program looping is ON
TEST: setting global ignore cal
TEST: setting do_cal flag to 1
in tl_user_postautocal()
TEST: unsetting global ignore cal
entering main()
TEST: calibration invalid, skipping tests
leaving main()
Device #0 No binning Test time = 0.034 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
in tl_user_preautocal()
Calibrating Voltmeter
Calibrating Source 1
IMAGE Solutions V8.3 21-54
IMAGE Base Language: Calibration: Autocal Examples
Table of Contents Index Home Master Index Search Help
Calibrating Source 2
Calibrating Source 3
Calibrating Source 4
Calibrating Source 5
Calibrating DUT Source 1
Calibrating DUT Source 2
Calibrating DUT Source 3
Calibrating DUT Source 4
Calibration Complete
in tl_user_postautocal()
TEST: unsetting global ignore cal
entering main()
TEST: calibration ONLY, skipping tests
TEST: setting do_cal to 0
leaving main()
Device #0 No binning Test time = 0.058 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
% entering main()
TEST: calibration valid, executing tests
leaving main()
Device #1 Bin #0 Test time = 0.270 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
entering main()
TEST: calibration valid, executing tests
leaving main()
:
:
:
Device #87 Bin #0 Test time = 0.082 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
entering main()
TEST: calibration valid, executing tests
leaving main()
Device #88 Bin #0 Test time = 0.084 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
entering main()
TEST: calibration valid, executing tests
leaving main()
Device #89 Bin #0 Test time = 0.083 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
in tl_user_preautocal()
TEST: setting global ignore cal
TEST: setting do_cal flag to 1
in tl_user_postautocal()
TEST: unsetting global ignore cal
entering main()
TEST: calibration invalid, skipping tests
leaving main()
IMAGE Solutions V8.3 21-55
IMAGE Base Language: Calibration: Autocal Examples
Table of Contents Index Home Master Index Search Help
Device #89 No binning Test time = 0.092 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
in tl_user_preautocal()
Calibrating Voltmeter
Calibrating Source 1
Calibrating Source 2
Calibrating Source 3
Calibrating Source 4
Calibrating Source 5
Calibrating DUT Source 1
Calibrating DUT Source 2
Calibrating DUT Source 3
Calibrating DUT Source 4
Calibration Complete
in tl_user_postautocal()
TEST: unsetting global ignore cal
entering main()
TEST: calibration ONLY, skipping tests
TEST: setting do_cal to 0
leaving main()
Device #89 No binning Test time = 0.113 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
entering main()
TEST: calibration valid, executing tests
leaving main()
Device #90 Bin #0 Test time = 0.095 sec
Test program size = 3128K. (text=1096K data=624K malloc data=1408K)
entering main()
TEST: calibration valid, executing tests
leaving main()
IMAGE Solutions V8.3 21-56
IMAGE Base Language: Calibration: Overriding Calibration Errors Using an Error Handler
Table of Contents Index Home Master Index Search Help
Overriding Calibration Errors Using an Error Handler
Another way to keep a tester calibrated involves creating a custom run time error handler.
This method traps specific run time errors which indicate that an instrument’s calibration has
expired and explicitly calibrates that instrument. The execution during which this error
condition is detected will result in a FAIL, but you can correct for this by setting retest. This
is not currently the recommended method. (See “Controlling Run-Time Errors” on page
15-31 for more information.)
The following program, custom_error.tl, illustrates using a custom error handler:
/* Standard header files */
#include <stdio.h>
#include <math.h>
#include <image.h>
#include <itlh/tlerror.h>
int my_error_function();
tl_init()
{
tl_cal_set_inst_crit("dc", "", 20.0, TL_AUTOCAL_TIME); /* 20 seconds */
set error handler = my_error_function; /* Call user function on error */
}
my_error_function(error)
int error;
{
switch(error) {
case 134:
printf("\n\nrecalibrating DC from my_error_function()\n\n");
tl_dccal_subr(0);
return(ERROR_IGNORE);
break;
}
return(ERROR_FORCE_HALT);
}
main()
{
seq1();
sort bin;
}
SEQUENCER seq1()
{
/*
test function test test limits test binning
name # low high label fail pass
_____________ ____ ___________ ___________________ _________*/
seq test_dc() $1 >2.9v <3.1v "test dc meter" f(0) p(1);
}
IMAGE Solutions V8.3 21-57
IMAGE Base Language: Calibration: Overriding Calibration Errors Using an Error Handler
Table of Contents Index Home Master Index Search Help
TESTF test_dc()
{
double reading;
set src=1 vrng=5v v=3.0v force:v;
set meter input: src=1:v vrng=5v;
set power on:dc;
wait 5ms;
reading=read_meter();
set power off:dc;
test reading;
}
Running this program would display the following in your station window (note the bin
numbers):
% load cal_custom_error.tl
...Load in progress
...Reading binary file /u/dcp/progs/cal_custom_error.bin
...Wait (Searching libraries)
...Wait (Loading)
...Load completed.
% loop -on
Test program looping is ON
%
recalibrating DC from my_error_function()
Data Retention Verified.
Reference serial number 0xc5c55
Last reference calibration on Mar. 17, 1994
Calibrating Voltmeter
Calibrating Source 1
Calibrating Source 2
Calibrating DUT Source 1
Calibration Complete
Device #1 Bin #0 Test time = 16.301 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
Device #2 Bin #1 Test time = 0.042 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
:
:
:
Device #17 Bin #1 Test time = 0.042 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
Device #18 Bin #1 Test time = 0.042 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
recalibrating DC from my_error_function()
Data Retention Verified.
Reference serial number 0xc5c55
Last reference calibration on Mar. 17, 1994
IMAGE Solutions V8.3 21-58
IMAGE Base Language: Calibration: Overriding Calibration Errors Using an Error Handler
Table of Contents Index Home Master Index Search Help
Calibrating Voltmeter
Calibrating Source 1
Calibrating Source 2
Calibrating DUT Source 1
Calibration Complete
Device #19 Bin #0 Test time = 15.952 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
Device #20 Bin #1 Test time = 0.042 sec
Test program size = 1384K. (text=792K data=544K malloc data=48K)
:
:
:
% loop -off
Test program looping is OFF
IMAGE Solutions V8.3 21-59
IMAGE Base Language: Calibration: Syntax Summary
Table of Contents Index Home Master Index Search Help
Syntax Summary
The following is the syntax summary of calibration parameters for the load command:
load [-autocal] [-ignore_cal] [-cal_after] [-nocalfile] [-pinmap_only]
[-frc_calfile]
[-<inst> [cal_type] noautocal ignore_cal nocalfile frc_calfile]
where <inst> can be one or more of:
dc plfsrc plfdig ...
The following is the syntax summary for the calibrate command:
calibrate [-station #] [-autocal | -noautocal] [-ignore_cal | -noignore_cal]
[-cal_after | -cal_before ] [-calfile | -nocalfile ]
[-frc_calfile | -nofrc_calfile ] [-all_copies | -pinmap_only ]
[-report]
calibrate [-station #] -<inst> [cal_type] [autocal | noautocal]
[-station #] -<inst> [cal_type] [ignore_cal | noignore_cal]
[-station #] -<inst> [cal_type] [calfile | nocalfile]
[-station #] -<inst> [cal_type] [frc_calfile | nofrc_calfile]
calibrate [-station #] -dc [file | verbose]
calibrate [-station #] -plfsrc
calibrate [-station #] -plfdig
:
:
:
The instrument list is configuration specific and generated at run-time.
IMAGE Solutions V8.3 21-60
IMAGE Base Language: Test System Alarms
Table of Contents Index Home Master Index Search Help
22 TEST SYSTEM ALARMS
In Catalyst and Catalyst Tiger test systems, some hardware alarms are common to all test
systems while other alarms are dependent on the test system configuration. This section
contains general information for all alarms. For details on alarms for individual instruments,
see the appropriate instrument section in the instrumentation manual for your test system.
An alarm indicates a hardware condition that may invalidate a measurement. These
conditions may be caused by a bad device, an incorrectly programmed instrument, or a test
system hardware malfunction. The action taken when a measurement alarm occurs is under
the control of the test program. Unless otherwise specified, alarms are always enabled.
This section includes the following topics:
• “How Alarms Work” on page 22-2
• “Alarm Checking” on page 22-4
• “Reporting Alarms” on page 22-5
• “Hardware Conditions That Cause Alarms” on page 22-7
• “Alarm Masking” on page 22-17
• “Alarm Programming Examples” on page 22-20
• “Debugging Alarms” on page 22-21
IMAGE Solutions V8.3 22-1
IMAGE Base Language: Test System Alarms: How Alarms Work
Table of Contents Index Home Master Index Search Help
How Alarms Work
IMAGE can perform a measurement over a span of time, such as when a digital pattern is
running or a digitizer is capturing data. Each digitized sample or digital truth table test is
considered a measurement that would be invalid if an alarm occurred. For this reason there
is a master alarm enable signal in Catalyst and Tiger testers. Alarms are latched when the
master alarm enable signal is active. This is true for all instruments in the tester except the
DC meter. The DC meter uses an alarm strobe which is pulsed immediately before making
the measurement.
In previous generation test equipment, DC meter alarm conditions were latched at the
occurrence of an alarm strobe. The alarm strobe was a pulse that latched the output of an
alarm detection circuit at the correct time, presumably just before strobing the A/D
converter. This detected an alarm condition that existed when the measurement was made.
When writing a test program, you want to know when alarms are enabled to avoid latching
alarms that result from changing conditions of the DUT or test instruments. For example, if
you capture data with a digitizer, the channel card continues to record alarms as long as
alarms are enabled, even after the capture is complete and the alarms are no longer
relevant to your test. Consider the case where you have programmed a digitizer to capture
256 samples, and trigger the digitizer from a pattern. The digitizer stops after 256 samples
are captured, and the data can be transferred using a move dig_cap statement. However,
alarms are still enabled until the next set statement is executed, as explained below.
Enabling Alarms
Before you take a measurement, enable alarms and wait for relays to settle. Alarms are
enabled and then immediately cleared during the rdelay() function if any set statement
was executed since the last rdelay. If two rdelay functions are executed in a row, only the
first will enable and clear alarms.
rdelay() calls can be written into the program explicitly, but this is usually not necessary
because the function is automatically embedded in other IMAGE statements.
Disabling Alarms
The set statements disable alarms, causing any alarms generated during the changing
states of the instruments to be ignored. At the simplest level, alarms are disabled by the
function tl_tba_settle(). This function sets the settling timer in the tester in increments
of 100 µs. tl_tba_settle() takes a single integer parameter to indicate the time, where 1
= 100 µs. This function is used by various drivers in the tester when a setup change is made.
The rdelay function calls the corresponding tl_tba_settle_wait function to wait for the
settling timer to expire.
You can insert tl_tba_settle(1); calls in your program directly to disable alarms. This
also ensures that the next rdelay clears alarms. However, we recommend that you use the
set all alarm statement.
IMAGE Solutions V8.3 22-2
IMAGE Base Language: Test System Alarms: How Alarms Work
Table of Contents Index Home Master Index Search Help
Controlling the Master Alarm Enable
You can enable and disable the master alarm signal using the following IMAGE statements:
set all alarm: ignore; /* to disable alarms */
set all alarm: default; /* to enable alarms */
The second statement uses default because it enables the alarms and resets them to their
default actions. The default action for an alarm is either force_fail (which is most common
and causes the test to fail) or force_bin (which stops the program and bins the device).
Any test that fails due to an alarm is binned in the appropriate error bin and, if datalogging
is enabled, is marked with an (A) on the output log. A sample datalog output with an alarm
is shown below:
Device: 1 Station: 1 Site: 1 Date: Mon Jun 8 15:00:54 1987
Sequencer: main_seq
10 alpha 64 volts (A) 20 beta -4.7 uf
30 gamma 29 kHz 35 binom 3.00
4000 res -63.00 40 delta -63.00
50 epsilon 0.00 mv (A) 60 theta 0.00 ma (A)
IMAGE Solutions V8.3 22-3
IMAGE Base Language: Test System Alarms: Alarm Checking
Table of Contents Index Home Master Index Search Help
Alarm Checking
Catalyst and Tiger test systems are designed to continually check for alarms. However,
since an instrument may trigger an alarm during a setup operation (as in a DC source), a
mechanism is provided to disable alarm checking during this time and to re-enable alarm
checking once an instrument has settled.
Alarms are checked when measurements are taken. In most cases, alarms are checked
throughout the tester. Some examples of statements at which checking occurs are as
follows:
read_meter()
read_tms();
test ac_functional... ;
read_pmm();
Reading the capture memory is a special case because reading capture memory only
checks for capture memory alarms. An alarm in capture memory data indicates that its
associated digitizer detected an alarm or that a parity error exists. Since this information is
retained in memory until it is read, you may not get an indication of an alarm until the
memory is read. The digitizer channel card may alarm, however, in which case it is reported
at the next full alarm check. This feature ensures the integrity of each individual captured
sample.
NOTE
Capture memory may also be noted as dig_cap, lfdig, hfdig, and plfdig.
Alarms have several causes:
• Faulty device
• A hardware malfunction.
• An incorrectly programmed instrument
A hardware malfunction is always a parity error, causes immediate binning of the part, and
stops the test program. These errors cannot be masked. Parity errors are checked even
when you have disabled alarm checking.
IMAGE Solutions V8.3 22-4
IMAGE Base Language: Test System Alarms: Reporting Alarms
Table of Contents Index Home Master Index Search Help
Reporting Alarms
By convention, IMAGE displays alarm messages to the terminal or console window from
which you started IMAGE. This is not always possible, however, when running under CDE.
The Alarm Manager collects messages that would normally go to the console window and
displays them in a common window.
This feature allows you to direct these messages to any of the following outputs:
• The window from which you started IMAGE (if possible)
• The Alarm Manager window
• The IMAGE_alarm_manager.log file
Figure 22-1. Alarm Manager Window
You control the output of console messages by including lines in the .Xdefaults file in your
home directory. The lines are in the format:
property: setting
You can set the following properties to control Alarm Manager’s behavior:
image.alarm_manager.use_alarm_manager
use_alarm_manager redirects IMAGE and system messages to
the Alarm Manager.
do_not_use_alarm_manager makes no change to where
messages are sent. (IMAGE error messages go to the window
from which you started IMAGE, if possible, and system
messages go to the console window, if possible.) This is the
default setting.
image.alarm_manager.screen_output
Terminal sends messages to the window from which you
started IMAGE. This is the default setting.
GUI sends messages to the Alarm Manager GUI window.
Terminal_and_GUI sends messages to both the Alarm
Manager window and to the terminal from which you started
IMAGE.
IMAGE Solutions V8.3 22-5
IMAGE Base Language: Test System Alarms: Reporting Alarms
Table of Contents Index Home Master Index Search Help
image.console.tester_output_action
Open causes the Alarm Manager GUI window to open to display
each new message. This is the default setting.
Beep sounds a beep for each new message.
Open_and_Beep causes the Alarm Manager GUI window to open
and sounds a beep for each new message.
None suppresses notification of new messages.
image.production.error_alarm_handling
screen_display sends messages to the screen (as specified in
other Alarm Manager properties). This is the default setting.
record_in_log writes the messages to the log file but does not
display them on the screen. The property
image.alarm_manager.screen_output has no effect if you
specify this setting.
screen_and_log displays messages on the screen and writes
the messages to a log file.
If you omit any of these properties from your .Xdefaults file, IMAGE uses the default value
for the property you omitted.
To select a message in the display, click anywhere on the message line.
Alarm Manager provides two buttons you can use to manage the list of messages:
• To acknowledge the selected message, click the ACK button.
• To remove the selected message from the list, click the DEL button.
You can change Alarm Manager’s display in a number of ways.
To select which of the detail columns (STATE, DATE, TIME) Alarm Manager should display,
select OPTIONS, then select the appropriate column title. This is a toggle; Alarm Manager
displays those columns with a check beside their names in this list.
Alarm Manager can insert new messages at the top or bottom of the list. To modify this
behavior, select OPTIONS, then choose INSERT NEW ALARMS AT TOP or INSERT NEW ALARMS
AT BOTTOM.
To change Alarm Manager’s appearance and color scheme, select LNF>METAL or
LNF>MOTIF. Note that this also resizes the window.
Note that the Alarm Manager display remains open after you close IMAGE. This is to allow
you to view any errors or messages that appear during the shutdown process.
IMAGE Solutions V8.3 22-6
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
Hardware Conditions That Cause Alarms
Table 22-1 lists the test system hardware that can generate an alarm at any time during a
test program run.
Table 22-1. Tester Hardware That Generates Alarms
Test System Type
Test System Hardware
Catalyst Tiger
AC Instrumentation
1 GHz Very High Frequency Digitizer 4 4
Arbitrary Waveform Generator LAN 4 4
Broadband AC Digitizer
Broadband AC Source
Floating point exceptions
GigaDig 4 4
Low Frequency AC Digitizer 4 4
Low Frequency AC Source 4 4
Precision Low Frequency Digitizer N/A
Precision Low Frequency Source Channel Card N/A
Very High Frequency Digitizer 4
DC Instrumentation
Advanced Analog Pin Unit 4 4
DC measurement system 4
DC sources 4
High Current Power Supply 4
High Current Unit 4
Octal V/I Source 4
Quad Voltage Source 4 4
Reference Source Channel Card
Universal Backplane V/I 4 4
IMAGE Solutions V8.3 22-7
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
Table 22-1. Tester Hardware That Generates Alarms (Continued)
Test System Type
Test System Hardware
Catalyst Tiger
Digital Instrumentation
Capture memory
Large vector memory 4 4
SERDES Port Qualifier 4
Source memory
Measurement Instrumentation
Low Current Ammeter 4
Precision Multimeter (PMM) 4
Time-Jitter Digitizer 4
Time-Jitter Analyzer 4
Other Instrumentation
Serial Bus Channel Card
Stored data bits (SDB)
Tester support circuitry 4 4
AC Instruments
Arbitrary Waveform Generator LAN
The AWGLAN has eight differential output pairs on Catalyst Tiger test systems and four
differential output pairs on Catalyst test systems. Each pin of each differential pair has a
dedicated Per Pin Measurement Unit (PPMU), which can generate the following alarms:
ppmu_over_i_range The input current to the AWGLAN’s PPMU is greater than the
maximum permissible value.
ppmu_under_i_range The input current to the AWGLAN’s PPMU is less than the
minimum permissible value.
ppmu_over_v_range The input voltage of the AWGLAN’s PPMU is greater than the
maximum permissible value.
ppmu_under_v_range The input voltage of the AWGLAN’s PPMU is less than the
minimum permissible value.
IMAGE Solutions V8.3 22-8
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
GigaDig
The GigaDig can generate the following alarm:
data The data sent from the digitizer’s capture memory have an
associated over-range alarm condition.
Low Frequency AC Digitizer
The Low Frequency AC Digitizer can generate the following alarm:
data The data alarm is an overrange alarm, which occurs when the
input voltage to the LFACDIG exceeds the programmed vrng
value. For example, an overrange alarm occurs if you set
vrng=5.12v and the input voltage rises to 6V. IMAGE checks for
the overrange alarm whenever you attempt to move captured
data.
Low Frequency AC Source
The Low Frequency AC Source can generate two alarms on each of the two signal delivery
channels, A and C:
i_limit_pos The source channel has a positive overload current condition.
i_limit_neg The source channel has a negative overload current condition.
Precision Low Frequency Digitizer
The Precision Low Frequency Digitizer can generate the following alarm:
data The input voltage to the PLFDIG exceeds the programmed vrng
value.
Precision Low Frequency Source Channel Card
The Precision Low Frequency Source Channel card can generate two alarms on each of
the two signal delivery channels, A and C:
i_limit_pos The source channel has a positive overload current condition.
i_limit_neg The source channel has a negative overload current condition.
Very High Frequency Digitizer
The Very High Frequency Digitizer and 1 GHz Very High Frequency Digitizer can generate
the following alarm:
data The data sent from the digitizer’s capture memory have an
associated over-range alarm condition.
IMAGE Solutions V8.3 22-9
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
DC Instruments
Advanced Analog Pin Unit
Each Advanced Analog Pin Unit (AAPU) channel contains two types of alarms:
guard Specifies a guard alarm.
overload Specifies an overload alarm.
AAPU alarms can become latched whenever the master alarm enable signal is active.
When making a measurement IMAGE checks for latched AAPU alarms. You can control the
action taken when an alarm is detected.
Since alarms often occur during AAPU setup, IMAGE disables alarms during this period.
Before changing the AAPU hardware state the AAPU set statement disables alarms. If the
connect, disconnect, or guard parameters are programmed, the settle time is set to 3ms.
Before a measurement is made IMAGE waits until the settle time has elapsed, enables
alarms, clears pre-existing latched alarms, and then checks for any new alarms that
became latched.
DC Measurement System
The DC Measurement System refers to the voltmeter and its various inputs and modes of
operation. As with source alarms, the specific alarm types are unlatched. A general report
indicates a past unlatched condition that no longer exists. A specific report indicates that the
unlatched condition continues to be generated. Four alarms are possible:
vm1 guard Voltmeter 1 (vm1) guard current exceeds ±1mA.
vm2 guard Voltmeter 2 (vm2) guard current exceeds ±1mA.
dgs Deviation ≥0.25V from chassis ground.
adcomp A/D converter over-range.
DC Sources
Most test systems can be configured with up to nine sources: four DUT sources and five
matrixed sources. Associated with each source are three unlatched alarms and a latched
alarm data bit. Whenever an unlatched condition occurs (as described below), the latched
data bit is set. Therefore, a source alarm can occur without a specific type description of
what caused it. This feature reports transient conditions that may occur during a
measurement. If a type is reported, the unlatched condition it represents is still occurring.
DC source alarms include
output The source has encountered an illegal range, an overheat
condition exists (>90°C), or an open loop condition exists.
guard A current ≥ ±1mA on the guard exists.
IMAGE Solutions V8.3 22-10
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
overload Source is set to force:v and is current limiting or is set to
force:i and is voltage limiting.
Delta Bus
A Delta Bus alarm indicates that the output deviates more than ±0.6V from the nominal
value of the D/A output.
High Current Power Source
The High Current Power Supply can generate the following alarms:
dps_clamp A clamp alarm detects one or more of the following:
The force line may not be connected to the DUT pin but
the sense line is.
The current flowing in the Hi Force lead of the channel is
greater than the maximum allowable current.
dps_open_kelvin An open Kelvin 1 alarm detects one or more of the following:
The Kelvin connection may be open in the device interface
The differential voltage between the force and sense of a
high/low line is greater than the maximum allowable
voltage
dps_open_kelvin2 An open Kelvin 2 alarm detects one or more of the following:
The Kelvin connection may be open at the DIB Pogo Block
The differential voltage between the force and sense of a
high/low line at the DIB Pogo Block is greater than the
maximum allowable voltage
dps_autorange An ammeter autorange alarm detects whether the ammeter
range has changed since the last time it was set.
High Current Unit
A test system can be configured with up to four High Current Units (HCUs). HCU cards
replace dc source cards in either the matrixed or nonmatrixed (DUT) slots. HCUs report one
alarm, overload for the dc source with which it is associated:
output The source has encountered an illegal range, an overheat
condition exists (>90°C), or an open loop condition exists.
guard A current ≥ ±1mA on the guard exists.
overload Source is set to force:v and is current limiting or is set to
force:i and is voltage limiting.
IMAGE Solutions V8.3 22-11
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
Octal V/I Source
OVI Open Kelvin Alarm
An open Kelvin alarm indicates one or more of the following. The
Kelvin connection may be open in the device interface or the
differential voltage between Hi Force/Sense and Lo Force/
Sense is greater than the maximum voltage.
OVI Sense Alarm A sense alarm indicates one or more of the following. The force
line may not be connected to the DUT pin but the sense line is.
The current flowing in the Hi/Lo Sense line is greater than the
specified max. current. (See section 11.3.1 in the “Octal V/I
Source” specifications.)
OVI Mode Alarm A mode alarm indicates one or more of the following. The load
seen by the OVI source is such that the load line intersects the
voltage/current clamp that is not programmed as the forced
parameter. The source is programmed to force:v and the
current clamp (i) is active, or the source is programmed to
force:i and current clamp is inactive.
OVI Open Loop Alarm An open loop alarm indicates one or more of the following. The
control loop cannot be satisfied when slewing, or the
programmed state cannot be satisfied with a given load. The OVI
source can be programmed to operate outside the specified
power limits. See section 7.0 in the “Octal V/I Source”
specifications. While modulating the OVI output, the sum of the
programmed dc value and adjusted wave bus signal may have
exceeded the maximum allowable amplitude as defined in the
OVI specifications. The current clamp can be programmed to a
value less than the offset current into an open load. See section
4.3 in the “Octal V/I Source” specifications for offset current
values for OVI current ranges.
Local Meter Overrange Alarm
An overrange alarm indicates that the voltage or current being
measured is greater than the programmed voltage or current
metering range. See vrng, irng, and amm_gain programming
instructions.
Quad Voltage Source
Open Kelvin Alarm An open Kelvin alarm detects one or more of the following. The
Kelvin connection may be open in the device interface. The
differential voltage between the Force and Sense of a Hi/Lo line
is greater than the maximum allowable voltage.
Sense Current Alarm A sense current alarm detects one or more of the following. The
force line may not be connected to the DUT pin but the sense line
is. The current flowing in the Hi Sense lead of the channel is
IMAGE Solutions V8.3 22-12
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
greater than the maximum allowable current. (See section 11.2.1
“DC Range Sense Current threshold” in the QVS specifications.)
Clamp Alarm A clamp alarm detects a channel whose voltage forcing ability is
limited by the specified current clamp.
Open Loop Alarm An open loop alarm detects that the control loop cannot be
satisfied when slewing, or that the programmed state cannot be
satisfied with a given load. Note the following points. The QVS
can be programmed to operate outside the specified power
limits. See the QVS specifications. The current clamp (ilim) can
be programmed to a value less than the offset current into an
open load. See “DC Accuracy, Calibrated” under “System
Current Metering” and “Local Current Metering” in the QVS
specifications for offset current values for QVS current ranges.
Universal Backplane V/I
Instrument alarms are caused by a bad device or a test system hardware problem. Alarms
indicate a hardware condition which may invalidate a measurement result. UB V/I alarms
can become latched whenever the master alarm enable signal is active. When making a
measurement, IMAGE checks for latched UB V/I alarms. You can control the action taken
when an alarm is detected.
UB - V/I source alarms include:
thermal The source has encountered an illegal range, an overheat
condition exists (>90°C), or an open loop condition exists.
guard A current ≥ ±1mA on the guard exists.
overload Source is set to force:v and is current limiting or is set to
force:i and is voltage limiting.
open loop The programmed voltage and current conditions can not be
satisfied by the loop control.
Digital Instruments
Capture Memory
Capture memory alarms can occur during movement of data from a digital capture memory
to another part of the test system. Only at this time are any capture memory alarms
reported, and they are only for the capture memory being read. The alarms are:
data The data from the digitizer has an alarm condition associated
with it.
parity A parity error exists in the section of capture memory just read.
This may reflect a real test system hardware problem or may be
IMAGE Solutions V8.3 22-13
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
caused by reading uninitialized memory. Take care when the
interpreting this alarm.
DCB (dig_src)
The only error that can occur on the digital source is a parity error in the data transferred
from the s_mem:
parity Indicates either a bad data path between the s_mem and DCB
or a fault on either one. This error cannot be masked.
Large Vector Memory (LVM)
The only error that occurs on the large memory results from faulty test system hardware:
parity LVM memory contains a parity error. This error cannot be
masked.
SERDES Port Qualifier
The SERDES Port Qualifier (SPQ) has six differential outputs. Each output has a dedicated
Per Pin Measurement Unit (PPMU), which can generate the following alarms:
ppmu_over_i_range The input current to the SPQ’s PPMU is greater than the
maximum permissible value.
ppmu_under_i_range The input current to the SPQ’s PPMU is less than the minimum
permissible value.
ppmu_over_v_range The input voltage of the SPQ’s PPMU is greater than the
maximum permissible value.
ppmu_under_v_range The input voltage of the SPQ’s PPMU is less than the minimum
permissible value.
Source Memory
The only error that can occur in source memory results from faulty test system hardware:
parity The microcode memory in the s_mem has a parity error. This
can only be caused by a faulty s_mem. This error cannot be
masked.
Measurement Instruments
Low Current Ammeter
The Low Current Ammeter (LCA) alarms when the voltage ramp produced in the integrate
mode is greater than a preset limit. It can generate the following alarms:
IMAGE Solutions V8.3 22-14
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
in_posv The input overvoltage is positive polarity.
in_negv The input overvoltage is negative polarity.
Precision Multimeter
The PMM supports five types of alarms. Four are related to the channel card (these alarms
are not supported on test systems without test heads), and the fifth is an overrange alarm.
The a and b designators specify which PMM channel pair is involved.
iout_a | iout_b Indicates overcurrent conditions on the guard driver outputs for
PMM channel A or B. If this alarm occurs, the guard drivers are
disabled.
vin_a | vin_b Indicates overvoltage conditions on the guard driver inputs from
PMM channel A or B. If this alarm occurs, the guard drivers are
disabled.
range Indicates an overrange condition. If this alarm occurs, the
number 1E+38 is returned.
Time-Jitter Digitizer
The Time-Jitter Digitizer (TJD) will time out and produce an alarm if all the expected
samples are not captured within a specified period of time. There is an alarm type for each
way that a data capture timeout can occur:
tjd_a_start_timeout A stamper did not start stamping events.
tjd_a_stop_timeout B stamper did not finish stamping events.
tjd_b_start_timeout A stamper did not start stamping events.
tjd_b_stop_timeout B stamper did not finish stamping events.
tjd_ab_start_timeout A and B stamper did not start stamping events.
tjd_ab_stop_timeout A and B stamper did not finish stamping events.
tjd_a_start_b_stop_timeout
A stamper did not start and B stamper did not finish.
tjd_b_start_a_stop_timeout
B stamper did not start and A stamper did not finish.
Time-Jitter Analyzer
The Time-Jitter Analyzer (TJA) will time out and produce an alarm if all the expected
samples are not captured within a specified period of time. There is an alarm type for each
way that a data capture timeout can occur:
tja_a_start_timeout A stamper did not start stamping events.
tja_a_stop_timeout B stamper did not finish stamping events.
IMAGE Solutions V8.3 22-15
IMAGE Base Language: Test System Alarms: Hardware Conditions That Cause Alarms
Table of Contents Index Home Master Index Search Help
tja_b_start_timeout A stamper did not start stamping events.
tja_b_stop_timeout B stamper did not finish stamping events.
tja_ab_start_timeout A and B stamper did not start stamping events.
tja_ab_stop_timeout A and B stamper did not finish stamping events.
tja_a_start_b_stop_timeout
A stamper did not start and B stamper did not finish.
tja_b_start_a_stop_timeout
B stamper did not start and A stamper did not finish.
tja_rc_a_precount_not_met
A stamper did not precount the specified number of events
(ratio_count measurements only).
Other Instruments
Serial Bus Channel Card
Each Serial Bus Channel Card (SBCC) channel contains the following alarm:
overcurrent Indicates overcurrent state in output drivers and for clock
timeout.
Stored Databits
A stored databit alarm indicates that an overload (>200mA) has been detected.
Tester Support Circuitry
Catalyst and Tiger test systems include protection against hazardous voltage and current
levels that may damage sensitive hardware.
Real-Time Alarm. The Real-Time Alarm occurs when an out of range voltage is applied to
a channel card or PPMU from a matrix source or the DUT. IMAGE checks for this condition
every time you make a connection and close a relay within a channel card. If this alarm
occurs, the affected relays do not close and the test program reports a run-time error.
Latched Alarm (Catalyst) and Over Current Alarm (Tiger). A latched alarm or over
current alarm occurs when an out of range voltage is applied to a channel card or PPMU
after you have made a connection and closed relays on a channel card. IMAGE checks for
this condition periodically; if an out of range voltage exists, IMAGE takes appropriate action
to protect the test system hardware (such as opening the affected relays).
IMAGE Solutions V8.3 22-16
IMAGE Base Language: Test System Alarms: Alarm Masking
Table of Contents Index Home Master Index Search Help
Alarm Masking
Test program syntax is available to mask alarms. Masking an alarm causes the test system
to ignore that alarm. At the beginning of a program all alarms are enabled (except where
noted for a particular instrument). To make the tester ignore an alarm, you must disable it
in the test program. You can also enable a previously masked alarm.
Note that masking an alarm results in longer test times. Ignoring a masked alarm is more
time-consuming for the software than checking for that alarm. Therefore, masking alarms,
especially masking all alarms, is not advisable in most circumstances.
The syntax for alarm masking and enabling is:
set <pin_spec> <instr> alarm: ignore [type: <alarm_type>]
force_fail
force_bin
default ;
where:
ignore Ignores an alarm if one occurs.
force_fail Forces the test to fail if an alarm occurs.
force_bin Forces the test to bin if an alarm occurs.
default Sets the alarm to the default condition.
<instr> Is one of the test system instruments listed in table 22-2.
<alarm_type> Is one of the alarm types for the instrument listed in table 22-2.
Table 22-2. Alarm Masking Syntax
Instrument
Instrument Alarm Types
Syntax
all All instruments
cdig Serial Bus Channel Card
dcms DC measurement system
delta Delta bus
dig_cap Digital Signal Capture Memory parity
(mixed-signal) data
IMAGE Solutions V8.3 22-17
IMAGE Base Language: Test System Alarms: Alarm Masking
Table of Contents Index Home Master Index Search Help
Table 22-2. Alarm Masking Syntax (Continued)
Instrument
Instrument Alarm Types
Syntax
dps High Current Power Source dps_clamp
dps_open_kelvin
dps_open_kelvin2
dps_autorange
Quad Voltage Source dps_clamp
dps_open_kelvin
dps_sense
dps_open_loop
duthcu DUT High Current Unit
dutsrc DC DUT source
gigadig GigaDig data
hcu Matrixed High Current Unit
hfdig Very High Frequency Digitizer data
1 GHz Very High Frequency
Digitizer
lca Low Current Ammeter in_posv
in_negv
lfacdig Low Frequency AC Digitizer data
lfacsrc Low Frequency AC Source
math Certain types of floating point
exceptions
ovi Octal V/I Source ovi_open_kelvin
ovi_sense
ovi_mode
ovi_open_loop
plfdig Precision Low Frequency Digitizer data
plfsrc Precision Low Frequency Source i_limit_pos
i_limit_neg
pmm Precision Multimeter iout_a
iout_b
vin_a
vin_b
range
src DC matrixed source
sdb Stored data bits
IMAGE Solutions V8.3 22-18
IMAGE Base Language: Test System Alarms: Alarm Masking
Table of Contents Index Home Master Index Search Help
Table 22-2. Alarm Masking Syntax (Continued)
Instrument
Instrument Alarm Types
Syntax
tja Time-Jitter Analyzer tja_a_start_timeout
tja_a_stop_timeout
tja_b_start_timeout
tja_b_stop_timeout
tja_ab_start_timeout
tja_ab_stop_timeout
tja_a_start_b_stop_timeout
tja_b_start_a_stop_timeout
tjd Time-Jitter Digitizer tjd_a_start_timeout
tjd_a_stop_timeout
tjd_b_start_timeout
tjd_b_stop_timeout
tjd_ab_start_timeout
tjd_ab_stop_timeout
tjd_a_start_b_stop_timeout
tjd_b_start_a_stop_timeout
vhfawg Arbitrary Waveform Generator ppmu_over_i_range
LAN ppmu_under_i_range
ppmu_over_v_range
ppmu_under_v_range
IMAGE Solutions V8.3 22-19
IMAGE Base Language: Test System Alarms: Alarm Programming Examples
Table of Contents Index Home Master Index Search Help
Alarm Programming Examples
Examples of programming alarms are shown below.
• All alarms:
set all /* <instr> */
alarm: ignore /* ignore | force_fail | force_bin | default */
• DC Sources:
set src= (1,2) /* src | dutsrc=<SRC_LIST> */
alarm: ignore /* ignore | force_fail | force_bin | default */
• Pin based instruments:
set dpin = 5 /* <dpin | dchan> */
dig_cap /* <instr> */
alarm: ignore /* ignore | force_fail | force_bin | default */
type: data /* <alarm_type> OPTIONAL */
• Pinless instruments:
set math /* <instr> */
alarm: ignore /* ignore | force_fail | force_bin | default */
IMAGE Solutions V8.3 22-20
IMAGE Base Language: Test System Alarms: Debugging Alarms
Table of Contents Index Home Master Index Search Help
Debugging Alarms
The following statements always clear (and enable) alarms:
tl_tba_settle(1);
rdelay();
You can poll for alarms by calling the following function:
tl_alarmcheck(0);
This can be called only when alarms are enabled. If you call this function when alarms are
disabled, you get the following error message:
ERROR #1506—Alarmdriver: no rdelay() since last relay was programmed
A lower level function is available to debug the alarm driver itself. It provides more detail on
alarms but is also partly obsolete. The function call is
tl_alarminfo();
This causes the following information to be printed in the station window after you have
executed set statements, but not rdelay:
gate word 0x0000
user alarms are enabled
Warning: hardware and software masks differ!
tl_alarm_cleared is FALSE (setup alarms still outstanding!)
status hi tbus 0x0000
status low tbus 0x0002
vector bus 0x0000
conv cage 0x0000
test head 1 0x0000
System is Safe
Ignore the following warning:
Warning: hardware and software masks differ!
This message is obsolete. No alarm is present in this example. Another example is:
gate word 0x8107 alarms enabled
user alarms are enabled
tl_alarm_cleared is TRUE (setup alarms cleared)
status hi tbus 0x0000
status low tbus 0x0003 alarming
vector bus 0x0000
conv cage 0x0000
test head 1 0x0001 alarming
System is Safe
The rdelay function was executed (alarms were cleared), but an alarm is present in test
head 1 and on the low speed terabus. The test head data bus is on the low speed terabus,
so the alarm is reflected there also. tl_alarmcheck(0); can now be called to identify the
alarm.
IMAGE Solutions V8.3 22-21
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
23 RESERVED WORD LIST
The following words are reserved everywhere, or in a set statement:
A0_CLK
A0_CLK_DIV
A1_CLK
A1_CLK_DIV
A2_CLK
A2_CLK_DIV
A3_CLK
A3_CLK_DIV
achan
acmeter
acsrc
ac_trigger
alarm
ALARMED
amfmsrc
apin
apu
asu
ath
auto
bin
blkman
blkmand
break
bvcs
C0_CLK
C0_CLK_DIV
call
case
cats
ccgnd
cdig
cdotpr
cfft
cfft2d
cfftb
cfftd
cfu
IMAGE Solutions V8.3 23-1
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
Chan_num
char
CLK_DLY_MODE
CLOCK_AC_CAGE
CLOSE
CMPHI_START
CMPHI_STOP
CMPLO_START
CMPLO_STOP
CMPL_SURND
CMP_STOP
cmu
COMPLEX
compute
connect
const
continue
conv
convert_offset_binary_to_r
create_list
cvadd
cvcomb
cvconj
cvexp
cvmags
cvmagsd
cvmov
cvmul
cvneg
cvrcip
cvsub
c_mem
c_mem_alt
C_MEM_READ_ALARM
C_MEM_READ_NOCLOCK
C_MEM_READ_NOTRIG
C_MEM_READ_PARITY
C_MEM_READ_SUCCESS
d0
d0b
d1
d2
d3
d3b
databits
datalog
dchan
decimal_mode
decimal_record
decimal_string
default
delta
IMAGE Solutions V8.3 23-2
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
deskew
device_bins
dibname
dig_cap
dig_cap_alt
dig_instrument
dig_src
dig_src_alt
disconnect
diu
do
dotpr
double
download
dpin
dps
dpu
DRV_START
DRV_STOP
dsf
dsio_instrument
dsp
DSPBUFFER
DSPMC
DSPSOFT
DSPZIP
dsys
duthcu
dutsrc
dutsrc100
dutsrc200
dut_trig_in
D_COMPLEX
ecms
edgefind
else
emt
emt_region
emt_subregion
enlfsrc
enlfsrc_alt
enum
error
expert_inst
extended
extern
ext_trig
FAILED
FALSE
fftwts
fftwtsd
FIELD
IMAGE Solutions V8.3 23-3
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
FILE
float
FMT_CAGES
FMT_CMPHI
FMT_CMPLGC
FMT_CMPLO
FMT_CMPMID
FMT_CMPPAT
FMT_COND_DISABLE
FMT_COND_FAIL
FMT_COND_LOGIC
FMT_ENABLE
FMT_FAIL
FMT_FAIL_DISABLE
FMT_FAIL_ENABLE
FMT_FHI
FMT_FLO
FMT_HIZ
FMT_LOGIC
FMT_NONE
FMT_NRZ
FMT_RZ
for
fpos_t
fp_exception_field_type
fvs
ghsd
goto
gpib
hamm
hammd
handler
hannd
hann
hbin
hccs
hclk
hcu
hcvs
hfdig
hfsrc
hfsrc_alt
hf_sampler_control
HIGHEST_CHAN_NUMBER
hist
histd
HIZ_START
HIZ_STOP
hpvi
hp_xpt
hsd
hsd50
IMAGE Solutions V8.3 23-4
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
hsd50_alt
hsds
HSD_FMT_BASE
HSD_NOHALTCODE
HSD_NOREADCODE
HSD_PATRUNNING
HSD_TVAL_CMP_START
HSD_TVAL_CMP_STOP
HSD_TVAL_DRVCMP_START
HSD_TVAL_DRVCMP_STOP
HSD_TVAL_DRV_START
HSD_TVAL_DRV_STOP
HSD_TVAL_HIZ_START
HSD_TVAL_HIZ_STOP
hva
hvs
idfb
if
inst_usage
int
kernel
laser
LA_LEVEL_HIGH
LA_LEVEL_LOW
LA_LEVEL_MID
LA_LEVEL_UNKNOWN
LA_PLOT_DATA
lca
lfacdig
lfacsrc
lfdig
lfdig_alt
lfsrc
lfsrc_alt
load
long
lveq
lvge
lvgt
lvne
lvnot
margin
MAXBIN
maxmgv
maxv
maxvi
MAX_A500_HEADS
MAX_AL_HEADS
MAX_DUTPINS
MAX_H50_CHANLIST
MAX_HEADS
MAX_HSD_CHAN
IMAGE Solutions V8.3 23-5
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
meamgv
meanv
measqv
measure
meter
minmgv
minv
minvi
mmul
modify
move
mtrans
M_CLK
M_CLK_ALT
M_CLK_AUX1
M_CLK_AUX2
ndutsrc
NO
NORESULT
NO_BINNING
nsrc
of
OFF
ON
opamp
OPEN
ost
ovi
pad
PASSED
pclock
pgu
pin
PINLIST
PINLIST_ENTRY
PINMAP
PINMAP_ENTRY
PINMAP_WORDS
plfdig
plfsrc
plfsrc_alt
pmm
polar
power
proto
pulse
pvmeter
pvsrc
pwrsrc
quadruple
r1
r2
IMAGE Solutions V8.3 23-6
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
read_laser
rect
refsrc
register
reset
resume
retrieve
return
rfft
rfft2d
rfftb
rfftd
rfftm
rfftsc
rfftscd
rfu
rmmul
rmsqv
rmtran
rt_histo
RT_HISTO_CAPTURE_DONE
RT_HISTO_CAPTURING
RT_HISTO_HISTO_OVERFLOW
RT_HISTO_NO_CAPTURE
RT_HISTO_NO_TRIG
RT_HISTO_PAGE_ERROR
RT_HISTO_WHISTO_OVERFLOW
RT_HISTO_W_CTR_OVERFLOW
save
schan
scm
sdig
SEGMENT
seq
SEQUENCER
SEQ_DATA
SEQ_DATA_STR
serial
serial_all
serial_disabled
serial_failed_sequencer
serial_max_sites
serial_sleep
set
setup
shmoo
short
sigfpe_code_type
sigfpe_handler_type
signed
single
sizeof
IMAGE Solutions V8.3 23-7
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
size_t
sleep_mode
slot
sort
specs
SPOT_PULSE
sps
sps_tgen
src
start
START_CLK
static
STDF_CUSTOM_BASELINE
stop
STOP_CLK
struct
subbus
supclk
sve
sved
svemg
svesq
svessq
svs
SWEEP_OFF
SWEEP_ON
switch
S_FMT
S_JOBNAME
S_LOTNAME
s_mem
s_mem_alt
S_MEM_STATUS_BUSY
S_MEM_STATUS_IDLE
S_MEM_STATUS_PRC
S_MEM_STATUS_SRC
S_OPNAME
S_STDF_STRING
S_TNAME
t_delay
t_mem
T0_CLK
T0_CLK_DIV
TB_REG
test
TESTF
testf_cond
test_conditions
tgen
TIMSPEC
tja
tjd
IMAGE Solutions V8.3 23-8
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
TJD_STATUS_AB_MEAS_NOT_COM
TJD_STATUS_AB_MEAS_NOT_STA
TJD_STATUS_A_MEAS_NOT_COMP
TJD_STATUS_A_MEAS_NOT_STAR
TJD_STATUS_B_MEAS_NOT_COMP
TJD_STATUS_B_MEAS_NOT_STAR
TJD_STATUS_MEAS_A_NOT_STAR
TJD_STATUS_MEAS_B_NOT_STAR
TJD_STATUS_MEAS_COMPLETE
TJD_STATUS_SET_SINCE_LAST_
tms
tmschan
to
trigger
TRUE
TSET_RTR
typedef
t_delay
t_mem
uhfmm
uhfsrc
UNDEFINED
union
unload
unsigned
uwport
uwrecv
vabs
vadd
vaddd
vaint
valog
vam
vandi
vatan
vatan2
vclip
vclr
vclrd
vcos
vcosd
vdiv
vdivd
vdpsp
veqvi
vexp
vexp10
vfill
vfix
vfix32
vfix32d
vfixd
IMAGE Solutions V8.3 23-9
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
vfloat
vfloatd
vflt32
vflt32d
vhfawg
vhfcw
vhfmm
vimag
vlim
vln
vlog
vlog10
vma
vmax
vmaxmg
vmcu
vmin
vminmg
vmov
vmovd
vmsa
vmsb
vmul
vmuld
vneg
vnegd
void
volatile
vori
vpoly
vramp
vrampd
vreal
vrvrs
vsadd
vsaddd
vsbm
vsdiv
vsdivd
vsin
vsind
vsma
vsmsa
vsmsb
vsmul
vsmuld
vspdp
vsq
vsqrt
vsqrtd
vssq
vsub
IMAGE Solutions V8.3 23-10
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
vsubd
vsum
wafer
wait
wdig
wfcap
wfsrc
wgen
while
xpt
YES
_h_val
_dsp_types_
__va_list
In addition, all words beginning with tl_, tt_, TL_, or TT_, are reserved everywhere.
The following words are reserved in a dpin or deskew statement (A500 and A540):
close
cmp
drv
drvcmp
format
hiz
hotclose
hotopen
ioh
iol
isdn
muxmode
open
rcv
time_src
tset
vcp
vih
vil
voh
vol
IMAGE Pattern Language (IPL) has a separate set of reserved words that is different from
IMAGE Test Language (ITL). One key difference between IPL reserved words and ITL
reserved words is that IPL is not case-sensitive. So if VHFAWG is reserved, vhfawg, Vhfawg,
VhFaWg, and every other capitalization of VHFAWG is also reserved.
Words used in digital pattern syntax are reserved.
The following words are reserved in some or all places in an advanced mixed-signal high
speed digital pattern source file. Do not use them as pin names in a pattern file or for pattern
label names:
A0_DEC
A0_INC
IMAGE Solutions V8.3 23-11
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
ALL
ANALOG
AND
CALL
CHAN
CLR_CODE
CLR_COND
CLR_FAIL
CLR_FLAG
CPU
DECR
DIB
DIG_CAP
DIG_CAP_ALT
DIG_SRC
DIG_SRC_ALT
D_IN
D_INOUT
D_OUT
DRV
DRV_RCV
ENABLE
END_ARG
END_LOOP
END_LOOP1
END_LOOP2
EXE_ARG
EXE_GLO
EXIT_LOOP
EXT
EXTERN_LABEL
EXTERN_PRAM_LABEL
EXTERN_SCAN_HEADER
EXTERN_SCAN_TRAILER
EXTERN_SCAN_SUBR
FAIL
FIELD
FILETYPE
FLAG
FMT
GLOBAL
HALT
HALTCODE
HEADER
HFDIG
ICYC
IF
INST
JMP_GLO
JMP_PRAM
JMP_SAM
JUMP
IMAGE Solutions V8.3 23-12
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
KEEP_ALIVE
LD_NOP
LOOP
LOOP1
LOOP2
MASK
MATCH
NEXT
NEXT1
NO_HALT
NONE
OR
OUTPUT_FILENAME
PASS
PINMAP
PINMAP_FILENAME
PLFDIG
PLFSRC
POP
POP_LOOP
PUSH
Q2
QUAL
RCV
READCODE
REALIGN
REPEAT
RESYNC
RETURN
RT_HISTO
SAM_ADDR0
SAM_ADDR1
SCAN
SCAN_CHAIN
SCAN_DEFAULT
SCAN_HDR
SCAN_HDR_VAR
SCAN_IN_PIN
SCAN_OUT_PIN
SCAN_PINS
SCAN_SETUP
SCAN_SUBR
SCAN_TEMPLATE
SCAN_TLR
SCAN_TLR_VAR
SCAN_TYPE
SCF
SEND
SEND10
SET_GLO
SET_LOOP
SET_LOOP1
IMAGE Solutions V8.3 23-13
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
SET_LOOP2
SET_SCF
SHIFT
SLOT
START
START1
STARTE
STARTE1
STOP
STOPE
STORE
TO
TRAILER
TRIG
TSET
TST1
TST2
VBC
VBC_STR
VBMS_INC
VECTOR
VHFAWG
WAVEFORMS
The following words are reserved in some or all places in a Catalyst high speed digital
pattern source file. Do not use them as pin names in a pattern file or for pattern label names.
An asterisk (*) denotes reserved words in Catalyst that do not exist in the advanced mixed-
signal IPL reserved word list. You must be aware of them when porting advanced mixed-
signal patterns to Catalyst.
A0_DEC
A0_INC
*ADD
*ADSS
*AI
ALL
*ALROT
AND
CALL
CHAN
CI
CLR_CODE
CLR_COND
CLR_FAIL
CLR_FLAG
*COND_ON
CPU
*DATA
DECR
DIB
DIG_CAP
DIG_CAP_ALT
IMAGE Solutions V8.3 23-14
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
DIG_SRC
DIG_SRC_ALT
*EMT
ENABLE
END_ARG
END_LOOP
END_LOOP1
END_LOOP2
*END_MODULE
*ETRAP
EXE_ARG
EXE_GLO
EXIT_LOOP
EXT
EXTERN_LABEL
EXTERN_PRAM_LABEL
EXTERN_SCAN_HEADER
EXTERN_SCAN_SUBR
EXTERN_SCAN_TRAILER
FAIL
FIELD
FILETYPE
FLAG
FMT
GIGADIG
GLOBAL
*GLOBAL_START
HALT
HALTCODE
HEADER
HFDIG
*HRAM_EN
*ICC
ICYC
IF
*IFC
INST
*INVC
JMP_GLO
JMP_PRAM
JMP_SAM
*JTRAP
JUMP
KEEP_ALIVE
*LDNEXT
LD_NOP
*LFACDIG
*LFACSRC
LOOP
LOOP1
LOOP2
MASK
IMAGE Solutions V8.3 23-15
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
MATCH
*MAX_T0
NEXT
NEXT1
NONE
*NOP
NO_HALT
*OP
OR
OUTPUT_FILENAME
PASS
*PASSA
*PASSB
PINMAP
PINMAP_FILENAME
PLFDIG
PLFSRC
POP
POP_LOOP
PUSH
Q2
QUAL
READCODE
REALIGN
REPEAT
*RESET
RESYNC
RETURN
*RF
*ROT
RT_HISTO
SAM_ADDR0
SAM_ADDR1
SCAN
SCAN_CHAIN
SCAN_HDR
SCAN_HDR_VAR
SCAN_IN_PIN
SCAN_OUT_PIN
SCAN_PINS
SCAN_SETUP
SCAN_SUBR
SCAN_TEMPLATE
SCAN_TLR
SCAN_TLR_VAR
SCAN_TYPE
SCF
SEND
SEND10
*SETMOV
*SETROTL
*SETROTR
IMAGE Solutions V8.3 23-16
IMAGE Base Language: Reserved Word List:
Table of Contents Index Home Master Index Search Help
SET_GLO
SET_LOOP
SET_LOOP1
SET_LOOP2
SET_SCF
*SET_TRAP
*SHFTL
*SHFTR
SHIFT
*SKIP1
*SKIP3
SLOT
*SLOW_PIN
START
START1
STARTE
STARTE1
STOP
STOPE
STORE
*SV0C
*SVC
*SVOUT
*SVOUTH
*SVOUTL
*SVRLT
*SYNC
TO
TRAILER
TRIG
TSET
TST1
TST2
*USEC
VBC
VBC_STR
VBMS_INC
VECTOR
VHFAWG
WAVEFORMS
*WRF
*WRINP
*WRRLT
*XEXT
*XFAIL
*XOR
IMAGE Solutions V8.3 23-17
IMAGE Base Language: Standard Test Data Format
Table of Contents Index Home Master Index Search Help
24 STANDARD TEST DATA FORMAT
Communication is easiest when all participants speak the same language. Following this
precept, Teradyne developed a standard data format that any tester can use to store test
results. Called the Standard Test Data Format (STDF), this standard establishes the basis
for flexible communications between A5xx and Catalyst test systems and other test
systems, database management systems, and data analysis software. IMAGE V6.4 and
later conforms to STDF V4.
A file structured according to the Standard Test Data Format is called an STDF file. IMAGE
uses an STDF file to store test data associated with a particular lot or group of devices.
IMAGE constructs this file from a set of software data structures called STDF records. In the
fields of these STDF records, IMAGE stores its test data.
This section covers the following STDF topics:
• “Generating STDF Files” on page 24-2
• “Sources for STDF File Data” on page 24-4
• “STDF Records” on page 24-6 explains how IMAGE uses STDF records to build STDF
files.
• “IMAGE STDF Record Set” on page 24-11 describes the data fields for each STDF
record supported by IMAGE V7.0.
• “Reading, Writing, and Processing an STDF File” on page 24-39
This appendix focuses on STDF information specific to A5xx and Catalyst test systems. It
provides additional information on the way the test system collects and formats test data.
For a general discussion of IMAGE data collection, see “Data Collection” on page 6-1.
For general information on the Standard Test Data Format, see “Introduction to STDF” on
page 1-1 in the STDF Specification Manual. For a comprehensive understanding of the
Standard Test Data Format, read both this appendix and the STDF Specification Manual.
IMAGE Solutions V8.3 24-1
IMAGE Base Language: Standard Test Data Format: Generating STDF Files
Table of Contents Index Home Master Index Search Help
Generating STDF Files
The following events trigger IMAGE to generate an STDF file:
• Selecting DATALOG TO:STDF FILE on data collection setup display
• Typing the datalog -on -stdf command in a station window
• Typing the datastream -on <sid> -stdf command in a station window
• Selecting HISTOGRAM:ON on the data collection setup display
• Issuing the histoset -on command at the keyboard
The following events trigger IMAGE to close STDF files:
• IMAGE receives an endlot or end of wafer signal from handler or prober
• IMAGE encounters tl_endlot() function call in a test program
• Issuing a summary -final command at the keyboard
• Pressing the END LOT button on the Start Switch
The number and size of the STDF files depends on the following factors:
• Whether you turned on IMAGE’s datalogging feature and with what options. (See
“Datalog Reports” on page 6-13.)
• Whether you turned on IMAGE’s histogramming feature and with what options. (See
“Real Time Yield Trend Monitor” on page 6-112.)
If you leave datalogging turned off and histogramming turned off, IMAGE generates a single
STDF file containing summary report records.
If you turn on datalogging and turn off histogramming, IMAGE generates one STDF file,
called a datalog STDF file, containing test data records followed by summary report records.
To turn on datalogging, select the DATALOG TO: STDF FILE option on the data collection
setup display or type the datalog -on -stdf or datalog -on -stdf_file <filename>
commands in a station window. To turn off histogramming, select the HISTOGRAM:OFF
option on the data collection setup display or issue the histoset -off command.
If you turn off datalogging and turn on histogramming, IMAGE generates one STDF file,
called a histogram STDF file, containing test data records followed by summary report
records. To turn off datalogging, click on the DATALOG TO:STDF FILE option on the data
setup display or type the datalog -off command in a station window. To turn on
histogramming, select the HISTOGRAM:ON option on the data setup display or type the
histoset on command.
If you turn on both datalogging and histogramming, IMAGE generates a single datalog
STDF file and a single histogram STDF file.
IMAGE constructs datalog and histogram files in the same way using the same set of STDF
records. Therefore, if you turn on both datalogging and histogramming with identical
options:
datalog -on -stdf -test all
histoset -on -test all
you generate two identical STDF files.
IMAGE Solutions V8.3 24-2
IMAGE Base Language: Standard Test Data Format: Generating STDF Files
Table of Contents Index Home Master Index Search Help
NOTE
Since IMAGE constructs datalog and histogram STDF files in the same way, it cannot
differentiate between them. Therefore, you can generate a histogram from either a
histogram or datalog STDF file.
IMAGE Solutions V8.3 24-3
IMAGE Base Language: Standard Test Data Format: Sources for STDF File Data
Table of Contents Index Home Master Index Search Help
Sources for STDF File Data
IMAGE collects the test data it transfers to an STDF file from several sources:
• IMAGE calculations and measurements
• Test program statements
• Test program utility functions
• IMAGE commands
Some test data originates from calculations and measurements performed by IMAGE. For
example, when IMAGE performs a test measurement, it saves the result in an STDF record
field named RESULT.
Most test data originates from statements in a test program. For example, the following test
program sequencer statement provides IMAGE with test data for the STDF record fields in
table 24-1:
seq vout $1 >4.5mv <5.8mv "voltage reg" f(0);
Table 24-1. Correspondence Between Sequencer Statement Values and STDF Record Fields
Sequencer Value STDF Record Field
voltage reg or vout TEST_NAM1 in TSR
1 TEST_NUM in PTR
4.5 LO_LIMIT in PTR
mv UNITS in PTR
5.8 HI_LIMIT in PTR
0 SBIN_NUM in SBR
1. If the datalog label is present (voltage reg, in this example), it is put in TEST_NAM. If this label
is not present, the sequencer name (vout, in this example) is placed in TEST_NAM.
Some test data originates from test program utility functions. For example, the function
tl_set_lot_id() provides IMAGE with a value for STDF record field LOT_ID.
tl_write_highlim() provides IMAGE with the upper limit for the current test, which it
stores in STDF record field HI_LIMIT. See “Base IMAGE Functions” on page 26-1 for a list
and description of program utility functions that provide IMAGE with test data values for
STDF record fields.
Some test data originates from IMAGE commands. For example:
• The lot command provides values for STDF record fields LOT_ID, SBLOT_ID, and
STAT_NUM
• The operator command provides an operator name for STDF record field OPER_NAM
• The testcond command provides a test code value for STDF record field TEST_COD
IMAGE Solutions V8.3 24-4
IMAGE Base Language: Standard Test Data Format: Sources for STDF File Data
Table of Contents Index Home Master Index Search Help
For information on how a particular STDF record field is set in an STDF file, contact
Teradyne Applications Engineering.
IMAGE Solutions V8.3 24-5
IMAGE Base Language: Standard Test Data Format: STDF Records
Table of Contents Index Home Master Index Search Help
STDF Records
An STDF file is organized as a collection of STDF records appended one to another.
Serving as building blocks for STDF files, STDF records vary in type and size. For general
information on the characteristics of each STDF record in the complete STDF record set,
refer to the “STDF Record Types” chapter in the STDF Specification Manual. For specific
information on how IMAGE 7.0 supports and implements STDF records, see “IMAGE STDF
Record Set” on page 24-11.
IMAGE V7.0 STDF Record Set
IMAGE V7.0 supports all STDF records except the Audit Trail Record (ATR) and Retest
Data Record (RDR). IMAGE also supports a custom record for creating your own STDF
records. (See “IMAGE Custom Record” on page 24-37.)
Ordering of Records in an STDF File
IMAGE builds an STDF file from the STDF records. (Note the acronym for each record, for
example, MIR for Master Information Record.) The STDF file creation process (figure 24-1)
is as follows:
• IMAGE opens an STDF file and writes a File Attributes Record (FAR)
• IMAGE writes a Master Information Record (MIR) and a Site Description Record (SDR)
for each device lot in the file.
• IMAGE adds a Part Information Record (PIR) to the STDF file when it begins testing a
new device (beginning of test program) and adds a Part Results Record (PRR) when it
finishes testing a new device (end of test program).
• IMAGE adds a Begin Program Section Record (BPS) to the STDF file when it enters a
sequencer function in a test program and adds an End Program Section Record (EPS)
when it exits a sequencer function.
• IMAGE writes a Parametric Test Result Record (PTR) or a Functional Test Result
Record (FTR) to the STDF file when it executes a test function. You get the Multiple
Result Parametric Record (MPR) when doing a HSD50 test and leakage datalog is
enabled. Normally only an (FTR) is generated1.
1. For Catalyst 400 systems, the FTR may be two records, an FTR and an FTR-PLUS. For more information,
see section on page 24-16.
IMAGE Solutions V8.3 24-6
IMAGE Base Language: Standard Test Data Format: STDF Records
Table of Contents Index Home Master Index Search Help
STDF File
FAR One per STDF file
MIR
SDR
PIR For first part tested
BPS
One pair for each PTR, FTR, or One per test; record type
sequencer function MPR corresponding to test type
EPS
One pair for PRR
For nth part
each device tested PIR
BPS
PTR, FTR, or One per test; record type One pair for
MPR corresponding to test type each device
EPS lot
PRR
SBR Summary Report Records
HBR
TSR
PCR
MRR
Figure 24-1. IMAGE STDF File.
• Before IMAGE closes an STDF file following an end of lot, it writes a set of summary
records:
– Software Bin Records (SBR) for each software bin
– Hardware Bin Records (HBR) for each hardware bin
– Test Synopsis Records (TSR) summarizing results for each sequencer line
executed
• Once the summary records are written, IMAGE writes a Part Count Record (PCR) and
a Master Results Record (MRR) for the lot to the STDF file and closes it.
In STDF V4, the first PTR or FTR confirms static or global data for a particular test.
Examples are: limits, limit format, and result scaling factor. If this data should change,
subsequent PTRs and FTRs will contain the modified data. Figure 24-2 shows how records
are arranged in an STDF file.
IMAGE Solutions V8.3 24-7
IMAGE Base Language: Standard Test Data Format: STDF Records
Table of Contents Index Home Master Index Search Help
STDF File
FAR User opens an STDF file
MIR User turns on datalogging or opens new device lot with startlot command
SDR
PIR IMAGE begins executing test program, begins testing first device.
BPS IMAGE encounters SEQUENCER all_tests() function in user test program
PTR IMAGE writes result of leak_vcc() test. IMAGE generates one PTR.
PTR IMAGE writes result of lcap_vcc(). IMAGE generates one PTR.
FTR IMAGE writes result of functional_test(). IMAGE generates one FTR.
FTR IMAGE writes results of dig_leak().
MPR IMAGE writes results of dig_leak() if leakage datalog is enabled (AMS HSD50 only).
DTR IMAGE encounters lprintf() statement.
PTR IMAGE writes result of ac_rip() test. IMAGE generates one PTR
EPS IMAGE encounters end of SEQUENCER all_tests() function
PIR IMAGE re-executes test program, begins testing next device
PRR main() function of test program exits
SBR IMAGE receives endlot signal from handler or user issues summary -final command
SBR
main()
SBR {
- all_tests();
Test Program
HBR sort bin;
HBR }
HBR SEQUENCER all_tests()
- {
TSR seq leak_vcc() $1 >10v <50v "leakage" f(0);
TSR seq lcap_vcc() $2 >0uf <2e-05uf "lcap" f(2);
seq dig_leak() $3 <100ua f(4);
TSR
seq functional_test();
- lprintf("AC test is next");
PCR
MRR seq ac_rip() $(tnum) >20khz <30khz "ac rip" f(3)p(1);}
TESTF leak_vcc() {leak_vcc code}
TESTF lcap_vcc() {lcap_vcc code}
TESTF dig_leak() {dig_leak code}
TESTF functional_test() { functional_test code}
TESTF ac_rip() {ac_rip code}
Figure 24-2. Ordering of Records in an STDF File
STDF Record Structure
Each STDF record is a software data structure organized as a collection of data fields.
Figure 24-3 illustrates the internal structure of an STDF Parametric Test Result Record.
IMAGE Solutions V8.3 24-8
IMAGE Base Language: Standard Test Data Format: STDF Records
Table of Contents Index Home Master Index Search Help
Parametric Test Result Record
Field Name Field Description
Header fields
REC_LEN Bytes of data following header
REC_TYP Record type (15)
TEST_NUM Test number
HEAD_NUM Test head number
SITE_NUM Test site number
Test data fields TEST_FLG Test flags (fail, alarm, etc.)
PARM_FLG Parametric test flags
RESULT Test result
TEST_TXT Test description text or label
ALARM_ID Name of alarm
OPT_FLAG Optional data flag
RES_SCAL Test result scaling exponent
LLM_SCAL Low limit scaling exponent
Optional test data fields HLM_SCAL High limit scaling exponent
LO_LIMIT Low test limit value
HI_LIMIT High test limit value
UNITS Test units
C_RESFMT ANSI C result format string
C_LLMFMT ANSI C low limit format string
C_HLMFMT ANSI C high limit format string
LO_SPEC Low specification limit value
TEST_TXT High specification limit value
Figure 24-3. Internal Organization of Parametric Test Result Record.
At the top of each STDF record are header fields that serve as the record’s identification.
Collectively known as an STDF record header, these header fields are named REC_LEN,
REC_TYP, and REC_SUB.
Header Fields
• REC_LEN specifies the number of bytes of data in a record following the record header.
Stated mathematically:
Record_size = size of STDF record, expressed as number of bytes
Header_size = size of STDF record header = 4 bytes
REC_LEN = Record_size – Header_size = Record_size – 4
• REC_TYP contains an integer value identifying record type. For example, IMAGE collects
test data for Parametric Test Result Records (PTRs) and Functional Test Result
Records (FTRs) after each test execution. No other STDF records have this
IMAGE Solutions V8.3 24-9
IMAGE Base Language: Standard Test Data Format: STDF Records
Table of Contents Index Home Master Index Search Help
characteristic. To indicate that PTR and FTR are the only records of this type, IMAGE
sets their REC_TYP field to integer value 15 (using STDF conventions) and sets the
REC_TYP field for all other STDF records to values other than 15. Each REC_TYP setting
conforms to STDF specifications, as stated in “Record Types and Subtypes” on page
2-3 of the STDF Specification Manual.
• REC_SUB contains an integer value identifying a specific STDF record of a given type
(REC_TYP). For example, both STDF records PTR and FTR are of the same type
(REC_TYP=15). IMAGE distinguishes PTRs from FTRs by setting the REC_SUB field for
all PTRs to integer value 10 and the REC_SUB field for all FTRs to integer value 20. As
with REC_TYP fields, each REC_SUB setting conforms to STDF specifications, as stated
in “Record Types and Subtypes” on page 2-3 of the STDF Specification Manual.
Each STDF record in the STDF record set can be uniquely identified by the integer value in
its REC_TYP and REC_SUB field. Consequently, Parametric Test Result Records can be
identified by name (Parametric Test Result Record), by acronym (PTR), or by their record
identifier fields (REC_TYP=15, REC_SUB=10).
Test Data Fields
Following the header fields in an STDF record are a series of test data fields which act as
storage compartments for test data. Each data field is designated to contain a specific item
and type of test data. For example, the RESULT data field in a Parametric Test Result Record
is of type real and is designated to store a test result.
Optional Test Data Fields
Certain test data fields in STDF records are defined as optional. Optional fields must be
present, but you can indicate that values in these fields are missing or invalid. Some fields
have a predefined value that means that the data for the field is missing, and some records
include an Optional Data bit field.
IMAGE Solutions V8.3 24-10
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
IMAGE STDF Record Set
This section contains tables describing all data fields for each STDF record supported by
IMAGE V6.4 and later.
• “Begin Program Section Record (BPS)” on page 24-12
• “Datalog Text Record (DTR)” on page 24-13
• “End Program Section Record (EPS)” on page 24-13
• “File Attributes Record (FAR)” on page 24-14
• “Functional Test Record (FTR)” on page 24-15
• “Functional Test Result (FTR)-PLUS Record” on page 24-16
• “Hardware Bin Record (HBR)” on page 24-17
• “Master Information Record (MIR)” on page 24-18
• “Multiple-Result Parametric Record (MPR)” on page 24-21
• “Master Results Record (MRR)” on page 24-23
• “Parametric Test Record (PTR)” on page 24-24
• “Part Count Record (PCR)” on page 24-26
• “Part Information Record (PIR)” on page 24-27
• “Part Results Record (PRR)” on page 24-27
• “Pin List Record (PLR)” on page 24-28
• “Pin Map Record (PMR)” on page 24-29
• “Site Description Record (SDR)” on page 24-30
• “Software Bin Record (SBR)” on page 24-31
• “Test Synopsis Record (TSR)” on page 24-32
• “Wafer Configuration Record (WCR)” on page 24-34
• “Wafer Information Record (WIR)” on page 24-36
• “Wafer Results Record (WRR)” on page 24-36
• “IMAGE Custom Record” on page 24-37
A key to the tables’ column headers is provided in figure 24-4.
IMAGE Solutions V8.3 24-11
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
STDF name assigned Short description of data yes = IMAGE V7.0 supports the field.
to field assigned to field
no = IMAGE V7.0 does not support the field.
Supported by Data
Field Name Field Description IMAGE V7.0? Type
B*1 One byte bit-encoded data
B*n Variable length bit encoded data
I*1 One byte signed integer
I*2 Two byte signed integer
I*4 Four byte signed integer
C*1 Single character (1 byte)
C*7 Seven character string (7 bytes)
C*n Variable length character string. First byte of string
contains an unsigned count of number of bytes in the
character string. Maximum length = 255 bytes.
C*f Variable length character string. String length stored
in another field.
U*1 One byte unsigned integer
U*2 Two byte unsigned integer
U*4 Four byte unsigned integer
R*4 Four byte floating point number
R*8 Eight byte floating point number
D*n Variable length bit encoded data
N*1 Unsigned integer data stored in nibble
nxTYPE Array of data of the type specified.
Figure 24-4. Key to STDF Record Field Tables.
Begin Program Section Record (BPS)
A BPS (table 24-2) marks the beginning of a sequencer function in a test program. A BPS
and EPS (End Program Section Record) delimit a sequencer function: a BPS marks its
beginning and an EPS marks its end. IMAGE writes a BPS to all open STDF files whenever
it encounters a sequencer function call.
Table 24-2. Begin Program Section Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
IMAGE Solutions V8.3 24-12
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-2. Begin Program Section Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_TYP Record type (20) yes U*1
REC_SUB Record sub-type (10) yes U*1
SEQ_NAME Datalog label for test yes C*n
For more information, see “Begin Program Section Record (BPS)” on page 3-55 in the
STDF Specification Manual.
Datalog Text Record (DTR)
A DTR (table 24-3) enables you to add a 255 character message to an STDF file. Any
lprintf() function call in your test program causes IMAGE to insert your message in a
DTR’s TEXT_DAT field. IMAGE then copies the DTR to a datalog STDF file. For example,
the function call
lprintf("Test should fail");
inserts the text string Test should fail into the TEXT_DAT field of a DTR.
IMAGE writes a DTR to a datalog STDF file whenever it encounters an lprintf() function
call in your test program.
Table 24-3. Datalog Text Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (50) yes U*1
REC_SUB Record sub-type (30) yes U*1
TEXT_DAT ASCII text string yes C*n
For more information, see “Datalog Text Record (DTR)” on page 3-60 in the STDF
Specification Manual.
End Program Section Record (EPS)
An EPS (table 24-4) marks the end of a sequencer function in a test program. A BPS (Begin
Program Section Record) and an EPS delimit a sequencer function: a BPS marks its
IMAGE Solutions V8.3 24-13
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
beginning and an EPS marks its end. IMAGE writes an EPS to all open STDF files
immediately before returning from a sequencer function call.
Table 24-4. End Program Section Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (20) yes U*1
REC_SUB Record sub-type (20) yes U*1
In versions of IMAGE before V5.6, if a test failed or a run-time error occurred, an End
Program Section record (EPS) was not generated for the failing sequencer. In V5.6 and
later, you can optionally modify this behavior and have an EPS record written to the datalog
stream.
To datalog an EPS record, call the function tl_datalog_endseq_on_fail() and pass it a
nonzero value. To turn this feature off, call the same function with an argument whose value
is zero.
By default IMAGE will not datalog an EPS record when a test fails or encounters a run-time
error.
For more information, see “End Program Section Record (EPS)” on page 3-56 in the STDF
Specification Manual.
File Attributes Record (FAR)
A File Attributes Record (FAR) (table 24-5) contains the information necessary to determine
how to decode the STDF data contained in the file.
Table 24-5. File Attributes Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (0) yes U*1
REC_SUB Record sub-type (10) yes U*1
CPU_TYPE Type of CPU that wrote this file yes U*1
STDF_VER STDF version number yes U*1
IMAGE Solutions V8.3 24-14
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
CPU_TYP
Indicates which type of CPU wrote this STDF file. IMAGE sets CPU_TYP to 1. According to
STDF specification, CPU_TYP=1 implies that Sun 1, Sun 2, Sun 3, or Sun 4 computer wrote
this STDF file.
STDF_VER
Identifies which version of the STDF specification IMAGE used when generating STDF files.
Allows data analysis programs to handle STDF specification enhancements.
For more information, see “File Attributes Record (FAR)” on page 3-5 in the STDF
Specification Manual.
Functional Test Record (FTR)
A FTR (table 24-6) contains the test results from a single execution of a functional test in a
test program. The first occurrence of this record also establishes the default values for all
semistatic information about the test, including limits, limit format, and result scaling factor.
Table 24-6. Functional Test Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (15) yes U*1
REC_SUB Record sub-type (20) yes U*1
TEST_NUM Test number yes U*4
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number yes U*1
TEST_FLG Test flags (such as fail or alarm) yes B*1
OPT_FLG Optional data flag yes B*1
CYCL_CNT Cycle count of vector yes U*4
REL_VADR Relative vector address yes U*4
REPT_CNT Repeat count of vector no U*4
NUM_FAIL Number of pins with one or more failures yes U*4
XFAIL_AD X logical device failure address no I*4
YFAIL_AD Y logical device failure address no I*4
IMAGE Solutions V8.3 24-15
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-6. Functional Test Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
VECT_OFF Offset from vector of interest yes I*2
RTN_ICNT Count of return data PMR indexes yes U*2
PGM_ICNT Count of programmed state indexes yes U*2
RTN_INDX Array of return data PMR indexes yes nxU*2
RTN_STAT Array of returned states yes nxU*1
PGM_INDX Array of programmed state indexes yes nxU*2
PGM_STAT Array of programmed states yes nxU*1
FAIL_PIN Failing pin bitfield (by tester channel) yes D*n
VECT_NAM Vector module pattern name yes C*n
TIME_SET Time set name yes C*n
OP_CODE Vector Op Code yes C*n
TEST_TXT Descriptive text or label yes C*n
ALARM_ID Name of alarm no C*n
PROG_TXT Additional programmed information no C*n
RSLT_TXT Additional result information no C*n
PATG_NUM Pattern generator number no U*1
SPIN_MAP Bit map of enabled comparators no D*n
FAIL_PIN
Encoded with PMR index 0 in bit 0 of the field, PMR index 1 in the first position, and so on.
Bits representing PMR indexes of failing pins are set to 1.
For more information, see “Functional Test Record (FTR)” on page 3-49 in the STDF
Specification Manual.
Functional Test Result (FTR)-PLUS Record
IMAGE V6.4 and later provides a new FTR-PLUS Record to handle larger-than-a-nibble
indexes for 4-character data codes. The FTR-PLUS Record looks like a subset of the
standard Functional Test Record (FTR) but it uses 8-bit fields (char) for the pgm_stat array,
rather than 4-bit fields. The FTR-PLUS Record always precedes the FTR Record with which
it is paired.
IMAGE Solutions V8.3 24-16
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
The definition of the IMAGE FTR-PLUS Record can be found in the header file
image_data_recs.h, located in the directory $IMAGEBIN/itlh. It is defined as follows:
a. typedef struct
{
unsigned short rec_len; /* Bytes of data to follow */
unsigned char rec_typ; /* Record Type */
unsigned char rec_sub; /* Record sub-type */
unsigned int test_num; /* Test number */
unsigned char head_num; /* Test head number */
unsigned char site_num; /* Test site number */
unsigned short pgm_icnt; /* Count of programmed state indexes */
unsigned short *pgm_indx; /* Array of programmed state indexes */
char *pgm_stat; /* Array of programmed states */
} IMAGE_FTR_PLUS;
The datalog formatters (including custom datalog formatters) treat a pair of FTR-PLUS and
FTR Records as one FTR. Since the internal memory representation of the existing FTR
uses a full 8 bits to store the 4 bits of data, existing formatters need only be relinked to the
new datalog formatter base code to work with the new records.
NOTE
If your code explicitly masks the pgm_stat 8-bit code with 0xF to force it to 4 bits, or if it
makes any other hard-coded assumptions that the data is no greater than 0xF, then this
code must be modified to work with the new records.
Hardware Bin Record (HBR)
An HBR (table 24-7) stores a count of the devices deposited into a particular bin. Like SBRs
(Software Bin Records) and TSRs (Test Synopsis Records), HBRs are summary report
records. IMAGE writes all its summary report records to all open STDF files when it closes
them. Events that cause IMAGE to close STDF files include:
• Issuing a summary -final command at a workstation.
• IMAGE receives an endlot or end of wafer signal from a handler or prober.
• IMAGE encounters a tl_endlot() function call in a test program.
• Pressing the END LOT button on the Start Switch.
IMAGE appends summary report records to STDF files in this order:
1. SBRs
2. HBRs
3. TSRs
followed by a single Part Count Record (PCR) and Master Results Record (MRR).
IMAGE Solutions V8.3 24-17
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-7. Hardware Bin Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (1) yes U*1
REC_SUB Record sub-type (40) yes U*1
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number no U*1
HBIN_NUM Hardware bin number yes U*2
HBIN_CNT Number of devices deposited in bin yes U*4
HBIN_PF Pass-fail indication yes C*1
HBIN_NAM Name of hardware bin yes C*n
HEAD_NUM
If this HBR contains a summary of the hardware bin counts for all test sites, this field must
be set to 255.
HBIN_NUM
Legal values range from 0 to 32767.
HBIN_PF
This field indicates whether a hardware bin was a passing or failing bin. Valid values are:
P = Passing bin
F = Failing bin
space = unknown
For more information, see “Hardware Bin Record (HBR)” on page 3-13 in the STDF
Specification Manual.
Master Information Record (MIR)
An MIR (table 24-8) contains global test information for a device lot. IMAGE generates a
single MIR for each device lot. However, if the datastream is connected, disconnected, and
then reconnected without doing a summary before reconnecting, an additional MIR record
is sent during the reconnection. An MIR is always the second record in an STDF file after
IMAGE Solutions V8.3 24-18
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
the File Attributes Record (FAR). IMAGE writes an MIR to all open STDF files in response
to either of two events:
• Selecting the STDF file as the destination for the datalog. (DATALOG TO STDF FILE: ON)
• Opening a new device lot with the startlot command.
Table 24-8. Master Information Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (1) yes U*1
REC_SUB Record sub-type (10) yes U*1
SETUP_T Date and time of test program setup yes U*4
START_T Date and time first device tested yes U*4
STAT_NUM Tester station number yes U*1
MODE_COD Test mode code (e.g. prod, dev) yes C*1
RTST_COD Lot retest code yes C*1
PROT_COD Data protection code no C*1
BURN_TIM Burn-in time (in minutes) yes U*2
CMOD_COD Command mode code no C*1
LOT_ID Lot ID (customer specified) yes C*n
PART_TYP Device type (or product ID) yes C*n
NODE_NAM Name of node generating data yes C*n
TSTR_TYP Tester type string yes C*n
JOB_NAM Test program name yes C*n
JOB_REV Test program revision number yes C*n
SBLOT_ID Sublot ID yes C*n
OPER_NAM Operator name or ID (at setup time) yes C*n
EXEC_TYP Tester executive software type yes C*n
EXEC_VER Tester executive software version number yes C*n
TEST_COD Test phase or step code yes C*n
TST_TEMP Test temperature yes C*n
IMAGE Solutions V8.3 24-19
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-8. Master Information Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
USER_TXT Generic user text no C*n
AUX_FILE Name of auxiliary data file no C*n
PKG_TYP Package type yes C*n
FAMLY_ID Product family ID yes C*n
DATE_COD Date code no C*n
FACIL_ID Test facility ID yes C*n
FLOOR_ID Test floor ID yes C*n
PROC_ID Fabrication process ID yes C*n
OPER_FRQ Operation frequency or step yes C*n
SPEC_NAM Test specification name yes C*n
SPEC_VER Test specification version number yes C*n
FLOW_ID Test flow ID yes C*n
SETUP_ID Test setup ID yes C*n
DSGN_REV Device design revision yes C*n
ENG_ID Engineering lot ID yes C*n
ROM_COD ROM code ID yes C*n
SERL_NUM Tester serial number yes C*n
SUPR_NAM Supervisor name or ID yes C*n
SETUP_T
Specifies when datalogging began. IMAGE represents data and time as the number of
seconds since midnight, January 1, 1970, adjusted for local time.
START_T
Specifies when first device was tested. IMAGE represents data and time as the number of
seconds since midnight, January 1, 1970, adjusted for local time.
IMAGE Solutions V8.3 24-20
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
PROT_COD
User-defined field indicating the protection desired for the test data being stored. Valid
values are the ASCII characters 0–9 and A–Z. A space in this field indicates a missing value
(default protection).
CMOD_COD
Indicates the tester command mode during testing. You or IMAGE define command mode
values. Valid values are the ASCII characters 0–9 and A–Z. A space indicates a missing
value.
TSTR_TYP
Identifies the type of tester performing the tests, such as A500 or A510.
TEST_COD
Specifies the phase of device testing or test conditions, such as WFR for wafer test or HOT for
hot test.
The testcond command sets the TEST_COD field. For example:
testcond HOT
sets TEST_COD to HOT. Valid characters for TEST_COD are ASCII characters 0–9 and A–Z.
For a test code of less than three characters, IMAGE inserts the test code into a TEST_COD
field left justified and padded with spaces.
TST_TEMP
The test temperature is an ASCII string. Therefore, it can be stored as degrees Celsius,
Fahrenheit, Kelvin, or any other scale. It can also be expressed in terms like HOT, ROOM, and
COLD.
For more information, see “Master Information Record (MIR)” on page 3-7 in the STDF
Specification Manual.
Multiple-Result Parametric Record (MPR)
An MPR (table 24-9) contains the results of a single execution of a parametric test in the test
program where that test returns multiple values. The first occurrence of this record also
establishes the default values for all semistatic information about the test, such as limits,
units, and scaling. The MPR is related to the Test Synopsis Record (TSR) by test number,
head number, and site number.
IMAGE Solutions V8.3 24-21
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-9. Multiple-Result Parametric Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (15) yes U*1
REC_SUB Record sub-type (15) yes U*1
TEST_NUM Test number yes U*4
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number yes U*1
TEST_FLG Test flags (such as fail or alarm) yes B*1
PARM_FLG Parametric test flags (such as drift) yes B*1
RTN_ICNT Count (j) of PMR indexes yes U*2
RSLT_CNT Count (k) of returned results yes U*2
RTN_STAT Array of returned states yes jxN*1
RTN_RSLT Array of returned results yes kxR*4
TEST_TXT Descriptive text or label yes C*n
ALARM_ID Name of alarm no C*n
OPT_FLAG Optional data flag yes B*1
RES_SCAL Test result scaling exponent yes I*1
LLM_SCAL Test low limit scaling exponent yes I*1
HLM_SCAL Test high limit scaling exponent yes I*1
LO_LIMIT Test low limit value yes R*4
HI_LIMIT Test high limit value yes R*4
START_IN Starting input value (condition) no R*4
INCR_IN Increment of input condition no R*4
RTN_INDX Array of PMR indexes yes jxU*2
UNITS Units of returned results no C*n
UNITS_IN Input condition units no C*n
C_RESFMT ANSI C result format string yes C*n
C_LLMFMT ANSI C low limit format string yes C*n
IMAGE Solutions V8.3 24-22
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-9. Multiple-Result Parametric Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
C_HLMFMT ANSI C high limit format string yes C*n
LO_SPEC Low specification limit value no R*4
HI_SPEC High specification limit value no R*4
RTN_INDX
The values used are:
5 = Failed low
6 = Failed high
2 = midband == PASSED
The RTN_INDX values are the same values that you would expect to find for the FTR
record, that is, channel number indexes not pin map record indexes.
For more information, see “Multiple-Result Parametric Record (MPR)” on page 3-43 in the
STDF Specification Manual.
Master Results Record (MRR)
An MRR (table 24-10) contains summary statistics for a device lot. An MRR complements
an MIR (Master Information Record). Both contain global test data; a single MIR introduces
the test data in an STDF file, and a single MRR concludes it. An MIR is always the second
record in an STDF file (after the File Attributes Record), and an MRR is always the last
record.
IMAGE writes an MRR to all open STDF files when it closes them. Events that cause IMAGE
to close STDF files include:
• You issue a summary -final command at a workstation.
• IMAGE receives an endlot or end of wafer signal from a handler or prober.
• IMAGE encounters a tl_endlot() function call in a test program.
• You press the END LOT button on the Start Switch.
Table 24-10. Master Results Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (1) yes U*1
IMAGE Solutions V8.3 24-23
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-10. Master Results Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_SUB Record sub-type (20) yes U*1
FINISH_T Date and time last device tested yes U*4
DISP_COD Lot disposition code no C*1
USR_DESC Lot description supplied by user no C*n
EXC_DESC Lot description supplied by exec no C*n
For more information, see “Master Results Record (MRR)” on page 3-10 in the STDF
Specification Manual.
Parametric Test Record (PTR)
A PTR (table 24-11) contains the results from a single execution of a parametric test in a
test program. The first occurrence of this record also establishes the default values for all
semistatic information about the test, such as limits, units, and scaling. The PTR is related
to the Test Synopsis Record (TSR) by test number, head number, and site number.
Table 24-11. Parametric Test Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (15) yes U*1
REC_SUB Record sub-type (10) yes U*1
TEST_NUM Test number yes U*4
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number yes U*1
TEST_FLG Test flags (such as fail and alarm) yes B*1
PARM_FLG Parametric test flags (such as drift) no B*1
RESULT Test result yes R*4
TEST_TXT Test description text or label yes C*n
ALARM_ID Name of alarm no C*n
OPT_FLAG Optional data flag yes B*1
IMAGE Solutions V8.3 24-24
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-11. Parametric Test Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
RES_SCAL Test result scaling exponent yes I*1
LLM_SCAL Low limit scaling exponent yes I*1
HLM_SCAL High limit scaling exponent yes I*1
LO_LIMIT Low test limit value yes R*4
HI_LIMIT High test limit value yes R*4
UNITS Test units yes C*n
C_RESFMT ANSI C result format string yes C*n
C_LLMFMT ANSI C low limit format string yes C*n
C_HLMFMT ANSI C high limit format string yes C*n
LO_SPEC Low specification limit value no R*4
HI_SPEC High specification limit value no R*4
C_RESFMT
Is an ANSI C format string for use in formatting the test result.
C_LLMFMT
Is an ANSI C format string for use in formatting the low test and spec limits.
C_HLMFMT
Is an ANSI C format string for use in formatting the high test and spec limits.
Test Result Formatting
IMAGE uses the following fields to format a test result:
• RES_SCAL contains the value for its exponent
• C_RESFMT contains the result format string
• UNITS contains the symbols for its units
IMAGE uses the following fields to format the low limit for a test result:
• LLM_SCAL contains the value for the low limit’s exponent
• C_LLMFMT contains the result format string
• UNITS contains the symbols for the low limit’s units
IMAGE Solutions V8.3 24-25
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
IMAGE uses the following fields to format the high limit for a test result:
• HLM_SCAL contains the value for the high limit’s exponent
• C_HLMFMT contains the result format string
• UNITS contains the symbols for the high limit’s units
For more information, see “Parametric Test Record (PTR)” on page 3-37 in the STDF
Specification Manual.
Part Count Record (PCR)
A Part Count Record (PCR) (table 24-12) contains the part count total for one or all test
sites.
Table 24-12. Part Count Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (1) yes U*1
REC_SUB Record sub-type (30) yes U*1
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number no U*1
PART_CNT Number of devices tested yes U*4
RTST_CNT Number of devices retested yes U*4
ABRT_CNT Number of aborts during testing yes U*4
GOOD_CNT Number of good (passed) parts tested yes U*4
FUNC_CNT Number of functional parts tested no U*4
HEAD_NUM
This field must be set to 255.
GOOD_CNT
A part is considered good when it is binned into one of the “passing” hardware bins.
For more information, see “Part Count Record (PCR)” on page 3-11 in the STDF
Specification Manual.
IMAGE Solutions V8.3 24-26
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Part Information Record (PIR)
A PIR (table 24-13) marks, in an STDF file, where testing begins for each device in a lot. A
PIR and a PRR (Parts Results Record) bracket all stored information pertaining to one
tested device. IMAGE writes a PIR to all open STDF files each time it begins testing a
device.
Table 24-13. Part Information Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (5) yes U*1
REC_SUB Record sub-type (10) yes U*1
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number yes U*1
For more information, see “Part Information Record (PIR)” on page 3-31 in the STDF
Specification Manual.
Part Results Record (PRR)
A PRR (table 24-14) summarizes the test results from all tests performed on a single device.
A PIR and a PRR (Part Results Record) bracket all the stored information in an STDF file
pertaining to one tested device. IMAGE writes a PRR to all open STDF files after it finishes
testing a device.
Table 24-14. Part Results Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (5) yes U*1
REC_SUB Record sub-type (20) yes U*1
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number yes U*1
PART_FLG Part information flag no B*1
NUM_TEST Number of tests executed yes U*2
IMAGE Solutions V8.3 24-27
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-14. Part Results Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
HARD_BIN Hardware bin number yes U*2
SOFT_BIN Software bin number yes U*2
X_COORD (Wafer) X coordinate yes I*2
Y_COORD (Wafer) Y coordinate yes I*2
TEST_T Elapsed test time in milliseconds no U*4
PART_ID Device identification number yes C*n
PART_TXT Part description text yes C*n
PART_FIX Part repair information yes B*n
X_COORD, Y_COORD, PART_ID
X_COORD and Y_COORD have legal values in the range -32767 to 32767. A value of -32768
indicates a missing value.
Note that X_COORD, Y_COORD, and PART_ID are all optional, but you should provide either the
PART_ID or the X_COORD and Y_COORD to make the resultant data useful for analysis.
PART_FIX
This is an application-specific field for storing device repair information. It may be used for
bit-encoded, integer, floating point, or character information. Regardless of the information
stored, the first byte must contain the number of bytes to follow. This field can be decoded
only by an application-specific analysis program.
For more information, see “Part Results Record (PRR)” on page 3-32 in the STDF
Specification Manual.
Pin List Record (PLR)
IMAGE V6.4 and later provides a new way of handling 4-character data codes in the PLR.
In any of the previous modes of IMAGE, including dual drive mode, data codes were a
maximum of two characters long. These two characters are stored in the STDF Pin List
Record (PLR) arrays called pgm_char and pgm_chal. The pgm_indx and pgm_stat fields
are stored in the Functional Test Record (FTR) for each pin for each test. The pgm_indx
tells you which string in the pgm_char and pgm_chal fields to look at and the pgm_stat field
tells you which character in those strings. For example, the PLR fields might look like the
following:
IMAGE Solutions V8.3 24-28
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Plr.pgm_char: Plr.pgm_chal:
0: 0X-1LMVH 0: <NULL> (1-character code)
1: 00001111 1: LXVHLXVH
2: 01010101 2: 00110011
If the FTR has a pgm_indx=1 and pgm_stat=4, the 2-character data code is 1L, because
pgm_char[pgm_indx=1][pgm_stat=4] is 1 and pgm_chal[pgm_indx=1][pgm_stat=4] is
L. If the FTR had a pgm_indx=0 and pgm_stat=1, then the 1-letter data code is X, because
pgm_char[pgm_indx=0][pgm_stat=1] is X, and pgm_chal[pgm_indx=0] is NULL.
Several modes on Catalyst 400 testers require 4-character data codes. In the existing STDF
PLR, the first character of both 1-character and 2-character codes is stored in the PLR
pgm_char field, and the second character of 2-character codes is stored in the PLR
pgm_chal field. To handle 4-character codes, and to make them obviously different from 1-
and 2-character codes, the pgm_char field is left blank for 4-character codes, and the entire
4-character code is placed in the pgm_chal field, with space separators. Thus, to store the
code 0000, 0001, 0010, 0011, 0100, etc., you see:
Plr.pgm_char: Plr.pgm_chal:
0: <NULL> 0: 0000 0001 0010 0011 0100 ...
In this case, if the FTR had a pgm_indx=0 and pgm_stat=1, then the 4-character data code
is 0001 because pgm_char[pgm_indx=0] is NULL and the 4 characters starting at
pgm_chal[pgm_indx=0][pgm_stat=1 * 5) +1] are 0001.
For more information, see “Pin List Record (PLR)” on page 3-20 in the STDF Specification
Manual.
Pin Map Record (PMR)
A PMR (table 24-15) provides indexing for tester channel names and maps them to physical
and logical pin names. Each PMR defines the information for a single channel/pin
combination. IMAGE only supports this record for digital channels.
Table 24-15. Pin Map Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (1) yes U*1
REC_SUB Record sub-type (60) yes U*1
PMR_INDX Unique index associated with pin yes U*2
CHAN_TYP Channel type yes U*2
CHAN_NAM Channel name yes C*n
PHY_NAM Physical name of pin no C*n
IMAGE Solutions V8.3 24-29
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-15. Pin Map Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
LOG_NAM Logical name of pin yes C*n
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number yes U*1
PMR_INDX
This field is used for the pin number.
CHAN_NAM
This field is used for the channel number.
LOG_NAM
This field is used for the pin name.
For more information, see “Pin Map Record (PMR)” on page 3-17 in the STDF Specification
Manual.
Site Description Record (SDR)
An SDR (table 24-16) contains the configuration information for one or more test sites,
connected to one test head, that compose a site group.
Table 24-16. Site Description Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (1) yes U*1
REC_SUB Record sub-type (80) yes U*1
HEAD_NUM Test head number yes U*1
SITE_GRP Site group number no U*1
SITE_CNT Number of test sites in test group yes U*1
SITE_NUM Array of test site numbers yes nxU*1
HAND_TYP Handler or prober type no C*n
IMAGE Solutions V8.3 24-30
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-16. Site Description Record Fields (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
HAND_ID Handler or prober ID yes C*n
CARD_TYP Probe card type yes C*n
CARD_ID Prober card ID yes C*n
LOAD_TYP Load board type yes C*n
LOAD_ID Load board ID yes C*n
DIB_TYP DIB board type no C*n
DIB_ID DIB board ID no C*n
CABL_TYP Interface cable type yes C*n
CABL_ID Interface cable ID yes C*n
CONT_TYP Handler contactor type yes C*n
CONT_ID Handler contactor ID yes C*n
LASR_TYP Laser type yes C*n
LASR_ID Laser ID yes C*n
EXTR_TYP Extra equipment type yes C*n
EXTR_ID Extra equipment ID yes C*n
For more information, see “Site Description Record (SDR)” on page 3-24 in the STDF
Specification Manual.
Software Bin Record (SBR)
An SBR (table 24-17) stores a count of the number of devices assigned to a logical bin. In
contrast to an SBR, an HBR (Hardware Bin Record) stores a count of the number of devices
actually deposited into a physical bin. HBRs record physical events, while SBRs record
software events. For information on mapping software bins to hardware bins, see “Assigning
Bin Numbers” on page 15-6.
Like HBRs (Hardware Bin Records) and TSRs (Test Synopsis Records), SBRs are
summary report records. IMAGE writes all its summary report records to all open STDF files
when it closes them. Events that cause IMAGE to close STDF files include
• You issue a summary -final command at a workstation.
• IMAGE receives an endlot or end of wafer signal from a handler or prober.
• IMAGE encounters a tl_endlot() function call in a test program.
IMAGE Solutions V8.3 24-31
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
• You press the END LOT button on the Start Switch.
IMAGE appends summary report records to STDF files in this order:
1. SBRs
2. HBRs
3. TSRs
followed by a single Master Results Record (MRR).
Table 24-17. Software Bin Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (1) yes U*1
REC_SUB Record sub-type (50) yes U*1
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number no U*1
SBIN_NUM Software bin number yes U*2
SBIN_CNT Number of devices in software bin yes U*4
SBIN_PF Pass/fail indication yes C*1
SBIN_NAM Name of software bin yes C*n
For more information, see “Software Bin Record (SBR)” on page 3-15 in the STDF
Specification Manual.
Test Synopsis Record (TSR)
A TSR (table 24-18) contains test execution and failure counts for each parametric or
functional test in a test program. Like HBRs (Hardware Bin Records) and SBRs (Software
Bin Records), TSRs are summary report records. IMAGE writes all its summary report
records to all open STDF files when it closes them. Events that cause IMAGE to close STDF
files include
• You issue a summary -final command at a workstation.
• IMAGE receives an endlot or end of wafer signal from a handler or prober.
• IMAGE encounters a tl_endlot() function call in a test program.
• You press the END LOT button on the Start Switch.
IMAGE appends summary report records to STDF files in this order:
1. SBRs
IMAGE Solutions V8.3 24-32
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
2. HBRs
3. TSRs
followed by one Part Count Record (PCR) and Master Results Record (MRR).
Table 24-18. Test Synopsis Record Fields
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (10) yes U*1
REC_SUB Record sub-type (30) yes U*1
HEAD_NUM Test head number yes U*1
SITE_NUM Test site number no U*1
TEST_TYP Test type yes C*1
TEST_NUM Test number yes U*4
EXEC_CNT Number of test executions yes U*4
FAIL_CNT Number of test failures yes U*4
ALRM_CNT Number of alarmed tests yes U*4
TEST_NAM Test name yes C*n
SEQ_NAME Datalog label for test yes C*n
TEST_LBL Test label or text yes C*n
OPT_FLG Optional data flag yes B*1
TEST_TIM Average test execution time in seconds no R*4
TEST_MIN Lowest test result value yes R*4
TEST_MAX Highest test result value yes R*4
TST_SUMS Sum of test result values yes R*4
TST_SQRS Sum of squares of test result values yes R*4
HEAD_NUM
This field must be set to 255.
IMAGE Solutions V8.3 24-33
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
TEST_TYP
Indicates what type of test the summary data is for. Either F (for functional) or P (for
parametric) is automatically set for any test that ran during the lot.
SEQ_NAME
STDF convention dictates that SEQ_NAME receive the name of a program section (or
sequencer). IMAGE deviates from this convention by assigning to SEQ_NAME the datalog
label for a particular test. For example, given the sequencer statement:
seq in_leak() $1 >-10ua <10ua "input leak pin 14" f(0);
IMAGE copies the datalog label input leak pin 14 to SEQ_NAME. If you omit the datalog
label from the sequencer statement, as in:
seq in_leak() $1 >-10ua <10ua f(0);
IMAGE responds by creating a datalog label from the test function name and copies it to
SEQ_NAME. In this case, IMAGE copies in_leak to SEQ_NAME.
For more information, see “Test Synopsis Record (TSR)” on page 3-35 in the STDF
Specification Manual.
Wafer Configuration Record (WCR)
A Wafer Configuration Record (WCR) contains the configuration information for wafers
tested by the test program. The WCR (table 24-19) provides the dimensions and orientation
information for all wafers and dice in the lot. This record is used only when testing at wafer
probe time.
Table 24-19. Wafer Configuration Record
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (2) yes U*1
REC_SUB Record sub-type (30) yes U*1
WAFR_SIZ Diameter of wafer in WF_UNITS yes R*4
DIE_HT Height of die in WF_UNITS yes R*4
DIE_WID Width of die in WF_UNITS yes R*4
WF_UNITS Units for wafer and die dimensions yes U*1
WF_FLAT Orientation of wafer flat yes C*1
CENTER_X X coord of center die on wafer yes I*2
IMAGE Solutions V8.3 24-34
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-19. Wafer Configuration Record (Continued)
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
CENTER_Y Y coord of center die on wafer yes I*2
POS_X Positive X direction of wafer yes C*1
POS_Y Positive Y direction of wafer yes C*1
WF_UNITS
Has these valid values:
0 = Unknown units
1 = Units are in inches
2 = Units are in centimeters
3 = Units are in millimeters
4 = Units are in mils
WF_FLAT
Has these valid values:
Space = Unknown
U = Up
D = Down
L = Left
R = Right
CENTER_X
Use the value -32768 to indicate that the field is invalid.
POS_X
Has these valid values:
Space = Unknown
L = Left
R = Right
POS_Y
Has these valid values:
Space = Unknown
U = Up
D = Down
IMAGE Solutions V8.3 24-35
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
For more information, see “Wafer Configuration Record (WCR)” on page 3-29 in the STDF
Specification Manual.
Wafer Information Record (WIR)
A Wafer Information Record (WIR) acts as a marker to indicate where testing of a particular
wafer begins for each wafer tested by the test program. The WIR (table 24-20) and the
Wafer Results Record (WRR) bracket all the stored information pertaining to one tested
wafer. This record is used only when testing at wafer probe.
Table 24-20. Wafer Information Record
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (2) yes U*1
REC_SUB Record sub-type (10) yes U*1
HEAD_NUM Test head number yes U*1
SITE_GRP Site group number no U*1
START_T Date and time first part tested yes U*4
WAFER_ID Wafer ID yes C*n
WAFER_ID
This field is optional but is strongly recommended to make the resulting data files as useful
as possible.
For more information, see “Wafer Information Record (WIR)” on page 3-26 in the STDF
Specification Manual.
Wafer Results Record (WRR)
A Wafer Results Record (WRR) contains the result information relating to each wafer tested
by the test program. The WRR (table 24-21) and the Wafer Information Record (WIR)
bracket all the stored information pertaining to one tested wafer. This record is used only
when testing at wafer probe time.
IMAGE Solutions V8.3 24-36
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
Table 24-21. Wafer Results Record
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (2) yes U*1
REC_SUB Record sub-type (20) yes U*1
HEAD_NUM Test head number yes U*1
SITE_GRP Site group number no U*1
FINISH_T Date and time last part tested yes U*4
PART_CNT Number of parts tested yes U*4
RTST_CNT Number of parts retested yes U*4
ABRT_CNT Number of aborts during testing yes U*4
GOOD_CNT Number of devices passing tests yes U*4
FUNC_CNT Number of functional parts tested no U*4
WAFER_ID Wafer ID yes C*n
FABWF_ID Fab wafer ID no C*n
FRAME_ID Wafer frame ID no C*n
MASK_ID Wafer mask ID no C*n
PRB_CARD Prober card ID no C*n
USR_DESC Wafer description supplied by user no C*n
EXC_DESC Wafer description supplied by exec no C*n
WAFER_ID
This field is optional but is strongly recommended to make the resulting data files as useful
as possible. A Wafer ID in the WRR supersedes any Wafer ID found in the WIR.
For more information, see “Wafer Results Record (WRR)” on page 3-27 in the STDF
Specification Manual.
IMAGE Custom Record
Use the tl_log_custom_record() function to create your own custom STDF record. This
function has the following arguments:
IMAGE Solutions V8.3 24-37
IMAGE Base Language: Standard Test Data Format: IMAGE STDF Record Set
Table of Contents Index Home Master Index Search Help
tl_log_custom_record(<type>, <subtype>, <byte count>, <pointer to data>);
where:
<type> Is the record type, which must be a number greater or equal to
200 and of type unsigned char. The number goes into the
REC_TYP field of the custom record.
<subtype> Is the record subtype, which can be any whole number of type
unsigned char. The number goes into the REC_SUB field.
<byte count> Is the number of bytes in the data you plan to move into your
custom record. The function expects the byte count to be of type
unsigned short. The byte count goes into the REC_LEN field.
<pointer to data> Is a pointer to the data. The data can reside in a structure, an
array, or any other data type. Given this pointer, the function
locates the data and appends it to the record’s header (REC_LEN,
REC_TYP, REC_SUB).
When this function is executed, it creates a custom STDF record (table 24-22) and writes it
to the datalog stream, where it flows into an STDF file with the other STDF records.
Table 24-22. IMAGE Custom STDF Record
Supported by Data
Field Name Field Description
IMAGE V8.0? Type
REC_LEN Bytes of data following header yes U*2
REC_TYP Record type (≥200) yes U*1
REC_SUB Record sub-type (≥0) yes U*1
none Data of any type yes any
type
NOTE
The tl_log_custom_record function is not designed for writing standard STDF records to
the datalog stream.
For more information, see “Begin Program Section Record (BPS)” on page 3-55 in the
STDF Specification Manual.
IMAGE Solutions V8.3 24-38
IMAGE Base Language: Standard Test Data Format: Reading, Writing, and Processing an STDF File
Table of Contents Index Home Master Index Search Help
Reading, Writing, and Processing an STDF File
To conserve space and increase processing speed, IMAGE generates STDF files in a
compact binary form rather than as ASCII text. Therefore, you need special, STDF-specific
software to read, write, or otherwise process STDF files.
NOTE
To have IMAGE generate an ASCII file for test data, select the DATALOG TO TEXT FILE:ON
option on the Data Collection Setup display or issue a datalog -file command.
To find out how to process STDF files and what software systems are available for
processing STDF files, contact your Teradyne representative.
IMAGE Solutions V8.3 24-39
IMAGE Base Language: STDF Utilities and Filters
Table of Contents Index Home Master Index Search Help
25 STDF UTILITIES AND FILTERS
This section covers the following topics:
• Reading STDF files (page 25-2)
• Changing and repairing STDF files (page 25-16)
• STDF filters (page 25-25)
IMAGE Solutions V8.3 25-1
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Reading STDF Files
This section describes utilities for reading the contents of STDF files. The utilities covered
are:
• “read_stdftool” a window-based tool for selecting and reading STDF files
• “read_stdf” and read_stdf_v3 for reading STDF files
• “analyze_stdf” for displaying a summary of an STDF file
• “stdf_print_field” which prints data from the STDF Master Information Record (MIR)
• “stdf_print_yield” which displays the yield from an STDF file
“Changing and Repairing STDF Files” on page 25-16 describes the following utilities for
changing or repairing STDF files:
• stdf_repair
• stdf_to_atdf and atdf_to_stdf
• stdf3_to_4
• stdf4_to_3
• stdf_merge
NOTE
All utilities in this section can read either Version 3 or Version 4 files, except for
read_stdf_v3 (which reads only V3 files) and stdf_print_yield (which reads only V4
files).
read_stdftool
read_stdftool is a window-based tool for selecting an STDF file and displaying its
contents one record type at a time.
Invoking
Type the following command from a Shell Tool or Command Tool window in OpenWindows:
% read_stdftool &
The ampersand (&) causes the tool to run in background mode.
NOTE
You can invoke read_stdftool as many times as your system permits. This allows you to
have multiple windows on a single STDF file.
When you first invoke read_stdftool, its control area looks as shown in figure 25-1.
IMAGE Solutions V8.3 25-2
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Read_stdftool
FIle View Display Records Clear
Figure 25-1. read_stdftool Control Area
Note on STDF V3 and V4
read_stdftool can read either an STDF Version 3 or Version 4 file. It does not convert a
V3 file to V4 format while reading it. When displaying a V3 file, read_stdftool uses the
Version 4 record structures, with some exceptions. For example:
• Some fields have been added to the V4 records. For example, BURN_TIM has been
added to the MIR. Such new V4 fields are listed as part of a V3 MIR display, but their
value is always “not present, not valid.” In addition, some V3 MIR fields have been
moved to other records under V4 (for example, CPU_TYPE is now part of the FAR, and
PRB_CARD is now part of the new SDR). These fields are included as part of the V3 MIR
display. (They do not appear when the file is V4.)
• Some record types have been dropped from Version 3 to Version 4; each record that
has been dropped has a comparable V4 record type: for example, the PDR has been
dropped, and its information is in the first PTR in the V4 file. When displaying a V3 file,
read_stdftool uses the comparable V4 record type structure to display any dropped
V3 records: for example, it uses the V4 PTR structure to display the V3 PDR (although
the REC_TYP and REC_SUB fields do display the proper values for the PDR). Any fields
that are not part of V3 have the value “not present, not valid.”
For a list of differences between V3 and V4, see the STDF Version 4 Specifications.
Mouse Buttons
When using read_stdftool, you use two mouse buttons, referred to as SELECT (left) and
MENU (right). This assumes that you are using a three-button mouse, and that you have
not redefined the buttons. If either of these assumptions is false, use your system’s
definitions for SELECT and MENU.
Loading a File
To load an STDF file, select FILE>LOAD. The Read_stdftool: Load window appears (figure
25-2).
IMAGE Solutions V8.3 25-3
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Read_stdftool: Load
1. Specify a directory. Directory: /opt/firms/stdf
2. Enter a filename Match: .std*
“match” template. File:
3. Click LIST. List:
4. Click the file you want.
5. Click LOAD. Load Restore defaults
Figure 25-2. Read_stdftool: Load Window
1. Specify the directory. The default is the current directory. To specify another directory,
enter an absolute path name or a path name relative to the directory where you invoked
read_stdftool. You can use the shell meta character tilde (~) to begin the path name.
2. Use a MATCH: template to specify what files you want read_stdftool to list. The
template can use these wildcard characters:
* (asterisk) Match a string of zero or more characters.
? (question mark) Match a single character.
[xy] (square brackets) Match one of the characters in the brackets.
The default template, *.std*, matches any filename whose extension begins with
“.std” (that is, any valid STDF filename).
3. Once you have specified a MATCH: template, click the LIST: button. read_stdftool lists
all the files in the directory that match the template.
NOTE
If you see an error message stating that an argument is too long, enter a new MATCH:
template that matches fewer files.
4. You can then click the filename you want. (If necessary, scroll through the files listed in
the window.)
The filename you select appears to the right of the FILE: label and is highlighted in the
Read_stdftool: Load window (see figure 25-3).
IMAGE Solutions V8.3 25-4
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Read_stdftool: Load
Directory: /home/wilde/data
Match: *.std*2?may94*
File: mch_ado_zero.std_benedick_23may94_152543
List: mch_ado_zero.std_beatrice_23may94_151630
mch_ado_zero.std_beatrice_26may94_124727
mch_ado_zero.std_beatrice_26may94_1623170
mch_ado_zero.std_benedick_23may94_152543
mch_ado_zero.std_benedick_26may94_143207
Load Restore defaults
Figure 25-3. Selecting the Filename
5. Click LOAD to load the specified file.
If you have changed any of the default values in the Load window, you can click
RESTORE DEFAULTS to reset the default values.
Displaying a Record Type
After you load a file, you can display its contents. In the control area, select VIEW>REPORT
SETUP. The Report Setup window appears (figure 25-4).
Read_stdftool: Report Setup
Display Mode: Full Records to display: 999999
Choose record type to display:
ATR 1 GDR 0 PDR 0 PTR 73969 SSB 0
BPS 0 HBR 32 PGR 4 RDR 1 STS 0
DTR 0 MIR 1 PIR 2555 SBR 33 TSR 29
EPS 0 MPR 0 PLR 1 SCR 0 WCR 1
FAR 1 MRR 1 PMR 4 SDR 1 WIR 1
FDR 0 PCR 1 PRR 2555 SHB 0 WRR 1
FTR 0
Display Records
Figure 25-4. Report Setup Window
IMAGE Solutions V8.3 25-5
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Each STDF record type is represented by its three-letter abbreviation. The number to the
right of each record type indicates how many records of that type are in the file. An entry
>100K means that the file contains more than 99,999 records of this type.
The Report Setup window lists all Version 3 and Version 4 record types, even though the
STDF file will contain only V3 or V4 types.
To display a record type, click the box for the record type, then click the DISPLAY RECORDS
button. (This button appears both on the Report Setup window and in the control area. You
can use either button.)
The window in which the records appear is editable. Click MENU in the display area to see
the editing options. Editing the display has no effect on the STDF file itself.
To clear the display, click the CLEAR button on the base window.
Controlling the Display
By default, read_stdftool displays all fields of all records of the highlighted type. To
display less information, use options on the Report Setup window:
• DISPLAY MODE:
Click MENU on this button to display the two options:
FULL Displays every field of the records.
BRIEF Displays only the most important fields of the records.
• RECORDS TO DISPLAY:
This text item, which you can edit, specifies how many records of this type to display.
The default is 999,999, which is the maximum number of records of a single type that
read_stdftool can display. If you need to view only a few records (for example, for
data verification) specify a smaller number. (Smaller numbers of records display more
quickly than larger numbers.)
After changing one of these settings, click DISPLAY RECORDS to redisplay the records.
Hardcopy Output
You can get hardcopy output of the currently displayed record type, by writing it to a file or
sending it to a printer. To display the Hardcopy window, select FILE>HARDCOPY. The
Hardcopy window appears.
The Hardcopy window prints the currently displayed record type. It does not redisplay a new
record type, even if you have changed Report Setup parameters since the previous
execution.
Set the fields of the Hardcopy window as shown in table 25-1.
IMAGE Solutions V8.3 25-6
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Table 25-1. Fields and Settings in the Hardcopy Window
Field Setting
FORMAT read_stdftool displays ASCII. You cannot change this value.
PROCESS CMD: Specify commands for processing the file, for example, to make it
suitable for a particular printer.
OUTPUT TO: Click in one or both boxes to indicate what kind of output you want:
FILE or PRINTER.
PRINTER: ∇ If OUTPUT TO: specifies Printer, this field is enabled. Either type in a
printer name or click MENU on this button to display a list of printers,
then SELECT to choose one.
The printer list is from your /etc/printcap file. For each
printcap entry, read_stdftool displays the second name
assigned to this printer. (If there is only one name, it is used.) For
example, from this printcap entry
varian|va|Benson Varian:
the second name, “va”, is displayed.
The default printer always appears on the printer list. To change the
default, use the Properties window (see “Setting Properties” on page
25-7).
FILE SPEC: ∇ If OUTPUT TO: specifies FILE, this field is enabled. Type in the filename
you want, either an absolute pathname or relative to the directory
where you invoked read_stdftool.
read_stdftool maintains a File Spec List of files you have specified
during this session. A file is added to this list when you press RETURN
or click FILE SPEC or PRINT. To use the list, click MENU on FILE SPEC,
then SELECT on a file. This lets you reuse (or edit) a filename.
PRINT After setting up the Hardcopy window, click PRINT to send the text to
the printer or write it to a file.
Setting Properties
To set defaults for read_stdftool, select VIEW>PROPERTIES. The Properties window
appears. Note these points:
• When you have changed values in a Properties window, click APPLY to use the new
values. The new values will be used the next time you invoke read_stdftool. They are
not used immediately within the current session.
• If you have changed values, but have not yet clicked APPLY, you can return to the
previous values by clicking RESET, which restores the values that were set previously.
IMAGE Solutions V8.3 25-7
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
• If you have changed the default values, you can click DEFAULT to restore the initial
default values. Clicking DEFAULT redisplays the initial defaults; to use these values, click
APPLY.
• Properties are set on a per-user basis. A user can change properties without affecting
other users.
• This window is pinnable. If you do not pin it, clicking APPLY dismisses it.
Fill in the fields of the Properties window as shown in table 25-2.
Table 25-2. Fields and Settings in the Properties Window
Field Setting
DIRECTORY: Default location for STDF files. The initial default is your current
directory.
MATCH: Default template for matching STDF filenames. The initial default is
*.std*, which matches any legal STDF filename.
FILE: STDF filename. The initial default is blank.
RECORD CHOICE: Which record type is initially selected when the Report Setup
window appears. Click MENU on RECORD CHOICE; then SELECT on
a record type. The initial default is MIR.
DISPLAY MODE: Click MENU on DISPLAY MODE to display the options: FULL (display
the complete record) and BRIEF (display the most important fields).
The initial default is FULL.
PROCESS CMD: Default command for processing the display before sending it to a
file or printer. The initial default is no command (blank).
OUTPUT TO: Default output: FILE and/or PRINTER. The initial default is PRINTER.
PRINTER: Default printer. The initial default is lp. The default listed here will
appear in the printer list in the Hardcopy window.
FILE SPEC: Default file for writing to a file. The initial default is blank.
read_stdf
read_stdf reads an STDF file and displays each record’s contents on the screen. The
syntax is:
% read_stdf [-f] [filename]
The -f switch causes read_stdf to display only one or two lines of the most important
information in each record. In addition, the line indentation indicates the record groupings.
For example, a paired PIR and PRR are similarly indented, while PTRs or FTRs within the
PIR/PRR pair are indented further. If you omit -f, read_stdf displays every field of every
record in the file.
IMAGE Solutions V8.3 25-8
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
read_stdf can accept input from a filename on the command line. If the filename is omitted,
input is from standard input (stdin).
read_stdf can read any V3 or V4 STDF file. It is useful for debugging STDF files you write.
You can also use read_stdf to check whether a file transfer has run to completion. (If a
transferred STDF file does not end with an MRR (Master Results Record), then the transfer
did not run to completion.)
STDF V3 and V4
read_stdf can read either an STDF Version 3 or Version 4 file. When displaying the
contents of an STDF V3 file, it uses the comparable Version 4 structures. For a more
complete explanation, see “Note on STDF V3 and V4” on page 25-3.
read_stdf for STDF V3
read_stdf reads an STDF V3 file into Version 4 structures. To use Version 3 structures,
type:
% read_stdf_v3 [-f] <filename>
If you do not include a filename, read_stdf_v3 looks for the file tfile.std in the working
directory. read_stdf_v3 cannot read from standard input.
analyze_stdf
The analyze_stdf utility displays a brief summary of the content and size of an STDF file,
categorized by STDF record type. Use this command line to invoke the utility:
analyze_stdf stdf-file
analyze_stdf can accept input from a filename on the command line. If the filename is
omitted, input is from standard input (stdin).
The STDF file can be in either Version 3 or Version 4 format. If you specify the filename on
the command line, you can compress the file; analyze_stdf cannot accept a compressed
file from stdin.
The utility displays statistics as shown in figure 25-5 (lines have been omitted).
IMAGE Solutions V8.3 25-9
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Filename: /home/wilde/data/h420.stdf
CPU Type: SUN
Version: 4
Size: 306344
TYPE COUNT MIN LEN AVG LEN MAX LEN TOT LEN
=========================================================
far 1 6 6 6 6
mir 1 178 178 178 178
rdr 1 12 12 12 12
...
wir 1 19 19 19 19
pir 2555 6 6 6 15330
ptr 66304 32 32 34 2126838
prr 2555 23 25 26 65323
...
pcr 1 18 18 18 18
mrr 1 8 8 8 8
---------------------------------------------------------
71523 2210091
Figure 25-5. Statistics Display From the Analyze_Stdf Utility
Note these points on the information displayed:
• The heading displays the STDF filename, the CPU type that wrote the file, the STDF
version number (3 or 4), and the size in bytes of the STDF file (obtained by an operating
system call — this is the actual size of the file, which may be compressed). If input is
from stdin, the filename and size are blank.
• analyze_stdf lists the record types in order of the first occurrence of each type in the
file.
• analyze_stdf does not stop reading when it reaches an MRR. If there are records
beyond the MRR it includes them in its calculations, even though this is not a legal STDF
file.
• An entry TYP in the TYPE column means the REC_TYP value is undefined; SUB means
the REC_SUB value is undefined. An undefined record type or subtype may be undefined
if it is user-defined.
• For each record type, the utility displays the number of records of that type in the file;
the minimum, average, and maximum length, in bytes, of records of that type; and the
total length of all the records of that type.
• Each length includes the four bytes of the STDF header (see the “STDF Record Header”
on page 2-2 in the STDF Specification Manual).
• The final line displays the total number of records in the file and the total length of all the
records. The length is the sum total of the TOT LEN value for each record type. This
represents an “uncompressed” size, even if analyze_stdf compresses the file itself. If
the total size here and the size of the uncompressed file in the heading disagree, the
difference is due to padding at the end of the file.
IMAGE Solutions V8.3 25-10
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
analyze_stdf provides the following exit status so that the disposition of the STDF file can
be determined programmatically:
0 Complete STDF file, no errors.
1 Error in reading the STDF file, or file not recognized as an STDF
file (missing FAR or MIR).
2 Incomplete STDF file.
An exit status of 1 may occur when analyze_stdf cannot open the specified STDF file or
when a compressed STDF file is being read from stdin.
stdf_print_field
The stdf_print_field utility returns a string containing the values from one or more fields
of the File Attributes Record (FAR) or Master Information Record (MIR) of a specified STDF
file. It prints this string on stdout. The STDF file can be Version 3 or 4 format.
One use of this utility is to rename an STDF file based on the kind of data it contains:
stdf_print_field can return a string that includes the file’s lot ID, part type, testing mode,
or any other FAR or MIR field, and the string can be used as the file’s new name.
Use the following command line to invoke the utility:
stdf_print_field [-w] [-s] file "format" field(s)...
where:
-w Removes all spaces, tabs, carriage returns, new lines, vertical
tabs, and form feeds from the output.
-s Removes all characters from the output that are not letters or
digits.
file Is the STDF file specification. The file can be in V3 or V4 format.
"format" Is an enquoted string that specifies the output format. Use the
codes shown in the table 25-3 on page 25-12. The format string
can also specify white space, punctuation, and any other
printable characters. The -w and -s options affect the format
string. For example, if the format string contains spaces, the -w
switch will remove them from the output.
field(s) Are the keywords specifying the MIR fields to display. The nth
field-name keyword corresponds to the nth format specifier in the
format string. The keywords are shown in table 25-3 on page
25-12, along with the correct format specifier for each. Each
keyword shown is the minimum acceptable string for the MIR
field. You can include more characters to improve readability: for
example, sub is the keyword for SBLOT_ID, but you could include
the complete string Sub-Lot. The case of the keywords is
unimportant.
IMAGE Solutions V8.3 25-11
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Note that MIR fields differ between STDF V3 and V4. If you request a field that is not
supported by the version of the STDF file, stdf_print_field returns a null string (if the
field format specified is %s) or the value 65,535 (for BURN_TIM, the only numeric field not
supported by both versions).
This is an example of an stdf_print_field command line:
stdf_print_field tfile.std "LOT %s_%s" lot par
It will return a string like this:
LOT 61772_D07X1
The value 61772 is the lot identifier, and D07X1 is the part type. The format string
concatenates the two values with an underscore.
Table 25-3 shows the FAR and MIR fields, the stdf_print_field keyword, and minimum
acceptable format specifier for each. It also shows which fields are supported only by STDF
Version 3 or Version 4.
Table 25-3. FAR and MIR Fields
FAR/MIR Field Keyword Format Specifier V3 or V4
CPU_VER cpu %d V3 & V4
STDF_VER stdf %d V3 & V4
SETUP_T set %s V3 & V4
START_T star %s V3 & V4
STAT_NUM stat %d V3 & V4
MODE_COD mode %c V3 & V4
RTST_COD rtst %c V3 & V4
PROT_COD prot %c V3 & V4
BURN_TIM burn %d V4
CMOD_COD cmod %c V3 & V4
LOT_ID lot %s V3 & V4
PART_TYP par %s V3 & V4
NODE_NAM nod %s V3 & V4
TSTR_TYP tes %s V3 & V4
JOB_NAM job %s V3 & V4
JOB_REV rev %s V3 & V4
SBLOT_ID sub %s V3 & V4
IMAGE Solutions V8.3 25-12
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
Table 25-3. FAR and MIR Fields (Continued)
FAR/MIR Field Keyword Format Specifier V3 or V4
OPER_NAM ope %s V3 & V4
EXEC_TYP exe %s V3 & V4
EXEC_VER ver %s V4
TEST_COD t_co %s V3 & V4
TST_TEMP temp %s V4
USER_TXT user %s V4
AUX_FILE aux %s V4
PKG_TYP pkg %s V4
FAMLY_ID fam %s V4
DATE_COD date %s V4
FACIL_ID fac %s V4
FLOOR_ID floo %s V4
PROC_ID proc %s V3 & V4
OPER_FRQ freq %s V4
SPEC_NAM s_na %s V4
SPEC_VER s_ve %s V4
FLOW_ID flow %s V4
SETUP_ID s_id %s V4
DSGN_REV dsgn %s V4
ENG_ID eng %s V4
ROM_COD rom %s V4
SERL_NUM serl %s V4
SUPR_NAM sup %s V3 & V4
HAND_ID han %s V3
PRB_CARD prob %s V3
IMAGE Solutions V8.3 25-13
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
stdf_print_yield
The stdf_print_yield utility determines the yield of good parts from an STDF file and
prints it on stdout. The yield appears as a percentage (without the percent sign). The STDF
file must be in Version 4 format.
Use this command line to invoke the utility:
stdf_print_yield file [ -s ] [ good-bins ]
where:
file Is the input file. The file must be in Version 4 format.
-s Specifies that the utility is to use counts from SBRs (Software Bin
Records). The default is to use the HBRs (Hardware Bin
Records).
good-bins Is a list of “good” bin numbers separated by commas. White
space is not permitted in the string of bin numbers. The meaning
of “good” is user-defined. The list specifies the bins
stdf_print_yield uses in calculating the yield. If the bin list is
not included, the utility uses its own definition of “good” parts, as
described below.
Yield is defined as: good-parts / total-parts
The “good-parts” numerator and “total-parts” denominator are defined in the following
sections.
Determining “Good Parts”
The “good-parts” numerator is determined as follows, in this order:
1. If the good-bin-list argument is included:
“good-parts” = the sum of the HBIN_CNT values from the HBRs for the bins listed. (HBRs
where HEAD_NUM = 255 are used; if they are not present, totals are calculated from site-
specific bins.) If -s is present, the SBRs are used.
2. If good-bin-list is not included:
“good-parts” = the sum of the HBIN_CNT values from all the HBRs in the file where
HBIN_PF is “P”. (HBRs where HEAD_NUM = 255 are used; if they are not present, totals
are calculated from site-specific bins.) If -s is present, the SBRs are used.
3. If HBIN_PF is blank for all HBRs (or SBIN_PF for all SBRs):
“good-parts” = the GOOD_CNT field of the PCR (Part Count Record) whose HEAD_NUM =
255.
4. If the GOOD_CNT of the PCR is not valid:
“good-parts” = HBIN_CNT of the HBR for Bin 1 (or SBIN_CNT of the SBR).
Determining “Total Parts”
The “total-parts” denominator is determined as follows, in this order:
IMAGE Solutions V8.3 25-14
IMAGE Base Language: STDF Utilities and Filters: Reading STDF Files
Table of Contents Index Home Master Index Search Help
1. If there is a PCR whose HEAD_NUM is 255, and its PART_CNT is not 0:
“total-parts” = the PART_CNT of the PCR.
2. If the PCR cannot be used, and if the good-bin-list argument is included:
“total-parts” = the sum of the HBIN_CNT values from the HBRs for the bins listed, where
HBIN_PF is “P” or “F”. (HBRs where HEAD_NUM = 255 are used; if they are not present,
totals are calculated from site-specific bins.) If -s is present, the SBRs are used.
3. If bin-list is not included:
“total-parts” = the number of PRRs (Part Results Records) in the file.
For information about the meaning of the fields of the records, see the STDF Version 4
Specification.
IMAGE Solutions V8.3 25-15
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
Changing and Repairing STDF Files
This section describes utilities for changing the contents of STDF files: either converting the
files to some other format, or repairing something in the files. The utilities covered are:
• stdf_repair, which repairs incomplete STDF files (page 25-16)
• stdf_to_atdf and atdf_to_stdf, for converting between STDF and ATDF (page
25-18)
• stdf3_to_4, for converting from STDF Version 3 to Version 4 (page 25-18)
• stdf4_to_3, for converting from STDF Version 4 to Version 3 (page 25-21)
• stdf_merge, for merging two STDF files into a single file (page 25-23)
Other documentation includes
• “STDF Filters” on page 25-25 describes filters that you can apply to STDF files. These
filters also change the contents of STDF files.
• “Reading STDF Files” on page 25-2 describes these utilities for reading STDF files:
– read_stdftool (page 25-2)
– read_stdf, read_stdf_v3, and write_stdf (page 25-8)
– analyze_stdf (page 25-9)
– stdf_print_field (page 25-11)
– stdf_print_yield (page 25-14)
Repairing STDF Files: stdf_repair
The stdf_repair utility can repair an incomplete STDF file. If testing is interrupted in the
middle of a lot (for example, by a test system crash), the result is an incomplete STDF file.
The file contains data for parts already tested, but it does not contain the required Master
Results Record (MRR) or Part Count Record (PCR). Data analysis software, therefore,
cannot process it.
stdf_repair lets you salvage as much of the STDF file as possible. It recovers all data for
parts that had completed testing, and it uses that data to generate the summary records
needed to complete the STDF file.
To invoke the utility, type:
stdf_repair input-stdf-file output-stdf-file
where:
input-stdf-file Is the name of a possibly incomplete STDF file. If the file is in
Version 3 format, stdf_repair automatically invokes the
stdf3_to_4 utility before stdf_repair processing begins. The
final file will have .v4 appended to its filename.
output-stdf-file Is the name of the STDF file to which stdf_repair writes the
repaired data. If output-stdf-file exists, stdf_repair will
IMAGE Solutions V8.3 25-16
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
overwrite it. The output file is in uncompressed format, even if
the input file is compressed.
stdf_repair writes messages to the screen indicating repairs it is making.
Changes Made to an Incomplete File
If it discovers that the input file is in fact incomplete (that is, it is missing either the MRR or
the PCR) stdf_repair makes these changes in generating the output STDF file:
• If the CPU type where stdf_repair is executed is different from the CPU type where
the STDF file was written, the CPU_TYPE field of the FAR is set to specify the CPU type
where stdf_repair is executed.
• To be meaningful, a PIR, FTR, or PTR must have a corresponding PRR, so that there
is a full set of records for each part. If the input file contains any PIR, FTR, or PTR
without a corresponding PRR, the information for that part is considered incomplete and
the records are not written to the output STDF file.
Exceptions are “dummy” PTRs, which contain static information but no test result. If a
PTR has head and site numbers set to zero, and if its “test not executed” bit is set,
stdf_repair recognizes it as a “dummy” PTR, and writes it to the output STDF file,
even if it does not appear between a PIR/PRR pair.
• If the STDF file has two PIRs in a row, one is removed.
• If TSRs are missing, stdf_repair uses the information in the FTRs, PTRs, and MPRs
to generate them.
• If bin records are missing, stdf_repair uses the information in the PRRs to generate
HBRs and SBRs.
• If the PCR is missing, stdf_repair uses the information in the PRRs to generate it.
• If the MRR is missing, stdf_repair generates one, using the START_T value from the
MIR as the FINISH_T for the MRR.
• An ATR (Audit Trail Record) is added to the file with the stdf_repair command line.
• stdf_repair writes GDRs (Generic Data Record) from the input file to the output file.
In previous releases, it did not write GDRs.
• stdf_repair copies user-defined record types (REC_TYP >= 200) and executive-
reserved record types (REC_TYP = 180 or 181) unchanged from the input file to the
output file. stdf_repair does not do any byte conversion on the data in these records.
It assumes that it is running on the same kind of CPU as the system that created the file.
stdf_repair does write the correct record length to the REC_LEN field of the header.
Change Made to a Complete File
Even if the input file is not incomplete, stdf_repair makes the following changes as it
writes the output file:
• It sets the FAR field CPU_TYPE to the executing CPU type
• It does not write GDRs to the output file
IMAGE Solutions V8.3 25-17
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
STDF-ATDF Conversions
The Data Pipeline package contains utilities for converting between Standard Test Data
Format (STDF) and ASCII Test Data Format (ATDF). The conversion utilities are:
stdf_to_atdf Converts an STDF Version 4 file into ATDF V2 format.
atdf_to_stdf Converts an ATDF Version 2 file into STDF V4 format.
To invoke one of these utilities, use this format:
utility-name input-file output-file
If you specify one file, it is assumed to be the input file and the utility writes output to stdout.
If you do not specify a file, the utility reads input from stdin and writes output to stdout.
For stdf_to_atdf, the input STDF file must be in Version 4 format.
For more information on the file formats, see:
• Standard Test Data Format (STDF) Specification — Version 4
• ASCII Test Data Format (ATDF) Specification — Version 2
Conversion between STDF and ATDF occurs with no loss of data, because the records and
fields of each are identical.
STDF V3 to V4 Conversion: stdf3_to_4
The stdf3_to_4 utility converts an STDF Version 3 file into STDF V4 format. If you need to
perform a conversion manually, you can use this utility.
To invoke this utility, use this format:
stdf3_to_4 input-file output-file
If you specify one file, the utility assumes it is the input file and writes output to stdout. If
you do not specify a file, the utility reads input from stdin and writes output to stdout. The
utility adds an ATR (Audit Trail Record) to the output file with the stdf3_to_4 command
line.
If stdf3_to_4 detects a premature end-of-file, it writes all TSRs to the output file, and then
calls stdf_repair to construct the PCR, MRR, and any other missing records.
The output V4 file is in uncompressed format, even if the input V3 file is compressed. If you
want the final file to be compressed, pipe the output as follows:
stdf3_to_4 v3_file.std | compress > v4_file.std.Z
Differences Between V3 and V4
There are differences between STDF Version 3 and Version 4. The stdf3_to_4 utility
handles these differences as follows:
• MIR (Master Information Record)
These fields have been eliminated from the V4 MIR: CPU_TYP, STDF_VER, HAND_ID, and
IMAGE Solutions V8.3 25-18
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
PRB_CARD. CPU_TYP and STDF_VER are now in the FAR (required as the first record in a
V4 file). If the MIR has a HAND_ID or PRB_CARD value, the utility creates an SDR (Site
Description Record, new in V4) for these values.
• MRR (Master Results Record)
These fields have moved from the MRR to the PCR (Part Count Record, new with V4):
PART_CNT, RTST_CNT, ABRT_CNT, and GOOD_CNT. When the utility reads a V3 MRR, it
writes a PCR with these values and with the HEAD_NUM and SITE_NUM values set to 255.
• WIR (Wafer Information Record)
When the utility writes a V4 WIR, it assigns the value 255 to the SITE_GRP field.
• WRR (Wafer Results Record)
When the utility writes a V4 WRR, it assigns the value 255 to the SITE_GRP field. The
utility does not store the V3 HAND_ID and PRB_CARD values.
• PMR (Pin Map Record)
The PMR has been redefined. The utility writes the V4 PMR as follows:
CHAN_NAM = PMR V3 CHAN_NUM
CHAN_TYP = 0
LOG_NAM = ""
HEAD_NUM = 1
SITE_NUM = 1
PMR_INDX = PMR V3 CHAN_NUM
PHY_NAM = PMR V3 PIN_NAME
In STDF V3, CHAN_NUM and PIN_NAME can be arrays. When the utility reads a V3 PMR,
it reads only the first CHAN_NUM into CHAN_NAM and PMR_INDX, and it reads only the first
PIN_NAME into PHY_NAM. The V3 CHAN_CNT and NAME_CNT are no longer necessary.
• PIR/PRR (Part Information Record/Part Results Record)
The X_COORD, Y_COORD, and PART_ID fields are no longer part of the PIR; instead, they
are found only in the PRR. When the utility reads a V3 PIR, it writes these values to the
PRR with the same site and head number, if it does not have them.
• PDR (Parametric Test Description Record)
The PDR has been dropped from V4, so the utility writes the fields from a PDR to a PTR.
The utility takes the following V4 fields from the V3 fields with the same name:
TEST_NUM, OPT_FLAG (although some bits are different), RES_SCAL, LO_LIMIT,
HI_LIMIT, LLM_SCAL, HLM_SCAL, and UNITS.
The utility sets the following fields to 0 (zero): HEAD_NUM, SITE_NUM, TEST_FLG (indicates
that test was not executed and that the FTR contains only default information),
PARM_FLG, RESULT, TEST_TXT, and ALARM_ID.
The utility fills in the format fields as follows:
C_RESFMT = Determined from PDR V3 RES_RDIG and RES_LDIG
C_LLMFMT = Determined from PDR V3 LLM_LDIG and LLM_RDIG
C_HLMFMT = Determined from PDR V3 HLM_LDIG and HLM_RDIG
The utility writes the V4 TEST_NAM and SEQ_NAME values to the TSR for this test, if it does
not already have them; if no corresponding TSR exists, the utility creates one for them.
The V3 DESC_FLG value is no longer necessary.
IMAGE Solutions V8.3 25-19
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
• PTR (Parametric Test Result Record)
The PTR no longer contains the TEST_NAM and SEQ_NAME fields. The utility writes these
values to the TSR for this test, if it does not already have them; if no corresponding TSR
exists, the utility creates one to hold these values.
• FDR (Functional Test Description Record)
The FDR has been eliminated from V4. The utility writes the V3 TEST_NAM and SEQ_NAME
values to the TSR for this test, if it does not already have them; if no corresponding TSR
exists, the utility creates one for them. The V3 DESC_FLG value is no longer necessary.
• FTR (Functional Test Result Record)
The FTR has been redefined. The utility writes the V4 FTR as follows:
REL_VADR = FTR V3 VECT_ADR
RSLT_TXT = FTR V3 PCP_ADDR
VECT_OFF = 0
SPIN_MAP = FTR V3 RPIN_MAP
TEST_TXT = FTR V3 TEST_TXT
In STDF V3, DEV_DAT is a variable-length binary string. The utility reads the length of the
data portion of the string (in bits) into RTN_ICNT; the utility reads the bits into the array
RTN_STAT; and it reads the integers from 0 to m (where m is the number of bits) into the
array RTN_INDX. Similarly, for the V3 field VECT_DATA, the utility reads the number of bits
into PGM_ICNT, it reads the data bits into the array PGM_STAT, and it reads the integers
from 0 to n into the array PGM_INDX.
The utility writes the V3 TEST_NAM and SEQ_NAME values to the TSR for this test, if it does
not already have them; if no corresponding TSR exists, it creates one for them. The V3
DESC_FLG value is no longer necessary.
• TSR (Test Synopsis Record)
The TSR no longer stores the TST_MEAN and TST_SDEV fields because these values can
be calculated from the other fields.
• STS (Site-Specific Test Synopsis Record)
The STS has been eliminated from V4. The utility writes any STS data to a TSR. The
utility does not store TST_MEAN and TST_SDEV values from the V3 STS. These values
can be calculated from other fields.
• SHB (Site-Specific Hardware Bin Record)
The SHB has been eliminated from V4. The utility writes any SHB data to an HBR.
• SSB (Site-Specific Software Bin Record)
The SSB has been eliminated from V4. The utility writes any SSB data to an SBR.
• SCR (Site-Specific Part Count Record)
The SCR has been eliminated from V4. The utility writes any SCR data to a PCR (Part
Count Record), a record type new in V4. The utility does not store the FINISH_T value
from the V3 SCR.
• User-defined record types
The utility copies user-defined record types (REC_TYP >= 200) and executive-reserved
record types (REC_TYP = 180 or 181) unchanged from the input file to the output file.
stdf3_to_4 does not do any byte conversion on the data in these records. It assumes
that it is running on the same kind of CPU as the system that created the file.
stdf3_to_4 does write the correct record length to the REC_LEN field of the header.
IMAGE Solutions V8.3 25-20
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
STDF V4 to V3 Conversion: stdf4_to_3
You may want to convert an STDF file from Version 4 format to Version 3 format: for
example, if a test system writes V4 files, but older custom analysis software can take only
V3 files as input. The stdf4_to_3 utility performs this conversion. To invoke it, use this
format:
stdf4_to_3 input-file output-file
If you specify one file, the utility assumes it is the input file and writes output to stdout. If
you do not specify a file, it reads input from stdin and writes output to stdout.
The output V3 file is in uncompressed format, even if the input V4 file is compressed. If you
want the final file to be compressed, pipe the output as follows:
stdf4_to_3 v4_file.std | compress > v3_file.std.Z
Differences Between V4 and V3
There are differences between STDF Version 3 and Version 4. The following list shows how
the stdf4_to_3 utility handles each V4 record type:
FAR Copy CPU_TYPE to output file. (Do not set it to the type of CPU on
which stdf4_to_3 is executing.) Set STDF_VER to 3.
ATR Eliminate. New in V4.
MIR Copy compatible data.
Copy MODE_COD value (new values defined for V4); copy first
three characters of TEST_COD (type change for V4); set
STDF_VER to 3.
Get CPU_TYPE from FAR; get HAND_ID and PRB_CARD from SDR.
Eliminate these fields: AUX_FILE, BURN_TIM, DATE_COD,
DSGN_REV, ENG_ID, EXEC_VER, FACIL_ID, FAMLY_ID, FLOOR_ID,
FLOW_ID, OPER_FRQ, PKG_TYP, ROM_COD, SERL_NUM, SETUP_ID,
SPEC_NAM, SPEC_VER, TST_TEMP, USER_TXT.
MRR Copy compatible data.
Get counts from PCR with HEAD_NUM = 255. These fields are
adjusted for type change (unsigned integer to signed integer):
ABRT_CNT, FUNC_CNT, GOOD_CNT, RTST_CNT.
PCR New V4 record; if HEAD_NUM = 255, copy count fields to MRR;
otherwise create SCR.
HBR If HEAD_NUM = 255, copy to HBR; otherwise create an SHB.
Copy compatible data. Drop HBIN_PF.
SBR If HEAD_NUM = 255, copy to SBR; otherwise create an SSB.
Copy compatible data. Drop SBIN_PF.
PMR Mostly compatible, except V3 does not support head/site fields,
so that a V4 file containing multiple head/site PMRs creates
IMAGE Solutions V8.3 25-21
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
multiply-defined PMRs in the V3 file.
Copy V4 CHAN_NUM to V3 CHAN_NUM, with type change.
Copy LOG_NAM or PHY_NAM to PIN_NAME.
Set CHAN_CNT and NAME_CNT to 1.
Use GRP_NAM from PGR as a PIN_NAME.
Use INDX_CNT from PGR as CHAN_CNT.
Use the PMR_INDX from PGR to access each V4 PMR to retrieve
the CHAN_NAM.
Eliminate PMR_INDX, CHAN_TYP, HEAD_NUM, SITE_NUM.
Save the V4 PMR to process PGR, PLR, and FTR.
PGR Not directly compatible, but information can be transferred to a
V3 PMR.
PLR Nothing in V3 supports this information type, but some data
contained in this record can be used in other records.
Save the PLR to process the “radix” data in FDR and FTR.
RDR Eliminate. New in V4.
SDR Eliminate. New in V4.
Save CARD_ID and HAND_ID indexed by SITE_GRP for use in
MRR and WRR.
WIR Copy compatible data. Drop SITE_GRP.
WRR Copy compatible data. These field values may be truncated
because of type change (unsigned integer to signed integer):
ABRT_CNT, FUNC_CNT, GOOD_CNT, RTST_CNT.
Get HAND_ID from SDR matched by SITE_GRP; get PRB_CARD
from SDR field CARD_ID matched by SITE_GRP.
Eliminate these fields: FABWF_ID, FRAME_ID, MASK_ID,
SITE_GRP.
WCR Copy all fields.
If WF_UNITS is set to one of the new values, set to “unknown.”
PIR Copy all fields.
Set PART_ID, X_COORD, and Y_COORD to “missing” to indicate
that the PRR contains this information.
PRR Copy compatible data. Drop TEST_T.
TSR If HEAD_NUM = 255, copy to TSR; otherwise create an STS.
Copy compatible data. Following field values may be truncated
because of type change (unsigned integer to signed integer):
ALRM_CNT, EXEC_CNT, FAIL_CNT.
Calculate TST_MEAN and TST_SDEV from TST_SQRS and
TST_SUMS.
Drop TEST_LBL, TEST_TIM, TEST_TYP.
PTR Copy compatible data. (UNITS type change may cause
truncation.)
IMAGE Solutions V8.3 25-22
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
Transform formatting data to V3 format.
Drop ALARM_ID.
From a “semi-static” PTR, copy formatting information into a
PDR.
MPR Drop. New in V4.
FTR Low compatibility because of significant V4 changes.
Copy compatible data. Note type changes for FAIL_PIN,
REPT_CNT, SPIN_MAP (V4 stores up to 8K bytes — V3 only stores
up to 255 bytes), and TIME_SET (complete type change — may
not be compatible).
Adjust for values change for OPT_FLAG.
Eliminate ALARM_ID, OP_CODE, PATG_NUM, PROG_TXT, RSLT_TXT,
VECT_NAM, VECT_OFF, XFAIL_AD, YFAIL_AD.
The V4 fields PGM_STAT and RTN_STAT represent pin states with
4-bit values whereas the V3 fields VECT_DAT and DEV_DAT use
only 1-bit. Where the V4 fields contain values other than 0 or 1,
set the V3 field bits to 0.
From a “semi-static” FTR, copy formatting information into an
FDR.
BPS Copy all fields.
EPS Copy all fields.
GDR Copy all fields.
DTR Copy all fields.
Merging STDF Files: stdf_merge
Because you can create more than one STDF file for a particular lot of devices, you may
wish to merge STDF files into one file representing the entire lot in a way that reflects the
final file if the lot were tested in its entirety. Use the following command to do this:
stdf_merge stdffile1 [stdffile2] -o output-file -no_renum -nosummary
If you specify only stdffile1, the utility repairs the file (see stdf_repair, on page 25-16).
If you specify both stdffile1 and stdffile2, the utility merges the files. The utility names
the resulting merged file output-file; this argument is required.
Input STDF files must be in Version 4 format. The output file is in uncompressed format,
even in the input files are in compressed format.
As a first pass, this utility preprocesses each input STDF file, looking for test description
records: Parametric Test Record (PTRs) or Functional Test Record (FTRs) in each file. If it
finds a test number that is parametric in one STDF file and functional in the other, it displays
a warning, and no merging occurs. In this preprocess step, the utility also merges
appropriate records, such as the hardware and software bin records and test synopsis
records.
IMAGE Solutions V8.3 25-23
IMAGE Base Language: STDF Utilities and Filters: Changing and Repairing STDF Files
Table of Contents Index Home Master Index Search Help
The utility does not try to merge the Master Information Records (MIRs) from each of the
STDF files. It uses the MIR from the first input file. The utility assumes the two STDF files
represent two halves of a lot and, as such, it uses the MIR from the first half.
When it is merging two STDF files, the utility renumbers devices from the second file to
follow the first sequentially. To turn off this renumbering, specify the -no_renum option.
If any limits or statistics (for example, mean or standard deviation) change for a given test
from one STDF file to the other, the utility marks the information as invalid in the merged
STDF file.
IMAGE Solutions V8.3 25-24
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
STDF Filters
DataPump software (see “Datapump Automation Software” on page 15-1) provides a set of
filters for use with STDF files. Each filter performs one function: for example, to exclude
certain bins, or to replace datalog readings with the retested readings, as identified by the
X/Y coordinates. You can call the filters from the command line and pipe them to each other.
This section covers the following topics:
• General points that apply to all filters
• Detailed descriptions of all filters
Note that “Changing and Repairing STDF Files” on page 25-16 describes these utilities for
changing or repairing STDF files:
• stdf_repair (page 25-16)
• stdf_to_atdf and atdf_to_stdf (page 25-18)
• stdf3_to_4 (page 25-18)
• stdf4_to_3 (page 25-21)
• stdf_merge (page 25-23)
General Points on Filters
The following points apply to the filters in general.
Command Line Invocation
To invoke a filter, you use a command line in one of these formats:
filter-name -i [item-list] [input-file] [output-file]
filter-name -e [item-list] [input-file] [output-file]
filter-name [input-file] [output-file]
where:
-i or -e Indicates that the filter is to include (-i) only the specified items,
or is to exclude (-e) the specified items. Not every filter takes the
-i or -e switch. If the filter does take a switch, you must include
the -i or -e; there is no default.
item-list Is a list of the items to be included or excluded: record types, test
numbers, or bin numbers. Not every filter requires items with the
switch. In the list, you separate items using commas; the string
cannot contain blanks or white space. If items are numbers, you
can use a range, in the format m-n, for example, 5-10.
input-file Is the name of the STDF file to filter.
output-file Is the name of the filtered file. The output file is in uncompressed
format, even if the input file was compressed.
IMAGE Solutions V8.3 25-25
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
If you omit input-file or output-file, the filter uses stdin and stdout, thus allowing
you to pipe filters together. The general form would be:
filter1 -e items input-file | filter2 -i items | \
filter3 -e items |....| filtern -i items > output-file
Additional Notes
The following sections describe the action of each filter. Note these points:
• In addition to the effects of the filters described here, each filter also adds an ATR (Audit
Trail Record) to the STDF file, containing the command line for the filter.
• Some filters exclude PTRs (Parametric Test Records). Some PTRs, however, contain
semistatic default data that describes the units and scaling information needed by other
records. For this reason, these filters write any PTRs with semistatic default data before
they write any of the PIR/PRR pairs, so that, even if datalog records are excluded, this
information is preserved.
Filter Types
The filters fall into these categories:
• Filter by some criterion
• Replace First-Pass Data With Retest Data
• Other
See tables 25-4, 25-5, and 25-6 for details about these filters.
Table 25-4. Filters By Some Criterion
Filter Action Page
filter_record Include or exclude certain STDF page 25-27
record types
filter_datalog Include or exclude datalog records page 25-28
filter_test Include or exclude certain test page 25-28
numbers
filter_hbr/sbr_bin Include or exclude certain bin numbers page 25-29
filter_failed_ devices Include or exclude records for page 25-29
failing devices
filter_nsigma Include or exclude datalog records page 25-30
outside a certain sigma
IMAGE Solutions V8.3 25-26
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
Table 25-5. Replace first-pass data with Retest Data
Filter Action Page
retest_by_part_id Replace data identified by part ID page 25-30
retest_by_xy_ coordinate Replace data identified by page 25-30
X/Y coordinates
Table 25-6. Other Filters
Filter Action Page
filter_extra Compress the STDF file by removing redundant page 25-31
records
filter_ftr Convert functional test records to parametric page 25-31
test records
stdf_repair Repair an incomplete STDF file page 25-33
null Do nothing (a null filter) page 25-33
Filter by Record Type: filter_record
Excludes or includes the specified STDF record types.
Format. The format of the filter_record command is as follows:
filter_record -i type,type,type...[input file] [output file]
filter_record -e type,type,type...[input file] [output file]
where type is the three-letter abbreviation for the STDF record type. All types must be in
lower case. You separate the abbreviations by commas. White space is not allowed in the
string of abbreviations.
For example, to include only the FAR, MIR, HBRs, PCRs, and MRR:
filter_record -i far,mir,hbr,pcr,mrr [input file] [output file]
Or to exclude all FTRs:
filter_record -e ftr [input file] [output file]
Action. This filter creates an STDF file containing only the specified record types. With the
-e switch, it excludes the listed types; with the -i switch, it creates a file consisting only of
the listed types.
It also adds an ATR for this filter. Even if the command line specifies omitting ATRs, the filter
adds an ATR for this pass.
IMAGE Solutions V8.3 25-27
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
Note that this filter can create an illegal STDF file, that is, a file that does not have an FAR,
MIR, and MRR. It is your responsibility to create a legal file or to be aware of the
consequences of generating an illegal one.
Filter Datalog Data: filter_datalog
Excludes or includes datalog records.
Format. The format of the filter_datalog command is as follows:
filter_datalog -i [input file] [output file]
filter_datalog -e [input file] [output file]
Action. This filter excludes (or includes only) those records that define datalog information.
These records are:
PIR Part Information Record
PTR Parametric Test Result Record
MPR Multiple-Result Parametric Record
FTR Functional Test Result Record
PRR Part Result Record
DTR Datalog Text Record
If you do not need datalog information, you can use this filter with the -e switch to store
much smaller STDF files in the Data Pipeline.
To create a legal STDF file, the -i switch includes not only the datalog records but also the
records that are required in a valid file: FAR, MIR, PCR, and MRR. It also includes all
existing ATRs, and adds an ATR for this filter.
Filter by Test Number: filter_test
Excludes or includes the records related to the specified tests.
Format. The format of the filter_test command is as follows:
filter_test -i test,test,test...[input file] [output file]
filter_test -e test,test,test...[input file] [output file]
where test is a single test number or a range of test numbers in the form m-n (for example,
1000-1999). You separate the items by commas. White space is not allowed in the string of
test numbers. The string cannot exceed 256 characters.
For example, to include only certain tests:
filter_test -i 2,3,5-10,12 [input file] [output file]
Action. This filter produces an output STDF file with test records only for the specified test
numbers. The test records are as follows:
TSR Test Synopsis Record
IMAGE Solutions V8.3 25-28
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
PTR Parametric Test Result Record
MPR Multiple-Result Parametric Record
FTR Functional Test Result Record
The filter does not affect the other record types in the input STDF file. With the -i switch,
the filter includes only those test records with the specified test numbers; with the -e switch,
it excludes test records with the specified numbers.
Filter by Bin Number: filter_hbr_bin and filter_sbr_bin
Excludes or includes the records related to the specified hardware or software bins.
Format. The filter_hbr_bin and filter_sbr_bin commands have the following
syntax:
For hardware bins:
filter_hbr_bin -i bin,bin,bin...[input file] [output file]
filter_hbr_bin -e bin,bin,bin...[input file] [output file]
For software bins:
filter_sbr_bin -i bin,bin,bin...[input file] [output file]
filter_sbr_bin -e bin,bin,bin...[input file] [output file]
where bin is a single bin number, or a range of bin numbers in the form m-n (for example,
0-2). You separate the items by commas. White space is not permitted in the string of bin
numbers. The string cannot exceed 256 characters.
Action. These filters produce an output STDF file that either excludes or includes records
for the devices in the specified hardware or software bins. These records are the HBRs
(Hardware Bin Records) or SBRs (Software Bin Records) for the specified bins, plus the
datalog records (PIR, PTR, MPR, FTR, PRR) for the devices in the bins. (See the note on
PTRs under “Additional Notes” on page 25-26.)
Filter Failing Devices: filter_failed_devices
Excludes or includes all datalog records for failed devices.
Format. The filter_failed_devices command has the following syntax:
filter_failed_devices -i [input file] [output file]
filter_failed_devices -e [input file] [output file]
Action. This filter excludes (or includes only) the datalog information on any device that
failed. Datalog information consists of these record types: PIR, PTR, MPR, FTR, and PRR.
The filter does not affect any other record type. With the -i switch, the filter includes datalog
records only for devices that failed; with the -e switch, it excludes datalog records for any
devices that failed. (See the note on PTRs under “Additional Notes” on page 25-26.)
A failed device is identified by testing bit 3 of the PART_FLG field of the PRR.
IMAGE Solutions V8.3 25-29
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
Filter by Standard Deviations: filter_nsigma
Exclude or include datalog readings that fall outside a certain number of sigmas.
Format. The filter_nsigma command has the following syntax:
filter_nsigma -i n [input file] [output file]
filter_nsigma -e n [input file] [output file]
where n is an integer from 1 to 10 indicating the number of sigmas.
Action. This filter excludes (or includes only) those datalog readings that fall outside the
specified number of sigmas. The program first reads the file and calculates the sigma for all
datalog tests; it then applies the filter limit, and includes or excludes the appropriate records.
With the -i switch, the filter includes only those PTRs (Parametric Test Result Records) or
MPRs (Multiple-Result Parametric Test Records) that fall outside the limits; with the -e
switch, it excludes any PTR or MPR that falls outside the limits. It does not affect any other
data types. (See the note on PTRs under “Additional Notes” on page 25-26.)
Retest Data: retest_by_part_id and retest_by_xy_coordinate
Replaces datalog readings with retest data.
Format. The retest_by_part_id and retest_by_xy_coordinate commands have the
following syntax:
retest_by_part_id [input file] [output file]
retest_by_xy_coordinate [input file] [output file]
Action. These filters replace datalog readings with retest data. The difference between the
two filters is how the retested part is identified: by part ID or by X/Y coordinates. This is
represented in the STDF file as follows:
• Identified by Part ID:
In the PRR, if bit 0 of the PART_FLG field is set, then the datalog records in the current
sequence supersede any previous sequence whose PRR has the same PART_ID value.
• Identified by X/Y Coordinates:
In the PRR, if bit 1 of the PART_FLG field is set, then the datalog records in the current
sequence supersede any previous sequence whose PRR has the same X_COORD and
Y_COORD values.
The filters work as follows:
• retest_by_part_id:
When bit 0 of the PART_FLG of the PRR is set, delete the earlier sequence of datalog
records whose PRR has the same PART_ID as this PRR.
• retest_by_xy_coordinate:
When bit 1 of the PART_FLG of the PRR is set, delete the earlier sequence of datalog
records whose PRR has the same X_COORD and Y_COORD values as this PRR.
In both cases, the deleted sequence is defined as the PIR, PTRs, MPRs, FTRs, and PRR
that have the same HEAD_NUM and SITE_NUM value. The filters do not affect any other record
types. (See the note on PTRs under “Additional Notes” on page 25-26.)
IMAGE Solutions V8.3 25-30
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
Compress the File: filter_extra
Removes redundant default data from PTRs.
Format. The filter_extra command has the following syntax:
filter_extra [-x] [-t] [input file] [output file]
Action. This filter excludes all redundant data in Parametric Test Records (PTRs). The
redundant PTR data consists of the default data concerning units, scaling, limits, and
formatting. Ideally, the default data should appear in the first PTR. All subsequent PTRs that
use the default values should have these fields omitted to save space.
If an STDF file has not omitted the redundant default data, this filter removes it. It first writes
the PTRs with the default data before any of the PIRs in the file. (This filter places the PTRs
containing the necessary default data before the PIRs to make sure that other filters do not
remove this data.) This filter then removes any redundant default data from the subsequent
PTRs.
The optional switch -x removes any PIR/PRR pair that has no PTRs associated with it.
“Empty” PIR/PRR pairs can cause problems for data conversion and analysis programs.
The optional switch -t removes the TEST_TXT field from all PTRs except for those PTRs
that appear before all PIRs, that is, the PTRs that contain the default data. (If the TEST_TXT
value varies between devices, do not use this switch.)
A subsequent PTR can have a value for a default field. This means that, for this execution
only, the current value overrides the default value. If the STDF file contains such variations
between devices, do not use this filter; if you do, you will lose valid values unique to a
device.
Some STDF files have a sequence like this:
PIR
PTR (test 5, no result, default fields)
PTR (test 5, result, no default fields)
...
PRR
Because the filter places the PTRs with default data in front of all PIRs, it removes any PTRs
with default data found within PIR/PRR pairs.
NOTE
This filter results in a format that is consistent with STDF V3 files converted into V4. In V3,
the default data was put in Parametric Test Description Records (PDRs). A V4 PTR
containing default data but no test result value is comparable to a V3 PDR.
Convert FTRs to PTRs: filter_ftr
Converts data in FTRs into PTRs.
IMAGE Solutions V8.3 25-31
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
Format. The filter_ftr command has the following syntax:
filter_ftr [c,v,r,n,x,y,f,b,o] [input file] [output file]
Action. This filter converts data in Functional Test Record (FTR) fields into Parametric Test
Records (PTRs). Many data analysis programs work only on parametric test data. This filter
lets you put functional test data into parametric format so you can use it with these tools.
The switches (detailed in table 25-7) specify which FTR fields this filter will convert into
PTRs. This filter creates one PTR for each field you specify. That is, if you specify five fields,
it will create up to five PTRs for each FTR in the file. (If a specified field in an FTR is empty,
this filter does not create a PTR.) This filter stores the FTR data value in the RESULT field
of the PTR.
The new PTRs need test numbers that do not conflict with existing PTR test numbers. To
generate unique PTR test numbers, the filter does the following:
• It calculates a base test number, which is the next multiple of 10 after the highest
existing PTR test number: for example, if the highest PTR test number is 124, the base
test number for the new PTRs will be 130.
• The first FTR to be converted will have test numbers that use this base test number. The
second FTR will use the base test number plus 10 (130), the third FTR will use the base
test number plus 20 (140), and so on.
• For each FTR, there will be one PTR for each FTR field specified by switches. Each field
has an offset defined for it. The filter adds this offset to the test number that has been
calculated for the FTR. That is, the test number for a PTR will be the base test number
plus the multiple of 10 for this FTR plus the offset for this field.
Assume the following:
• The highest existing PTR test number is 124, so the base test number is 130
• Three FTRs are to be converted that will use test numbers 130, 140, and 150
• The specified FTR fields are NUM_FAIL (offset = 3) and FAIL_PIN (offset = 7)
The six PTRs generated from these three FTRs will have these test numbers: 133, 137, 143,
147, 153, and 157.
This filter also creates a Test Synopsis Record (TSR) for each PTR created to store the test
name. The new TSR takes the test name from the existing TSR for the source FTR and
appends to it the FTR field name whose value the filter has stored in the new PTR.
Switches used to specify fields and the offset for each field are shown in table 25-7
Table 25-7. Switches Used to Specify Fields
Switch FTR Field Offset
c CYCL_CNT 0
v REL_VADR 1
r REPT_CNT 2
IMAGE Solutions V8.3 25-32
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
Table 25-7. Switches Used to Specify Fields (Continued)
Switch FTR Field Offset
n NUM_FAIL 3
x XFAIL_AD 4
y YFAIL_AD 5
f VECT_OFF 6
b FAIL_PIN 7
o OP_CODE 8
If you do not include any switches, all nine fields are considered to be specified.
If there are FTRs that you do not want to convert, first use filter_test to remove them
from the file before calling filter_ftr.
Repair STDF Files: stdf_repair
stdf_repair repairs incomplete STDF files. For details on stdf_repair, see “Repairing
STDF Files: stdf_repair” on page 25-16.
The stdf_repair utility uses stdin and stdout; therefore, you can use it with other filters.
NOTE
If you use stdf_repair, it must be the first filter in the pipe.
The format is as follows:
stdf_repair input-file | filter_test -e 2,4,6 > output-file
Null Filter
In addition to the other filters, the Datapump provides the C code and make file for a null
filter. The null filter program reads an STDF file, and writes out a nearly identical STDF file.
The only difference is that it adds an ATR to indicate the filter that it applied.
Like all other valid record types, user-defined record types (REC_TYP >= 200) and executive-
reserved record types (REC_TYP = 180 or 181) are copied unchanged from the input file to
the output file. The null filter does not do any byte conversion on the data in these records.
It assumes that it is running on the same kind of CPU as the system that created the file.
The null filter does write the correct record length to the REC_LEN field of the header.
IMAGE Solutions V8.3 25-33
IMAGE Base Language: STDF Utilities and Filters: STDF Filters
Table of Contents Index Home Master Index Search Help
The null filter takes two arguments: the input and output files. If you omit the output file, the
filter writes the file to stdout; if you omit both files, the filter reads the input from stdin and
writes to stdout.
You can use this program as a template for writing your own filters. The C code is fully
commented for easy modification.
You can find the null filter program and its make file in:
$IMAGEBIN/custom/stdf.filters
As installed, the null filter program is not compiled. To compile it, use the make file in the
same directory. Use this command line:
% make -f make_null
IMAGE Solutions V8.3 25-34
IMAGE Base Language: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
26 BASE IMAGE FUNCTIONS
This section describes functions you can call from test programs. Functions are listed in
table 26-1, and function definitions begin on page 26-39. Table 26-11 describes obsolete
functions for your reference.
Additional functions specific to tester types are listed in other manuals as follows:
• “Catalyst Functions” in the Catalyst Instrumentation Manual
• “Catalyst Tiger Functions” in the Catalyst Tiger Instrumentation Manual
• “FlexDSP Programmer’s Reference” on page 27-1 lists all functions for FlexDSP data
arrays
IMAGE Solutions V8.3 26-1
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Base IMAGE Functions
IMAGE calls functions that set values used to begin testing a device lot only if the values
are unchanged (using other commands) since the start of the lot. If the values have
changed, IMAGE reads these functions and assigns the values to the next device lot. See
“Opening a Lot Using the startlot Command” on page 6-7 on the startlot command and
starting device lots.
Note that some read functions take an “array to be filled in” as an argument. In general,
declare such arrays as S_STDF_STRING in size. That is, as: char s[S_STDF_STRING];. The
STDF specification supports strings of up to 256 characters, which is the current value of
the macro S_STDF_STRING. (See “Standard Test Data Format” on page 24-1 for information
on STDF.)
Table 26-1. Base IMAGE Test Program Functions
Function Action
ftoi Convert double to int with rounding
handlerprober_bin Send bin command to handler (obsolete)
handlerprober_init Initialize handler software interface
handlerprober_reset Reset handler software interface
handlerprober_start Wait for handler start (obsolete)
Hprintf Print a heading string to the datalog
Lprintf Print a formatted string to the datalog report
lprintf Print a formatted string to the datalog report
Mprintf Print a formatted string to the datalog report
next_device_is_retest Force the next device to be a retest
rdelay Function to wait for relay delay
rdelay_time Wait for relay delay then return time waited
read_ac_clock Read back An clock frequency setting
read_ac_freq_pin Return the frequency of the ac clock
read_ac_vrng Read back the voltage range of an ac instrument
read_ac_vrng_chan Read back the voltage range of an AC instrument
read_ac_vrng_slot Read back the voltage range of an AC instrument
read_apu Read results of simulated APU local meter
measurement
IMAGE Solutions V8.3 26-2
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
read_apu_pin Read results APU local meter measurement
read_apu_pin_multisite Read results APU local meter measurement
read_apu_pin_status Read status of APU pin number
read_apu_status Read status of APU number
read_bin_is_open Is a bin open or closed?
read_bin_is_pass Is a bin is a pass bin or a fail bin?
read_cdig_all_fail_vectors Get information for all failing vectors
read_cdig_all_fail_vectors_pin Get information for all failing vectors
read_cdig_failed Check for pattern failures
read_cdig_failed_segment Check if pattern failed in segment
read_cdig_failed_slot Check for pattern failures
read_cdig_n_fail_vectors Get information for first n failing vectors
read_cdig_n_fail_vectors_pin Get information for first n failing vectors
read_cdig_timing_range Read currently set timing range
read_cdig_timing_range_pin Read currently set timing range
read_configuration_status Read status of last configuration check
read_current_site Get current site number
read_databits User level read databits function
read_databits_true User level read databits function
read_dps_amm_pin_status Read status of DPS ammeter
read_dps_dib_ctrl_data Reads DIB control data
read_dps_low_i_n Read low current from QVS Local Meter and average
read_dps_low_i_time Read low current from QVS Local Meter and
read_dps_meter_pin_status Read status of DPS ammeter
read_dps_pin Read current from DPS Local Meter
read_dps_pin_n Read current from DPS Local Meter and average
read_dps_pin_nostrobe Read current from DPS Local Meter
IMAGE Solutions V8.3 26-3
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
read_dps_pin_status Returns the status of the last CPU
read_dps_pin_time Read current from DPS Local Meter and
read_fail_vectors Return vector number of failed vector
read_funct_halt Read HSD pattern haltcode.
read_h50_code Read SCM READCODE register
read_h50_code_nac Read SCM READCODE, no alarm check.
read_hfdig_vrng Read back the voltage range of an HFDIG
read_hram_loc Search History RAM for a cycle
read_hram_scm Read SCM information for a History RAM location
read_hsd50_results Get Catalyst failed pin list.
read_lfdig_vrng Read back the voltage range of an LFDIG
read_lowest_bin_at_fail Read back best bin at point of failure
read_lowest_open_bin Bin number of best currently open bin
read_measurement Take and return a DC measurement.
read_measurement_n Return the average of N measurements
read_measurement_nostrobe Read a previously-taken measurement
read_measurement_time Average of measurements over time
read_measurement_time_and_n Average and number of measurements over time
read_meter Take a measurement with the system DC meter
read_meter_n Return average of N readings
read_meter_nostrobe Return reading without taking a new one
read_meter_time Return average of readings over time
read_meter_time_and_n Return average and number of readings over time
read_opamp_loop_alarm Read status of opamp open loop alarm
read_opamp_osc_alarm Read status of opamp osc alarm
read_ovi_amm_pin_status Read status of OVI ammeter
read_ovi_amm_status Read status of OVI ammeter
IMAGE Solutions V8.3 26-4
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
read_ovi_i Read current from OVI local meter
read_ovi_i_n Read current from OVI local meter and average
read_ovi_i_nostrobe Read voltage from OVI local meter without strobing
read_ovi_i_pin Read current from OVI local meter
read_ovi_i_pin_n Read current from OVI local meter and average
read_ovi_i_pin_nostrobe Read current from OVI local meter
read_ovi_i_pin_time Read current from OVI local meter and average over
time
read_ovi_i_time Read current from OVI local meter and average
read_ovi_meter_pin_status Read status of OVI voltmeter and ammeter
read_ovi_meter_status Read status of OVI voltmeter and ammeter
read_ovi_r Calculate for a channel
read_ovi_r_pin Calculate resistance for a channel
read_ovi_v Read voltage from OVI local meter
read_ovi_v_i Read voltage, current from OVI local meter
read_ovi_v_i_n Read voltage, current from OVI local meter
read_ovi_v_i_nostrobe Read voltage, current from OVI local meter
read_ovi_v_i_pin Read voltage and current from OVI local meter
read_ovi_v_i_pin_n Read voltage and current from OVI local meter
read_ovi_v_i_pin_nostrobe Read voltage and current from local meter
read_ovi_v_i_pin_time Read voltage and current from OVI local meter
read_ovi_v_i_time Read voltage and current from OVI local meter
read_ovi_vm_pin_status Read status of OVI voltmeter
read_ovi_vm_status Read status of OVI voltmeter
read_ovi_v_n Read voltage from OVI local meter and average
read_ovi_v_nostrobe Read voltage from OVI local meter without strobing
read_ovi_v_pin Read voltage from OVI local meter
read_ovi_v_pin_n Read voltage from OVI local meter and average
IMAGE Solutions V8.3 26-5
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
read_ovi_v_pin_nostrobe Read voltage from OVI local meter
read_ovi_v_pin_time Read voltage from OVI local meter and average
read_ovi_v_time Read voltage from OVI local meter and average
read_pacs_clock Read A(n) clock frequency for PACS
read_plfdig_vrng Read back the voltage range of a PLFDIG
read_plfs_integrator Read the input bits of the PLFSRC
read_proto_slot_reg Read the value of specified prototype board register
read_qvs_low_i Intermediate func to call read_qvs_low_i2()
read_sitemask_all Return site mask for all sites
read_sitemask_disabled Return site mask for all disabled sites
read_sitemask_enabled Return site mask for all enabled sites
read_sitemask_failed_sequencer Return site mask for failed sites
read_sitemask_sleep Return site mask for all sleeping sites
read_spec Read back the current value of a spec
read_spec_max Read back the maximum value of a spec
read_spec_min Read back the minimum value of a spec
read_test_condition Return currently selected test condition
read_test_condition_name Get name of selected test condition
read_test_status Read status of last test executed
read_test_status_alarm Check if last test executed had alarm
read_tjd_sample_count Read the count of the TJD captured samples
read_tjd_status Return the status of the last Time-Jitter Digitizer
capture
read_tset_num Read back tset number of the given tset name
read_uwport_one_port Read calibrated s-parameter
read_uwport_one_port_cal_std S-parameter calibration
read_uwport_one_port_cal_std_slot S-parameter calibration
read_uwport_one_port_slot Read calibrated s-parameter
IMAGE Solutions V8.3 26-6
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
read_uwport_raw_one_port Read uncalibrated s-parameter
read_uwport_raw_one_port_slot Read uncalibrated s-parameter
read_uwport_raw_two_port_s11 Raw s11 readback function (2-port)
read_uwport_raw_two_port_s11_slot Uncalibrated s11 readback
read_uwport_raw_two_port_s12 Raw s12 readback function (2-port)
read_uwport_raw_two_port_s12_slot Uncalibrated s12 readback
read_uwport_raw_two_port_s21 Raw s21 readback function (2-port)
read_uwport_raw_two_port_s21_slot Uncalibrated s21 readback
read_uwport_raw_two_port_s22 Raw s22 readback function (2-port)
read_uwport_raw_two_port_s22_slot Uncalibrated s22 readback
read_uwport_two_port_cal_std_forward S-parameter calibration
read_uwport_two_port_cal_std_forward_ S-parameter calibration
slot
read_uwport_two_port_cal_std_reverse S-parameter calibration
read_uwport_two_port_cal_std_reverse_ S-parameter calibration
slot
read_uwport_two_port_s11 Calibrated s11 readback
read_uwport_two_port_s11_slot Calibrated s11 readback
read_uwport_two_port_s12 Calibrated s12 readback
read_uwport_two_port_s12_slot Calibrated s12 readback
read_uwport_two_port_s21 Calibrated s21 readback
read_uwport_two_port_s21_slot Calibrated s21 readback
read_uwport_two_port_s22 Calibrated s22 readback
read_uwport_two_port_s22_slot Calibrated s22 readback
read_uwrecv_amp Calibrated amplitude readback
read_uwrecv_amp_array Read back calibrated power measurements
read_uwrecv_amp_array_slot Read back calibrated power
read_uwrecv_amp_byif Read amplitude for IF freq
IMAGE Solutions V8.3 26-7
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
read_uwrecv_amp_slot Slot version of read_uwrecv_amp()
read_uwrecv_amp_slot_byif Read calibrated amplitude
read_uwrecv_cal_const Return calibration constant used by Microwave
Receiver
read_uwrecv_cal_const_array Read back Microwave Receiver calibration constants
read_uwrecv_cal_const_array_slot Read back power calibration constants
read_uwrecv_cal_const_slot Return calibration constant used by Microwave
Receiver
read_uwrecv_fs Read back the fs a UWRECV is using
read_uwrecv_fs_slot Read back the fs a UWRECV is using
read_uwrecv_if Read back the if a UWRECV is using
read_uwrecv_if_slot Read back the if a UWRECV is using
read_uwrecv_phase_noise_PSD Read back calibrated phase noise
read_uwrecv_phase_noise_PSD_array Read back calibrated phase noise
read_uwrecv_phase_noise_PSD_array_slo Read back calibrated phase noise
t
read_uwrecv_phase_noise_PSD_slot Read back calibrated phase noise
read_uwrecv_PSD Read back calibrated power spectral
read_uwrecv_PSD_array Read back calibrated power spectral
read_uwrecv_PSD_array_slot Read the calibrated Power Spectral Density estimate
read_uwrecv_PSD_slot Read calibrated Power Spectral Density
read_uwrecv_sample_size Return number of samples UWRECV programmed to
take
read_uwrecv_sample_size_slot Return number of samples UWRECV programmed to
take
read_uwrecv_uncal_amp Read uncalibrated RF amplitude
read_uwrecv_uncal_amp_array Read back uncalibrated power
read_uwrecv_uncal_amp_array_slot Read back uncalibrated power
read_uwrecv_uncal_amp_byif Read uncalibrated amplitude at frequency
IMAGE Solutions V8.3 26-8
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
read_uwrecv_uncal_amp_slot Read uncalibrated amplitude
read_uwrecv_uncal_amp_slot_byif Read uncalibrated amplitude at frequency
read_uwrecv_uncal_PSD Read uncalibrated Power Spectral Density
read_uwrecv_uncal_PSD_array Read back uncalibrated power
read_uwrecv_uncal_PSD_array_slot Read back uncalibrated power
read_uwrecv_uncal_PSD_slot Read uncalibrated Power Spectral
read_vmcu Driver function to read VMCU values
smprintf Print a formatted string to the summary report
tl_add_datalog_output Add an output stream to datalog
tl_add_datastream Enable a new data stream
tl_addr_r Read from an address in Terabus space
tl_addr_w Write to pointer into Terabus space
tl_alarmcheck Check test system for alarms and take action
tl_apu_cal_set_interval Set calibration time interval
tl_apucal_time Query time since last UB APU calibration
tl_apu_read_pin_status Read status of APU pin number
tl_asu_present Check ASU present
tl_asu_read_ad Read A/D value with correction value
tl_asu_read_code Read A/D code
tl_asu_read_lsb Read LSB value
tl_asy_conn_pmm_vmdiff Connect PMM to matrix lines 7 and 8
tl_asy_disc_pmm Disconnect PMM from ASY
tl_ath_area_size Return area size
tl_ath_measure_data_pin_freq Measure DATA pin frequency
tl_ath_measure_gate_pin_freq Measure GATE pin frequency
tl_ath_read_capacitance Get capacitance value
tl_ath_read_counter Get frequency counter value
IMAGE Solutions V8.3 26-9
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_ath_read_frequency Get frequency value
tl_awg4800_max_fs_to_6400 Changes fsmax to 6400MHz from 4800MHz
tl_awg4800_vca_map_debug Set vca mapping debug flags.
tl_bbac_disable_clock_error_messages Disable clock error
tl_bbac_disable_dut_connects Disable connections to the DUT
tl_bbac_disable_linearity_corrections Disable linearity corr.
tl_bbac_enable_clock_error_messages Enable clock error
tl_bbac_enable_dut_connects Enable connections to the DUT
tl_bbac_enable_linearity_corrections Enable linearity corr.
tl_begin_lot Begin a new device lot
tl_begin_new_lot Begin a new device lot
tl_bin_fail Set device bin to fail bin
tl_bin_pass Set device bin to pass bin
tl_cal_get_autocal_mode Return autocal mode (on/off/ignore)
tl_cal_get_autocal_state Return flag indicating calibration state
tl_cal_get_inst_crit Get autocal criteria for instrument
tl_cal_get_inst_mode Return autocal mode for instrument (on/off/ign)
tl_cal_get_inst_state Return flag indicating instrument calibration state
tl_cal_get_remaining Get remaining time/temp until calibration required
tl_cal_inst Calibrate this instrument
tl_cal_report Print a report of autocal for all instruments
tl_cal_set_autocal_mode Change autocal mode (on/off/ignore)
tl_cal_set_inst_crit Change autocal criteria for instrument
tl_cal_set_inst_mode Change autocal mode for instrument (on/off/ign)
tl_cal_set_uncal Force instrument to be uncalibrated
tl_cdig_set_cal_interval Set Serial Bus channel card calibration interval
tl_change_auto Change the auto debug mode
IMAGE Solutions V8.3 26-10
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_change_datalog Change the setup of the active datalogs
tl_change_datatastream Change the setup of the specified datastream
tl_change_site Change the default debug display site number
tl_close_mux Close the mux
tl_cmu_get_roi_height Get height of ROI
tl_cmu_get_roi_width Get width of ROI
tl_cmu_get_roi_x_pos Get X position of First pixel
tl_cmu_get_roi_y_pos Get Y position of First pixel
tl_create_tsr_for_ival In STDF output stream create TSR records for
intermediate values
tl_d_dump_all_patterns Dump all digital patterns
tl_d_no_timing_reset Flag to disable timing resets
tl_d_share_enable Enable pattern sharing for digital subsystem
tl_databits_address_set_board Set board address of expansion databits in RTP
tl_databits_unlock_code_set Set unlock code of databits
tl_databits_unlock_code_set_board Set unlock code of databits
tl_datalog_endseq_on_fail Have IMAGE datalog (or not)
tl_datalog_ival Datalog intermediate values
tl_datalog_start_new_device Begin datalog for new device
tl_dccal_dump_constants Dump DC calibration constants to a file
tl_dccal_meter Calibrate voltmeter
tl_dc_cal_set_interval Set DC Subsystem calibration time interval
tl_dccal_src Calibrate a single source in DC Subsystem
tl_dccal_status Return calibration status of each DC Subsystem
instrument
tl_dccal_subr Calibrate DC Subsystem
tl_dccal_time Read time and result of last DC Subsystem calibration
tl_dc_meter_tsy_digitize Digitize with DC meter and trigger switchyard
IMAGE Solutions V8.3 26-11
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_dcvm_cal_status Return cal status of dc voltmeter
tl_debug_site Get the number of the debug display site
tl_declare_event Send a FIRMS event message to the event manager
tl_delay Execute a delay
tl_dfc_disable Disable the Device Focused Checker execution
tl_dfc_enable Enable Device Focused Checkers
tl_dfc_fail_run Return true if DFC failed at last execution
tl_dfc_inst_status Return instrument status
tl_dfc_request Request Device Focused Checker execution
tl_disable_hp_after_rte_off Turn off autodisable of handler or prober on run time
error
tl_disable_hp_after_rte_on Turn on autodisable of handler or prober on run time
error
tl_disable_hp_after_rte_state Return state of autodisable of handler or prober on
run time error
tl_display_autosum_setup Display autosummary setup in station window
tl_dlg_endwafer Datalog end of wafer
tl_dlg_startwafer Datalog start of wafer
tl_dps_set_hotswitch_protection Set test head relay delay flag and two kelvin flag
tl_dsp_check_mem Report on the DSP buffer and memory usage
tl_dsp_dump_info Print DSP memory and buffer information
tl_dsp_get_buffer_address Get real memory address of DSP buffer
tl_dsp_get_mem_size Report in bytes size of usable data memory
tl_dsp_query_ap_type Determine type of DSP engine
tl_dsp_sync Synchronize the test program and Array Processor
tl_dump_configuration Writes valid configuration file to destination
tl_dump_data Dump datalog buffer
tl_edge_binary_search Edge binary search
IMAGE Solutions V8.3 26-12
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_edge_linear_search Edge linear search
tl_efd_is_enabled Determine if Enhanced Functional Datalog setups
exist
tl_endlot Close out an existing lot, generate an auto summary
tl_error_user User error message
tl_exch_comment Write comment to simulator stimulus stream
tl_exch_is_dvx_mode Determine if ExChange is in DVX mode
tl_exch_is_enabled Determine if ExChange is enabled
tl_fflush_nowait fflush without resetting nowait mode
tl_force_jobstats Force job statistics even on handler runs
tl_fvs_cal_dump Dump the FVS calibration table
tl_get_autocal_on Return TRUE if autocal is on, FALSE if off
tl_get_autosetup Retrieve setup information from data server
tl_get_burn_tim Get the burn-in time of parts being tested
tl_get_cabl_id Get the interface cable ID of parts being tested
tl_get_cabl_typ Get the interface cable type of parts being tested
tl_get_cont_id Get the contactor ID of parts being tested
tl_get_cont_typ Read the contactor type of parts being tested
tl_get_data_collection_state Get current state of data collection
tl_get_data_collection_streams Get names/IDs of currently enabled data collection
streams
tl_get_datalog Get information regarding setup of datalog
tl_get_datalog_directory Get name of directory which dataserv is writing
datalog files to
tl_get_datalog_directory_for_stream Get directory a stream is writing a file to
tl_get_datastream Get information regarding setup of datastream
tl_get_degrees_d Convert a double value from radians to degrees
tl_get_degrees_f Convert a float value from radians to degrees
IMAGE Solutions V8.3 26-13
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_get_dib_id Get the DIB board type of the parts being tested
tl_get_dib_typ Get the DIB board type of the parts being tested
tl_get_dsgn_rev Get the device design revision of the parts being
tested
tl_get_eng_id Get the engineering lot ID of the parts being tested
tl_get_extr_id Read the extra equipment id of the parts being tested
tl_get_extr_typ Get the extra equipment type of the parts being tested
tl_get_facil_id Get the test facility ID of the parts being tested
tl_get_famly_id Get the device family ID of the parts being tested
tl_get_floor_id Get the test floor ID of the parts being tested
tl_get_flow_id Get the test_flow ID of the parts being tested
tl_get_hbin_device_count Return the device count for the desired hardware bin
tl_get_hp_name Get the name of the handler or prober
tl_get_hp_type Get the name of the handler or prober
tl_get_hsd_type Get type of digital subsystem
tl_get_inker Get the inker number to fire when bin result received
tl_get_lasr_id Get the laser ID of parts being tested
tl_get_lasr_typ Get the laser_type of parts being tested
tl_get_last_seq_bin Get bin number for last sequencer
tl_get_load_id Get the load board ID of parts being tested
tl_get_load_path Convert a file name into a full path name
tl_get_load_typ Get the load board type of the parts being tested
tl_get_number_of_testheads Get the number of test heads
tl_get_oper_frq Get the test operation frequency of parts being tested
tl_get_part_datalogged Return if current set of parts will be datalogged
tl_get_pkg_typ Get the package type of parts being tested
tl_get_prb_card Get the probe card ID of the parts being tested
tl_get_prb_typ Get the probe card type of the parts being tested
IMAGE Solutions V8.3 26-14
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_get_prog_nam_fullpath Get the fully rooted path name of the test program
tl_get_radians_d Convert a double value from degrees to radians
tl_get_radians_f Convert a float value from degrees to radians
tl_get_sbin_device_count Return the device count for the desired software bin
tl_get_seq_bin Get the sequencer bin number for a site
tl_get_setup_id Get the test setup ID of parts being tested
tl_get_slot_from_pin Return test head slot number from pin
tl_get_sort_bin Get bin number assigned in sort bin statement
tl_get_sort_hbin Get handler bin assigned in sort bin statement
tl_get_spec_nam Get the test spec. name of parts being tested
tl_get_spec_ver Get the test spec. version of parts being tested
tl_getstdftimeofday Return the value of the GMT time of day (in STDF
format)
tl_get_stream_criteria Get test criteria for the given stream
tl_get_stream_filename Return the name of the file the datalog stream is
writing
tl_get_stream_sample_info Return streams sampling rate
tl_get_tester_number Read current tester number
tl_get_tst_temp Get the testing temperature of parts being tested
tl_get_user_power Get the state of the user power relay
tl_get_wavefile_sample_size Get the sample size from a waveform file
tl_gigadig_report_ac_corr_spectrum return error correction spectrum
tl_gigadig_report_chan_mismatch_data report mismatch data between channels
tl_gigadig_report_err report error at a single freq.
tl_gigadig_skew_clock skew GigaDig capture clock
tl_gpib_dump_bus_info Dump information about the GPIB
tl_gpib_dump_gpibcap_info Dump the driver’s copy of gpibcap
tl_gpib_get_ifc_at_reset Read whether IFC is asserted during reset
IMAGE Solutions V8.3 26-15
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_gpib_set_ifc_at_reset Set whether IFC is asserted during reset
tl_h50_channel_to_pin Convert HSD channel number to pin
tl_h50_check_pattern_running Check if pattern is running
tl_h50_check_pattern_running_or_in_ka Check if sequencer run
tl_h50_debug_pmtrc Set the debug state variable for HSD50 parametric
testing
tl_h50_define_scan_headers Set count of variable headers
tl_h50_dsim_roundtrip_delay_time Set or get dsim round trip time
tl_h50_get_pin_name Look up DUT pin name from number
tl_h50_get_site_from_chan Get HSD channel site
tl_h50_highest_chan Get highest channel number
tl_h50_mcfreq Get value of master clock frequency
tl_h50_pin_to_channel Get HSD channel number for a pin
tl_h50_read_dmc_divider Read back DMC divider value
tl_h50_supclk_to_dc (Dis)connect supclk and matrix
tl_handlerprober_exec_action When using GPIB interface, tell IMAGE to execute an
action
tl_hcps_connect_pinmap Connect/disconnect hcps
tl_hcps_debug_kelvin_pin Utility to debug kelvin alarms.
tl_hcps_set_connect_ilim Set current ilim for connect.
tl_hcucal_src Calibrate a single HCU source
tl_hcu_override Override HCU protection
tl_hfdig_report_err Report HFDIG error at a single frequency
tl_hfsc_ramp_cal Perform ramp calibration
tl_hp_abort_probing Stop probing, break device contact
tl_hp_assign_good_die_bins Define what bin codes are considered “good” and
“bad”
tl_hp_assign_logical_ink Define what inkers are fired in response to a particular
bin
IMAGE Solutions V8.3 26-16
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_hp_bin_to_category Send binning command to handler/prober
tl_hp_break_device_contact Open handler jaws at specified site
tl_hp_clear_alarm Clear alarm on handler/prober
tl_hp_get_prober_info Get status information from current prober
tl_hp_gpib_sendcmd Send a command to a handler or prober over the
GPIB
tl_hp_gpib_sendvarcmd Send a command to handler or prober over GPIB bus
tl_hp_handlerconf_flags Show handler setup with handcap information
tl_hp_handlerconf_show Print information on current handlers
tl_hp_handler_isconnected Detect if handler is connected
tl_hp_handler_isenabled Detect if handler is enabled
tl_hp_input_empty_status Determine which input tubes are empty
tl_hp_is_handler Detect if peripheral is handler
tl_hp_is_prober Detect if peripheral is prober
tl_hp_load_setup Load handler/prober setup from file
tl_hp_load_wafer Unload the current wafer on the prober chuck
tl_hp_make_device_contact Close handler jaws at specified site
tl_hp_move_absolute_die Move prober to absolute <x,y> coordinates
tl_hp_move_relative_die Move prober to <x,y> coordinates relative to current
location
tl_hp_move_relative_machine Move prober <x,y> steps relative to current location,
0.1 mil steps
tl_hp_move_z_down Move the Z stage of prober down (out of contact with
probes)
tl_hp_move_z_to_given_height Move Z stage to specified height
tl_hp_move_z_up Move the Z stage of prober up (into contact with
probes)
tl_hp_output_full_status Determine which output tubes are full
tl_hp_parallel_clear_all_start Clear any latched start, retest, and reject signals
IMAGE Solutions V8.3 26-17
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_hp_parallel_clear_autosum Clear a latched auto summary signal
tl_hp_parallel_clear_reject Clear a reject signal latched on the parallel interface
tl_hp_parallel_clear_start Clear any latched start and retest signals
tl_hp_parallel_read_alarm Read the current state of the handler alarm line
tl_hp_parallel_read_all_start Get the state of any latched start, retest, reject, alarm,
and auto summary signals
tl_hp_parallel_set_eos Set the current state of the parallel interface EOS line
tl_hp_probe_wafer Begin probing the wafer on the chuck
tl_hp_request_dut_id Request DUT ID from handler/prober
tl_hp_request_error_code Get current handler/prober error code
tl_hp_request_error_msg Get current handler/prober error message
tl_hp_request_peripheral_id Read ID of handler/prober
tl_hp_request_start Poll handler/prober for start signal
tl_hp_send_command Send RS232 command to handler or prober
tl_hp_send_request Send request to handler/prober, get reply
tl_hp_unload_wafer Unload the current wafer on the prober chuck
tl_hpd_user_fprintf Print to the hpmonitor display and a stream
simultaneously
tl_hpd_user_printf Print to hpmonitor display and station window stdout
simultaneously
tl_hpm_reset Reset the High Power Matrix
tl_hsd50_calibrate_all Calibrate calsets which need it
tl_hsd_connect_pin_to_thads Connect the THADS to a digital channel
tl_hsd_disconnect_pin_from_thads Disconnect the THADS from TDR
tl_hsd_flush_stat_cache Flush the stat system call cache when using load path
in pattern name
tl_hw_settle Wait for hardware relays to settle
tl_i2c_construct_msg Write specified I2C information
tl_i2c_construct_msg_burst Write specified I2C information
IMAGE Solutions V8.3 26-18
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_i2c_construct_msg_pin Write specified I2C information
tl_i2c_construct_msg_setup Write specified I2C information
tl_i2c_construct_msg_setup_pin Write specified I2C information
tl_i2c_data_test Write data and check for acknowledge
tl_i2c_data_test_burst Burst pattern and check for fail
tl_i2c_data_test_pin Write data and check for acknowledge
tl_i2c_data_test_setup Set up pattern for acknowledge
tl_i2c_data_test_setup_pin Set up pattern for acknowledge
tl_i2c_extended_addr_check Write addresses and check for acknowledge
tl_i2c_extended_addr_check_pin Write addresses and check for acknowledge
tl_i2c_free_string_memory Free string memory used by I2C functions
tl_i2c_rcv_data_rpt_test Read data and check for acknowledge
tl_i2c_rcv_data_rpt_test_burst Set up rpt_test_setup patterns
tl_i2c_rcv_data_rpt_test_pin Read data and check for acknowledge
tl_i2c_rcv_data_rpt_test_setup Set up rpt_test_setup patterns
tl_i2c_rcv_data_rpt_test_setup_pin Set up rpt_test_setup patterns
tl_i2c_rcv_data_test Read data and check for acknowledge
tl_i2c_rcv_data_test_burst Burst pattern and return read data
tl_i2c_rcv_data_test_pin Read data and check for acknowledge
tl_i2c_rcv_data_test_setup Set up reads data and check
tl_i2c_rcv_data_test_setup_pin Set up reads data and check
tl_i2c_single_addr_check Write addresses and check for acknowledge
tl_i2c_single_addr_check_burst Write addresses and check for acknowledge
tl_i2c_single_addr_check_burst_pin Write addresses and check for acknowledge
tl_i2c_single_addr_check_pin Write addresses and check for acknowledge
tl_i2c_single_addr_check_rcv Write addresses and check for acknowledge
tl_i2c_single_addr_check_rcv_burst Write addresses and check for acknowledge
IMAGE Solutions V8.3 26-19
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_i2c_single_addr_check_rcv_pin Write addresses and check for acknowledge
tl_i2c_single_addr_check_rcv_setup Write addresses and check for acknowledge
tl_i2c_single_addr_check_rcv_setup_pi Write addresses and check for acknowledge
n
tl_i2c_single_addr_check_setup Set up pattern for address check
tl_i2c_single_addr_check_setup_pin Set up pattern for address check
tl_init Initialize a test program
tl_input_adjust Find an appropriate input given an output
tl_job_is_in_debug Determine if test program is running in debug mode
tl_legal_pin_array Determine if variable is legal pin number
tl_legal_pin_number Determine if variable is legal pin number
tl_lfacd_02_move_alarm_bit Control whether alarm bit is moved
tl_lfacdig_set_precharge_time Set the global pin-independent time for the precharge
tl_lfac_disable_dut_connects Disable connections to the DUT
tl_lfac_enable_dut_connects Enable connections to the DUT
tl_lfacs_conn_deltabus Connect LFACSRC output to delta bus
tl_lfacs_get_wave_fs Read back Fs of an LFACSRC waveform
tl_lfacs_multitone_ac_crest_factor Get crest factor for LFACSRC
tl_lfacsrc_get_grow_dir Get LFACSRC segment growth direction
tl_lfacs_sinxx_amp Calculate LFACSRC sin x/x corrected amplitude
tl_matrix_bank_force Override auto open/close of bank relays
tl_mcfd_clear_counter Reset maximum consecutive failing device count
tl_mcfd_disable_site Disable maximum consecutive failing device
monitoring
tl_mcfd_init Initialize maximum consecutive failure levels
tl_mcfd_monitor_hbin Monitor hardware bins
tl_mcfd_monitoring_on Return state of maximum consecutive failing device
monitoring
IMAGE Solutions V8.3 26-20
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_mcfd_monitor_sbin Monitor software bins for maximum consecutive
device failure
tl_mcfd_switch_off Turn off maximum consecutive failing devices
monitoring
tl_mcfd_switch_on Turn on maximum consecutive failing devices
monitoring
tl_measure_calibrate Calibrate raw measurement samples
tl_measure_calibrate_n Calibrate N raw samples
tl_measure_sample_period Return adjusted sample period
tl_memman_recompact_off Turn off memory recompaction
tl_memman_recompact_on Turn on memory recompaction
tl_memman_recompact_pattern Recompact pattern memory
tl_meter_ave_time_and_n Return average and number of readings over time
tl_meter_filter_info Return the status of the meter's filter
tl_opamp_read_loop_alarm Read status of Opamp Module loop alarm
tl_opamp_read_osc_alarm Read status of Opamp Module osc alarm
tl_open_mux Open the mux
tl_ovi_alarm_disable Disable specified alarms for OVI channel
tl_ovi_local_meter_reset Reset local OVI meter
tl_ovi_set_hotswitch_protection Set OVI test head relay delay flag
tl_ovi_set_thads_atten Set THADS bus attenuation
tl_ovi_set_wave_gain Set gain for wave programming
tl_pacs2_cal_debug_flag Set PACS II calibration debug flag
tl_pacs2cal_dump_cal_tables Print PACS II calibration table
tl_pacs2_clk_cal Perform PACS II clock calibration
tl_pacs2_fetch_cal_val Get PACS II cal constants
tl_pacs2_set_cal_datalog Enable or disable datalog during calibration
tl_pacs_sinxx_amp Calculate sin x/x corrected amplitude
IMAGE Solutions V8.3 26-21
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_pause_data_collection Pause data collection
tl_pgu_change_repeat Change PGU repeat number
tl_pgu_pattern_memory_size Returns the PGU pattern memory size
tl_pin_for_pin_id Translate an alphanumeric pin ID into a pinmap index
tl_pin_id_for_pin Get alphanumeric pin ID for pin number
tl_pinmap_name_for_dchan Get pin name for passed digital channel
tl_pinmap_name_for_pin Get pin name for pin number
tl_plfd_cal_interval Set the PLFDIG calibration interval
tl_plfd_set_optimization Run PLFDIG in optimized setup mode
tl_plfs_cal_interval Set the PLFSRC calibration interval
tl_plfs_conn_deltabus Connect PLFSRC output to the delta bus
tl_plfs_get_amp_filt Apply PLFSRC filter correction to given amplitude
tl_plfs_get_amp_filt_spec Apply PLFSRC filter correction to given amplitude
tl_plfs_undo_amp_filt Undo PLFSRC filter correction to given amplitude
tl_plfs_undo_amp_filt_spec Undo PLFSRC filter correction to given amplitude
tl_plfsrc_get_type_slot Returns plfsrc type given slot number
tl_powerup Variable indicating first execution since powerup
tl_prod_init Provide pre-initialization test program checking
tl_profile_end Close last bin during custom profiling
tl_profile_mark Specify a mark for custom profiling
tl_psrr_lfacsrc_slot Set LFACSRC amp, connect to waveform bus
tl_psrr_plfsrc_slot Set PLFSRC amp and connect to waveform bus
tl_psrr_plfsrc_to_wave Connect an AC Source to the wave bus or Delta bus
tl_ptr_r Read from pointer into Terabus space
tl_ptr_w Write to pointer into Terabus space
tl_qsc_map_dump Dump synthesizer mapping to the station window
tl_qsc_state Dump synthesizer state to the station window
IMAGE Solutions V8.3 26-22
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_qvs_alarm_disable Disable specified alarms for QVS channel
tl_qvs_combine Combine two QVS channels into one
tl_qvs_set_hotswitch_protection Set test head relay delay flag and two kelvin flag
tl_read_and_set_dib_info Read and set the DIB ID and DIB type
tl_read_and_set_prb_info Read and set the probe card ID and type
tl_read_cmod_cod Return the value of the command mode code
tl_read_datnum Read the datalog number for a test
tl_read_device Read the value of the current DUT
tl_read_device_site Read the value of the DUT of given site
tl_read_dib_type_int Read back DIB Type code as integer.
tl_read_disp_cod Read the value of the lot disposition
tl_read_exec_typ Return the name of the test executive
tl_read_format Return the format for the current test
tl_read_gigadig_hpfilt_slot Returns status of hpfilt setting.
tl_read_hbin_is_pass Is a hardware bin is a pass bin or a fail bin?
tl_read_hfdig_hpfilt Return status of HFDIG hpfilt setting
tl_read_hfdig_hpfilt_slot Return status of HFDIG hpfilt setting
tl_read_highlim Return the value of the upper test limit
tl_read_ids Get a concatenation of the lot and sublot IDs
tl_read_job_nam Return the name of the currently loaded test program
tl_read_job_rev Return the test program revision
tl_read_label Read the label assigned to the current test
tl_read_label_size Return the size of the label assigned to the current
test
tl_read_label_truncate Return the label assigned to the current test
tl_read_lot_id Read the value of the current lot ID
tl_read_lowlim Return the value of the lower test limit
tl_read_meter_n_wmd_set Set tl_read_meter_n_wmd to value
IMAGE Solutions V8.3 26-23
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_read_mode_cod Read the mode code for the current lot
tl_read_node_nam Read the tester (network) node name
tl_read_oper_nam Return the name of the current operator
tl_read_part_cnt Read the number of parts tested for the lot
tl_read_part_id Read the device number (or other ID) for the DUT
tl_read_part_typ Read the part type text string
tl_read_proc_id Read the process ID of the parts being tested
tl_read_prot_cod Read the value of the data protection code
tl_read_rtst_cod Read the value of the retest code
tl_read_sbin_is_pass Is a software bin is a pass bin or a fail bin?
tl_read_sblot_id Return the value of the sublot ID
tl_read_setup_t Read the value of the setup time variable
tl_read_start_t Read the time a lot was started
tl_read_station_num Read current station number
tl_read_supr_nam Return the name of the current supervisor
tl_read_test_cod Read the test code
tl_read_tja Read measurement val from DARRAY
tl_read_tja_array Read measurement array from DARRAY
tl_read_tmscal_status Return calibration state of TMS
tl_read_tstr_typ Read the tester type
tl_read_usr_desc Read the user description
tl_read_user_eeprom_all_data Read all data from HUC IDPROM
tl_read_user_eeprom_id_data Read coded data from HUC IDPROM
tl_read_uwrecv_digslot Read back the slot of the digitizer UWRECV is using
tl_read_uwrecv_digslot_slot Read back the slot of the digitizer UWRECV is using
tl_read_uwrecv_thads Read back THADS the UWRECV is using
tl_read_uwrecv_thads_slot Read back THADS the UWRECV is using
IMAGE Solutions V8.3 26-24
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_read_wafer Read back wafer coordinates, if set
tl_read_wafer_mapping_ink_bin Return value of ink bin
tl_remove_datastream Remove a data stream
tl_remove_datalog_output Remove an output stream from datalog
tl_reprobing_device Report whether the current set of
tl_restore_site_state Restore a saved site state
tl_resume_data_collection Resume data collection if it was paused
tl_retesting_device Report whether the current set of
tl_retrieve_d Retrieve the value of a variable of type double
tl_retrieve_i Retrieve the value of an integer variable
tl_rs232_close Close a device specified by devHandle
tl_rs232_open Open a tty (RS232) device
tl_rs232_open_remote_port Open remote rs232 port
tl_rs232_read Read from a tty (RS232) device
tl_rs232_write Write to a tty (RS232) device
tl_send_to_SECS_GEM Send a string to SECS/GEM
tl_set_alarm_msg_mode Set destination for alarm messages
tl_set_autocal_onoff Turn autocal on or off
tl_set_autosummary Set autosummary from the test program
tl_set_burn_tim Set burn-in time for the current lot
tl_set_cabl_id Set interface cable ID for the current lot
tl_set_cabl_typ Set interface cable type for the current lot
tl_set_cmod_cod Set command mode code for the current lot
tl_set_cont_id Set contactor ID for the current lot
tl_set_cont_typ Set contactor type for the current lot
tl_set_datalog Provides user control of datalog
tl_set_datalog_disk_usage Set expected datalog disk usage for the Disk Monitor
IMAGE Solutions V8.3 26-25
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_set_device Set device ID for current run
tl_set_dib_id Set DIB ID for the current lot
tl_set_dib_typ Set DIB board type for the current lot
tl_set_disp_cod Set disp_cod for the current lot
tl_set_dlg_enable Enable/disable datalog
tl_set_dsgn_rev Set the device design revision for the current lot
tl_set_efd_datalog Provides user control of EFD
tl_set_eng_id Set the engineering lot ID for the current lot
tl_set_extr_id Set extra equipment ID for the current lot
tl_set_extr_typ Set extra equipment type for the current lot
tl_set_facil_id Set the test facility ID for the current lot
tl_set_famly_id Set device family ID for the current lot
tl_set_floor_id Set test floor ID for the current lot
tl_set_flow_id Set test flow ID for the current lot
tl_set_hand_id Set handler id for the current lot (obsolete)
tl_set_hp_name Set the handler or prober ID string
tl_set_hp_type Set the handler or prober type
tl_set_inker_map Create mapping of inker to site and define bin
numbers to fire inker
tl_set_job_nam Set program name for the current lot
tl_set_job_rev Set test program revision for the current lot
tl_set_lasr_id Set laser ID for the current lot
tl_set_load_id Set load board ID for the current lot
tl_set_load_typ Set load board type for the current lot
tl_set_lot_id Set the lot ID for the current lot
tl_set_lot_ids Set both lot and sublot ID for the current lot
tl_set_mode_cod Set mode code for the current lot
tl_set_msg_mode Set destination for error/alarm messages
IMAGE Solutions V8.3 26-26
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_set_next_device Set device ID for next run
tl_set_ONLY_test_condition Set the test condition for the current lot without
changing the test_cod field
tl_set_oper_frq Set the testing operation frequency for the current lot
tl_set_oper_nam Set operator name for the current lot
tl_set_part_datalogged Set whether or not the current
tl_set_part_fix Set user-defined part fix string
tl_set_part_typ Set part type for the current lot
tl_set_pkg_typ Set the package type for the current lot
tl_set_plfdig_legacy_filter_settling_time Set or clear a flag to use old PLFDIG filter settling
s times
tl_set_prb_card Set probe card ID for the current lot
tl_set_prb_typ Set probe card type for the current lot
tl_set_proc_id Set process ID for the current lot
tl_set_prog_nam Set program name for the current lot
tl_set_prot_cod Set protection code for the current lot
tl_set_rom_cod Set the ROM code id for the current lot
tl_set_rtst_cod Set the retest code for the current lot
tl_set_sblot_id Set sublot ID for the current lot
tl_set_serl_num Set the tester serial number for the current lot
tl_set_setup_id Set setup ID for the current lot
tl_set_spec_nam Set test specification name for the
tl_set_spec_ver Set sub
tl_set_supr_nam Set supervisor name for the current lot
tl_set_test_cod Set test code for the current lot
tl_set_test_condition Set the test condition for a lot
tl_set_test_condition_during_lot Set the test condition for a lot during the lot
tl_set_tmode Set program termination mode
IMAGE Solutions V8.3 26-27
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_set_tsr_test_tim Set the Average Test Time field in the Test Synopsis
Record
tl_set_tst_temp Set the testing temperature for the current lot
tl_set_user_power Set the state of user power
tl_set_usr_desc Set user-defined lot information string
tl_set_wafer Set wafer coordinates for current devices
tl_set_wafer_id Set wafer ID for the current wafer
tl_set_wafer_mapping_ink_bin Designate bin number for the ink bin
tl_set_wait Set a retriggerable wait time
tl_set_wait_timeout Set user retriggerable wait timeout
tl_simwave_name Set file name for AC wave source simulator
tl_sinxx_amp Calculate sin x/x corrected amplitude
tl_site Global variable indicating current site number
tl_site_active Determine if sites are still qualified
tl_site_shutdown Call user function when site fails
tl_smem_read_wave_sample_max Return the wave sample size maximum
tl_smem_set_wave_sample_max Set the wave sample size maximum
tl_sps_ammeter_connect Set the HVA connect bit
tl_sps_ammeter_disable_alarm Disable the selected alarm
tl_sps_ammeter_enable_alarm Enable the selected alarm
tl_sps_ammeter_reset Reset the High Voltage Ammeter
tl_sps_discon_meter_input Disconnect SPS from meter input
tl_sps_gateoff Set the SPS gate enable bit off
tl_sps_gateon Set the SPS gate enable bit
tl_sps_get_amm_cal_stat Return HVA calibration status
tl_sps_get_amm_cal_time Return HVA calibration time
tl_sps_get_fvs_status Get FVS alarm status
tl_sps_get_hccs_status Get HCCS alarm status
IMAGE Solutions V8.3 26-28
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_sps_get_hcvs_status Get HCVS alarm status
tl_sps_get_hpvi_status Get HPVI alarm status
tl_sps_get_hvs_status Get HVS alarm status
tl_sps_hccs_comp Set HCCS compensation
tl_sps_hccs_connect Connect the HCCS to the DUT
tl_sps_hccs_disconnect Disconnect the HCCS from the DUT
tl_sps_hcvs_comp Set HCVS compensation
tl_sps_hcvs_connect Connect the HCVS to the DUT
tl_sps_hcvs_disconnect Disconnect the HCVS from the DUT
tl_sps_hpvcc_alarm_clear Set the HPVI alarm clear bit
tl_sps_hpvcc_connect Connect the HPVCC to the DUT
tl_sps_hpvcc_connect_bvcs Optimized connect to the BVCS
tl_sps_hpvcc_disconnect Disconnect the HPVCC from the DUT
tl_sps_hpvcc_gateoff Set the gate enable bit off the HPVCC
tl_sps_hpvcc_gateon Set the HPVCC gate enable bit
tl_sps_hpvcc_reset Reset the HPVI
tl_sps_hpvi_comp Set compensation
tl_sps_hvs_connect Connect the HVS to the DUT
tl_sps_hvs_disconnect Disconnect the HVS from the DUT
tl_sps_reset Resets all SPS
tl_sps_set_ammeter Set up the HVA
tl_sps_set_hpvcc Set HPVCC voltage and current
tl_sps_testfor_safety Read the safety bit
tl_statmon_memo Write a memo string to the station monitor display
tl_system Execute a system command from inside a test
program
tl_system_timeout Execute system command from inside a test program
tl_tach_trg_ctrl Connect the TACH trigger bus to the TSY
IMAGE Solutions V8.3 26-29
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_tba_read_timer Use Terabus timer to time something
tl_tbase_addr Get pointer to word of Terabus space
tl_tdef_remaining Get number of test statements remaining
tl_testfor_safety Determine if the tester safety signal is asserted
tl_tj306_delta_drives_wave Set delta bus to drive AABUS II
tl_tj306_wave_drives_delta Set AABUS II wave bus to drive the delta bus
tl_tja_calc_avg_clock Calculate clock period based on event
tl_tja_calc_deviations Calculate event deviations from
tl_tja_calc_intervals Calculate the event intervals between
tl_tja_calc_max Calculate the maximum of the list of numbers.
tl_tja_calc_mean Calculate the mean of the list of numbers.
tl_tja_calc_min Calculate the minimum of the list of numbers.
tl_tja_calc_periods Calculate the periods between event pairs.
tl_tja_calc_pkpk Calculate the peak to peak of the list of
tl_tja_calc_std_dev Calculate the standard deviation of the
tl_tja_move_raw_data_to_darray Does non-mvsched move
tl_tja_num_stamps_captured Return # of stamps captured
tl_tja_read_duty_cycle Read duty cycle val from DARRAY
tl_tja_read_duty_cycle_array Read duty cycle array from
tl_tja_read_event_count Read event_count value from DARRAY.
tl_tja_read_frequency Read frequency val from DARRAY
tl_tja_read_period Read period val from DARRAY
tl_tja_read_period_array Read period array from DARRAY
tl_tja_read_pin_to_pin_delay Read pin-to-pin delay val
tl_tja_read_pin_to_pin_delay_array Read pin-to-pin delay
tl_tja_read_pulse_width Read pulse width val from DARRAY
tl_tja_read_pulse_width_array Read pulse width array from
IMAGE Solutions V8.3 26-30
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_tja_read_ratio_count Read ratio_count val from DARRAY
tl_tja_read_rise_or_fall_time Read rise/fall time val
tl_tja_read_rise_or_fall_time_array Read rise/fall time
tl_tja_read_status Return the status of last capture
tl_tja_read_timestamps Read timestamps from DARRAY
tl_tjd_calc_avg_clock Calculate TJD clock period based on event list
tl_tjd_calc_deviations Calculate TJD event deviations from underlying clock
tl_tjd_calc_intervals Calculate the TJD event intervals between the two
lists
tl_tjd_calc_max Calculate the TJD maximum of the list of numbers
tl_tjd_calc_mean Calculate the TJD mean of the list of numbers
tl_tjd_calc_min Calculate the TJD minimum of the list of numbers
tl_tjd_calc_periods Calculate the periods between event pairs for the TJD
tl_tjd_calc_pkpk Calculate the TJD peak to peak of the list of numbers
tl_tjd_calc_std_dev Calculate the TJD standard deviation of the numbers
tl_tms_cal_has_run Status indicating whether TMS calibration ran
tl_tms_cal_set_interval Set TMS calibration time interval
tl_tsy_cpu_trg_clr Clear the specified TSY trigger latches
tl_tsy_trg_ctrl Connect the mainframe trigger bus to test head
tl_turbo_apply_downconverter_compensation Applies Turbo AC downconverter calibration
compensations to signal spectrum
tl_turbo_apply_downconverter_compensation Applies full Turbo AC downconverter calibration
_full compensations to signal spectrum
tl_turbo_disable_dut_connects Disable connections to the DUT
tl_turbo_disable_linearity_corrections Disable linearity corrrection
tl_turbo_enable_dut_connects Enable connections to the DUT
tl_turbo_enable_linearity_corrections Enable linearity corrrections
tl_turbo_get_1knotch_compensation Report attenuation through 1k notch for a given
frequency
IMAGE Solutions V8.3 26-31
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_turbo_get_downconverter_compensation Retrieves Turbo AC downconverter calibration
compensation for specific frequencies
tl_turbo_measure_src_vrms Measure Vrms amplitude of source channel
tl_turbo_set_cw_cal_amp_tolerance Set amplitude tolerance of CW level calibration
tl_turbo_set_cw_cal_freq_tolerance Set amplitude tolerance of CW level calibration
tl_turbosrc_lp_filter_auto_set Set Turbo AC Source low-pass filter
tl_turn_multi_threaded Turns multithreading on or off or reads current mode
tl_ubvi100_set_supply_reset_state Change reset state of power supply selector
tl_uhfmm_read_freq Return UHFMM freq parameter setting
tl_uhfmm_read_if_freq Return UHFMM if_freq parameter setting
tl_uhfsrc_cal_interval Set the UHFSRC calibration interval
tl_uhfsrc_get_freq Return the current frequency of the UHFSRC
tl_uhfsrc_is_lin_cal_data_valid Print out if lin cal data are valid
tl_uhfsrc_level_table_valid Return whether UHFSRC leveling is valid
tl_uhfsrc_level_table_valid_slot Return whether UHFSRC leveling is valid
tl_uhfsrc_max_freq Return the maximum CW frequency for selected
UHFSRC
tl_uhfsrc_max_mod_freq Return maximum allowable carrier frequency for
UHFSRC
tl_uhfsrc_mod_synth_freq Inquire UHFSRC for its current synth.
tl_uhfsrc_set_table_size Set the maximum size of table for the UHFSRC
tl_uhfsrc_use_lin_cal_data Set uhfsrc_use_lin_cal_data on or off
tl_update_data_collection_state Update data structures in test program with the latest
data collection setup information
tl_user_datalog_changed User function to take action
tl_user_eeprom_present Determine whether EEPROM is present
tl_user_endlot User callable function for custom endlot
tl_user_mcfd_handler User defined function called when a site experiences
maximum consecutive failing devices (MCFD)
IMAGE Solutions V8.3 26-32
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_user_postautocal Called after any instrument calibration from autocal
tl_user_preautocal Called before any instrument calibration from autocal
tl_user_resetall Call user function at end of reset all
tl_user_shutdown Get user function when site fails
tl_user_startup Call user function at end of test program
tl_using_simulator Flag indicating tester is in simulator mode
tl_uwmm_dump Print ASCII representation of UHFMM state
tl_uwms_present Return modulation option of the source directly behind
the specified UWPORT pin (no add path)
tl_uwms_present_slot Return modulation option of the source behind a
UWPORT pin
tl_uwport_caldib_find_interpolated_ENR Find the interpolated ENR and the source match at
the given schan of the UWPORT
tl_uwport_caldib_find_interpolated_system Find the interpolated system NF at the given
_NF UWPORT slot or schan
tl_uwport_cal_s_params Calibrate s-parameters from autocal
tl_uwport_config Return a bit vector of UWPORT config information
tl_uwport_current_pin Pin power de-embedding is done on
tl_uwport_current_pin_slot Pin power de-embedding is done on
tl_uwport_do_s11 Hook to replace driver s-param code (use DSP)
tl_uwport_do_spar_proc Perform s-parameter processing
tl_uwport_dump UWPORT debugging function
tl_uwport_dump_1port Debug s-parameter cal
tl_uwport_dump_closest_freq Print closest calibrated frequency
tl_uwport_dump_closest_freq_slot Print closest calibrated frequency
tl_uwport_dump_de_embed_file Print UWPORT de_embed_file
tl_uwport_dump_de_embed_file_slot Print UWPORT de_embed_file
tl_uwport_dump_fixture S-parameter debug function
tl_uwport_dump_fixture_slot S-parameter debug function
IMAGE Solutions V8.3 26-33
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_uwport_dump_one_port S-parameter debugging function
tl_uwport_dump_one_port_slot S-parameter debug function
tl_uwport_dump_port S-parameter debugging function
tl_uwport_dump_s_param_timing Debug s-parameter captures
tl_uwport_dump_two_port 2-port s-parameter debug
tl_uwport_dump_two_port_slot 2-port s-parameter debug
tl_uwport_free_data Free memory used by UWPORT s-parameter cal
tl_uwport_get_num_chans_slot Find number of channels for the given UWPORT
tl_uwport_hw_version Returns UWPORT hardware version number
tl_uwport_inst_slot Slot num for connected source/measure
tl_uwport_invalidate_s_param_cal Invalidate s-parameter calibration for one UWPORT
tl_uwport_invalidate_s_param_cal_all Invalidate s-parameter calibration for one UWPORT
tl_uwport_invalidate_s_param_cal_slot Invalidate s-parameter calibration
tl_uwport_lna Report whether the UWPORT lna is on
tl_uwport_noise_source_present Noise source option present?
tl_uwport_noise_source_present_slot Noise source present?
tl_uwport_num_user_chans Return the number of user channels
tl_uwport_pin_to_slot_and_schan Convert UWPORT pin to slot and schan
tl_uwport_read_match_and_measure_gain Power de-embed data
tl_uwport_read_match_and_measure_gain Power de-embed data
_slot
tl_uwport_read_match_and_source_gain Power de-embed data
tl_uwport_read_match_and_source_gain_ Power de-embed data
slot
tl_uwport_read_power_de_embed Read power_de_embed state
tl_uwport_read_power_de_embed_slot Read power_de_embed state
tl_uwport_read_s1p Read one-port s-parameter file (.s1p)
tl_uwport_read_s2p Read one-port s-parameter file (.s2p)
IMAGE Solutions V8.3 26-34
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_uwport_receiver_slot Find slot of UWMM attached to UWPORT
tl_uwport_set_gain_error_limits Power de-embed error check
tl_uwport_set_gain_error_limits_slot Power de-embed error check
tl_uwport_set_interpolation_frequency Power de-embedding interpolation
_range
tl_uwport_simulate_capture Set results of s-param capture
tl_uwport_simulate_capture_slot Set results of s-param capture
tl_uwport_source_freq_range Maximum and minimum UWPORT source
frequencies
tl_uwport_source_freq_range_slot Maximum and minimum UWPORT source frequency
tl_uwport_s_param_sample_size Read back s-parameter capture size
tl_uwport_s_param_snr_test_enable S-param capture quality testing
tl_uwport_sparam_timer S-param hardware timer supported?
tl_uwport_sparam_timer_slot Hardware s-param timing supported?
tl_uwport_thinfo Return UWPORT info structure
tl_uwport_user_cal_std_func Demand calibration func for user
tl_uwport_write_s1p Write one-port s-parameter file (.s1p)
tl_uwport_write_s1p_fmt Write one-port s-parameter file (.s1p)
tl_uwport_write_s2p Write 2-port s-parameter file (.s2p)
tl_uwport_write_s2p_fmt Write 2-port s-parameter file (.s2p)
tl_uwrecv_ap_read_uncal_amp User’s Array Processor based code for UWRECV
tl_uwrecv_characterize_phase_noise_PS Get the complete characterization of the phase noise
D
tl_uwrecv_czt Evaluate and return all DFT samples using CZT
tl_uwrecv_get_PSD_use_AP Return the current state of “use Array Processor” flag
tl_uwrecv_phase_noise_signal_check Enable or disable checks on the input signal to the
phase noise analyzer
tl_uwrecv_read_ampval Return amp param setting
tl_uwrecv_read_ampval_slot Return amp param setting
IMAGE Solutions V8.3 26-35
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_uwrecv_read_level Read back UWRECV ’level’ parameter
tl_uwrecv_read_level_slot Read back UWRECV ’level’ parameter
tl_uwrecv_set_PSD_turbo_avg Enable or disable Turbo Avg in PSD estimators
tl_uwrecv_set_PSD_use_AP Enable or disable use of Array Processor/radix2 FFT
in PSD estimator
tl_uwrecv_spectrum_reversed Return 1 if IF spectrum reversed
tl_uwrecv_spectrum_reversed_slot Return 1 if IF spectrum reversed
tl_uwrecv_suggest_digitizer Read back source amplitude in dBm
tl_uwrecv_suggest_digitizer_slot Find a digitizer for UWRECV
tl_uwsrc_read_amp_dbm_slot Read back source amplitude in dBm
tl_uwsrc_read_connection_slot Returns UWSRC connection state
tl_uwsrc_read_freq_slot Read back source freq parameter
tl_vhfawg_cal_interval Set the VHFAWG calibration interval
tl_vhfawg_fs_sclk_cond Prevent VHFAWG fs and sclk race condition
tl_vhfawg_get_dccal_size Return dccal table size
tl_vhfawg_get_dccal_size_slot Return dccal table size
tl_vhfawg_get_level_table_size Return leveling table size
tl_vhfawg_get_level_table_size_slot Return leveling table size
tl_vhfawg_get_pll_value Read back VHFAWG phase-lock loop value
tl_vhfawg_get_type Return VHFAWG option type given pin number
tl_vhfawg_get_type_slot Return VHFAWG type given slot number
tl_vhfawg_level_table_valid Return whether VHFAWG leveling is valid
tl_vhfawg_level_table_valid_slot Return whether VHFAWG leveling is valid
tl_vhfawg_move_event Move event pulses within a segment after segment is
defined
tl_vhfawg_segment_ltable_valid Return whether a VHFAWG segment
tl_vhfawg_segment_ltable_valid_slot Return whether a VHFAWG
IMAGE Solutions V8.3 26-36
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_vhfawg_set_dccal_size Set maximum number of dccal entries in the look-up
table
tl_vhfawg_set_level_size Set maximum number of pre-level entries
tl_vhfawg_sine_gen_debug Set leveling sine generation debug flag
tl_vhfawg_wave_freq Report actual frequency
tl_vhfawg_wave_fs Report actual sample rate
tl_vhfawg_wave_size Report sample size
tl_vhfcw_cal_interval Set the VHFCW calibration interval
tl_vhfcw_level_table_valid Return whether VHFCW leveling is valid
tl_vhfcw_level_table_valid_slot Return whether VHFCW leveling is valid
tl_vhfcw_set_dccal_size Set the maximum VHFCW dccal setups
tl_vhfcw_set_level_max Set number of maximum allowable VHFCW levelling
setups
tl_vmcu_busy_wait Wait until VMCU is idle
tl_vreg_dutsrc_to_channel Which channel am I?
tl_vreg_dutsrc_to_slot Which slot am I in?
tl_vreg_image_dump Dump information about the state of the Vreg
tl_vreg_slot_to_dutsrc Which DUTSRC am I cabled to?
tl_wait Execute a delay
tl_wait_wait Wait for a retriggerable wait time
tl_wf_cal_temp_diff Set the cal temperature interval
tl_wf_cal_time_interval Set the calibration interval
tl_wfcap_current_bank Return the current memory bank number
tl_wfcap_get_actual_sample_rate Return actual programmed sample rate
tl_wfcap_num_samples_captured Get number of captured samples
tl_wfcap_num_samples_overranged Get number of overranged samples
tl_wf_disable_80MHz_clock Disable clocks on all WF instruments
tl_wf_enable_80MHz_clock Enable clocks on all WF instruments
IMAGE Solutions V8.3 26-37
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Functions
Table of Contents Index Home Master Index Search Help
Table 26-1. Base IMAGE Test Program Functions (Continued)
Function Action
tl_wfsrc_get_crest_factor Get crest factor of segment
tl_wfsrc_get_frequency Get frequency of segment
tl_wfsrc_get_last_sample_rate Get sample rate of last started segment
tl_wfsrc_get_sample_rate Get sample rate of segment
tl_wfsrc_get_segment_data Get segment data
tl_wfsrc_get_segment_memory_size Get total memory size
tl_wfsrc_get_segment_size Get segment size
tl_wfsrc_show_segment_info Retrieve and print segment information
tl_write_datnum Change the test datalog number
tl_write_format Change the test result datalog format
tl_write_highlim Change the upper test limits for a test
tl_write_label Change the test’s label string
tl_write_lowlim Change the lower test limit for a test
tl_write_user_eeprom_all_data Write all data to HUC IDPROM
tl_write_user_eeprom_id_data Write coded data to HUC IDPROM
tl_xachan Read/write a register in the A500 test head (analog)
tl_xath Read or write a register in the A500 test head (analog)
tl_xcc Read or write a register in an A500 conversion cage
tl_xpacs Read or write a register in a Precision AC cage
tl_xvb Read or write a register in an A500 vector bus cage
wait_until_cdig_halt Check for stopped SBCC hardware
wait_until_cdig_halt_slot Check for stopped SBCC hardware
wait_until_h50_halt check if SCM is still running.
wait_until_h50_halt_scm check if SCM is still running.
IMAGE Solutions V8.3 26-38
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Base IMAGE Function Reference
ftoi
Convert double to int with rounding.
SYNOPSIS int ftoi(doubleval)
double doubleval;
DESCRIPTION A C cast such as doublex=(int)intx truncates the value to the
next smallest whole number. Frequently this is an inappropriate
conversion. ftoi() rounds to the nearest whole number
instead.
ARGUMENTS doubleval—The number to convert.
RETURN VALUE The converted value.
handlerprober_bin
Send bin command to handler (obsolete)
SYNOPSIS handlerprober_bin()
DESCRIPTION This function sends a binning command to the handler currently
connected and enabled. It is designed to be used in combination
with the routine "handlerprober_start()".
This routine was designed for programs using versions of
IMAGE before Version 2. It is supported mainly for backwards
compatibility; most programs written for later versions of IMAGE
take advantage of version 2's more powerful handler software, in
which the Image executive sends the bin command to handler
automatically after each run.
ARGUMENTS None
RETURN VALUE -1 for error, 1 for success
SIDE EFFECTS None
handlerprober_init
Initialize handler software interface.
SYNOPSIS handlerprober_init(name)
char *name;
DESCRIPTION Initializes the handler or prober software interface for the current
test head. This function only needs to be called once; it is
unnecessary to call it for each run of a test program. You must
IMAGE Solutions V8.3 26-39
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
call this function if your test program uses any of the tl_hp_...
handler library functions.
You can use this function in one of two modes. In the first (and
most useful) mode, the function initializes the interface based on
the handler type previously selected using the handlerconf
command. This mode is most often used when the test program
must perform some form of handler control in addition to the
basic operations supported by IMAGE, although it can also be
used when the test program is doing all of the handler control
(“independent” mode).
In the second mode, this function initializes the interface based
on the name of the peripheral passed as a parameter. This mode
was designed primarily for programs written before IMAGE V2.0,
which required that all handler control be done from the test
program.
ARGUMENTS name—String with name of handler to select, or 0 to use handler
selected by handlerconf -connect
RETURN VALUE 1—interface initialized successfully (starts enabled)
0—interface initialized successfully (starts disabled)
-1—initialization failed
SIDE EFFECTS May print error messages to the station window
handlerprober_reset
Reset handler software interface.
SYNOPSIS handlerprober_reset()
DESCRIPTION This function resets the handler software interface within a test
program, effectively disabling all handler library calls. To re-
enable the handler interface software, make another call to
handlerprober_init().
ARGUMENTS None
RETURN VALUE -1 for failure, 1 for success
handlerprober_start
Wait for handler start (obsolete)
SYNOPSIS handlerprober_start()
DESCRIPTION This function polls the currently enabled handler or prober,
waiting for a start signal. It will block until a start is received or
until an error of some sort takes place.
IMAGE Solutions V8.3 26-40
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
This routine was designed for programs using versions of
IMAGE before version 2. It is supported mainly for backwards
compatibility; most programs written for later versions of Image
take advantage of version 2's more powerful handler software, in
which the Image executive polls the handler for start signals.
ARGUMENTS None
RETURN VALUE -1 for error, 1 for success
SIDE EFFECTS Blocks (waits) until handler start or error
Hprintf
Print a heading string to the datalog.
SYNOPSIS void Hprintf(char * header_fmt, ...);
DESCRIPTION This function prints into the datalog the first 255 characters of the
string resulting from the formatting of the header_fmt argument,
and any variable arguments. It does this once for every datalog
stream that is enabled. The calling convention for this function is
identical to the printf() family of functions. Embedded newline
characters are accepted as part of the string.
ARGUMENTS Calling conventions is the same as the printf function family.
header_fmt—The format string for the string to be placed into
the datalog.
...—Variable arguments for any format specifiers in the format
string.
RETURN VALUE None
SIDE EFFECTS Multiple calls to this function are ignored.
Lprintf
Print a formatted string to the datalog report.
SYNOPSIS Lprintf(fmt, arg, arg, ...)
char *fmt;
...
DESCRIPTION This function allows a formatted string to be written to the
datalogger, which will place it into datalog reports, if datalogging
is enabled. The calling convention for this function is identical to
printf().
This function is identical to lprintf(), with the exception that it
allows the a string to be printed to the datalog report regardless
of the "mode" in which data is being collected (i.e. all tests, list of
tests, etc.). Its primary purpose is to allow a datalog message to
IMAGE Solutions V8.3 26-41
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
be recorded within a checker when data is being collected only
for failed tests.
ARGUMENTS Calling convention is identical to printf()
RETURN VALUE Same as printf()
lprintf
Print a formatted string to the datalog report.
SYNOPSIS lprintf(fmt, arg, arg, ...)
char *fmt;
...
DESCRIPTION This function allows a formatted string to be written to the
datalogger, which will place it into datalog reports, if datalogging
is enabled. The calling convention for this function is identical to
printf().
ARGUMENTS Calling convention is identical to printf()
RETURN VALUE Same as printf()
Mprintf
Print a formatted string to the datalog report regardless of datalog mode or binning status.
SYNOPSIS Mprintf(fmt, arg, arg, ...)
char *fmt; ...
DESCRIPTION This function allows a formatted string to be written to the
datalogger, which will place it into datalog reports if datalogging
is enabled. The calling convention for this function is identical to
printf().
This function is similar to Lprintf(), but it writes the string to the
datalog regardless of whether or not the device has been binned.
Its primary purpose is to print information to the datalog that is
not related to any specific test or the pass/fail status of any
device. Normal Lprintf() operation does not output to the
datalog after binning a device.
For more information about this function, see “Writing Text to a
Datalog Report” on page 14-24.
ARGUMENTS Calling convention is identical to printf()
RETURN VALUE Same as printf()
next_device_is_retest
Force the next device to be a retest
IMAGE Solutions V8.3 26-42
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS void next_device_is_retest();
DESCRIPTION This function tells IMAGE to treat the next device tested as a
retest. Testing on the current device is not affected in any way.
ARGUMENTS None
RETURN VALUE None
rdelay
Function to wait for relay delay.
SYNOPSIS int rdelay()
DESCRIPTION Waits for both the DC Subsystem hardware busy bit and the
Terabus settling timer.
ARGUMENTS None
RETURN VALUE Always 0
SIDE EFFECTS tl_tba_settle_wait is always called, so all alarms are cleared
and a new latched alarm window begins.
rdelay_time
Wait for relay delay then return time waited.
SYNOPSIS double rdelay_time()
DESCRIPTION Waits for both the DC Subsystem hardware busy bit and the
Terabus settling timer.
ARGUMENTS None
RETURN VALUE Returns the number of seconds which elapsed during rdelay().
This is intended as an aid in optimizing test programs. Returns
the time waited in seconds as a double.
SIDE EFFECTS tl_tba_settle_wait is always called so all alarms are cleared
and a new latched alarm window begins.
read_ac_clock
Read back An clock frequency setting.
SYNOPSIS double read_ac_clock(clock)
int clock;
DESCRIPTION Function to read back the frequency of one of the analog clocks.
Note that for mixed-signal instrumentation, the A0 clock has a
special feature. Using the set clock: a0_mode:c0 statement,
A0 can be put into a mode where the C0 clock is actually
IMAGE Solutions V8.3 26-43
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
delivered down the A0 wire to the instruments. In this case the
frequency cannot be read back on a static basis, since it
depends on timing set number.
For the Precision AC Subsystem (PACS), this function returns
the frequency for the analog clock in cage #1.
ARGUMENTS clock—integer 0, 1, 2, or 3 to indicate which An clock to read
back the frequency of.
RETURN VALUE Returns the frequency in Hz of the clock requested or -1.0. -1.0
is returned if an attempt is made to read the A0 frequency while
set clock:a0_mode:c0 is in effect. Test for a return value <0.0
rather than testing explicitly for -1.0 since this is a floating point
quantity.
SEE ALSO “read_pacs_clock”
read_ac_freq_pin
Return the frequency of the ac clock attached to the instrument described by the pin
number.
SYNOPSIS double read_ac_freq_pin(pin)
int pin;
DESCRIPTION This function reads the ac clock frequency of an instrument.
Given a pin number, the clock frequency of the appropriate
instrument is returned.
ARGUMENTS pin—Pin number
RETURN VALUE Frequency of the ac clock connected to the instrument
referenced by pin.
read_ac_vrng
Read back the voltage range of an ac instrument.
SYNOPSIS double read_ac_vrng(pin)
int pin;
DESCRIPTION This function reads back the voltage range (or max amplitude
setting) for one of the ac instruments. Called with a device pin
number, it returns the vrange of the instrument behind that pin.
It is an error to have more that one ac instrument behind a pin.
Consider using read_lfdig_vrng or read_hfdig_vrng to
make it unambiguous.
ARGUMENTS pin—Instrument pin number.
RETURN VALUE Voltage range of the instrument behind that pin.
IMAGE Solutions V8.3 26-44
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “read_ac_vrng_chan” for using channel numbers instead of
device pins.
read_ac_vrng_chan
Read back the voltage range of an ac instrument.
SYNOPSIS double read_ac_vrng_chan(chan)
char *chan;
DESCRIPTION This function reads back the voltage range (or maximum
amplitude setting) for an ac instrument. Called with a tester
channel number string, it returns the vrange of the instrument
behind that channel.
ARGUMENTS chan—Instrument channel number.
RETURN VALUE Voltage range of the instrument behind that channel.
SEE ALSO “read_ac_vrng_chan” for using pin numbers instead of device
channels.
read_ac_vrng_slot
Read back the voltage range of an ac instrument.
SYNOPSIS double read_ac_vrng_slot(slot)
int slot;
DESCRIPTION This function reads back the voltage range (or maximum
amplitude setting) for an HFDIG instrument. Called with a tester
slot number, it returns the vrange of the instrument behind that
slot.
ARGUMENTS slot—The slot number of the instrument.
RETURN VALUE Voltage range of the instrument behind that slot.
SEE ALSO “read_ac_vrng” for using pin numbers instead of slot.
read_apu
Read results of simulated APU local meter measurement.
SYNOPSIS double read_apu(apu_number_array, result_array)
short *apu_number_array;
double *result_array;
DESCRIPTION Reads the results of an APU local meter measurement which
was simulated via the measure driver and measure bus. If
apu_number_array consists of a single APU number the
reading is returned by the function and the parameter
result_array is ignored. Otherwise, the readings are returned
IMAGE Solutions V8.3 26-45
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
as elements in the array and the function return value is
meaningless. This function is required for compatibility with the
original APU driver.
ARGUMENTS short *apu_number_array—Pointer to list of APU numbers
double *result_array—Pointer to list of APU results
RETURN VALUE See description.
SEE ALSO “read_apu” (original APU driver version), “read_apu_pin”,
“tl_apu_read_pin”
read_apu_pin
read results APU local meter measurement
SYNOPSIS double read_apu_pin(pin_number_array, result_array)
short *pin_number_array;
double *result_array;
DESCRIPTION Note: This function does not work properly on multisite programs
and exists only for legacy purposes. It is replaced by
read_apu_pin_multisite.
Reads the results of an APU local meter measurement for a
single pin or list of pins and returns the result(s) in result_array.
The first parameter can either be a single pin number or a pointer
to a 0-terminated list of pin numbers. The second parameter is a
two-dimensional array of doubles of the form
result_array[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
If the first parameter is a single pin then the measurement result
will also be returned as the function return value. If there is not
exactly one active test site then 0 will be returned. If the first
parameter specifies a list of pins then the function return value is
undefined.
If the test program uses parallel test result_array must be large
enough to store values from all test sites. The function does not
fill in results for sites that are not active.
double results[TL_SYS_MAX_SITES][NUMBER_OF_PINS];
int i;
serial {
read_apu_pin(APU_PINS, results);
for (i = 0; i < NUMBER_OF_PINS; i++)
test results[tl_site][i];
}
IMAGE Solutions V8.3 26-46
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For the UB APU this function reads the results of an APU local
meter measurement which was simulated via the measure driver
and measure bus.
ARGUMENTS short *pin_number_array—pointer to list of APU pin numbers
double *result_array —pointer to list of apu results
RETURN VALUE See description.
SIDE EFFECTS Produces a run-time error for error conditions.
SEE ALSO tl_apu_read_pin
read_apu
read_apu_pin_multisite
read_apu_pin_multisite
Read results APU local meter measurement.
SYNOPSIS double read_apu_pin_multisite(pin_number_array,
result_array)
short *pin_number_array;
double *result_array;
DESCRIPTION Reads the results of an APU local meter measurement for a
single pin or list of pins and returns the result(s) in result_array.
The first parameter can either be a single pin number or a pointer
to a 0-terminated list of pin numbers. The second parameter is a
two-dimensional array of doubles of the form
result_array[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter.
If the first parameter is a single pin then the measurement result
will also be returned as the function return value. If there is not
exactly one active test site then 0 will be returned. If the first
parameter specifies a list of pins then the function return value is
undefined.
If the test program uses parallel test result_array must be large
enough to store values from all test sites. The function does not
fill in results for sites that are not active.
double results[TL_SYS_MAX_SITES][NUMBER_OF_PINS];
int i;
read_apu_pin_multisite(APU_PINS, results);
serial {
for (i = 0; i < NUMBER_OF_PINS; i++)
test results[tl_site][i];
}
IMAGE Solutions V8.3 26-47
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For the UB APU this function reads the results of an APU local
meter measurement which was simulated via the measure driver
and measure bus.
ARGUMENTS short *pin_number_array—Pointer to list of APU pin numbers
double *result_array—Pointer to list of apu results
RETURN VALUE See description.
SIDE EFFECTS Produces a run-time error for error conditions.
SEE ALSO “tl_apu_read_pin”, “read_apu”, “read_apu_pin_multisite”
read_apu_pin_status
Read status of APU pin number.
SYNOPSIS read_apu_pin_status(pin_number)
short pin_number;
DESCRIPTION Reads the status of an APU pin. It checks if an APU channel
behind the specified pin number is actually installed and
determines whether an APU alarm has been latched.
Do not use this function inside a serial loop:
short pin_number;
int status;
serial {
status = read_apu_pin_status(pin_number);
}
If the function is not used inside a serial loop and there is more
than one active test site the return value will be 0.
ARGUMENTS pin_number—APU pin number from pinmap
RETURN VALUE 0—APU pin number is invalid or specified APU pin not found in
pinmap or APU hardware behind the pin is not present or called
outside serial loop and more than one active test site
2—Corresponding APU hardware is present and no alarm is
latched
3—APU hardware is present and guard or overload alarm is
latched
SIDE EFFECTS Produces a run-time error for error conditions.
SEE ALSO “tl_apu_read_pin_status”, “read_apu_status”
read_apu_status
Read status of APU number.
IMAGE Solutions V8.3 26-48
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS read_apu_status(apu_number)
short apu_number;
DESCRIPTION Reads the status of an APU channel. It checks if the specified
APU instrument number is actually installed and determines
whether an APU alarm has been latched. This function is
provided for compatibility with the original APU software.
ARGUMENTS short apu_number—APU instrument number (1..192)
RETURN VALUE 0—APU number is invalid or specified hardware is not present
2—APU hardware is present and no alarm is latched
3—APU hardware is present and guard or overload alarm is
latched
SEE ALSO “tl_apu_read_pin_status”
read_bin_is_open
Is a bin open or closed?
SYNOPSIS int read_bin_is_open(bin)
int bin;
DESCRIPTION The function determines whether or not a specified bin is open
or closed. In a multisite test program this must be called from
inside a serial block.
ARGUMENTS bin—A bin number between 1 and 32.
RETURN VALUE TRUE if the bin is open, FALSE otherwise.
read_bin_is_pass
Is a bin is a pass bin or a fail bin?
SYNOPSIS int read_bin_is_pass(bin)
int bin;
DESCRIPTION The function determines whether a specified bin is a pass bin or
fail bin as defined in the device_bins declaration. By default bin
1 is a pass bin and all other bins are fail bins. See “The
device_bins Declaration” on page 15-13.
ARGUMENTS bin—A bin number between 0 and MAXBIN (256).
RETURN VALUE TRUE if the bin is a pass bin
FALSE if the bin is a fail bin
read_cdig_all_fail_vectors
Get information for all Serial Bus Channel Card failing vectors.
IMAGE Solutions V8.3 26-49
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int read_cdig_all_fail_vectors(slot, patname,
fail_chans, fail_vectors)
int slot;
char * patname;
unsigned char fail_chans[n];
unsigned short fail_vectors[n];
DESCRIPTION Reads the hardware receive memory to find all failing vectors in
the receive memory for pattern patname. The search will
terminate when the end of the pattern is reached. This function
also clears the pattern fail register, so that read_cdig_failed()
will return FALSE after this function is called.
Note: arrays fail_chans and fail_vectors must be declared
as the appropriate type arrays of at least size 65536. Otherwise,
the function may violate segmentation without warning if the
number of failures exceeds the size of the array. This is because
the program cannot determine the size of arrays passed as
function arguments at runtime.
ARGUMENTS slot—Slot number of SBCC
patname—Name of the pattern
fail_chans—Array of unsigned char of at least size 65537 in
which
failed channel information is returned.
fail_vectors—Array of unsigned short of at least size 65537
in which
failed vector information is returned
RETURN VALUE TRUE if any failures were found
FALSE if no failures were found
fail_chans[i] = 1 if channel 1 failed
= 2 if channel 2 failed
= 3 if both channel 1 and 2 failed
= 0 if there are no more failing pins.
fail_vectors[i]
If pattern name is not NULL, will have the vector number
in pattern patname where the failure in fail_chans[i]
was found. If pattern name is NULL, will have the
hardware address where the failed vector was found.
SIDE EFFECTS Clears AFR bit, even though it was not used.
read_cdig_all_fail_vectors_pin
Get information for all Serial Bus Channel Card failing vectors.
SYNOPSIS int read_cdig_all_fail_vectors_pin(pin, patname,
fail_chans, fail_vectors)
int pin;
IMAGE Solutions V8.3 26-50
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
char * patname;
unsigned char fail_chans[n];
unsigned short fail_vectors[n];
DESCRIPTION Reads the hardware receive memory to find all failing vectors in
the receive memory for pattern patname. The search will
terminate when the end of the pattern is reached.
This function also clears the pattern fail register, so that
read_cdig_failed() will return FALSE after this function is
called.
Note: arrays fail_chans and fail_vectors must be declared
as the appropriate type arrays of at least size 65536. Otherwise,
the function may violate segmentation without warning if the
number of failures exceeds the size of the array. This is because
the program cannot determine the size of arrays passed as
function arguments at runtime.
ARGUMENTS pin—A pin number in front of the cdig slot
patname—Name of the pattern
fail_chans—Array of unsigned char of at least size 65537 in
which failed channel information is returned.
fail_vectors—Array of unsigned short of at least size 65537
in which failed vector information is returned
RETURN VALUE TRUE if any failures were found
FALSE if no failures were found
fail_chans[i] = 1 if channel 1 failed
= 2 if channel 2 failed
= 3 if both channel 1 and 2 failed
= 0 if there are no more failing pins.
fail_vectors[i]
If pattern name is not NULL, will have the vector number
in pattern patname where the failure in fail_chans[i]
was found. If pattern name is NULL, will have the
hardware address where the failed vector was found.
SIDE EFFECTS Clears AFR bit, even though it was not used.
read_cdig_failed
Check for Serial Bus channel card pattern failures.
SYNOPSIS read_cdig_failed(pin)
int pin;
DESCRIPTION Returns TRUE if a pattern on the board(s) indicated by pin has
failed since the last time pattern failures were read. Returns
FALSE otherwise.
IMAGE Solutions V8.3 26-51
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Clears the hardware fail bit (AFR). Call the
wait_until_cdig_halt function before calling
read_cdig_failed. This function does not check if the
hardware has stopped.
Note: Failures are cleared whenever the hardware is reset.
ARGUMENTS pin—Pin number of channel on Serial Bus Channel Card to be
checked
RETURN VALUE TRUE—Pattern failure occurred
FALSE—No pattern failure
SIDE EFFECTS Clears hardware AFR bit.
SEE ALSO “wait_until_cdig_halt”, “wait_until_cdig_halt_slot”
read_cdig_failed_segment
Check if Serial Bus channel card pattern failed in segment.
SYNOPSIS read_cdig_failed_segment(slot, patternname,
segmentname, segment_instance);
int slot;
char * patternname, segmentname;
int segment_instance;
DESCRIPTION Checks for a pattern failure in instance segment_instance of
segment segmentname in pattern patternname on the SBCC in
slot slot. The pattern must have stopped, so call one of the
wait_until_cdig_halt functions before calling this function. A
runtime error is issued if this function is called while the segment
is still running.
Clears the pattern fail, so read_cdig_failed() returns FALSE
after this function is called.
ARGUMENTS slot—Slot number of segment to be checked
patternname—Name of the pattern of interest
segmentname—Name of the segment of interest in patternname
segment_instance—Instance of the segment, usually 1 for first
instance of the segment, unless there are multiple
instances of the segment in the pattern.
RETURN VALUE n—Where n is the number of the first failing vector, if a failure
was found. That is, 1 = 1st vector failed and so on.
0—No failure found
-1—An error occurred
SIDE EFFECTS Clears AFR bit, even though it was not used in the determination.
IMAGE Solutions V8.3 26-52
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_cdig_failed_slot
Check for Serial Bus channel card pattern failures.
SYNOPSIS read_cdig_failed_slot(pin)
int slot;
DESCRIPTION Returns TRUE a pattern on the board indicated by slot has failed
since the last time pattern failures were read. Returns FALSE
otherwise.
Clears the hardware fail bit (AFR). Call the
wait_until_cdig_halt function before calling
read_cdig_failed_slot. This function does not check if the
hardware has stopped.
Note: Failures are cleared whenever the hardware is reset.
ARGUMENTS slot—Slot number of channel on Serial Bus Channel Card to be
checked
RETURN VALUE TRUE—Pattern failure occurred
FALSE—No pattern failure
SIDE EFFECTS Clears hardware AFR bit.
SEE ALSO “read_cdig_failed”, “wait_until_cdig_halt”,
“wait_until_cdig_halt_slot”
read_cdig_n_fail_vectors
Get information for first n Serial Bus channel card failing vectors.
SYNOPSIS int read_cdig_n_fail_vectors(slot, patname, n,
fail_chans, fail_vectors)
int slot;
char * patname;
int n;
unsigned char fail_chans[n];
unsigned short fail_vectors[n];
DESCRIPTION Reads the hardware receive memory to find n failing vectors in
the receive memory for pattern patname. The search terminates
when n failing vectors are found or the end of the pattern is
reached.
This function also clears the pattern fail register, so that
read_cdig_failed() returns FALSE after this function is called.
Warning: arrays fail_chans and fail_vectors must be
declared as the appropriate type arrays of at least size n + 1.
Otherwise, the function may violate segmentation without
warning if the number of failures exceeds the size of the array.
IMAGE Solutions V8.3 26-53
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
This is because the program cannot determine the size of arrays
passed as function arguments at runtime.
ARGUMENTS slot—SBCC slot number
patname—Pattern name
n—Number of failures to find
fail_chans—Array of unsigned char of at least size n+1 in
which failed channel information will be returned
fail_vectors—array of unsigned short of at least size n+1 in
which failed vector information will be returned
RETURN VALUE TRUE—Failures found
FALSE—No failures found
-1—An error occurred
fail_chans[i] = 1 if channel 1 failed
= 2 if channel 2 failed
= 3 if channel 1 and channel 2 failed
= 0 if there are no more failing pins
fail_vectors[i] will have the vector number in pattern
patname where the failure in fail_chans[i] was found.
SIDE EFFECTS Clears AFR bit, even though it was not used.
read_cdig_n_fail_vectors_pin
Get information for first n Serial Bus channel card failing vectors.
SYNOPSIS int read_cdig_n_fail_vectors_pin(pin, patname, n,
fail_chans, fail_vectors)
int pin
char * patname;
int n;
unsigned char fail_chans[n];
unsigned short fail_vectors[n];
DESCRIPTION Reads the hardware receive memory to find n failing vectors in
the receive memory for pattern patname. The search terminates
when n failing vectors are found or the end of the pattern is
reached.
This function also clears the pattern fail register, so that
read_cdig_failed() returns FALSE after this function is called.
Note: arrays fail_chans and fail_vectors must be declared
as the appropriate type arrays of at least size n + 1. Otherwise,
the function may violate segmentation without warning if the
number of failures exceeds the size of the array. This is because
the program cannot determine the size of arrays passed as
function arguments at runtime.
IMAGE Solutions V8.3 26-54
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS pin—Cdig pin number
patname—Pattern name
n—Number of failures to find
fail_chans—Array of unsigned char of at least size n+1 in
which failed channel information will be returned
fail_vectors—Array of unsigned short of at least size n+1 in
which failed vector information will be returned
RETURN VALUE TRUE—Failures found
FALSE—No failures found
-1—An error occurred
fail_chans[i] = 1 if channel 1 failed
= 2 if channel 2 failed
= 3 if channel 1 and channel 2 failed
= 0 if there are no more failing pins
fail_vectors[i] will have the vector number in pattern
patname where the failure in fail_chans[i] was found.
SIDE EFFECTS Clears AFR bit, even though it was not used.
read_cdig_timing_range
Read currently set timing range for Serial Bus channel card.
SYNOPSIS int read_cdig_timing_range(slot)
int slot;
DESCRIPTION Reads the hardware and returns current setting of timing range.
ARGUMENTS slot—Slot number of the card to check
RETURN VALUE 1, 2, 4, 8, 16—the timing range
-1—Error occurred
read_cdig_timing_range_pin
Read currently set timing range for Serial Bus channel card.
SYNOPSIS int read_cdig_timing_range(pin)
int pin;
DESCRIPTION Reads the hardware and returns current setting of timing range.
ARGUMENTS pin—Pin number in front of the card to check
RETURN VALUE 1, 2, 4, 8, 16—The timing range
-1—Error occurred
read_configuration_status
Read status of last configuration check.
IMAGE Solutions V8.3 26-55
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int read_configuration_status()
DESCRIPTION The return value from this function indicates whether or not the
last configuration check passed or failed. It is useful for
preventing the execution of a test program on a test system not
containing all the instrumentation required to run the test
program.
ARGUMENTS None
RETURN VALUE TRUE (1) if the configuration check passed
FALSE (0) if the configuration check failed
read_current_site
Get current site number.
SYNOPSIS int read_current_site();
DESCRIPTION This function is only useful in a multisite test program and only
inside a serial block. The function returns the current site
number. This is normally the same as the value of tl_site.
However, after a site is disabled, for example by failing, tl_site
takes on a negative value, but read_current_site() returns
the site number.
ARGUMENTS None
RETURN VALUE The number of the current site. In a single site test program the
return value will always be 0. In a multisite test program, inside
a serial block, the site number is returned. Outside a serial block,
a negative value is returned.
SEE ALSO “tl_site”
read_databits
User level read databits function.
SYNOPSIS int read_databits(param)
int param;
DESCRIPTION This is the user level read databits function. In a multisite test
program, you must use read_databits inside a serial block if
you are trying to read the value of a bit name which maps to
different bits for each site. If you try to do this outside of a serial
block, it results in a run-time error.
ARGUMENTS You can pass either a single bit name from the pinmap or a bit
number between 1 and 48 as the parameter to read a single bit.
The value of the single bit (0 or 1) is returned.
IMAGE Solutions V8.3 26-56
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
You can alternatively pass a field name or a pointer to a list of bits
as the parameter. In this case, the function returns an integer
with the lower order bits matching the values of the bits on the bit
list. For example if bit 3 was 1, bit 2 was 0, and bit 1 was 0, then
passing a bit list (3,2,1) would return 5.
RETURN VALUE Since the function returns an integer it cannot return the values
of more than 32 bits.
SIDE EFFECTS If a bit list is greater than 32 bits or any bits are out of range, a
run-time error results
read_databits_true
User level read databits (true readback) function.
SYNOPSIS int read_databits_true(param)
int param;
DESCRIPTION This function is the same as read_databits except that it
employs true readback which reads the value of the bit at the
device pin rather than the value latched in the programmable
register.
In a multisite test program, you must use read_databits inside
a serial block if you are trying to read the value of a bit name
which maps to different bits for each site. Doing this outside a
serial block gives you a runtime error.
ARGUMENTS You can pass either a single bit name from the pinmap, or a bit
number between 1 and 48 as the parameter to read a single bit.
The value of the single bit (0 or 1) is returned.
You can alternatively pass a field name or a pointer to a list of bits
as the parameter. In this case, the function returns an integer
with the lower order bits matching the values of the bits on the bit
list. For example if bit 3 was 1, bit 2 was 0 and bit 1 was 0, then
passing a bit list (3,2,1) would return 5.
RETURN VALUE Since the function returns an integer it cannot return the values
of more than 32 bits.
SIDE EFFECTS If a bit list is greater than 32 bits or any bits are out of range, a
run-time error results.
read_dps_amm_pin_status
Read status of DPS ammeter
SYNOPSIS int read_dps_amm_pin_status(pin, statusp)
unsigned short *pin;
int *statusp;
IMAGE Solutions V8.3 26-57
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns the alarm and error status of the specified
DPS ammeter. The alarms and errors of interest are those that
were present at the time the local ammeter was strobed. The first
parameter can either be a single pin number or a pointer to a 0-
terminated list of pin numbers. The second parameter is a two-
dimensional array of integers of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter.
ARGUMENTS pin—A single DPS pin number or a 0-terminated list of pins
statusp—Pointer to array where the status of each DPS will be
stored
RETURN VALUE A general status is returned.
1 = errors or alarms were found.
0 = no alarms or errors found on any channels.
For each pin specified, function inserts an encoded status of
alarms and errors in the integer pointed to by statusp. The value
entered is encoded as follows:
Alarms and errors at time of current ADC strobe:
QVS_AMM_INVALID_DATA—Valid data from a recent QVS
conversion has not yet been read.
QVS_AMM_OVERWRITE_DATA—Previously unread, valid data has
been overwritten by another QVS conversion.
QVS_AMM_MISSED_TRIGGER—A QVS conversion strobe was
received while another conversion was in progress.
QVS_AMM_OPEN_KELVIN—QVS open kelvin alarm at time of
strobe.
QVS_AMM_SENSE_CURR—QVS sense current alarm at time of
strobe
QVS_AMM_CLAMP—QVS clamp alarm at time of strobe
QVS_AMM_OVERRANGE—QVS voltmeter overrange alarm
QVS_AMM_OPEN_LOOP—QVS open loop alarm at time of strobe
SIDE EFFECTS Sets tl_qvs_selected.
read_dps_dib_ctrl_data
Reads DIB control data
SYNOPSIS void read_dps_dib_ctrl_data(pin, resultp)
unsigned short *pin;
int *resultp;
DESCRIPTION Reads the current dib control data for the given pin/pin field.
ARGUMENTS unsigned short *pin—a single DPS pin number or a pin field
IMAGE Solutions V8.3 26-58
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int *resultp—pointer to location where result is to be stored.
This should an array of the form
resultp[NUMBER_OF_SITES][NUMBER_OF_PINS]
RETURN VALUE None
SIDE EFFECTS None
SEE ALSO
read_dps_low_i_n
Read low current from QVS Local Meter and average
SYNOPSIS int read_dps_low_i_n(pin_names, n, max_expected_i,
wmd, &data)
DESCRIPTION This function basically measures a lower current value than what
the DPS normally encounters. It takes the specified number of
current readings per pin and returns averaged values as results.
This function first prepares to take a low current measurement
from the pin(s) passed into it. After error checking for incorrect
values (see below), it makes a copy of the values of ammeter
range, current limiter (ilim), the DIB control parameter (dib_ctrl),
the DCC capacitance parameter (dcc_cap), and the comp value.
Once these values are copied, the function turns off the dib_ctrl
and the DCC capacitance, bypasses the sense boost, and then
sets the amm_rng and the gain to the user specified values.
The function then takes the current measurements, and stores
them into a two-dimensional array of doubles of the form
data[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter. It then resets the QVS back to the way that it was,
retrieving the older values.
ARGUMENTS pin_names—A single DPS pin number or a 0-terminated list of
pins
int n—# of readings to average
max_expected_i—User input expected current, in the range
0-.000200A inclusive. If that value is not .000020 or
.000200(A), the program will round up to whichever of
those values is nearer.
wmd—Wait measure delay - user defined time for device to
stabilize so that accurate measurement can be made (in
seconds) this value must between 0 < 3.000 (s)
data—Returned current measurements may be one
measurement or array of many measurements - this will
depend on how many pins are being measured
IMAGE Solutions V8.3 26-59
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
SIDE EFFECTS Changes tl_qvs_selected.
read_dps_low_i_time
Read low current from QVS Local Meter and average over time.
SYNOPSIS int read_dps_low_i_time(pin_names, t,
max_expected_i, wmd, &data)
DESCRIPTION This function basically measures a lower current value than what
the DPS normally encounters. It takes as many current readings
as possible during the specified time period and then returns
averaged values as results.
This function first prepares to take a low current measurement
from the pin(s) passed into it. After error checking for incorrect
values (see below), it makes a copy of the values of ammeter
range, current limiter (ilim), the DIB control parameter
(dib_ctrl), the DCC capacitance parameter (dcc_cap), and the
comp value.
Once these values are copied, the function turns off the
dib_ctrl and the DCC capacitance, bypasses the sense boost,
and then sets the amm_rng and the gain to the user specified
values.
The function then takes the current measurements, and stores
them into a two-dimensional array of doubles of the form
data[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter. It then resets the QVS back to the way that it was,
retrieving the older values.
ARGUMENTS pin_names—A single DPS pin number or a 0-terminated list of
pins
double t—Time period (in seconds) over which measurements
are to be averaged
max_expected_i—User input expected current, in the range
0-.000200A inclusive. If that value is not .000020 or
.000200(A), the program will round up to whichever of
those values is nearer.
wmd—Wait measure delay - user defined time for device to
stabilize so that accurate measurement can be made (in
seconds) this value must between 0 < 3.000 (s)
data—Returned current measurements may be one
measurement or array of many measurements - this will
depend on how many pins are being measured
IMAGE Solutions V8.3 26-60
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Returns number of measurements taken in the specified time
period. (Returns 0 if error.)
SIDE EFFECTS Changes tl_qvs_selected.
read_dps_meter_pin_status
Read status of DPS ammeter.
SYNOPSIS int read_dps_meter_pin_status(pin, statusp)
unsigned short *pin;
int *statusp;
DESCRIPTION This function returns the alarm and error status of the specified
DPS ammeter. The alarms and errors of interest are those that
were present at the time the local ammeter were strobed. The
first parameter can either be a single pin number or a pointer to
a 0-terminated list of pin numbers. The second parameter is a
two-dimensional array of integers of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter.
ARGUMENTS pin—a single DPS pin number or a 0-terminated list of pins
statusp—pointer to array where the status of each DPS will be
stored
RETURN VALUE A general status is returned. 1 = errors or alarms were found.
0 = no alarms or errors found on any channels.
For each pin specified, function inserts an encoded status of
alarms and errors in the integer pointed to by statusp. The value
entered is encoded as follows:
Alarms and errors at time of current ADC strobe:
QVS_AMM_INVALID_DATA—Valid data from a recent QVS
conversion has not yet been read.
QVS_AMM_OVERWRITE_DATA—Previously unread, valid data has
been overwritten by another QVS conversion.
QVS_AMM_MISSED_TRIGGER—A QVS conversion strobe was
received while another conversion was in progress.
QVS_AMM_OPEN_KELVIN—QVS open kelvin alarm at time of
strobe.
QVS_AMM_SENSE_CURR—QVS sense current alarm at time of
strobe
QVS_AMM_CLAMP—QVS clamp alarm at time of strobe
QVS_AMM_OVERRANGE—QVS voltmeter overrange alarm
QVS_AMM_OPEN_LOOP—QVS open loop alarm at time of strobe
SIDE EFFECTS Sets tl_qvs_selected.
IMAGE Solutions V8.3 26-61
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_dps_pin
Read current from DPS Local Meter.
SYNOPSIS void read_dps_pin(pin, resultp)
unsigned short *pin;
double *resultp;
DESCRIPTION Strobe the DPS Local ammeter, wait for the A/D conversion, and
put the measured value in the specified location. The first
parameter can either be a single pin number or a pointer to a 0-
terminated list of pin numbers. The second parameter is a two-
dimensional array of doubles of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter.
ARGUMENTS unsigned short *pin—A single DPS pin number or a 0-
terminated list of pins (must be at least one pin!)
double *resultp—Pointer to location where result is to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_qvs_selected
read_dps_pin_n
Read current from DPS Local Meter and average.
SYNOPSIS void read_dps_pin_n(pin, n, resultp)
unsigned short *pin;
int n;
double *resultp;
DESCRIPTION Strobe the DPS Local ammeter and take a current reading the
specified number of times and put averaged result into the result
location. The second parameter is a two-dimensional array of
doubles of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter.
ARGUMENTS unsigned short *pin—A single DPS pin number or a
0-terminated list of pins (must be at least one pin)
int n—# of readings to average
double *resultp—Pointer to location where result is to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_qvs_selected.
IMAGE Solutions V8.3 26-62
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_dps_pin_nostrobe
Read current from DPS Local Meter
SYNOPSIS void read_dps_pin_nostrobe(pin, resultp)
unsigned short *pin;
double *resultp;
DESCRIPTION Read the DPS Local ammeter for the specified pin and put the
measured value in the specified location. The first parameter can
either be a single pin number or a pointer to a 0-terminated list of
pin numbers. The second parameter is a two-dimensional array
of doubles of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter.
ARGUMENTS unsigned short *pin—A single DPS pin number or a
0-terminated list of pins
double *resultp—Pointer to location where result is to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_qvs_selected.
read_dps_pin_status
Returns the status of the last CPU strobe performed.
SYNOPSIS void read_dps_pin_status(pin, statusp)
unsigned short *pin;
double *statusp;
DESCRIPTION For each hchan/pgid specified an integer value pointed to by
statusp is returned. The components of each such integer can be
accessed as shown below:
Alarms at time of CPU strobe:
BIT # RIGHT SHIFT MASK
0: DPS_MES_CLAMP_ALM DPS_MES_CLAMP_ALM_MASK
1: DPS_MES_OPEN_KELVIN_ALM DPS_MES_OPEN_KELVIN_ALM_MASK
2: DPS_MES_OPEN_KELVIN2_ALM DPS_MES_OPEN_KELVIN2_ALM_MASK
3: DPS_MES_AUTORANGE_ALM DPS_MES_AUTORANGE_ALM_MASK
4: DPS_MES_OSCILLATION_ALM DPS_MES_OSCILLATION_ALM_MASK
-------------------------------
Errors at the time of the strobe:
5: DPS_DATA_OVERWRITE DPS_DATA_OVERWRITE_MASK
previously unread, valid data has been overwritten by another conversion
IMAGE Solutions V8.3 26-63
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
6: DPS_CPU_STB_CONFLICT DPS_CPU_STB_CONFLICT_MASK
a CPU strobe conversion was received while another CPU strobe conversion was in
progress
7: DPS_ARBITOR_CONFLICT DPS_ARBITOR_CONFLICT_MASK
a measurement was requested by a command controller when a request by one of the
other 3 controllers was being handled by the arbiter
-------------------------------
8,9,10:DPS_INPUT_MODE DPS_INPUT_MODE_MASK
Input mode at the time of the strobe
-------------------------------
ARGUMENTS unsigned short *pin—a single DPS pin number or a pin field
int *statusp—Pointer to a location where the status readings are
to be stored. This should an array of the form
statusp[NUMBER_OF_SITES][NUMBER_OF_PINS]
RETURN VALUE None
SIDE EFFECTS None
SEE ALSO
read_dps_pin_time
Read current from DPS Local Meter and average over time
SYNOPSIS int read_dps_pin_time(pin, t, resultp)
unsigned short *pin;
double t;
double *resultp;
DESCRIPTION Strobe the DPS Local ammeter and take as many current
readings as possible in the specified time period and put
averaged result into the result location. The first parameter can
either be a single pin number or a pointer to a 0-terminated list of
pin numbers. The second parameter is a two-dimensional array
of doubles of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS] where
NUMBER_OF_PINS is the number of pins specified in the first
parameter.
ARGUMENTS unsigned short *pin—A single DPS pin number or a
0-terminated list of pin (must be at least one pin!)
double t—Time period (in seconds) over which measurements
are to be averaged
double *resultp—Pointer to location where result is to be
stored
IMAGE Solutions V8.3 26-64
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Returns number of measurements taken in the specified time
period. (Returns 0 if there was an error.)
SIDE EFFECTS Changes tl_qvs_selected.
read_fail_vectors
Return vector number of failed vector
SYNOPSIS int read_fail_vectors(fail_number, patnamep)
int fail_number;
char *patnamep;
DESCRIPTION Return the vector number and pattern name of any failed vector
captured in History RAM.
This function only works for failures where both the failing cycle
itself AND the cycle where the SCM fail flag gets set (34 cycles
later) are captured in HRAM.
This usually requires that:
—HRAM1 is in “unqualified” mode (capture all cycles).
—Repeat compress is off.
The default system HRAM setup meets these requirements.
This function may not return the correct (or any) pattern name if
a pattern was unloaded after the last pattern run.
Reading and reconstructing HRAM is a lengthy process and
calling any of the HRAM read functions has about a 25ms
overhead for the first call after a new pattern run.
This function will give a runtime error if a pattern is running and
not in keepalive.
ARGUMENTS fail_number—Which failure to get (1 = first failure)
patnamep—Name of a character array in which to write the
pattern name of the failing vector. Must be large enough to
hold the longest pattern name used in the test program.
May be zero; in this case, the pattern name is not returned.
RETURN VALUE Vector number of failing vector, or -1 if there were less than
fail_number fails captured.
read_funct_halt
Read HSD pattern haltcode.
SYNOPSIS int read_funct_halt()
IMAGE Solutions V8.3 26-65
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Reads the current pattern haltcode if pattern has stopped.
Checks alarms. On the simulator, causes pattern execution to
continue.
ARGUMENTS None
RETURN VALUE HSD_PATRUNNING if pattern is still running and not in keepalive,
else HSD_NOHALTCODE if pattern did not specify a halt code, else
the halt code specified in the pattern (0 to 1023).
read_h50_code
Read SCM READCODE register.
SYNOPSIS int read_h50_code()
DESCRIPTION Retrieves the read code written by the pattern to the READCODE
register on the 1st SCM. Does an rdelay() and checks alarms.
On the simulator, this function may cause the pattern to execute.
ARGUMENTS None
RETURN VALUE Value from 0 - 2047, the READCODE specified in the pattern.
TL_H50_NOREADCODE if the pattern didn’t specify a READCODE.
SEE ALSO Note for driver writers: Call this version only during test program
execution and never during anything like a debug display fetch
function, or it may cause pattern debugger deadlock.
read_h50_code_nac
Read SCM READCODE, no alarm check.
SYNOPSIS int read_h50_code_nac(which_scm) int which_scm;
DESCRIPTION Retrieves the read code written by the pattern to the READCODE
register on the specified SCM. This function does not do an
rdelay nor does it check alarms. On the simulator, this function
may cause the pattern to execute.
ARGUMENTS which_scm—0 for 1st SCM, 1 for 2nd SCM
RETURN VALUE Value from 0 - 2047, the READCODE specified in the pattern.
TL_H50_NOREADCODE if the pattern didn’t specify a READCODE.
SEE ALSO “read_h50_code”, read_h50_code_scm in the Functions chapter
of your test head manual
read_hfdig_vrng
Read back the voltage range of a High Frequency Digitizer.
IMAGE Solutions V8.3 26-66
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS double read_hfdig_vrng(pin)
int pin;
DESCRIPTION This function reads back the voltage range (or maximum
amplitude setting) for an HFDIG instrument. Called with a device
pin number, it returns the vrange of the HFDIG behind that pin.
ARGUMENTS pin—Pin number of the instrument.
RETURN VALUE Returns the vrange of the HFDIG behind that pin.
SEE ALSO “read_ac_vrng_chan” for using channel numbers instead of
device pins.
read_hram_loc
Search History RAM for a cycle.
SYNOPSIS int read_hram_loc(how, which, n)
int how
int which;
int n;
DESCRIPTION Searches History RAM for a specified cycle. Returns the location
of the cycle, used for accessing the information.
Type of search is specified by the how argument:
TL_HRAM_BY_CYCLE—find n’th cycle whose cycle number
matches which
TL_HRAM_BY_VECTOR—find n’th cycle whose vector number
matches which
TL_HRAM_BY_FAIL—find n’th failing cycle
TL_HRAM_BY_TSET—find n’th cycle whose tset number matches
which
Reading and reconstructing HRAM is a lengthy process and
calling any of the HRAM read functions has an overhead of 1ms
- 100ms on the first call after a pattern run, depending on the
number of cycles captured and the number of channels to be
read. Subsequent calls of the HRAM read functions for the same
pattern run will be faster ONLY if the channel or pin list specified
in the first call (if any) does not change. This function does not
work properly for failing cycles if the ICYC opcode is used.
ARGUMENTS how—TL_HRAM_BY_CYCLE, TL_HRAM_BY_VECTOR,
TL_HRAM_BY_FAIL, or TL_HRAM_BY_TSET
which—The cycle, vector or tset number to find.
n—Which cycle to find if more than one satisfy the requirement.
Value of 1 gets the first.
This function will give a runtime error if a pattern is running and
not in keepalive.
IMAGE Solutions V8.3 26-67
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Location of requested cycle in History RAM (from 1 to 1024), or
-1 if the specified cycle is not found.
SEE ALSO read_hram_loc_scm(), read_hram_loc_precond() in the
Functions chapter of your test head manual
read_hram_scm
Read SCM information for a History RAM location.
SYNOPSIS int read_hram_scm(loc, what)
int loc;
int what;
DESCRIPTION Reads the specified piece of information for a location in History
RAM. The location is usually obtained using read_hram_loc().
ARGUMENTS loc—The History RAM location to read, from 1 to 1024.
what—The information to return. Choices are:
TL_HRAM_SCM_CYCLE—the cycle number of the location
TL_HRAM_SCM_VECTOR—the vector number of the location
TL_HRAM_SCM_TSET—the tset number of the cycle in that
location
TL_HRAM_SCM_LOOP—the loop count of the cycle in that location.
If the loop count is invalid, 0 will be returned.
Reading and reconstructing HRAM is a lengthy process and
calling any of the HRAM read functions has an overhead of 25
ms on the first call after a new pattern run.
This function will give a runtime error if a pattern is running and
not in keepalive.
RETURN VALUE The information requested as above, or -1 if the location did not
contain a captured cycle.
read_hsd50_results
Get Catalyst failed pin list.
SYNOPSIS int read_hsd50_results(faillist)
unsigned short *faillist;
int read_hsd50_results_scm(faillist, which_scm)
unsigned short *faillist;
int which_scm;
DESCRIPTION Get the list of DUT pin numbers listed as failing by the
Accumulated Fail Register. Writes null-terminated list of failing
channel numbers into the user-supplied array faillist.
Returns the number of failed pins. The pattern may be running.
IMAGE Solutions V8.3 26-68
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
The function read_hsd50_results() returns failures for the first
sequencer read_hsd50_results_scm(which_scm) returns
them for the SCM number specified.
If pattern passed, function returns zero and the fail array has its
first location set to zero.
If a channel fails that is not found mapped to a pin in the pinmap,
it is not included in the faillist array but will be included in the
number of fails returned.
A pass/fail-only check can be made by passing a faillist of zero.
In this case the fail list is not created and the function just returns
0 for passed or 1 for failed. The advantage of this is faster
execution when failures are present.
Example: Print list of failed pin numbers
{
unsigned short failpins[MAX_H100_CHANLIST];
unsigned short *failptr;
int num_fails;
num_fails = read_hsd50_results(failpins);
if (num_fails) {
printf("Failed pin numbers: ");
for (failptr=failpins; *failptr != 0; failptr++)
printf("%d ", *failptr);
printf("\n");
}
}
ARGUMENTS faillist—Name of array which will be filled with a
null- terminated pin list; array must be of size
MAX_H100_CHANLIST. Argument may be zero to prevent
writing list and just return number of failures.
int which_scm—FIRST_SEQ for scm 1, SECOND_SEQ for scm 2
RETURN VALUE If faillist provided, return number of failing channels.
If faillist zero, return 0 for passed or 1 for failed.
read_lfdig_vrng
Read back the voltage range of a Low Frequency Digitizer.
SYNOPSIS double read_lfdig_vrng(pin)
int pin;
DESCRIPTION This function reads back the voltage range (or maximum
amplitude setting) for an LFDIG instrument. Called with a device
pin number, it returns the vrange of the LFDIG behind that pin.
ARGUMENTS pin—Pin number of the instrument.
IMAGE Solutions V8.3 26-69
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Returns the vrange of the LFDIG behind that pin.
SEE ALSO “read_ac_vrng_chan” for using channel numbers instead of
device pins.
read_lowest_bin_at_fail
Read the best bin number at point of failure.
SYNOPSIS int read_lowest_bin_at_fail();
DESCRIPTION Only use this function in a test program using close binning. It
returns the bin number into which the device would be binned
had it been binned at the point all pass bins were closed (unless
an explicit pass or fail bin assignment has been made).
When running in stop_on_fail mode (the default), testing stops
at the point when all pass bins are closed. When running in
continue_on_fail mode, however, binning may change after
this point. Use this function to put the device where it would have
been binned in stop_on_fail mode.
In a multisite test program this must be called from inside a serial
block.
ARGUMENTS None
RETURN VALUE Lowest open bin number [1-32] at point of failure or NO_BINNING
if all bins closed.
read_lowest_open_bin
Read bin number of best currently open bin.
SYNOPSIS int read_lowest_open_bin()
DESCRIPTION This function determines the lowest currently open bin number.
This is the bin into which the device would be binned if a sort
bin statement was executed at this point in the test program
(unless an explicit pass or fail bin assignment has been made).
In a multisite test program this must be called from inside a serial
block.
ARGUMENTS None
RETURN VALUE Lowest open bin number [1–32] or NO_BINNING if all bins closed.
read_measurement
Take and return a DC measurement.
SYNOPSIS double read_measurement();
IMAGE Solutions V8.3 26-70
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Takes an immediate measurement of the instrument last named
in a set measure from: statement. The unit of the
measurement, for instance volts or amperes, depends on the
instrument.
ARGUMENTS None
RETURN VALUE Calibrated measurement.
SIDE EFFECTS Strobes the selected digitizer to take the measurement.
read_measurement_n
Return the average of N measurements.
SYNOPSIS double read_measurement_n(n_times);
int n_times;
DESCRIPTION Takes N immediate measurement of the instrument last named
in a set measure from: statement and returns the average.
The unit of the measurement, such as volts or amperes,
depends on the instrument.
ARGUMENTS n_times—Number of measurements to take. Limited by the size
of an integer, which must be able to contain the sum of all raw
readings without overflow. This is:
(log2(MAXINT) - log2(digitizer_raw) - 1)
since raw readings are internally shifted left by one bit to
preserve accuracy. Log2(digitizer_raw) for the DC Meter is 14.
Log2(MAXINT) on a SPARC engine 1 is 32, so n can be 1..2**17-
1.
RETURN VALUE Average measurement.
SIDE EFFECTS Strobes the selected digitizer to take the measurement.
read_measurement_nostrobe
Read a previously-taken measurement.
SYNOPSIS double read_measurement_nostrobe();
DESCRIPTION Reads back a measurement that was taken by strobing the
selected meter by other means, for instance a trigger.
ARGUMENTS None
RETURN VALUE Calibrated measurement.
read_measurement_time
Read average of measurements over time.
IMAGE Solutions V8.3 26-71
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS double read_measurement_time(t);
double t;
DESCRIPTION Takes immediate measurements of the instrument last named in
a set measure from: statement, repeating the measurement
for t seconds, returning the average. The unit of the
measurement, for instance volts or amperes, depends on the
instrument.
ARGUMENTS None
RETURN VALUE Average measurement.
SIDE EFFECTS Strobes the selected digitizer to take the measurement.
read_measurement_time_and_n
Average and number of measurements over time.
SYNOPSIS double read_measurement_time(t, n);
double t;
int *n;
DESCRIPTION Takes immediate measurements of the instrument last named in
a set measure from: statement, repeating the measurement
for t seconds, returning the average. The unit of the
measurement, for instance volts or amperes, depends on the
instrument. Sets n to be the number of measurements actually
taken.
ARGUMENTS t—Time
n—Pointer to int, to be filled in.
RETURN VALUE Average measurement.
SIDE EFFECTS Strobes the selected digitizer to take the measurement.
read_meter
Take a measurement with the test system DC meter.
SYNOPSIS double read_meter();
DESCRIPTION The system meter takes a measurement of its input and returns
a calibrated reading. The unit of the reading, such as volts,
amps, or some other unit, depending on the instrument being
measured.
ARGUMENTS None
RETURN VALUE Reading
IMAGE Solutions V8.3 26-72
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_meter_n
Return average of N readings.
SYNOPSIS double read_meter_n(n_times);
int n_times;
DESCRIPTION Like read_meter(), but takes N readings and returns their
average.
ARGUMENTS n_times—Number of readings
RETURN VALUE Average reading
read_meter_nostrobe
Return reading without taking a new one.
SYNOPSIS double read_meter_nostrobe();
DESCRIPTION Like read_meter(), but does not strobe the meter with the CPU.
It is assumed that the meter was strobed by another means,
such as a trigger line or an external input to A/D Strobe.
ARGUMENTS None
RETURN VALUE Reading
read_meter_time
Return average of readings over time.
SYNOPSIS double read_meter_time(time);
double time;
DESCRIPTION Read meter averaged over time. Averages the meter over the
specified duration. Time is specified in seconds. A negative
duration generates an error and zero is returned. It is guaranteed
that the meter is read at least once.
ARGUMENTS time—in seconds.
RETURN VALUE Average reading.
read_meter_time_and_n
Return average and number of readings over time.
SYNOPSIS double read_meter_time_and_n(time, n);
double time;
int *n;
DESCRIPTION Read meter averaged over time. Averages the meter over the
specified duration. Time is specified in seconds. A negative
IMAGE Solutions V8.3 26-73
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
duration generates an error and zero is returned. The meter will
be read at least once. n is filled in with a value indicating how
many meter reads occurred.
ARGUMENTS time—In seconds.
n—Pointer to a variable to be filled in.
RETURN VALUE Average reading.
read_opamp_loop_alarm
Read status of Quad Opamp channel card open loop alarm.
SYNOPSIS int read_opamp_loop_alarm (pinnum)
int pinnum;
DESCRIPTION This function accepts a pin number, as specified in the pin map.
The alarm register is read on the opamp channel specified and,
if the alarm bit is set, a 1 is returned. If the bit is not set or the site
is inactive, a 0 is returned. The function supports multisite test. If
the program is a multisite program, the function must be
enclosed in a serial block.
ARGUMENTS int pinnum—The pin number from the pin map
RETURN VALUE 0 if ok
1 if alarm
read_opamp_osc_alarm
Read status of Quad Opamp channel card osc alarm.
SYNOPSIS int read_opamp_osc_alarm (pinnum)
int pinnum;
DESCRIPTION This function accepts a pin number, as specified in the pin map.
The alarm register is read on the opamp channel specified and if
the alarm bit is set a 1 is returned. If the bit is not set or the site
is inactive, a 0 is returned. The function supports multisite test. If
the program is a multisite program, the function must be
enclosed in a serial block.
ARGUMENTS int pinnum—The pin number from the pin map
RETURN VALUE 0 if ok
1 if alarm
read_ovi_amm_pin_status
Read status of OVI ammeter.
IMAGE Solutions V8.3 26-74
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int read_ovi_amm_pin_status(pin, statusp)
unsigned short *pin;
int *statusp;
DESCRIPTION This function returns the alarm and error status of the specified
OVI ammeter. The alarms and errors of interest are those that
were present at the time the local ammeter was strobed. The first
parameter can either be a single pin number or a pointer to a 0-
terminated list of pin numbers. The second parameter is a two-
dimensional array of integers of the form:
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
statusp—Pointer to array where the status of each OVI will be
stored
RETURN VALUE A general status is returned.
1 = errors or alarms were found.
0 = no alarms or errors found on any channels.
For each pin specified, function inserts an encoded status of
alarms and errors in the integer pointed to by statusp. The
value entered is encoded as follows:
Alarms and errors at time of current ADC strobe
OVI_AMM_INVALID_DATA—Valid data from a recent conversion
has not yet been read
OVI_AMM_OVERWRITE_DATA—Previously unread, valid data has
been overwritten by another conversion
OVI_AMM_MISSED_TRIGGER—A conversion strobe was received
while another conversion was in progress
OVI_AMM_OPEN_KELVIN—Open Kelvin alarm at time of strobe
OVI_AMM_SENSE_CURR—Sense current alarm at time of strobe
OVI_AMM_MODE—Mode alarm at time of strobe
OVI_AMM_OVERRANGE—Voltmeter overrange alarm
OVI_AMM_OPEN_LOOP—Open loop alarm at time of strobe
SIDE EFFECTS Sets tl_ovi_selected.
read_ovi_amm_status
Read status of OVI ammeter
SYNOPSIS int read_ovi_amm_status(channel, statusp)
unsigned short *channel;
int *statusp;
IMAGE Solutions V8.3 26-75
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns the alarm and error status of the specified
OVI ammeter. The alarms and errors of interest are those that
were present at the time the local ammeter was strobed.
ARGUMENTS channel—A single OVI channel number or a 0-terminated list of
channels (1 based)
statusp—Pointer to array where the status of each OVI will be
stored
RETURN VALUE A general status is returned.
1 = errors or alarms were found.
0 = no alarms or errors found on any channels.
For each channel specified, function inserts an encoded status
of alarms and errors in the integer pointed to by statusp. The
value entered is encoded as follows:
Alarms and errors at time of current ADC strobe
OVI_AMM_INVALID_DATA—valid data from a recent conversion
has not yet been read
OVI_AMM_OVERWRITE_DATA—previously unread, valid data has
been overwritten by another conversion
OVI_AMM_MISSED_TRIGGER—a conversion strobe was received
while another conversion was in progress
OVI_AMM_OPEN_KELVIN—Open Kelvin alarm at time of strobe
OVI_AMM_SENSE_CURR—Sense current alarm at time of strobe
OVI_AMM_MODE—Mode alarm at time of strobe
OVI_AMM_OVERRANGE—Voltmeter overrange alarm
OVI_AMM_OPEN_LOOP—Open loop alarm at time of strobe
SIDE EFFECTS Sets tl_ovi_selected.
read_ovi_i
Read current from OVI local meter.
SYNOPSIS void read_ovi_i(channel,resultp)
unsigned short *channel;
double *resultp;
DESCRIPTION Strobe the OVI local ammeter, wait for the A/D conversion, and
put the measured value in the specified location.
ARGUMENTS channel—a single OVI channel number or a 0-terminated list of
channels (1 based)
resultp—pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
IMAGE Solutions V8.3 26-76
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_ovi_i_n
Read current from OVI local meter and average
SYNOPSIS void read_ovi_i_n(channel, n, resultp)
unsigned short *channel;
int n;
double *resultp;
DESCRIPTION Strobe the OVI local meter and take a current reading the
specified number of times and put averaged result into the result
location.
ARGUMENTS channel—a single OVI channel number or a 0-terminated list of
channels (1 based)
n—number of measurements to be averaged
resultp—pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_i_nostrobe
Read voltage from OVI local meter without strobing.
SYNOPSIS void read_ovi_i_nostrobe (channel, resultp)
unsigned short *channel;
double *resultp;
DESCRIPTION Read the OVI local meter and put the measured value in the
specified location.
ARGUMENTS channel—A single OVI channel number or a 0-terminated list of
channels (1 based)
resultp—Pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_i_pin
Read current from OVI local meter.
SYNOPSIS void read_ovi_i_pin(pin,resultp)
unsigned short *pin;
double *resultp;
DESCRIPTION Strobe the OVI local meter, wait for the A/D conversion, and put
the measured value in the specified location. The first parameter
can either be a single pin number or a pointer to a 0-terminated
IMAGE Solutions V8.3 26-77
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
list of pin numbers. The second parameter is a two-dimensional
array of doubles of the form:
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
resultp—Pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_i_pin_n
Read current from OVI local meter and average.
SYNOPSIS void read_ovi_i_pin_n(pin,n,resultp)
unsigned short *pin;
int n;
double *resultp;
DESCRIPTION Strobe the OVI local meter and take a current reading the
specified number of times and put averaged result into the result
location. The second parameter is a two-dimensional array of
doubles of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
n—Number of readings to average
resultp—Pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_i_pin_nostrobe
Read current from OVI local meter.
SYNOPSIS void read_ovi_i_pin_nostrobe(pin, resultp)
unsigned short *pin;
double *resultp;
DESCRIPTION Read the OVI local meter for the specified pin and put the
measured value in the specified location. The first parameter can
either be a single pin number or a pointer to a 0-terminated list of
pin numbers. The second parameter is a two-dimensional array
of doubles of the form
IMAGE Solutions V8.3 26-78
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
resultp—Pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_i_pin_time
Read current from OVI local meter and average over time.
SYNOPSIS void read_ovi_i_pin_time(pin,t,resultp)
unsigned short *pin;
double t;
double *resultp;
DESCRIPTION Strobe the OVI local meter and take as many current readings as
possible in the specified time period and put averaged result into
the result location. The first parameter can either be a single pin
number or a pointer to a 0-terminated list of pin numbers. The
second parameter is a two-dimensional array of doubles of the
form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
t—Time period (in seconds) over which measurements are to be
averaged
resultp—Pointer to location where result is to be stored
RETURN VALUE Returns number of measurements taken in the specified time
period
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_i_time
Read current from OVI local meter and average over time.
SYNOPSIS int read_ovi_i_time(channel, t, resultp)
unsigned short *channel;
double t;
double *resultp;
IMAGE Solutions V8.3 26-79
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Strobe the OVI local meter and take as many current readings as
possible in the specified time period and put averaged result into
the result location.
ARGUMENTS channel—A single OVI channel number or a 0-terminated list of
channels (1 based)
t—Time period (in seconds) over which measurements are to be
averaged
resultp—Pointer to location where result is to be stored
RETURN VALUE Returns number of measurements taken in the specified time
period
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_meter_pin_status
Read status of OVI voltmeter and ammeter.
SYNOPSIS int read_ovi_meter_pin_status(pin, statusp)
unsigned short *pin;
int *statusp;
DESCRIPTION This function returns the alarm and error status of the specified
OVI voltmeter and ammeter. The alarms and errors of interest
are those present at the time the local voltmeter and ammeter
were strobed. The first parameter can either be a single pin
number or a pointer to a 0-terminated list of pin numbers. The
second parameter is a two-dimensional array of integers of the
form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
statusp—Pointer to array where the status of each OVI will be
stored
RETURN VALUE A general status is returned.
1 = errors or alarms were found.
0 = no alarms or errors found on any channels.
For each pin specified, function inserts an encoded status of
alarms and errors in the integer pointed to by statusp. The
value entered is encoded as follows:
Alarms and errors at time of voltage ADC strobe.
OVI_VM_INVALID_DATA—valid data from a recent conversion
has not yet been read
OVI_VM_OVERWRITE_DATA—previously unread, valid data has
IMAGE Solutions V8.3 26-80
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
been overwritten by another conversion
OVI_VM_MISSED_TRIGGER—a conversion strobe was received
while another conversion was in progress
OVI_VM_OPEN_KELVIN—Open Kelvin alarm at time of strobe
OVI_VM_SENSE_CURR—Sense current alarm at time of strobe
OVI_VM_MODE—Mode alarm at time of strobe
OVI_VM_OVERRANGE—Voltmeter overrange alarm
OVI_VM_OPEN_LOOP—Open loop alarm at time of strobe
Alarms and errors at time of current ADC strobe
OVI_AMM_INVALID_DATA—valid data from a recent conversion
has not yet been read
OVI_AMM_OVERWRITE_DATA—previously unread, valid data has
been overwritten by another conversion
OVI_AMM_MISSED_TRIGGER—A conversion strobe was received
while another conversion was in progress
OVI_AMM_OPEN_KELVIN—Open Kelvin alarm at time of strobe
OVI_AMM_SENSE_CURR—Sense current alarm at time of strobe
OVI_AMM_MODE—Mode alarm at time of strobe
OVI_AMM_OVERRANGE—Voltmeter overrange alarm
OVI_AMM_OPEN_LOOP—Open loop alarm at time of strobe
SIDE EFFECTS Sets tl_ovi_selected.
read_ovi_meter_status
Read status of OVI voltmeter and ammeter.
SYNOPSIS int read_ovi_meter_status(channel, statusp)
unsigned short *channel;
int *statusp;
DESCRIPTION This function returns the alarm and error status of the specified
OVI voltmeter and ammeter. The alarms and errors of interest
are those that were present at the time the local voltmeter and
ammeter were strobed.
ARGUMENTS channel—A single OVI channel number or a 0-terminated list of
channels (1 based)
statusp—Pointer to array where the status of each OVI will be
stored
RETURN VALUE A general status is returned.
1 = errors or alarms were found.
0 = no alarms or errors found on any channels.
For each channel specified, function inserts an encoded status
of alarms and errors in the integer pointed to by statusp. The
value entered is encoded as follows:
Alarms and errors at time of voltage ADC strobe
IMAGE Solutions V8.3 26-81
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
OVI_VM_INVALID_DATA—valid data from a recent conversion
has not yet been read
OVI_VM_OVERWRITE_DATA—previously unread, valid data has
been overwritten by another conversion
OVI_VM_MISSED_TRIGGER—a conversion strobe was received
while another conversion was in progress
OVI_VM_OPEN_KELVIN—Open Kelvin alarm at time of strobe
OVI_VM_SENSE_CURR—Sense current alarm at time of strobe
OVI_VM_MODE—Mode alarm at time of strobe
OVI_VM_OVERRANGE—Voltmeter overrange alarm
OVI_VM_OPEN_LOOP—Open loop alarm at time of strobe
Alarms and errors at time of current ADC strobe
OVI_AMM_INVALID_DATA—Valid data from a recent conversion
has not yet been read
OVI_AMM_OVERWRITE_DATA—Previously unread, valid data has
been overwritten by another conversion
OVI_AMM_MISSED_TRIGGER—A conversion strobe was received
while another conversion was in progress
OVI_AMM_OPEN_KELVIN—Open Kelvin alarm at time of strobe
OVI_AMM_SENSE_CURR—Sense current alarm at time of strobe
OVI_AMM_MODE—Mode alarm at time of strobe
OVI_AMM_OVERRANGE—Voltmeter overrange alarm
OVI_AMM_OPEN_LOOP—Open loop alarm at time of strobe
SIDE EFFECTS Sets tl_ovi_selected.
read_ovi_r
Calculate for a channel.
SYNOPSIS void read_ovi_r(channel, resultp)
ARGUMENTS unsigned short *channel—A single OVI channel number or a
0-terminated list of channels (1 based)
double *resultp—Pointer to location where result is to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected
read_ovi_r_pin
Calculate resistance for a pin.
SYNOPSIS void read_ovi_r_pin(pin, resultp)
ARGUMENTS unsigned short *pin—A single OVI pin number or a 0-
terminted list of pins (1 based)
IMAGE Solutions V8.3 26-82
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
double *resultp—Pointer to location where result is to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected
read_ovi_v
Read voltage from OVI local meter.
SYNOPSIS void read_ovi_v(channel,resultp)
unsigned short *channel;
double *resultp;
DESCRIPTION Strobe the OVI local voltmeter, wait for the A/D conversion, and
put the measured value in the specified location.
ARGUMENTS channel—A single OVI channel number or a 0-terminated list of
channels (1 based)
resultp—Pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_i
Read voltage and current from OVI local meter.
SYNOPSIS void read_ovi_v_i(v_channel, i_channel, v_resultp,
i_resultp)
unsigned short *v_channel;
unsigned short *i_channel;
double *v_resultp;
double *i_resultp;
DESCRIPTION Strobe the OVI local voltmeter and ammeter, wait for the A/D
conversions, and put the measured values in the specified
location.
ARGUMENTS v_channel—Voltmeters to be read. A single OVI channel
number or a 0-terminated list of channels (1 based).
i_channel—Ammeters to be read. A single OVI channel
number or a 0-terminated list of channels (1 based).
v_resultp—Pointer to location where voltage readings are to
be stored
i_resultp—Pointer to location where current readings are to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
IMAGE Solutions V8.3 26-83
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_ovi_v_i_n
Read voltage and current from OVI local meters and average.
SYNOPSIS void read_ovi_v_i_n(v_channel, i_channel, n,
v_resultp, i_resultp)
unsigned short *v_channel;
unsigned short *i_channel;
int n;
double *v_resultp;
double *i_resultp;
DESCRIPTION Strobe the OVI Local voltmeter and ammeter at the same time,
take both a voltage reading and a current reading the specified
number of times, and put averaged results into the result
location.
ARGUMENTS v_channel—Voltmeters to be read. A single OVI channel
number or a 0-terminated list of channels (1 based).
i_channel—Ammeters to be read. A single OVI channel
number or a 0-terminated list of channels (1 based).
n—number of measurements to be averaged
v_resultp—Pointer to location where voltage readings are to
be stored
i_resultp—Pointer to location where current readings are to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_i_nostrobe
Read voltage and current from OVI local meter without strobing.
SYNOPSIS void read_ovi_v_i_nostrobe(v_channel, i_channel,
v_resultp, i_resultp)
unsigned short *v_channel;
unsigned short *i_channel;
double *v_resultp;
double *i_resultp;
DESCRIPTION Read the OVI local voltmeter and ammeter and put the
measured values in the specified location.
ARGUMENTS v_channel—Voltmeters to be read. A single OVI channel
number or a 0-terminated list of channels (1 based).
i_channel—Ammeters to be read. A single OVI channel
number or a 0-terminated list of channels (1 based).
v_resultp—Pointer to location where voltage readings are to
be stored
IMAGE Solutions V8.3 26-84
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
i_resultp—Pointer to location where current readings are to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_i_pin
Read voltage and current from OVI local meter.
SYNOPSIS void read_ovi_v_i_pin(v_pin, i_pin, v_resultp,
i_resultp)
unsigned short *v_pin;
unsigned short *i_pin;
double *v_resultp;
double *i_resultp;
DESCRIPTION Strobe the OVI Local voltmeter and ammeter, wait for the A/D
conversions, and put the measured values in the specified
location. The first two parameters can either be a single pin
number or a pointer to a 0-terminated list of pin numbers. The
third and fourth parameters are two-dimensional arrays of
doubles of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS v_pin—Voltmeters to be read. A single OVI pin number or a 0-
terminated list of pins.
i_pin—Ammeters to be read. A single OVI pin number or a 0-
terminated list of pins.
v_resultp—Pointer to location where voltage readings are to
be stored
i_resultp—Pointer to location where current readings are to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_i_pin_n
Read voltage and current from OVI local meters and average.
SYNOPSIS void read_ovi_v_i_pin_n(v_pin, i_pin, n, v_resultp,
i_resultp)
unsigned short *v_pin;
unsigned short *i_pin;
int n;
IMAGE Solutions V8.3 26-85
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
double *v_resultp;
double *i_resultp;
DESCRIPTION Strobe the OVI Local voltmeter and ammeter at the same time,
take both a voltage reading and a current reading the specified
number of times, and put averaged results into the result
location. The first two parameters can either be a single pin
number or a pointer to a 0-terminated list of pin numbers. The
fourth and fifth parameters are two-dimensional array of doubles
of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS v_pin—Voltmeters to be read. A single OVI pin number or a
0-terminated list of pins.
i_pin—Ammeters to be read. A single OVI pin number or a 0-
terminated list of pins.
n—number of readings to average
v_resultp—Pointer to location where voltage readings are to
be stored
i_resultp—Pointer to location where current readings are to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_i_pin_nostrobe
Read voltage and current from OVI local meters without strobing.
SYNOPSIS void read_ovi_v_i_pin_nostrobe(v_pin, i_pin,
v_resultp, i_resultp)
unsigned short *v_pin;
unsigned short *i_pin;
double *v_resultp;
double *i_resultp;
DESCRIPTION Read the OVI local voltmeter and ammeter behind the specified
pins and put the measured values in the specified location. The
first and second parameters can either be a single pin number or
a pointer to a 0-terminated list of pin numbers. The third and
fourth parameters are two-dimensional arrays of doubles of the
form:
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
IMAGE Solutions V8.3 26-86
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS v_pin—Voltmeters to be read. A single OVI pin number or a
0-terminated list of pins.
i_pin—Ammeters to be read. A single OVI pin number or a
0-terminated list of pins.
v_resultp—Pointer to location where voltage readings are to
be stored
i_resultp—Pointer to location where current readings are to be
stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_i_pin_time
Read voltage and current from OVI local meters and average over time.
SYNOPSIS void read_ovi_v_i_pin_time(v_pin, i_pin, t,
v_resultp, i_resultp)
unsigned short *v_pin;
unsigned short *i_pin;
double t;
double *v_resultp;
double *i_resultp;
DESCRIPTION Strobe the OVI Local voltmeter and ammeter at the same time,
take as many voltage readings and current readings as possible
in the specified time period and put the averaged results into the
result location. The first two parameters can either be a single pin
number or a pointer to a 0-terminated list of pin numbers. The
last two parameters are two-dimensional arrays of doubles of the
form:
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS v_pin—Voltmeters to be read. A single OVI pin number or a
0-terminated list of pins.
i_pin—Ammeters to be read. A single OVI pin number or a
0-terminated list of pins.
t—Time period (in seconds) over which measurements are to be
averaged
v_resultp—Pointer to location where voltage readings are to
be stored
i_resultp—Pointer to location where current readings are to be
stored
RETURN VALUE Returns number of measurements taken in the specified time
period
IMAGE Solutions V8.3 26-87
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_i_time
Read voltage and current from OVI local meters and average over time.
SYNOPSIS int read_ovi_v_i_time(v_channel, i_channel, t,
v_resultp, i_resultp)
unsigned short *v_channel;
unsigned short *i_channel;
double t;
double *v_resultp;
double *i_resultp;
DESCRIPTION Strobe the OVI local voltmeter and ammeter at the same time,
take as many voltage readings and current readings as possible
in the specified time period and put the averaged results into the
result location.
ARGUMENTS v_channel—Voltmeters to be read. A single OVI channel
number or a 0-terminated list of channels (1 based).
i_channel—Ammeters to be read. A single OVI channel
number or a 0-terminated list of channels (1 based).
t—Time period (in seconds) over which measurements are to be
averaged
v_resultp—Pointer to location where voltage readings are to
be stored
i_resultp—Pointer to location where current readings are to be
stored
RETURN VALUE Returns number of measurements taken in the specified time
period
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_vm_pin_status
Read status of OVI voltmeter.
SYNOPSIS int read_ovi_vm_pin_status(pin, statusp)
unsigned short *pin;
int *statusp;
DESCRIPTION This function returns the alarm and error status of the specified
OVI voltmeter. The alarms and errors of interest are those that
were present at the time the local voltmeter was strobed. The
first parameter can either be a single pin number or a pointer to
a 0-terminated list of pin numbers. The second parameter is a
two-dimensional array of integers of the form:
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
IMAGE Solutions V8.3 26-88
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
statusp—Pointer to array where the status of each OVI will be
stored
RETURN VALUE A general status is returned.
1—errors or alarms were found.
0—no alarms or errors found on any channels.
For each pin specified, function inserts an encoded status of
alarms and errors in the integer pointed to by statusp. The
value entered is encoded as follows:
Alarms and errors at time of voltage ADC strobe
OVI_VM_INVALID_DATA—valid data from a recent conversion
has not yet been read
OVI_VM_OVERWRITE_DATA—previously unread, valid data has
been overwritten by another conversion
OVI_VM_MISSED_TRIGGER—a conversion strobe was received
while another conversion was in progress
OVI_VM_OPEN_KELVIN—Open Kelvin alarm at time of strobe
OVI_VM_SENSE_CURR—Sense current alarm at time of strobe
OVI_VM_MODE—Mode alarm at time of strobe
OVI_VM_OVERRANGE—Voltmeter overrange alarm
OVI_VM_OPEN_LOOP—Open loop alarm at time of strobe
SIDE EFFECTS Sets tl_ovi_selected.
read_ovi_vm_status
Read status of OVI voltmeter.
SYNOPSIS int read_ovi_vm_status(channel, statusp)
unsigned short *channel;
int *statusp;
DESCRIPTION This function returns the alarm and error status of the specified
OVI voltmeter. The alarms and errors of interest are those that
were present at the time the local voltmeter were strobed.
ARGUMENTS channel—a single OVI channel number or a 0-terminated list of
channels (1 based)
statusp—pointer to array where the status of each OVI will be
stored
RETURN VALUE A general status is returned.
1—errors or alarms were found.
0—no alarms or errors found on any channels.
IMAGE Solutions V8.3 26-89
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For each channel specified, function inserts an encoded status
of alarms and errors in the integer pointed to by statusp. The
value entered is encoded as follows:
Alarms and errors at time of voltage ADC strobe
OVI_VM_INVALID_DATA—valid data from a recent conversion
has not yet been read
OVI_VM_OVERWRITE_DATA—previously unread, valid data has
been overwritten by another conversion
OVI_VM_MISSED_TRIGGER—a conversion strobe was received
while another conversion was in progress
OVI_VM_OPEN_KELVIN—Open Kelvin alarm at time of strobe
OVI_VM_SENSE_CURR—Sense current alarm at time of strobe
OVI_VM_MODE—Mode alarm at time of strobe
OVI_VM_OVERRANGE—Voltmeter overrange alarm
OVI_VM_OPEN_LOOP—Open loop alarm at time of strobe
SIDE EFFECTS Sets tl_ovi_selected.
read_ovi_v_n
Read voltage from OVI local meter and average.
SYNOPSIS void read_ovi_v_n(channel, n, resultp)
unsigned short *channel;
int n;
double *resultp;
DESCRIPTION Strobe the OVI local voltmeter and take a voltage reading the
specified number of times and put averaged result into the result
location.
ARGUMENTS channel—a single OVI channel number or a 0-terminated list of
channels (1-based)
n—number of measurements to be averaged
resultp—pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_nostrobe
Read voltage from OVI local meter without strobing.
SYNOPSIS void read_ovi_v_nostrobe(channel, resultp)
unsigned short *channel;
double *resultp;
DESCRIPTION Read the OVI local voltmeter and put the measured value in the
specified location.
IMAGE Solutions V8.3 26-90
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS channel—a single OVI channel number or a 0-terminated list of
channels (1-based)
resultp—pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_pin
Read voltage from OVI local meter.
SYNOPSIS void read_ovi_v_pin(pin,resultp)
unsigned short *pin;
double *resultp;
DESCRIPTION Strobe the OVI local voltmeter, wait for the A/D conversion, and
put the measured value in the specified location. The first
parameter can either be a single pin number or a pointer to a
0-terminated list of pin numbers. The second parameter is a two-
dimensional array of doubles of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
resultp—Pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_pin_n
Read voltage from OVI local meter and average.
SYNOPSIS void read_ovi_v_pin_n(pin,n,resultp)
unsigned short *pin;
int n;
double *resultp;
DESCRIPTION Strobe the OVI Local voltmeter and take a voltage reading the
specified number of times and put averaged result into the result
location. The second parameter is a two-dimensional array of
doubles of the form
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
IMAGE Solutions V8.3 26-91
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
n—Number of readings to average
resultp—Pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_pin_nostrobe
Read voltage from OVI local meter.
SYNOPSIS void read_ovi_v_pin_nostrobe(pin, resultp)
unsigned short *pin;
double *resultp;
DESCRIPTION Read the OVI local voltmeter for the specified pin and put the
measured value in the specified location. The first parameter can
either be a single pin number or a pointer to a 0-terminated list of
pin numbers. The second parameter is a two-dimensional array
of doubles of the form:
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
resultp—Pointer to location where result is to be stored
RETURN VALUE None
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_pin_time
Read voltage from OVI local meter and average over time.
SYNOPSIS void read_ovi_v_pin_time(pin,t,resultp)
unsigned short *pin;
double t;
double *resultp;
DESCRIPTION Strobe the OVI local voltmeter and take as many voltage
readings as possible in the specified time period and put
averaged result into the result location. The first parameter can
either be a single pin number or a pointer to a 0-terminated list of
pin numbers. The second parameter is a two-dimensional array
of doubles of the form:
resultp[TL_SYS_MAX_SITES][NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
IMAGE Solutions V8.3 26-92
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS pin—A single OVI pin number or a 0-terminated list of pins
t—Time period (in seconds) over which measurements are to be
averaged
resultp—Pointer to location where result is to be stored
RETURN VALUE Returns number of measurements taken in the specified time
period
SIDE EFFECTS Changes tl_ovi_selected.
read_ovi_v_time
Read voltage from OVI local meter and average over time.
SYNOPSIS int read_ovi_v_time(channel, t, resultp)
unsigned short *channel;
double t;
double *resultp;
DESCRIPTION Strobe the OVI local voltmeter and take as many voltage
readings as possible in the specified time period and put
averaged result into the result location.
ARGUMENTS channel—a single OVI channel number or a 0-terminated list of
channels (1-based) double
t—time period (in seconds) over which measurements are to be
averaged
resultp—pointer to location where result is to be stored
RETURN VALUE Returns number of measurements taken in the specified time
period
SIDE EFFECTS Changes tl_ovi_selected.
read_pacs_clock
Read A(n) clock frequency for PACS.
SYNOPSIS double read_pacs_clock(clk, cage)
int clk;
int cage;
DESCRIPTION This function reads the current frequency of an A(n) clock for the
Precision AC Subsystem.
ARGUMENTS clk—Which clock to read (0, 1, 2, 3)
cage—Cage to read, 1 to PACS_MAX_CAGES.
RETURN VALUE Frequency in Hz of the clock requested
IMAGE Solutions V8.3 26-93
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_plfdig_vrng
Read back the voltage range of a Precision Low Frequency Digitizer.
SYNOPSIS double read_plfdig_vrng(pin)
int pin;
DESCRIPTION This function reads back the voltage range (or maximum
amplitude setting) for a PLFDIG instrument. Called with a device
pin number, it returns the vrange of the PLFDIG behind that pin.
ARGUMENTS pin—Pin number of the instrument.
RETURN VALUE Voltage range of the PLFDIG behind that pin.
SEE ALSO “read_ac_vrng_chan” for using channel numbers instead of
device pins.
read_plfs_integrator
Read the input bits of the selected PLFSRC.
SYNOPSIS int read_plfs_integrator();
DESCRIPTION Reads the input bits of the selected Precision Low Frequency
Source.
ARGUMENTS None
RETURN VALUE The input bits of the selected PLFSRC.
read_proto_slot_reg
Read the value of the specified prototype board register.
SYNOPSIS int read_proto_slot_reg(slot, reg, echo)
int slot;
int reg;
int echo;
DESCRIPTION Use tl_xath to read back from the specified register of the given
slot directly from the hardware.
ARGUMENTS slot—Test head slot number
reg—Prototype board register (0-63)
echo—0: read direct
non-0: read echo RAM
RETURN VALUE None
read_qvs_low_i
Intermediate function to call read_qvs_low_i2().
IMAGE Solutions V8.3 26-94
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int read_qvs_low_i(pin_names, max_expected_i, wmd,
&data)
DESCRIPTION See read_qvs_low_i2()
read_sitemask_all
Return site mask for all sites.
SYNOPSIS unsigned int read_sitemask_all()
DESCRIPTION This function determines all sites in use in a multisite test
program. This includes all enabled sites, all disabled sites, and
all sleeping sites. Only sites enabled at the start of the test
program are identified.
ARGUMENTS None
RETURN VALUE A site mask with a bit set for each site in use
SEE ALSO “read_sitemask_disabled”, “read_sitemask_enabled”
read_sitemask_disabled
Return site mask for all disabled sites.
SYNOPSIS unsigned int read_sitemask_disabled()
DESCRIPTION This function determines which sites in a multisite test program
are currently disabled. Only sites enabled at the start of the test
program are identified. For example, if a program supports three
sites, but only two of these were enabled by a handler for this run
of the test program, the bit for the site which was not enabled by
the handler is never set.
ARGUMENTS None
RETURN VALUE A site mask with a bit set for each site currently disabled
SEE ALSO “read_sitemask_enabled”
read_sitemask_enabled
Return site mask for all enabled sites.
SYNOPSIS unsigned int read_sitemask_enabled()
DESCRIPTION This function determines which sites in a multisite test program
are currently enabled. A site mask is an unsigned integer with
each bit representing a different site. Bit 0 represents site 0, bit 1
site 1, and so on. For example:
unsigned int enabled_sitemask;
enabled_sitemask = read_sitemask_enabled();
IMAGE Solutions V8.3 26-95
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Assume sites 0 and 2 are currently enabled. After executing the
code above, enabled_sitemask will be set to 0x5 (101 in
binary).
NOTE
Use this function only if complicated site manipulation is required. In most instances, use of
the serial block is preferable and simpler.
ARGUMENTS None
RETURN VALUE A site mask with a bit set for each site current enabled
SEE ALSO “tl_site_active”
read_sitemask_failed_sequencer
Return site mask for failed sites.
SYNOPSIS unsigned int read_sitemask_failed_sequencer()
DESCRIPTION This function determines all sites that failed the last sequencer in
a multisite test program. If called from within a sequencer, the
site mask returned identifies the sites that failed that sequencer.
ARGUMENTS None
RETURN VALUE A site mask with a bit set for each site that failed the last
sequencer
SEE ALSO “read_sitemask_enabled”, “tl_get_seq_bin”
read_sitemask_sleep
Return site mask for all sleeping sites.
SYNOPSIS unsigned int read_sitemask_sleep()
DESCRIPTION This function determines which sites in a multisite test program
are currently in the sleep state.
ARGUMENTS None
RETURN VALUE A site mask with a bit set for each site currently sleeping
SEE ALSO “read_sitemask_enabled”
read_spec
Read back the current value of a spec.
SYNOPSIS double read_spec(const char *sname)
IMAGE Solutions V8.3 26-96
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function gets the current value for the named spec and
returns it. The current value is that specified in a set spec
statement if any apply to that spec. Otherwise, it is the value
relative to the currently active specset for the speclist that spec
is a member of. The active specset is set whenever a set hsd50
create_setup or load hsd50 setup statement occurs.
ARGUMENTS const char *sname—The string name of the spec
RETURN VALUE The value of the spec; NaN: one of the following has occurred:
—Spec does not exist and the test program ignores the
subsequent error.
—Spec has no defined value for the currently active specset.
—No currently active specset.
read_spec_max
Read back the maximum value of a spec.
SYNOPSIS double read_spec_max(const char *sname)
DESCRIPTION This function gets the maximum value for the named spec and
returns it. This is the maximum value specified for the spec in the
currently active specset. The active specset is set whenever a
set hsd50 create_setup or load hsd50 setup statement
occurs.
ARGUMENTS const char *sname—the string name of the spec
RETURN VALUE The maximum value of the spec; NaN: one of the following has
occurred:
1. the spec does not exist and the test program ignores the
subsequent error.
2. the spec has no defined value for the currently active specset.
3. there is no currently active specset.
SIDE EFFECTS None.
SEE ALSO None.
read_spec_min
Read back the minimum value of a spec.
SYNOPSIS double read_spec_min(const char *sname)
DESCRIPTION This function gets the minimum value for the named spec and
returns it. This is the minimum value specified for the spec in the
currently active specset. The active specset is set whenever a
IMAGE Solutions V8.3 26-97
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
set hsd50 create_setup or load hsd50 setup statement
occurs.
ARGUMENTS const char *sname— the string name of the spec
RETURN VALUE The minimum value of the spec; NaN: one of the following has
occurred:
1. the spec does not exist and the test program ignores the
subsequent error.
2. the spec has no defined value for the currently active specset.
3. there is no currently active specset.
SIDE EFFECTS None.
SEE ALSO None.
read_test_condition
Return currently selected test condition.
SYNOPSIS int read_test_condition()
DESCRIPTION This function returns the value of the currently selected test
condition. Test conditions are defined in the test_conditions
declaration. The current test condition is selected at test program
load time or using the testcond keyboard command. (See “Test
Conditions” on page 15-27 and “Setting Test Conditions Using
the testcond Command” on page 6-10.)
ARGUMENTS None
RETURN VALUE The value of the currently selected test condition or zero if no test
condition selected.
read_test_condition_name
Get name of selected test condition.
SYNOPSIS char * read_test_condition_name()
DESCRIPTION This function returns the name of the currently selected test
condition. Test conditions are defined in the test_conditions
declaration. The current test condition is selected at test program
load time or using the testcond keyboard command. (See “Test
Conditions” on page 15-27 and “Setting Test Conditions Using
the testcond Command” on page 6-10.)
ARGUMENTS None
IMAGE Solutions V8.3 26-98
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE A pointer to the name of the currently selected test condition or
NULL if no test condition selected. This pointer is valid until the
next call to this function.
read_test_status
Read status of last test executed.
SYNOPSIS int read_test_status()
DESCRIPTION Determine the pass/fail status of the last test statement
executed. This function does not return alarm information; use
read_test_status_alarm().
ARGUMENTS None
RETURN VALUE -1, if called before first test statement was executed.
PASSED if last test passed.
FAILED if last test failed.
Both (PASSED | FAILED) if close (passed alternate limits).
read_test_status_alarm
Check if last test executed had an alarm.
SYNOPSIS int read_test_status_alarm()
DESCRIPTION Determines if the last test statement executed produced an
alarm.
ARGUMENTS None
RETURN VALUE TRUE if last test had an alarm, otherwise FALSE
read_tjd_sample_count
Read the count of the captured samples in TJD stamp_a and stamp_b.
SYNOPSIS void read_tjd_sample_count(stamp_a, stamp_b)
int *stamp_a;
int *stamp_b;
DESCRIPTION Returns the count of the captured samples in the Time-Jitter
Digitizer Stamp A and Stamp B in the respective pointers
provided, stamp_a and stamp_b, by first waiting for the current
capture activity to complete or time out.
ARGUMENTS stamp_a—Pointer to return the capture count in TJD stamp a
stamp_b—Pointer to return the capture count in TJD stamp b
RETURN VALUES None
IMAGE Solutions V8.3 26-99
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_tjd_status
Return the status of the last Time-Jitter Digitizer capture.
SYNOPSIS int read_tjd_status()
DESCRIPTION Returns the status of the last Time-Jitter Digitizer (TJD) capture.
On a simulated system this function always returns that the
capture completed.
ARGUMENTS None
RETURN VALUE ERR_TJD_MEAS_COMPLETE—capture completed
ERR_TJD_A_MEAS_NOT_STARTED—A did not start
ERR_TJD_A_MEAS_NOT_COMPLETED—A did not finish
ERR_TJD_B_MEAS_NOT_STARTED—B did not start
ERR_TJD_B_MEAS_NOT_COMPLETED—B did not finish
ERR_TJD_AB_MEAS_NOT_STARTED—A and B did not start
ERR_TJD_AB_MEAS_NOT_COMPLETED—A and B did not finish
ERR_TJD_MEAS_A_NOT_STARTED_B_NOT_COMPLETED—A did not
start, B did not finish
ERR_TJD_MEAS_B_NOT_STARTED_A_NOT_COMPLETED—B did not
start, A did not finish
ERR_TJD_SET_SINCE_LAST_ARM—cannot move data from TJD
until after arming TJD
read_tset_num
Read back tset number of the given tset name.
SYNOPSIS int read_tset_num(tsetname, scm)
char *tsetname;
int scm;
DESCRIPTION This function takes a tset name and SCM and returns the tset
number for that tset name, or 0 if no number has yet been
assigned for that tset name on that SCM. A runtime error will
occur if the SCM number is illegal.
ARGUMENTS tsetname—ptr to tset name
scm—TL_FIRST_SCM or TL_SECOND_SCM
RETURN VALUE Tset number from 1 to 1023, or 0 if no number has been assigned
to that name.
read_uwport_one_port
Read calibrated UWPORT s-parameter.
SYNOPSIS void read_uwport_one_port(port, s_param, mag, arg)
int port;
IMAGE Solutions V8.3 26-100
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Reads the result of an UWPORT s-parameter measurement and
calibrates it using the data collected during standard calibration
and the de-embed file. s_param, mag, and arg can be NULL
pointers if their value is not desired.
ARGUMENTS port—pin name or number. Must do a
start uwport:ports = port
s_params:s11; before calling this function.
s_param—s11 in (real, imaginary) format.
mag—s11 magnitude
arg—s11 angle in degrees
RETURN VALUE None
SEE ALSO “read_uwport_raw_one_port”, “read_uwport_one_port_cal_std”
read_uwport_one_port_cal_std
S-parameter calibration.
SYNOPSIS int read_uwport_one_port_cal_std(pin, cal_std,
filename)
int pin;
TL_UWPORT_CAL_STD cal_std;
char *filename;
DESCRIPTION This function is used during s-parameter calibration with external
cal standards. It tells the UWPORT to interpret the last s-
parameter measurement as an s-parameter calibration
standard.
To calibrate the UWPORT:
- Connect the cal standard at the appropriate pin.
- Set up source and measure instruments (freq, amp, connect).
- Start UWPORT.
- read_uwport_two_port_cal_std() (both source and
measure connected to pin).
This is the same as any other one-port s-parameter
measurement except that the cal_std function is called instead
of a normal readback. IMAGE maintains all required information
for you.
The definition of the enumerated type TL_UWPORT_CAL_STD must
be loaded by adding the following statement to the header of
your .tl file:
#include <itlh/uwport_std_cal.h>
IMAGE Solutions V8.3 26-101
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
The one-port cal standards (open, short, and load) are
TL_UWPORT_CAL_OPEN, TL_UWPORT_CAL_SHORT, and
TL_UWPORT_CAL_LOAD. They can be attached to any pin at any
frequency in any order. IMAGE maintains this information for
you. As long as all three standards have been measured for the
desired frequency and amplitude when
read_uwport_one_port() is called, everything is calibrated. An
additional constraint is that the termination provided by the
source connection must also be the same. That is, if you
calibrate by connecting source1 through the add path, the driver
will complain that it does not have cal data if you do try to make
a measurement using source2. This assumes you did not do a
separate calibration with source2.
Describe each standard by a .s1p file. If you do not provide the
.s1p file for all standards, the standards are assumed to be
ideal.
If you are using DIB switching, each pin must be calibrated
separately. All pins on a single UWPORT channel (A, B, C, or D)
must be calibrated using this function if any of them is. You can
use the internal cal standards (UWPORT 949-310-12 and later)
for some UWPORT channels and external standards for others.
For 2-port calibration, see
“read_uwport_two_port_cal_std_forward” for information on
TL_UWPORT_CAL_THRU and TL_UWPORT_CAL_ISOLATE.
This function partially replaces
tl_uwport_std_cal_one_port() which was replaced because
it did not record the terminations within the UWPORT which were
used with each standard measurement.
This can introduce error if measurements were made with the
hardware set up differently from the way calibration was
performed. (The most likely case is calibrating with source1
through add path then using source2 to perform the actual
measurement or vice versa. The frequency, amplitude, and
slot/schan numbers are the same for both, so the driver cannot
apply the correct cal factors.) This new calibration strategy does
not require you to keep track of the arrays of raw s-parameter
measurements. It should be easier to use and more robust.
ARGUMENTS pin—pin with cal standard connected to it
cal_std—TL_UWPORT_CAL_OPEN, TL_UWPORT_CAL_SHORT,
TL_UWPORT_CAL_LOAD
filename—.s1p file describing cal standards
RETURN VALUE 0 if OK
-1 if error
IMAGE Solutions V8.3 26-102
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “read_uwport_two_port_cal_std_forward”,
“read_uwport_two_port_cal_std_reverse”,
“read_uwport_one_port_cal_std_slot”, “read_uwport_one_port”,
“tl_uwport_dump_port”, “tl_uwport_dump_1port”
read_uwport_one_port_cal_std_slot
S-parameter calibration.
SYNOPSIS int read_uwport_one_port_cal_std_slot(slot, schan,
cal_std, filename)
int slot, schan;
TL_UWPORT_CAL_STD cal_std;
char *filename;
DESCRIPTION This function is used for s-parameter calibration with external cal
standards. For a complete description, see
“read_uwport_one_port_cal_std”. The difference between these
functions is that slot and schan should be substituted for pin.
DIB switching is not supported for slot programming.
ARGUMENTS slot—UWPORT slot
schan—UWPORT schan
cal_std—one of TL_UWPORT_CAL_OPEN,
TL_UWPORT_CAL_SHORT, or TL_UWPORT_CAL_LOAD
filename—name of .s1p file which characterizes the standard
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_one_port_slot”, “read_uwport_one_port_cal_std”,
“read_uwport_two_port_cal_std_forward”,
“read_uwport_two_port_cal_std_reverse”, “tl_uwport_dump”,
“tl_uwport_dump_1port”
read_uwport_one_port_slot
Read calibrated s-parameter.
SYNOPSIS void read_uwport_one_port_slot (slot, schan,
s_param,
mag, arg)
int slot, schan;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Reads the result of an s-parameter measurement and calibrates
it using the data collected during standard calibration and the de-
embed file. s_param, mag, and arg can be NULL pointers if their
value is not desired.
IMAGE Solutions V8.3 26-103
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS slot, schan—UWPORT slot and schan numbers
s_param—s11 in (real, imaginary) format.
mag—magnitude of s11
arg—angle of s11 in degrees
RETURN VALUE None
SEE ALSO “read_uwport_raw_one_port”
read_uwport_raw_one_port
Read uncalibrated s-parameter.
SYNOPSIS void read_uwport_raw_one_port(port, s_param, mag,
arg)
int port;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Reads the result of an s-parameter measurement without doing
any calibration. Uncalibrated results are typically not very useful
themselves, but they are required for doing calibration with
external cal standards.
s_param, mag, and arg can be set to NULL for any value that is
not desired.
ARGUMENTS port—pin name or number; must do a start uwport:ports=
port s_params:s11; before calling this function.
s_param—s11 in (real, imaginary) format
mag—magnitude of s11
arg—angle of s11 in degrees
RETURN VALUE None
SEE ALSO “read_uwport_one_port”
read_uwport_raw_one_port_slot
Read uncalibrated s-parameter.
SYNOPSIS void read_uwport_raw_one_port_slot(slot, schan,
s_param, mag, arg)
int slot, schan;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Reads the result of an s-parameter measurement without doing
any calibration. Uncalibrated results are typically not very useful
themselves, but they are required for doing calibration with
external cal standards.
IMAGE Solutions V8.3 26-104
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
s_param, mag, and arg can be set to NULL for any value that is
not desired.
ARGUMENTS slot, schan—UWPORT slot and schan
s_param—s11 in (real, imaginary) format
mag—magnitude of s11
arg—angle of s11 in degrees
RETURN VALUE None
SEE ALSO “read_uwport_raw_one_port”, “read_uwport_one_port_slot”,
“read_uwport_one_port_cal_std_slot”
read_uwport_raw_two_port_s11
Raw s11 readback function (2-port).
SYNOPSIS int read_uwport_raw_two_port_s11(pin1, pin2,
s_param, mag, arg)
int pin1, pin2;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION This function reads back the uncalibrated value of s11. It can
only be called after a start uwport: ports= (A, B)
s_params:forward; statement. s11 is the coefficient of
reflection of pin A.
NOTE
Binning on this value is not likely to be useful since it is a very strong function of the test
head hardware and the DIB, dutcard, and socket or probe you are using. Use the calibrated
readback functions instead.
Any of s_param, mag, and arg can be NULL pointers if you do not
need to have their value returned.
ARGUMENTS pin1—A from the example in the description
pin2—B from the example in the description
s_param—s-parameter in (real, imaginary) format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s11”
IMAGE Solutions V8.3 26-105
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_uwport_raw_two_port_s11_slot
Uncalibrated s11 readback.
SYNOPSIS int read_uwport_raw_two_port_s11_slot(slot1, schan1,
slot2, schan2, s_param, mag, arg)
int slot1, schan1, slot2, schan2; D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Same as read_uwport_raw_two_port_s11() except slot1 and
schan1 replace pin1 and slot2 and schan2 replace pin2.
start uwport:
port_slots = (slot1, slot2)
port_schans = (schan1, schan2)
s_params: forward;
ARGUMENTS slot1—First slot in port_slots=(slot1,slot2)
schan1—First schan in port_schans=(schan1, schan2)
slot2—Second slot in port_slots=(slot1, slot2)
schan2—Second schan in port_schans=(schan1, schan2)
s_param—s-parameter in D_COMPLEX (real, imaginary) format
mag—Magnitude of s_param
arg—Angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_raw_two_port_s11”,
“read_uwport_two_port_cal_std_forward_slot”
read_uwport_raw_two_port_s12
Raw s12 readback function (2-port).
SYNOPSIS int read_uwport_raw_two_port_s12(pin1, pin2,
s_param, mag, arg)
int pin1, pin2;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION This function reads back the uncalibrated value of s12. It can
only be called after a start uwport: ports= (A, B)
s_params:reverse; statement. s12 is the reverse isolation or
gain from B to A.
NOTE
Binning on this value is not likely to be useful since it is a very strong function of the test
head hardware and the DIB, dutcard, and socket or probe you are using. Use the calibrated
readback functions instead.
IMAGE Solutions V8.3 26-106
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Any of s_param, mag, and arg can be NULL pointers if you do not
need to have their value returned.
ARGUMENTS pin1—A from the example in the description
pin2—B from the example in the description
s_param—s-parameter in (real, imaginary) format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s12”
read_uwport_raw_two_port_s12_slot
Uncalibrated s12 readback.
SYNOPSIS int read_uwport_raw_two_port_s12_slot(slot1, schan1,
slot2, schan2, s_param, mag, arg)
int slot1, schan1, slot2, schan2; D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Same as read_uwport_raw_two_port_s12() except slot1
and schan1 replace pin1 and slot2 and schan2 replace pin2.
Corresponding start statement:
start uwport:
port_slots = (slot1, slot2)
port_schans = (schan1, schan2)
s_params: forward;
ARGUMENTS slot1—First slot in port_slots=(slot1, slot2)
schan1—First schan in port_schans=(schan1,schan2)
slot2—Second slot in port_slots=(slot1, slot2)
schan2—Second schan in port_schans=(schan1, schan2)
s_param—s-parameter in D_COMPLEX (real, imaginary) format
mag—Magnitude of s_param
arg—Angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_raw_two_port_s12”,
“read_uwport_two_port_cal_std_forward_slot”
read_uwport_raw_two_port_s21
Raw s21 readback function (2-port).
SYNOPSIS int read_uwport_raw_two_port_s21(pin1, pin2,
s_param, mag, arg)
IMAGE Solutions V8.3 26-107
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int pin1, pin2;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION This function reads back the uncalibrated value of s21. It can
only be called after a start uwport: ports= (A, B)
s_params:forward; statement. s21 is the gain of the device
from A to B.
NOTE
Binning on this value is not likely to be useful since it is a very strong function of the test
head hardware and the DIB, dutcard, and socket or probe you are using. Use the calibrated
readback functions instead.
Any of s_param, mag, and arg can be NULL pointers if you do not
need to have their value returned.
ARGUMENTS pin1—A from the example in the description
pin2—B from the example in the description
s_param—s-parameter in (real, imaginary) format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s11”
read_uwport_raw_two_port_s21_slot
Uncalibrated s21 readback.
SYNOPSIS int read_uwport_raw_two_port_s21_slot(slot1, schan1,
slot2, schan2, s_param, mag, arg)
int slot1, schan1, slot2, schan2; D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Same as read_uwport_raw_two_port_s21() except slot1
and schan1 replace pin1 and slot2 and schan2 replace pin2.
Corresponding start statement:
start uwport:
port_slots = (slot1, slot2)
port_schans = (schan1, schan2)
s_params: forward;
ARGUMENTS slot1—first slot in port_slots=(slot1, slot2)
schan1—First schan in port_schans=(schan1, schan2)
slot2—Second slot in port_slots=(slot1, slot2)
IMAGE Solutions V8.3 26-108
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
schan2—Second schan in port_schans=(schan1, schan2)
s_param—s-parameter in D_COMPLEX (real, imaginary) format
mag—Magnitude of s_param
arg—Angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_raw_two_port_s21”,
“read_uwport_two_port_cal_std_forward_slot”
read_uwport_raw_two_port_s22
Raw s22 readback function (2-port).
SYNOPSIS int read_uwport_raw_two_port_s22(pin1, pin2,
s_param, mag, arg)
int pin1, pin2;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION This function reads back the uncalibrated value of s22. It can
only be called after a start uwport: ports= (A, B)
s_params:forward; statement. s22 is the coefficient of
reflection of pin B.
NOTE
Binning on this value is not likely to be useful since it is a strong function of the test head
hardware and the DIB, dutcard, and socket or probe you are using. Use the calibrated
readback functions instead.
Any of s_param, mag, and arg can be NULL pointers if you do not
need to have their value returned.
ARGUMENTS pin1—A from the example in the description
pin2—B from the example in the description
s_param—s-parameter in (real, imaginary) format
mag—Magnitude of s_param
arg—Angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s11”
read_uwport_raw_two_port_s22_slot
Uncalibrated s22 readback.
IMAGE Solutions V8.3 26-109
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int read_uwport_raw_two_port_s22_slot(slot1, schan1,
slot2, schan2, s_param, mag, arg)
int slot1, schan1, slot2, schan2; D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Same as “read_uwport_raw_two_port_s22” except slot1 and
schan1 replace pin1 and slot2 and schan2 replace pin2.
Corresponding start statement:
start uwport:
port_slots = (slot1, slot2)
port_schans = (schan1, schan2)
s_params: forward;
ARGUMENTS slot1—First slot in port_slots=(slot1, slot2)
schan1—First schan in port_schans=(schan1, schan2)
slot2—Second slot in port_slots=(slot1, slot2)
schan2—Second schan in port_schans=(schan1, schan2)
s_param—s-parameter in D_COMPLEX (real, imaginary)
format
mag—Magnitude of s_param
arg—Angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_raw_two_port_s11”,
“read_uwport_two_port_cal_std_forward_slot”
read_uwport_two_port_cal_std_forward
S-parameter calibration.
SYNOPSIS int read_uwport_two_port_cal_std_forward(pin1, pin2,
cal_std, filename)
int pin1, pin2;
TL_UWPORT_CAL_STD cal_std;
char *filename;
DESCRIPTION This function is used during s-parameter calibration with external
standards. (See the end of this description for the steps to take
to calibrate the UWPORT.) “Forward” is normally associated with
the source, while “reverse” refers to the DUT as the source.
This is the same as any other 2-port s-parameter measurement,
except that the cal_std function is called instead of a normal
readback. IMAGE maintains all required information for you.
The _forward and corresponding _reverse measurements can
be made in either order. Unlike the normal readback functions,
the frequencies do not have to be done in pairs. (That is, normal
s-parameter measurements require the same frequency to be
IMAGE Solutions V8.3 26-110
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
measured on both pins at the same time for the readback
function to work correctly. These two functions can be run
together or looped independently [steps 2, 3, 4 and 5, 6, 7 below]
if more convenient.) As with normal readback functions,
measurements of standards on different pins can be interleaved,
so long as the pins are not muxed off the same UWPORT
connection. (Measure pin A and pin B then read back pin A and
pin B, so long as pins A and B are not muxed off the same
UWPORT channel.)
The definition of the enumerated type TL_UWPORT_CAL_STD must
be loaded by adding the following statement to the header of
your .tl file:
#include <itlh/uwport_std_cal.h>
The two port standards are TL_UWPORT_CAL_THRU,
TL_UWPORT_CAL_ISOLATE, and
TL_UWPORT_CAL_ISOLATE_ONLY. Use
read_uwport_one_port_cal_std() for the open, short, and
load standards.
TL_UWPORT_CAL_THRU
The thru standard is a cable which goes from pin1 to pin2. The
.s2p file describing the thru should have s11 corresponding to
pin1.
If you do not specify a file for the thru standard, it is assumed you
are connecting the ends of the cables directly together.
TL_UWPORT_CAL_ISOLATE
TL_UWPORT_CAL_ISOLATE_ONLY
The isolation measurement is optional. Isolation within the
UWPORT is at the noise floor when the add path is off and may
still be insignificant when the add path is on. However,
characteristics of sockets and probe needles may make isolation
measurements essential.
If you do not do isolation cal, isolation is assumed to be perfect.
If you are calibrating for isolation, the isolate standard is
assumed to be a pair of loads. To avoid redundant
measurements, measurement of the cal standard on pin1 is also
be applied to the 1-port load standard measurement for pin1.
Specify the .s1p file corresponding to the load on pin1 for
filename. Load on pin2 is handled by:
read_uwport_two_port_cal_std_reverse().
If you are measuring isolation but do not want to use the same
load standards you use for 1-port s-parameter calibration, you
can use TL_UWPORT_CAL_ISOLATE_ONLY, which does not
assume the device is any particular standard and only makes an
IMAGE Solutions V8.3 26-111
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
isolation measurement. If you are using a short standard for your
isolation measurement, you can call:
read_uwport_one_port_cal_std(pin1, TL_UWPORT_CAL_SHORT,
"short_standard_filename.s1p")
after the 2-port start statement used for isolation. This avoids a
separate
start uwport: ports = pin1 s_params: s11
statement.
Two port calibration is not complete until 1-port calibration has
been done on both pins as well.
For quicker calibrations, measure the THRU standard before
measuring the 1-port standards or isolation. This prevents a
redundant calibration of the internal 1-port standards. Making a
2-port measurement (using std_cal:automatic | immediate)
causes the internal THRU and 1-port standards to be measured,
even if the 1-port standards have been measured already.
To calibrate the UWPORT in the forward direction:
1. Connect the calibration standard at the appropriate pin of the DIB or thru hardware.
2. Set up source and measure instruments (freq, amp, connect; source connected to
pin1; measure connected to pin2).
3. Include the following lines in your test program (or issue them in the immediate mode
window):
start uwport: ports = (pin1, pin2)
s_params: forward;
4. Read the results by including the following line in your test program (or issuing it in the
immediate mode window):
read_uwport_two_port_cal_std_forward()
To calibrate the UWPORT in both directions, continue with the following (see
“read_uwport_two_port_cal_std_reverse”):
5. Change connections (source connected to pin2; measure connected to pin1).
6. Include the following lines in your test program (or in the immediate mode window):
start uwport: ports = (pin1, pin2)
s_params: reverse;
7. Read the results by including the following line in your test program (or issuing it in the
immediate mode window):
read_uwport_two_port_cal_std_reverse()
ARGUMENTS pin1—first pin in ports=(pin1, pin2)
pin2—second pin in ports=(pin1, pin2)
cal_std—TL_UWPORT_CAL_THRU, TL_UWPORT_CAL_ISOLATE,
TL_UWPORT_CAL_ISOLATE_ONLY
IMAGE Solutions V8.3 26-112
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
filename—Name of a .s2p file for the thru, .s1p for isolate,
ignored ("") for isolate only.
RETURN VALUE 0—OK
-1—Error
SEE ALSO “read_uwport_two_port_cal_std_reverse”,
“read_uwport_one_port_cal_std”,
“read_uwport_two_port_cal_std_forward_slot”,
“read_uwport_two_port_s11”
read_uwport_two_port_cal_std_forward_slot
S-parameter calibration.
SYNOPSIS int
read_uwport_two_port_cal_std_forward_slot(slot1,
schan1, slot2, schan2, cal_std, filename)
int slot1, schan1, slot2, schan2; TL_UWPORT_CAL_STD
cal_std;
char *filename;
DESCRIPTION This function is used during s-parameter calibration with external
standards.
This is the same as any other 2-port s-parameter measurement,
except that the cal_std function is called instead of a normal
readback. IMAGE maintains all required information for you.
The definition of the enumerated type TL_UWPORT_CAL_STD must
be loaded by adding the following statement to the header of
your .tl file:
#include <itlh/uwport_std_cal.h>
The two port standards are TL_UWPORT_CAL_THRU,
TL_UWPORT_CAL_ISOLATE, and
TL_UWPORT_CAL_ISOLATE_ONLY. Use
read_uwport_one_port_cal_std_slot() for the open, short,
and load standards.
TL_UWPORT_CAL_THRU
The thru standard is a cable which goes from slot1, schan1 to
slot2, schan2. The .s2p file describing the thru should have s11
corresponding to slot1, schan1.
If you do not specify a file for the thru standard, it is assumed you
are connecting the ends of the cables directly together.
TL_UWPORT_CAL_ISOLATE
TL_UWPORT_CAL_ISOLATE_ONLY
The isolation measurement is optional. Isolation within the
UWPORT is at the noise floor when the add path is off and still
IMAGE Solutions V8.3 26-113
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
not too bad when the add path is on. However, characteristics of
sockets and probe needles may make isolation measurements
essential. If you do not do isolation cal, isolation is assumed to
be perfect.
If you are calibrating for isolation with TL_UWPORT_CAL_ISOLATE,
the isolate standard is assumed to be a pair of loads. For
convenience, the measurement of the cal standard on slot1,
schan1 is also applied to the 1-port load standard measurement.
Specify the .s1p file corresponding to the load on slot1, schan1.
(Load on slot2, schan2 is handled by
read_uwport_two_port_cal_std_reverse_slot().)
If you are measuring isolation but do not want to use the same
load standards you use for 1-port s-parameter calibration, you
can use TL_UWPORT_CAL_ISOLATE_ONLY, which does not
assume the device is any particular standard and only makes an
isolation measurement. It does not matter what file you specify;
"" is fine. If you use 1-port standards, you can also call:
read_uwport_one_port_cal_std_slot(slot1, schan1, <std>, <std file>)
in addition to this 2-port function to avoid measuring the same
standard twice.
Two port calibration is not complete until 1-port calibration is
done on both pins as well.
For quicker calibrations, measure the THRU standard before
measuring the 1-port standards or isolation. This prevents a
redundant calibration of the internal 1-port standards. Making a
2-port measurement (using std_cal:automatic | immediate)
causes the internal THRU and 1-port standards to be measured,
even if the 1-port standards have been measured already.
To calibrate the UWPORT in the forward direction:
1. Connect the calibration standard(s) at the appropriate slots and schans (source
connected to slot1, schan1 and measure connected to slot2, schan2).
2. Set up source and measure instruments (freq, amp, connect).
3. Include the following lines in your test program (or issue them in the immediate mode
window):
start uwport:
port_slots=(slot1,slot2)
port_port_schans=(schan1,schan2)
s_params: forward;
4. Read the results by including the following line in your test program (or issuing it in the
immediate mode window):
read_uwport_two_port_cal_std_forward_slot()
IMAGE Solutions V8.3 26-114
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
To calibrate the UWPORT in both directions, continue with the following (see
“read_uwport_two_port_cal_std_reverse_slot”):
5. Change the connection (source connected to slot2, schan2; measure connected to
slot1, schan1).
6. Include the following lines in your test program (or issue them in the immediate mode
window):
start uwport:
port_slots=(slot1,slot2)
port_port_schans=(schan1,schan2)
s_params: reverse;
7. Read the results by including the following line in your test program (or issuing it in the
immediate mode window):
read_uwport_two_port_cal_std_reverse_slot()
ARGUMENTS slot1—first slot in port_slots=(slot1,slot2)
schan1—first schan in port_schans=(schan1, schan2)
slot2—second slot in port_slots=(slot1, slot2)
schan2—second schan in port_schans=(schan1, schan2)
cal_std—TL_UWPORT_CAL_THRU, TL_UWPORT_CAL_ISOLATE,
TL_UWPORT_CAL_ISOLATE_ONLY
filename—name of a .s2p file for the thru, .s1p for isolate,
ignored ("") for isolate only
RETURN VALUE 0—OK
-1—Error
SEE ALSO “read_uwport_one_port_cal_std_slot”,
“read_uwport_two_port_cal_std_forward”,
“read_uwport_two_port_s11_slot”
read_uwport_two_port_cal_std_reverse
S-parameter calibration.
SYNOPSIS int read_uwport_two_port_cal_std_reverse(pin1, pin2,
cal_std, filename)
int pin1, pin2;
TL_UWPORT_CAL_STD cal_std;
char *filename;
DESCRIPTION This function is used during s-parameter calibration with external
standards. For more information, see
read_uwport_two_port_cal_std_forward().
The difference between these functions is that this function
should be called when the source is connected to pin2 and the
measure is connected to pin1.
One effect of this is that when measuring isolation, the coefficient
of reflection of the isolate standard on pin2 is interpreted as a
IMAGE Solutions V8.3 26-115
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
load standard and filename should be filled in with the
appropriate .s1p file.
The thru standard should still be connected from pin1 to pin2 and
the .s2p file that describes it should still have s11 refer to pin1
as for the forward function.
To calibrate the UWPORT in the reverse direction:
1. Connect the calibration standard at the appropriate pin of the DIB or thru hardware.
2. Set up source and measure instruments (freq, amp, connect; source connected to
pin2; measure connected to pin1).
3. Include the following lines in your test program (or issue them in the immediate mode
window):
start uwport: ports = (pin1, pin2)
s_params: reverse;
4. Read the results by including the following line in your test program (or issuing it in the
immediate mode window):
read_uwport_two_port_cal_std_reverse()
To calibrate the UWPORT in both directions, continue with the following (see
“read_uwport_two_port_cal_std_forward”):
5. Change connections (source connected to pin1; measure connected to pin2).
6. Include the following lines in your test program (or in the immediate mode window):
start uwport: ports = (pin1, pin2)
s_params: forward;
7. Read the results by including the following line in your test program (or issuing it in the
immediate mode window):
read_uwport_two_port_cal_std_forward()
ARGUMENTS pin1—first pin in ports=(pin1, pin2)
pin2—second pin in ports=(pin1, pin2)
cal_std—TL_UWPORT_CAL_THRU, TL_UWPORT_CAL_ISOLATE,
TL_UWPORT_CAL_ISOLATE_ONLY
filename—name of a .s2p file for the thru, .s1p for isolate,
ignored ("") for isolate only.
RETURN VALUE 0—OK
-1—Error
SEE ALSO “read_uwport_one_port_cal_std_slot”,
“read_uwport_two_port_cal_std_reverse”,
“tl_uwport_dump_port”
“tl_uwport_dump_1port”
read_uwport_two_port_cal_std_reverse_slot
S-parameter calibration.
IMAGE Solutions V8.3 26-116
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int
read_uwport_two_port_cal_std_reverse_slot(slot1,
schan1, slot2, schan2, cal_std, filename)
int slot1, schan1, slot2, schan2; TL_UWPORT_CAL_STD
cal_std;
char *filename;
DESCRIPTION This function is used during s-parameter calibration with external
standards. For more information, see
read_uwport_two_port_cal_std_forward_slot().
The difference between these functions is that this function
should be called when the source is connected to slot2 schan2
and the measure is connected to slot1 schan1.
One effect of that is that when measuring isolation, the
coefficient of reflection of the isolate standard on slot2 schan2 is
interpreted as a load standard and filename should be filled in
with the appropriate .s1p file for TL_UWPORT_CAL_ISOLATE.
TL_UWPORT_CAL_ISOLATE_ONLY does not require a .s1p file. (""
is fine.)
The thru standard should still be connected from slot1 schan1 to
slot2 schan2 and the .s2p file that describes it should still have
s11 refer to slot1 schan1 as with the forward function.
To calibrate the UWPORT in the reverse direction:
1. Connect the calibration standard(s) at the appropriate slots and schans (source
connected to slot2, schan2 and measure connected to slot1, schan1).
2. Set up source and measure instruments (freq, amp, connect).
3. Include the following lines in your test program (or issue them in the immediate mode
window):
start uwport:
port_slots=(slot1,slot2)
port_port_schans=(schan1,schan2)
s_params: reverse;
4. Read the results by including the following line in your test program (or issuing it in the
immediate mode window):
read_uwport_two_port_cal_std_reverse_slot()
To calibrate the UWPORT in both directions, continue with the following (see
“read_uwport_two_port_cal_std_forward_slot”):
5. Change the connection (source connected to slot1, schan1; measure connected to
slot2, schan2).
6. Include the following lines in your test program (or issue them in the immediate mode
window):
start uwport:
port_slots=(slot1,slot2)
IMAGE Solutions V8.3 26-117
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
port_port_schans=(schan1,schan2)
s_params: forward;
7. Read the results by including the following line in your test program (or issuing it in the
immediate mode window):
read_uwport_two_port_cal_std_forward_slot()
ARGUMENTS slot1—first slot in port_slots=(slot1,slot2)
schan1—first schan in port_schans=(schan1, schan2)
slot2—second slot in port_slots=(slot1, slot2)
schan2—second schan in port_schans=(schan1, schan2)
cal_std—TL_UWPORT_CAL_THRU, TL_UWPORT_CAL_ISOLATE,
TL_UWPORT_CAL_ISOLATE_ONLY
filename—name of a .s2p file for the thru, .s1p for isolate,
ignored ("") for isolate only
RETURN VALUE 0—OK
-1—Error
SEE ALSO “read_uwport_one_port_cal_std_slot”,
“read_uwport_two_port_cal_std_reverse”, “tl_uwport_dump”,
“tl_uwport_dump_1port”
read_uwport_two_port_s11
Calibrated s11 readback.
SYNOPSIS int read_uwport_two_port_s11(pin1, pin2, s_param,
mag, arg)
int pin1, pin2;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION This function returns the calibrated value of s11. s11 is the
coefficient of reflection for pin A when measured during a start
statement like this:
start uwport:
ports = (A, B)
s_params: forward;
Terminations of both ports are taken into account, so both the
forward and reverse measurements must be made before this
function is called.
Any of s_param, mag, and arg can be NULL pointers if you do not
need to have their value returned.
ARGUMENTS pin1—A in the example
pin2—B in the example
s_param—s11 in D_COMPLEX (real, imaginary) format
mag—magnitude of s_param
arg—angle (argument) of s_param
IMAGE Solutions V8.3 26-118
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s21”,
“read_uwport_two_port_cal_std_forward”,
“read_uwport_raw_two_port_s11”, “read_uwport_one_port”,
“tl_uwport_dump_port”, “tl_uwport_dump_1port”
read_uwport_two_port_s11_slot
Calibrated s11 readback.
SYNOPSIS int read_uwport_two_port_s11_slot(slot1, schan1,
slot2, schan2, s_param, mag, arg)
int slot1, schan1, slot2, schan2; D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Same as read_uwport_two_port_s11() except slot1 and
schan1 replace pin1 and slot2 and schan2 replace pin2.
Corresponding start statement:
start uwport:
port_slots = (slot1, slot2)
port_schans = (schan1, schan2)
s_params: forward;
Both forward and reverse start statements must be made before
this function can be called.
ARGUMENTS slot1—first slot in port_slots=(slot1,slot2)
schan1—first schan in port_schans=(schan1, schan2)
slot2—second slot in port_slots=(slot1, slot2)
schan2—second schan in port_schans=(schan1, schan2)
s_param—s-parameter in D_COMPLEX (real, imaginary)
format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_cal_std_forward_slot”,
“tl_uwport_dump_port”, “tl_uwport_dump_1port”
read_uwport_two_port_s12
Calibrated s12 readback.
SYNOPSIS int read_uwport_two_port_s12(pin1, pin2, s_param,
mag, arg)
int pin1, pin2;
IMAGE Solutions V8.3 26-119
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION This function returns the calibrated value of s12. s12 is the
reverse isolation of the device (gain from B to A) when measured
during a start statement like this:
start uwport:
ports = (A, B)
s_params: reverse;
Terminations of both ports are taken into account so both the
forward and reverse measurements must be made before this
function is called.
Any of s_param, mag, and arg can be NULL pointers if you do not
need to have their value returned.
ARGUMENTS pin1—A in the example
pin2—B in the example
s_param—s-parameter in D_COMPLEX (real, imaginary) format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s11”,
“read_uwport_two_port_cal_std_forward”,
“read_uwport_two_port_s12”, “read_uwport_one_port”
read_uwport_two_port_s12_slot
Calibrated s12 readback.
SYNOPSIS int read_uwport_two_port_s12_slot(slot1, schan1,
slot2, schan2, s_param, mag, arg)
int slot1, schan1, slot2, schan2; D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Same as read_uwport_two_port_s12() except slot1 and
schan1 replace pin1 and slot2 and schan2 replace pin2.
Corresponding start statement:
start uwport:
port_slots = (slot1, slot2)
port_schans = (schan1, schan2)
s_params: forward;
Both forward and reverse start statements must be made before
this function can be called.
ARGUMENTS slot1—first slot in port_slots=(slot1, slot2)
schan1—first schan in port_schans=(schan1, schan2)
IMAGE Solutions V8.3 26-120
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
slot2—second slot in port_slots=(slot1, slot2)
schan2—second schan in port_schans=(schan1, schan2)
s_param—s-parameter in D_COMPLEX (real, imaginary)
format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s12”,
“read_uwport_two_port_cal_std_reverse_slot”,
“tl_uwport_dump”, “tl_uwport_dump_1port”
read_uwport_two_port_s21
Calibrated s21 readback.
SYNOPSIS int read_uwport_two_port_s21(pin1, pin2, s_param,
mag, arg)
int pin1, pin2;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION This function returns the calibrated value of s21. s21 is the
reverse isolation of the device (gain from B to A) when measured
during a start statement like this:
start uwport:
ports = (A, B)
s_params: forward;
Terminations of both ports are taken into account so both the
forward and reverse measurements must be made before this
function is called.
Any of s_param, mag, and arg can be NULL pointers if you do not
need to have their value returned.
ARGUMENTS pin1—A in the example
pin2—B in the example
s_param—s-parameter in D_COMPLEX(real, imaginary)
format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s11”,
“read_uwport_two_port_cal_std_forward”,
“read_uwport_raw_two_port_s21”, “read_uwport_one_port”,
“tl_uwport_dump_port”, “tl_uwport_dump_1port”
IMAGE Solutions V8.3 26-121
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_uwport_two_port_s21_slot
Calibrated s21 readback.
SYNOPSIS int read_uwport_two_port_s21_slot(slot1, schan1,
slot2, schan2, s_param, mag, arg)
int slot1, schan1, slot2, schan2; D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Same as read_uwport_two_port_s21() except slot1 and
schan1 replace pin1 and slot2 and schan2 replace pin2.
Corresponding start statement:
start uwport:
port_slots = (slot1, slot2)
port_schans = (schan1, schan2)
s_params: forward;
Both forward and reverse start statements must be made
before this function can be called.
ARGUMENTS slot1—first slot in port_slots=(slot1, slot2)
schan1—first schan in port_schans=(schan1, schan2)
slot2—second slot in port_slots=(slot1, slot2)
schan2—second schan in port_schans=(schan1, schan2)
s_param—s-parameter in D_COMPLEX(real, imaginary)
format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s21”,
“read_uwport_two_port_cal_std_forward_slot”,
“tl_uwport_dump_port”, “tl_uwport_dump_1port”
read_uwport_two_port_s22
Calibrated s22 readback.
SYNOPSIS int read_uwport_two_port_s22(pin1, pin2, s_param,
mag, arg)
int pin1, pin2;
D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION This function returns the calibrated value of s22. s22 is the
coefficient of reflection for pin B measured during a start
statement like this:
IMAGE Solutions V8.3 26-122
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
start uwport:
ports = (A, B)
s_params: reverse;
Terminations of both ports are taken into account so both the
forward and reverse measurements must be made before this
function is called.
Any of s_param, mag, and arg can be NULL pointers if you do not
need to have their value returned.
ARGUMENTS pin1—A in the example
pin2—B in the example
s_param—s-parameter in D_COMPLEX(real, imaginary)
format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_two_port_s11”,
“read_uwport_two_port_cal_std_forward”,
“read_uwport_raw_two_port_s12”, “read_uwport_one_port”,
“tl_uwport_dump_port”, “tl_uwport_dump_1port”
read_uwport_two_port_s22_slot
Calibrated s22 readback.
SYNOPSIS int read_uwport_two_port_s22_slot(slot1, schan1,
slot2, schan2, s_param, mag, arg)
int slot1, schan1, slot2, schan2; D_COMPLEX *s_param;
double *mag, *arg;
DESCRIPTION Same as read_uwport_two_port_s22() except slot1 and
schan1 replace pin1 and slot2 and schan2 replace pin2.
Corresponding start statement:
start uwport:
port_slots = (slot1, slot2)
port_schans = (schan1, schan2)
s_params: reverse;
Both forward and reverse start statements must be made
before this function can be called.
ARGUMENTS slot1—first slot in port_slots=(slot1, slot2)
schan1—first schan in port_schans=(schan1, schan2)
slot2—second slot in port_slots=(slot1, slot2)
schan2—second schan in port_schans=(schan1, schan2)
s_param—s-parameter in D_COMPLEX(real, imaginary)
IMAGE Solutions V8.3 26-123
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
format
mag—magnitude of s_param
arg—angle (argument) of s_param
RETURN VALUE 0 if OK
-1 if error
SEE ALSO “read_uwport_raw_two_port_s22”,
“read_uwport_two_port_cal_std_reverse_slot”,
“tl_uwport_dump_port”, “tl_uwport_dump_1port”
read_uwrecv_amp
Calibrated UWRECV amplitude readback.
SYNOPSIS double read_uwrecv_amp(pin, f_rf)
int pin;
double f_rf;
DESCRIPTION Reads the calibrated amplitude of the f_rf component of the
signal captured by a start uwrecv statement. This function
assumes that the UWRECV IF spectrum corresponds directly
with the RF spectrum. The IF spectrum, however, is actually
reversed because the UWMM always uses a high side LO
(unless spur aversion is on). This means that when f_rf is not
equal to the UWRECV freq setting, you must adjust f_rf to get
the correct result. The relationship is:
f_rf = 2 * freq - f_interest
where:
f_rf = frequency we claim is going into UWRECV
freq = UWRECV freq parameter (set statements, rfdisp)
f_interest = the frequency coming out of the device you want
to read back
For information about the relationship between the RF, IF, and
LO, see “read_uwrecv_amp_byif”.
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
f_rf—frequency of interest going into UWRECV (Hz)
RETURN VALUE Calibrated amplitude of signal at f_rf
SIDE EFFECTS Clobbers digital capture if needs to calibrate.
SEE ALSO “read_uwrecv_amp_byif”, “read_uwrecv_amp_slot”,
“read_uwrecv_uncal_amp”, “read_uwrecv_cal_const”
read_uwrecv_amp_array
Read back calibrated power measurements.
IMAGE Solutions V8.3 26-124
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int read_uwrecv_amp_array(pin, num_freqs, rf_freqs,
results)
int pin;
int num_freqs;
double rf_freqs[];
double results[];
DESCRIPTION Reads back the calibrated power measurement at the given
array of RF frequencies for the specified pin. This routine
correctly handles the effects of IF spectrum reversal, and further,
compared to the iterated calls of read_uwrecv_amp(), it is
optimized to handle multiple frequency points by eliminating the
redundant capture data movement involved in the repeated calls
of read_uwrecv_amp().
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
rf_freqs— Array of RF freqs to read back on
results— Array to return the results in
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SIDE EFFECTS None
SEE ALSO read_uwrecv_pwr(), read_uwrecv_amp()
read_uwrecv_amp_array_slot
Read back calibrated power measurements.
SYNOPSIS int read_uwrecv_amp_array_slot(slot, schan,
num_freqs, rf_freqs, results)
int slot;
int schan;
int num_freqs;
double rf_freqs[];
double results[];
DESCRIPTION Slot version of read_uwrecv_amp_array()
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan— UWRECV (UWMM) or UWPORT schan
num_freqs— Number of valid rf freqs in the array, rf_freqs[]
rf_freqs— Array of rf freqs
results—Array to return the results in
RETURN VALUE Number OF rf freqs successfully processed or -1 for a run-time
error
SIDE EFFECTS None
SEE ALSO read_uwrecv_amp_array(), read_uwrecv_amp_slot()
IMAGE Solutions V8.3 26-125
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_uwrecv_amp_byif
Read amplitude for IF freq.
SYNOPSIS double read_uwrecv_amp_byif (pin, f_if)
int pin;
double f_if;
DESCRIPTION Reads back a calibrated amplitude from the UWRECV for the
specified IF. The UWRECV must be started before this function
is called to load the capture into digital capture. If the UWRECV
has not been used for a calibrated readback with this setup
before (freq, if_freq, amp, dut connection, and so on) or if
level:immediate, the UWRECV calibrates itself, clobbering
digital capture in the process. This means you cannot use
multiple calibrated read statements one after the other unless
you know that the cal constants have already been obtained. (To
avoid this problem, call read_uwrecv_cal_const() for each
frequency of interest before doing the start and set
level:automatic.) Also, because calibration happens here but
the capture happened in the start statement, the UWRECV
hardware state must not be changed between the start and
read_uwrecv_XXX() statements.
If the f_if you specify when calling this function is not the same
as the if_freq the UWRECV was set to in the last set
statement, you must know whether the IF spectrum is reversed
(high side LO) to determine what frequency a given RF signal will
be digitized at. If the IF spectrum is reversed, the formula is:
f_if = LO - f_rf
LO = freq + if_freq
where:
f_rf = frequency of interest from DUT (into UWMM)
f_if = downconverted f_rf (into digitizer)
freq = UWRECV freq parameter (programmed by user)
if_freq = UWRECV if_freq parameter (calibrated @ 1MHz)
Table 26-2 shows the relationship of frequency to RF and IF.
Table 26-2. Frequency, RF, and IF
freq if_freq RF IF
1 GHz 1 MHz 1 GHz + 100 kHz 1 MHz-100 kHz
1.0001 GHz 0.9 MHz
1 GHz 1 MHz 1 GHz 1 MHz
1 GHz 1 MHz 1 GHz-100 kHz 1 MHz + 100 kHz
0.9999 GHz 1.1 MHz
IMAGE Solutions V8.3 26-126
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Increasing RF frequency --> decreasing IF frequency.
If the IF spectrum is not reversed, the formula is:
f_if = LO + f_rf
LO = freq - if_freq
Increasing RF frequency --> increasing IF frequency.
tl_uwrecv_spectrum_reversed(pin) returns 1 if the first
formula is used and 0 if the second is used.
Currently, all hardware uses the first formula unless
spur_aversion:on. Turning spur aversion on does not
necessarily result in the second formula being used. Also, the
formulas used when spur aversion is on will change with future
hardware and software changes, so be sure to call
tl_uwrecv_spectrum_reversed() to decide which formula to
use.
ARGUMENTS pin—UWRECV or UWPORT pin
f_if—Frequency of downconverted signal as captured by
digitizer
RETURN VALUE Calibrated amplitude of captured signal at specified frequency
SIDE EFFECTS Clobbers digital capture if calibration happens
SEE ALSO “read_uwrecv_amp”, “tl_uwrecv_spectrum_reversed”,
“read_uwrecv_uncal_amp_byif”
read_uwrecv_amp_slot
Slot version of read_uwrecv_amp().
SYNOPSIS double read_uwrecv_amp_slot(slot, schan, f_rf)
int slot;
int schan;
double f_rf;
DESCRIPTION This function is the slot version of read_uwrecv_amp().
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
f_rf—RF frequency
RETURN VALUE Calibrated amplitude
SIDE EFFECTS Clobbers digital capture if calibration occurs
SEE ALSO “read_uwrecv_amp”, “read_uwrecv_uncal_amp_slot”,
“read_uwrecv_cal_const_slot”, “read_uwrecv_amp_slot_byif”
IMAGE Solutions V8.3 26-127
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_uwrecv_amp_slot_byif
Read calibrated amplitude.
SYNOPSIS double read_uwrecv_amp_slot_byif(slot, schan, f_if)
int slot;
int schan;
double f_if;
DESCRIPTION This function is the slot version of read_uwrecv_amp_byif().
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
f_if—frequency of signal as captured by digitizer
RETURN VALUE Calibrated amplitude of captured signal at specified frequency
SIDE EFFECTS Clobbers digital capture if calibration occurs
SEE ALSO “read_uwrecv_amp_byif”, “read_uwrecv_amp_slot”,
“read_uwrecv_amp_slot_byif”
read_uwrecv_cal_const
Return calibration constant used by Microwave Receiver.
SYNOPSIS double read_uwrecv_cal_const(uwrecv_pin, freq)
int uwrecv_pin;
double freq;
DESCRIPTION Return the calibration constant used by the specified Microwave
Receiver (UWRECV) for the last measurement of the specified
frequency.
ARGUMENTS pin—Pin of Microwave Receiver
freq—Frequency of signal measured by UWRECV
RETURN VALUE Double specifying calibration constant for last measurement with
specified UWRECV
SEE ALSO “read_uwrecv_cal_const_slot”
read_uwrecv_cal_const_array
Read back the Microwave Receiver calibration constants.
SYNOPSIS int read_uwrecv_cal_const_array(pin, num_freqs,
rf_freqs, cal_factors)
int pin;
int num_freqs;
double rf_freqs[];
double cal_factors[];
IMAGE Solutions V8.3 26-128
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Array version of read_uwrecv_cal_const(). Unlike the other
_array_ based functions, this function does not offer a
performance advantage over its single point version.
ARGUMENTS pin—Pin number
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
rf_freqs—Array of RF freqs
cal_factors—Array to return the cal factor in
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_cal_const”
read_uwrecv_cal_const_array_slot
Read back the power cal constants.
SYNOPSIS int read_uwrecv_cal_const_array_slot(slot, schan,
num_freqs, rf_freqs, cal_factors)
int slot;
int schan;
int num_freqs;
double rf_freqs[];
double cal_factors[];
DESCRIPTION Slot version of read_uwrecv_cal_const_array().
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
rf_freqs—Array of RF freqs
cal_factors—Array to return the cal factors in
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_cal_const”
read_uwrecv_cal_const_slot
Return calibration constant used by Microwave Receiver.
SYNOPSIS double read_uwrecv_cal_const_slot(slot, schan,
freq);
int slot;
int schan;
double freq;
DESCRIPTION Return calibration constant used by the specified Microwave
Receiver (UWRECV) for the last measurement of specified
frequency.
IMAGE Solutions V8.3 26-129
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS slot—Slot of UWRECV or UWPORT upstream of UWRECV
schan—Schan of UWRECV or UWPORT upstream of UWRECV
freq—Freq of signal measured by UWRECV
RETURN VALUE Double specifying calibration constant for last measurement with
the specified UWRECV
SEE ALSO “read_uwrecv_cal_const”
read_uwrecv_fs
Read back the fs a Microwave Receiver is using.
SYNOPSIS double read_uwrecv_fs(pin)
int pin;
DESCRIPTION Read back the fs a Microwave Receiver (UWRECV) is using.
ARGUMENTS pin—Pin the UWRECV is behind
RETURN VALUE fs a UWRECV is using
SEE ALSO “read_uwrecv_fs_slot”
read_uwrecv_fs_slot
Read back the fs a Microwave Receiver is using.
SYNOPSIS double read_uwrecv_fs_slot (slot, schan)
int slot;
int schan;
DESCRIPTION Read back the fs a Microwave Receiver (UWRECV) is using.
ARGUMENTS slot—Slot the UWRECV is in
schan—Schan of UWRECV
RETURN VALUE fs a UWRECV is using
SEE ALSO “read_uwrecv_fs”
read_uwrecv_if
Read back the if that a UWRECV is using.
SYNOPSIS double read_uwrecv_if(pin)
int pin;
DESCRIPTION Read back the if that a UWRECV is using.
ARGUMENTS pin—pin the UWRECV is behind
RETURN VALUE The if that a UWRECV is using
SEE ALSO “read_uwrecv_if_slot”
IMAGE Solutions V8.3 26-130
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_uwrecv_if_slot
Read back the if that a UWRECV is using.
SYNOPSIS double read_uwrecv_if_slot(slot, schan)
int slot;
int schan;
DESCRIPTION Readback the if that a UWRECV is using.
ARGUMENTS slot—slot the UWRECV is in
schan—schan of UWRECV
RETURN VALUE The if that a UWRECV is using, 0.0 if error
SEE ALSO “read_uwrecv_if”
read_uwrecv_phase_noise_PSD
Reads back the calibrated phase noise spectral density estimate.
SYNOPSIS double read_uwrecv_phase_noise_PSD(pin, offset_f,
num_avg)
int pin;
double offset_f;
int num_avg;
DESCRIPTION The last UWRECV capture is assumed to be the output of the
phase noise detector. The detector’s output is analyzed to
estimate the phase noise power spectral density at the given
offset frequency.
Then, the calibrated single side band phase noise PSD at the
given frequency is returned in the unit of dBc/Hz.
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
offset_f—Offset frequency of interest
num_avg—Number of PSD estimates to average; the captured
data will be divided into num_avg count of segments
RETURN VALUE Single Side Band phase noise PSD estimate in dBc/Hz or
HUGE_VAL if any errors
SEE ALSO “read_uwrecv_uncal_PSD_slot”
read_uwrecv_phase_noise_PSD_array
Reads back the calibrated phase noise PSD estimates.
SYNOPSIS int read_uwrecv_phase_noise_PSD_array(pin,
num_freqs, offset_freqs, results, num_avg)
int pin;
int num_freqs;
IMAGE Solutions V8.3 26-131
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
double offset_freqs[];
double results[];
int num_avg;
DESCRIPTION The last UWRECV capture is assumed to be the output of the
phase noise detector. The detector’s output is analyzed to
estimate the phase noise power spectral density at the given
array of offset frequencies.
Then, the calibrated single side band phase noise PSD at the
requested frequency points are returned in the array, results, in
the unit of dBc/Hz.
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
offset_freqs—Array of offset freqs of interest
results—Array to return the results in
num_avg—Number of avg
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_phase_noise_PSD”
read_uwrecv_phase_noise_PSD_array_slot
Reads back the calibrated phase noise PSD estimates.
SYNOPSIS int read_uwrecv_phase_noise_PSD_array_slot(slot,
schan, num_freqs, offset_freqs,results,
num_avg)
int slot;
int schan;
int num_freqs;
double offset_freqs[];
double results[];
double num_avg;
DESCRIPTION Slot version of read_uwrecv_phase_noise_PSD_array().
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
num_freqs—Number of valid rf freqs in the array, rf_freqs[]
offset_freqs—Array of offset freqs of interest
results—Array to return the results in
num_avg—Number of avg
RETURN VALUE Number of rf freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_uncal_PSD_array”)
IMAGE Solutions V8.3 26-132
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_uwrecv_phase_noise_PSD_slot
Reads back the calibrated phase noise spectral density estimate.
SYNOPSIS double read_uwrecv_phase_noise_PSD_slot(slot, schan,
offset_f, num_avg)
int slot, schan;
double offset_f;
int num_avg;
DESCRIPTION Slot version of read_uwrecv_phase_noise_PSD().
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
offset_f—Offset frequency of interest
num_avg—Number of PSD estimates to average; the captured
data will be divided into num_avg count of segments
RETURN VALUE Single Side Band phase noise PSD estimate in dBc/Hz
SEE ALSO “read_uwrecv_uncal_PSD_slot”
read_uwrecv_PSD
Reads back the calibrated power spectral density estimate.
SYNOPSIS double read_uwrecv_PSD(pin, f_rf, num_avg)
int pin;
double f_rf;
int num_avg;
DESCRIPTION Reads back an estimate of the calibrated power spectral density
at the specified RF freq, f_rf, in the unit of dBm/Hz. The
captured signal is assumed to be a realization of an ergodic and
stationary random process whose power spectral density is to be
estimated. The spectral estimation technique employed in this
function is through periodogram averaging; the captured signal
is first divided into num_avg number of non-overlapping
segments. Then, each segment generates an independent
estimate of the requested PSD. Finally, the average of all the
estimates is returned.
With a given sample data size, the choice of the number of
average results in the trade-off between the variance and the
bias of the estimate. Specifically, the variance is inversely
proportional to the number of averages whereas reduction of the
bias of the estimate requires maximizing the data samples in
each segment.
The technique employed in this function is most effective for
relatively smooth PSDs. For PSDs with sharp peaks, this
IMAGE Solutions V8.3 26-133
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
function would introduce significant distortion by smearing the
peaks.
The unit of dBm as the return value is based on the 50 ohm
impedance assumption which may not be applicable to certain
applications. In that case, convert it back to the unit of V^sq / Hz
as shown below:
V_sq = 50ohm*1.0mW*exp10(result/10.0);
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
f_rf—Frequency of interest going into UWRECV (Hz)
num_avg—Number of periodogram averages >= 1
RETURN VALUE Calibrated power spectral density estimate at f_rf or
HUGE_VAL for any errors
SIDE EFFECTS Clobbers cmem if needs to calibrate
SEE ALSO “read_uwrecv_uncal_PSD”, “read_uwrecv_cal_const”
read_uwrecv_PSD_array
Read back the calibrated power spectral density estimates.
SYNOPSIS int read_uwrecv_PSD_array(pin,num_freqs, rf_freqs,
results, num_avg)
int pin;
int num_freqs;
double rf_freqs[];
double results[];
int num_avg;
DESCRIPTION Reads back the calibrated power spectral density estimate at
each of the RF frequencies in the array, rf_freqs[]. Specify the
number of frequency points of interest in num_freqs.
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
rf_freqs—Array of RF freqs
results—Array to return the results in
num_avg—Number of avg
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_PSD_array”, “read_uwrecv_uncal_PSD”
read_uwrecv_PSD_array_slot
Read back the calibrated power spectral density.
IMAGE Solutions V8.3 26-134
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int read_uwrecv_PSD_array_slot(uwrecv_slot,
uwrecv_schan, num_freqs, rf_freqs, results,
num_avg)
int uwrecv_slot;
int uwrecv_schan;
int num_freqs;
double rf_freqs[];
double results[];
int num_avg;
DESCRIPTION Slot version of read_uwrecv_PSD_array().
ARGUMENTS uwrecv_slot—UWRECV (UWMM) or UWPORT slot
uwrecv_schan—UWRECV (UWMM) or UWPORT schan
num_freqs—Number of valid rf freqs in the array, rf_freqs[]
rf_freqs—Array of RF freqs
results—Array to return the results in
num_avg—Number of avg
RETURN VALUE Number of rf freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_uncal_PSD_array”,
“read_uwrecv_uncal_PSD_slot”
read_uwrecv_PSD_slot
Read the calibrated Power Spectral Density estimate.
SYNOPSIS double read_uwrecv_PSD_slot(slot, schan, f_rf,
num_avg)
int slot;
int schan;
double f_rf;
int num_avg;
DESCRIPTION Slot version of read_uwrecv_PSD().
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
f_rf—Frequency of interest going into UWRECV (Hz)
num_avg—Number of PSD estimates to average; the captured
data will be divided into num_avg count of segments
RETURN VALUE Calibrated power spectral density estimate in dBm/Hz
SEE ALSO “read_uwrecv_uncal_PSD”, “read_uwrecv_PSD_array”
read_uwrecv_sample_size
Read back the number of samples a Microwave Receiver is programmed to take.
IMAGE Solutions V8.3 26-135
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS double read_uwrecv_sample_size(pin)
int pin;
DESCRIPTION Read back the number of samples a Microwave Receiver
(UWRECV) is programmed to take.
ARGUMENTS pin—Pin the UWRECV is behind
RETURN VALUE Number of samples UWRECV programmed to take
SEE ALSO “read_uwrecv_sample_size_slot”
read_uwrecv_sample_size_slot
Read back the number of samples the UWRECV is programmed to take.
SYNOPSIS double read_uwrecv_sample_size_slot (slot, schan)
int slot;
int schan;
DESCRIPTION Read back the number of samples the Microwave Receiver
(UWRECV) is programmed to take.
ARGUMENTS slot—Slot the UWRECV is in
schan—Schan of the UWRECV
RETURN VALUE Number of samples the UWRECV is programmed to take.
SEE ALSO “read_uwrecv_sample_size”
read_uwrecv_uncal_amp
Read the uncalibrated RF amplitude.
SYNOPSIS double read_uwrecv_uncal_amp(pin, f_rf)
int pin;
double f_rf;
DESCRIPTION Reads back the uncalibrated amplitude of the f_rf Hz
component of the signal captured by the digitizer. See
“read_uwrecv_amp” for more information about f_rf.
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
f_rf—Frequency of interest from DUT
RETURN VALUE Uncalibrated amplitude
SEE ALSO “read_uwrecv_uncal_amp_slot”, “read_uwrecv_amp”,
“read_uwrecv_uncal_amp_slot_byif”
read_uwrecv_uncal_amp_array
Read back uncalibrated pwr.
IMAGE Solutions V8.3 26-136
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int read_uwrecv_uncal_amp_array(pin, num_freqs,
rf_freqs, results
int pin;
int num_freqs;
double rf_freqs[];
double results[];
DESCRIPTION Reads back the uncalibrated power measurement at the given
array of RF frequencies for the specified pin. This function
correctly handles the effects of IF spectrum reversal, and further,
compared to the iterated calls of read_uwrecv_uncal_amp(),
this function is optimized to handle multiple frequency points by
eliminating the redundant capture data movement involved in the
repeated calls of read_uwrecv_uncal_amp().
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
rf_freqs—Array of RF freqs to read back on
results—Array to return the results in
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_uncal_amp”
read_uwrecv_uncal_amp_array_slot
Read back uncalibrated power.
SYNOPSIS int read_uwrecv_uncal_array_slot(slot, schan,
num_freqs, rf_freqs, results)
int slot;
int schan;
int num_freqs;
double rf_freqs[];
double results[];
DESCRIPTION Slot version of read_uwrecv_uncal_amp_array().
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
rf_freqs—Array of RF freqs
results—Array to return the results in
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_uncal_amp_array”,
“read_uwrecv_uncal_amp_array_slot”
IMAGE Solutions V8.3 26-137
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
read_uwrecv_uncal_amp_byif
Read the uncalibrated amplitude at frequency.
SYNOPSIS double read_uwrecv_uncal_amp_byif(pin, f_if)
int pin;
double f_if;
DESCRIPTION Returns the uncalibrated amplitude of the f_if Hz component of
the signal captured during a start:UWRECV statement. See
“read_uwrecv_amp_byif” for a description of f_if.
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
f_if—Frequency of downconverted signal
RETURN VALUE Uncalibrated amplitude of signal at f_if
SEE ALSO “read_uwrecv_uncal_amp”, “read_uwrecv_amp”,
“read_uwrecv_uncal_amp_slot_byif”
read_uwrecv_uncal_amp_slot
Read the uncalibrated amplitude.
SYNOPSIS double read_uwrecv_uncal_amp_slot(slot, schan, f_rf)
int slot;
int schan;
double f_rf;
DESCRIPTION See “read_uwrecv_uncal_amp”.
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
f_rf—RF frequency
RETURN VALUE Uncalibrated amplitude
SEE ALSO “read_uwrecv_uncal_amp”, “read_uwrecv_amp_slot”,
“read_uwrecv_uncal_amp_slot_byif”
read_uwrecv_uncal_amp_slot_byif
Read the uncalibrated amplitude at frequency.
SYNOPSIS double read_uwrecv_uncal_amp_slot_byif(slot, schan,
f_if)
int slot, schan;
double f_if;
DESCRIPTION This function is the slot version of
read_uwrecv_uncal_amp_byif().
IMAGE Solutions V8.3 26-138
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
f_if—IF frequency
RETURN VALUE Uncalibrated amplitude of signal at f_if
SEE ALSO “read_uwrecv_uncal_amp_byif”, “read_uwrecv_amp”,
“read_uwrecv_uncal_amp_slot”
read_uwrecv_uncal_PSD
Read uncalibrated Power Spectral Density estimate.
SYNOPSIS double read_uwrecv_uncal_PSD(pin, f_rf, num_avg)
int pin;
double f_rf;
int num_avg;
DESCRIPTION Reads back an estimate of the uncalibrated power spectral
density at the specified RF freq, f_rf, in the unit of dBm/Hz. The
captured signal is assumed to be a realization of an ergodic and
stationary random process whose power spectral density is to be
estimated. The spectral estimation technique employed in this
function is through periodogram averaging; the captured signal
is first divided into num_avg number of non-overlapping
segments. Then, each segment generates an independent
estimate of the requested PSD. Finally, the average of all the
estimates is returned.
With a given sample data size, the choice of the number of
average results in the trade-off between the variance and the
bias of the estimate. Specifically, the variance is inversely
proportional to the number of averages whereas reduction of the
bias of the estimate requires maximizing the data samples in
each segment.
The technique employed in this function is most effective for
relatively smooth PSDs. For PSDs with sharp peaks, this
function would introduce significant distortion by smearing the
peaks.
The unit of dBm as the return value is based on the 50ohm
impedance assumption which may not be applicable to certain
applications. In that case, convert it back to the unit of V^sq / Hz
as shown below:
V_sq = 50ohm*1.0mW*exp10(result/10.0);
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
f_rf—Frequency of interest going into UWRECV (Hz)
num_avg—Number of PSD estimates to average; the captured
data will be divided into num_avg count of segments
IMAGE Solutions V8.3 26-139
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Calibrated power spectral density estimate in dBm/H
SEE ALSO “read_uwrecv_uncal_PSD_array”
read_uwrecv_uncal_PSD_array
Read uncalibrated Power Spectral Density estimates.
SYNOPSIS int read_uwrecv_uncal_PSD_array(pin, num_freqs,
rf_freqs, results, num_avg)
int pin;
int num_freqs;
double rf_freqs[];
double results[];
int num_avg;
DESCRIPTION Reads back the power spectral density estimate at each of the
RF frequencies in the array, rf_freqs[]. Specify the number of
frequency points of interest in num_freqs.
ARGUMENTS pin—UWRECV (UWMM) or UWPORT pin
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
rf_freqs—Array of RF freqs
results—Array to return the results in
num_avg—Number of avg
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_uncal_PSD”
read_uwrecv_uncal_PSD_array_slot
Read back uncalibrated Power Spectral Density.
SYNOPSIS int read_uwrecv_uncal_PSD_array_slot(uwrecv_slot,
uwrecv_schan, num_freqs, rf_freqs, results)
int uwrecv_slot;
int uwrecv_schan;
int num_freqs;
double rf_freqs[];
double results[];
int num_avg;
DESCRIPTION Slot version of read_uwrecv_uncal_PSD_array().
ARGUMENTS uwrecv_slot—UWRECV (UWMM) or UWPORT slot
uwrecv_schan—UWRECV (UWMM) or UWPORT schan
num_freqs—Number of valid RF freqs in the array, rf_freqs[]
rf_freqs—Array of RF freqs
results—Array to return the results in
num_avg—Number of avg
IMAGE Solutions V8.3 26-140
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Number of RF freqs successfully processed or -1 for a run-time
error
SEE ALSO “read_uwrecv_uncal_PSD_array”
read_uwrecv_uncal_PSD_slot
Read uncalibrated Power Spectral Density estimate.
SYNOPSIS double read_uwrecv_uncal_PSD_slot(slot, schan, f_rf,
num_avg)
int slot;
int schan;
double f_rf;
int num_avg;
DESCRIPTION Reads back an estimate of the uncalibrated power spectral
density at the specified RF freq, f_rf, in the unit of dBm/Hz. The
captured signal is assumed to be a realization of an ergodic and
stationary stochastic process whose power spectral density is to
be estimated. The PSD is estimated through the periodogram
averaging technique; the captured signal is first divided into
num_avg number of non-overlapping segments. Then, each
segment generates an independent estimate of the requested
PSD. Finally, the average of all the estimates is returned.
When measuring the signal to noise ratio of a sinusoid, first
measure the power of the sinusoid with read_uwrecv_amp(),
and then measure the noise floor with a _PSD_ function. As the
theory dictates, the power spectral density of a deterministic
sinusoid would be a very large value representing the infinite
magnitude of the dirac delta function at that frequency point.
With a given sample data size, the choice of the number of
average results in the trade-off between the variance and the
bias of the estimate.
The technique employed in this function is most effective for
relatively smooth PSDs. For PSDs with sharp peaks, this
function would introduce significant distortion by smearing the
peaks.
The unit of dBm as the return value is based on the 50ohm
impedance assumption which may not be applicable to certain
applications. In that case, convert it back to the unit of V^sq / Hz
as shown below:
V_sq = 50ohm*1.0mW*exp10(result/10.0);
ARGUMENTS slot—UWRECV (UWMM) or UWPORT slot
schan—UWRECV (UWMM) or UWPORT schan
f_rf—Frequency of interest going into UWRECV (Hz)
IMAGE Solutions V8.3 26-141
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
num_avg—Number of PSD estimates to average; the captured
data will be divided into num_avg count of segments
RETURN VALUE Uncalibrated power spectral density estimate in dBm/Hz or
HUGE_VAL in case of any errors
SEE ALSO “read_uwrecv_uncal_PSD”, “read_uwrecv_uncal_PSD_array”
read_vmcu
Driver function to read VMCU values.
SYNOPSIS double read_vmcu(vmcu_num, type, location, bplane)
int vmcu_num
enum Vmcu_data_type type;
int *location, bplane;
DESCRIPTION This function reads Video Memory and Control Unit (VMCU)
data from memory or other registers.
ARGUMENTS int vmcu_num—VMCU number
type:
TL_VMCU_PIXEL (read pixel)
TL_VMCU_MIN (read minimum value after minmax process)
TL_VMCU_MAX (read maximum value after minmax
process)
TL_VMCU_MEAN (read mean value after accumulate
process)
TL_VMCU_ACC (read accumulator value after accumulate
process)
TL_VMCU_COUNT (read counter after count process)
location—x-y coordinate array for pixel read.
bplane—bitplane for pixel read.
RETURN VALUE Value
smprintf
Print a formatted string to the summary report.
SYNOPSIS smprintf(fmt, arg, arg, ...)
char *fmt;
...
DESCRIPTION This function allows a formatted string to be written to the
summary report for the current lot. The calling convention for this
function is identical to printf(). For more information about this
function, “Writing to a Summary Report” on page 14-25.
ARGUMENTS Calling convention is identical to printf()
RETURN VALUE Same as printf()
IMAGE Solutions V8.3 26-142
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_add_datalog_output
Add an output stream to datalog.
SYNOPSIS int tl_add_datalog_output(unsigned int key...);
DESCRIPTION This function operates like the command datalog
-add_output. If datalogging is already set up and turned on, you
can add an output, such as an STDF file to the existing
datalogging. If datalogging is not already turned on, or if you
want to make a complete change to the datalog setup, use
tl_set_datalog(TL_DLG_ON, ...) instead.
Multiple streams can be added in one
tl_add_datalog_output() call.
This function must be called before the first device is tested.
Once the test program has run, calls to
tl_add_datalog_output() are rejected.
ARGUMENTS Variable number of arguments, generally in pairs <flag,
argument>. Arguments can be unsigned integer bit vectors,
unsigned integer arrays, or character strings. The entire
argument list must be terminated by NULL. For example
err_code = tl_add_datalog_output(TL_DLG_OUTPUT,
TL_DLG_O_STDF, NULL);
See tl_set_datalog() for a complete list of arguments. Only
the following arguments are valid for
tl_add_datalog_output():
TL_DLG_OUTPUT
TL_DLG_FILE_NAME
TL_DLG_STDF_NAME
TL_DLG_DWIN_DISP
RETURN VALUE 0—An error occurred, either connecting to the data server or the
arguments were incorrectly specified or testing has already
begun on this lot.
1—Success, the command line was correct and the command
was successfully processed.
SIDE EFFECTS Affects the state of datalog.
SEE ALSO “tl_set_datalog”,“tl_get_datalog”, “tl_remove_datalog_output”,
“tl_change_datalog”
tl_add_datastream
Enable a new data stream.
SYNOPSIS int tl_add_datastream(unsigned int key...);
IMAGE Solutions V8.3 26-143
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function is used to start new Datastream from the test
program; and should be used rather than calling the datastream
command processor with -on option from the test program using
the tl_system function.
If the data server is busy, that is processing data from the
previous test program run, this function will wait until the data
server is free.
Use of this function is similar to using the datastream command
processor with -on option; you must minimally specify the
stream_id the datastream criteria (passing, failing, all, and so
on). This function takes a variable number of arguments. The
arguments are of two types:
flags: Indicate what function the user is attempting to perform.
These are represented by macros. They are analagous to '-test',
'-samprate', '-file'. Some flags accept a value. Others may be
used by themselves.
values: These arguments are values to a particular flag and must
immediately follow the particular flag they are used with. The
values are of four types:
1. Unsigned integer array which is terminated by 0 (zero), that is
the last element is zero.
2. Unsigned integer bit vector.
3. NULL terminated character string.
4. Unsigned integer.
Note that none of the values can be equal to zero. Specifying
sample rate and sample limits of 0 effectively turns writing
datalog data to the output, but leaves all of the overhead. Test
lists and ranges cannot be zero.
Table 26-3 describes the macros used for flags and their values.
In the case of flags that accept bit vectors for arguments the
macros used are listed. In general, value macros cannot be used
as flags. Flags that have no corresponding entry in the Value
column may be used without arguments.
Table 26-3. Options and Values for tl_add_datastream
Flag Value
TL_DSTRM_ID char * (stream_id)
TL_DSTRM_LKG_PINS TL_DSTRM_LKG_ALL_PINS
TL_DSTRM_LKG_FAIL_PINS
IMAGE Solutions V8.3 26-144
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Table 26-3. Options and Values for tl_add_datastream (Continued)
Flag Value
TL_DSTRM_LKG_STATE TL_DSTRM_LKG_OFF
TL_DSTRM_LKG_ALL
TL_DSTRM_LKG_FAIL
TL_DSTRM_OPEN_SHORT_PINS TL_DSTRM_OPEN_SHORT_ALL_PINS
TL_DSTRM_OPEN_SHORT_FAIL_PINS
TL_DSTRM_OPEN_SHORT_STATE TL_DSTRM_OPEN_SHORT_OFF
TL_DSTRM_OPEN_SHORT_ALL
TL_DSTRM_OPEN_SHORT_FAIL
TL_DSTRM_PROG_NAME char * - Name of the test program.
TL_DSTRM_SAMP_LIMIT unsigned int - sample limit
TL_DSTRM_SAMP_RATE unsigned int - sample rate
TL_DSTRM_SEQ_NAME char * - Name of SEQUENCER
TL_DSTRM_STDF_MODE TL_DSTRM_S_MODE_LIGHT
TL_DSTRM_S_MODE_HEAVY
TL_DSTRM_S_MODE_XLIGHT
TL_DSTRM_STDF_NAME char * - Name for datalog STDF file
TL_DSTRM_TEST TL_DSTRM_ALL_TEST
TL_DSTRM_PASS_TEST
TL_DSTRM_FAIL_TEST
TL_DSTRM_ANALOG_TEST
TL_DSTRM_DIGITAL_TEST
TL_DSTRM_TEST_FILE char * - path of file containing test list info
TL_DSTRM_TEST_LIST unsigned int array, each element a test number
TL_DSTRM_TEST_NAME char * - Name of test
TL_DSTRM_TEST_RNG unsigned int array, where pairs of elements specify the start
and end of a range
TL_DSTRM_WAFER_MAP No value. Get X/Y data for all devices in sample datalog.
For all datastream commands stream_id is a required
parameter.
ARGUMENTS Variable number of arguments, generally in pairs:
<flag, argument>
IMAGE Solutions V8.3 26-145
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
The arguments may be unsigned integer bit vectors, unsigned
integer arrays, or character strings. The entire argument list
MUST be terminated by NULL: For example:
err_code = tl_add_datastream(TL_DSTRM_ID,
"new_stream" TL_DSTRM_TEST, TL_DSTRM_ALL_TEST,
NULL);
RETURN VALUE 0 (zero) - There was an error either connecting to the data server,
or the arguments were incorrectly specified, or testing has
already begun on this lot.
1 - Success: the command line was correct and the command
successfully processed by the data server.
SIDE EFFECTS None
SEE ALSO “Data Collection” on page 6-1, tl_change_datatastream,
tl_remove_datastream, tl_change_datastream_mode.
tl_addr_r
Read from address in Terabus space.
SYNOPSIS unsigned short tl_addr_r(addr)
int addr;
DESCRIPTION This function reads back the data at the specified Terabus
address.
ARGUMENTS addr—address (offset) in Terabus space
RETURN VALUE data at address
tl_addr_w
Write to pointer into Terabus space.
SYNOPSIS void tl_addr_w(addr, data)
int addr;
unsigned short data;
DESCRIPTION This function writes the data into the specified Terabus address.
ARGUMENTS addr—address (offset) in Terabus space
data—data value to be written
RETURN VALUE None
tl_alarmcheck
Check test system for alarms and take action.
SYNOPSIS int tl_alarmcheck(no_strobe)
IMAGE Solutions V8.3 26-146
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function checks the test system for alarm conditions and
initiates action (binning, halting the program, and so on). based
on any alarm conditions detected. Note that rdelay() must
have been called before calling tl_alarmcheck().
ARGUMENTS int no_strobe
1–do not strobe test system for alarms
0–strobe test system for alarms
RETURN VALUE None
tl_apu_cal_set_interval
Set calibration time interval.
SYNOPSIS void tl_apu_cal_set_interval(interval)
time_t interval;
DESCRIPTION Sets the amount of time the apu calibration is considered valid.
This is used in the above tl_apu_cal_time_check function.
ARGUMENTS time_t interval—Number of seconds. Normally set to 4 * 60
* 60 (four hours).
RETURN VALUE None.
tl_apucal_time
Query time since last UB APU calibration.
SYNOPSIS tl_apucal_time()
DESCRIPTION This function is supported for compatibility with a user-level
function in the original APU driver. It queries the time in minutes
since the last UB APU calibration. It finds the UB APU channel
with the oldest time stamp among all installed APU channels
which passed calibration. It then computes the difference
between the current time and the oldest time stamp.
ARGUMENTS None
RETURN VALUE >=0—time in minutes (fractional minutes are truncated)
<0—no UB APUs are installed or no installed APU passed
calibration.
SEE ALSO “tl_apucal_subr”, “tl_apu_cal_set_interval”, “tl_apucal_time”
tl_apucal_time (in original APU driver file spmucal.c)
system/standards/drivers/s.calibrator.rules
system/standards/drivers/s.cal_util.doc
IMAGE Solutions V8.3 26-147
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_apu_read_pin_status
Read status of APU pin number.
SYNOPSIS tl_apu_read_pin_status(pin_number, results_array)
int pin_number;
int *results_array;
DESCRIPTION Reads the status of an APU pin and returns the results in the
parameter results_array. It checks if an APU channel behind
the specified pin number is actually installed and determines
whether an APU alarm has been latched.
The parameter result_array must be large enough to store
values from all test sites. The function does not fill in results for
sites that are not active. The function can be used outside or
inside a serial loop:
int pin_number;
int results_array[TL_SYS_MAX_SITES];
int status;
tl_apu_read_pin_status(pin_number, results_array);
serial {
status = tl_apu_read_pin_status(pin_number,
results_array);
}
If the function is used outside a serial loop and there is more than
one active test site, the return value will be 0.
ARGUMENTS pin_number—APU pin number from pinmap
results_array—Array to store results
RETURN VALUE Stored in the array results_array.
0—APU pin number is invalid or specified APU pin not found in
pinmap or APU hardware behind the pin is not present or called
outside serial loop and more than one active test site
2—Corresponding APU hardware is present and no alarm is
latched
3—APU hardware is present and guard or overload alarm is
latched
SIDE EFFECTS Produces a run-time error for error conditions.
SEE ALSO “read_apu_pin_status”, “read_apu_pin”
tl_asu_present
Check if ASU is present.
IMAGE Solutions V8.3 26-148
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS tl_asu_present(asu_num)
int asu_num;
DESCRIPTION Get Analog Sampling Unit (ASU) present status.
ARGUMENTS asu_num—ASU channel
RETURN VALUE None
tl_asu_read_ad
Read ASU A/D value with correction value.
SYNOPSIS tl_asu_read_ad(channel)
int channel;
DESCRIPTION Reads data of Analog Sampling Unit (ASU) A/D strobe value.
ARGUMENTS channel—ASU channel
RETURN VALUE Reading value
tl_asu_read_code
Read A/D code.
SYNOPSIS unsigned int tl_asu_read_code(channel)
int channel;
DESCRIPTION Reads data of A/D code.
ARGUMENTS channel—ASU channel
RETURN VALUE Code value
tl_asu_read_lsb
Read LSB value.
SYNOPSIS tl_asu_read_lsb(ch)
int channel;
DESCRIPTION Reads LSB value in current vrng.
ARGUMENTS channel—ASU channel
RETURN VALUE LSB value
tl_asy_conn_pmm_vmdiff
Connect the Precision Multimeter (PMM) to matrix lines 7 and 8.
SYNOPSIS void tl_asy_conn_pmm_vmdiff();
IMAGE Solutions V8.3 26-149
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Connects the PMM 2-wire inputs to matrix lines 7 and 8 in the
AD650 ASY.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Disconnects PMM from measure and accessory busses. Closes
external L7 and L8 connections to meter.
SEE ALSO “tl_asy_disc_pmm”
tl_asy_disc_pmm
Disconnect the Precision Multimeter (PMM) from ASY.
SYNOPSIS void tl_asy_disc_pmm();
DESCRIPTION Disconnects PMM 2-wire inputs at the AD650 ASY.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_asy_conn_pmm_vmdiff”
tl_ath_area_size
Return area size.
SYNOPSIS int tl_ath_area_size()
DESCRIPTION This function returns the number of data line per area.
ARGUMENTS None
RETURN VALUE Number of data line per area
tl_ath_measure_data_pin_freq
Measure DATA pin frequency on Array Test Head (ATH).
SYNOPSIS int tl_ath_measure_data_pin_freq(pin, cycle)
int pin;
int cycle;
DESCRIPTION Measures the specified data pin frequency to check if the pin is
connected to the probe pin. If this function returns 1, you can
determine the measured frequency or capacitance converted
from frequency using the following functions:
tl_ath_read_counter()—get frequency count
tl_ath_read_frequency()—get frequency
tl_ath_read_capacitance()—get capacitance
IMAGE Solutions V8.3 26-150
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
The following example checks the line frequency for pin number
1 using the rate 1/16:
func1()
{
extern int tl_ath_measure_data_pin_freq();
extern double tl_ath_read_frequency();
double freq;
if (tl_ath_measure_data_pin_freq(1, 5) == 1)
freq = tl_ath_read_frequency();
}
ARGUMENTS pin—gate pin number
cycle—number of cycle to be counted It must be between 0 and
15.
RETURN VALUE 1—success
0—parameter error, invalid parameter
-1—overflow, counter over flow
-2—timeout, 5 sec passed
SEE ALSO “tl_ath_read_counter”, “tl_ath_read_frequency”,
“tl_ath_read_capacitance”
tl_ath_measure_gate_pin_freq
Measure GATE pin frequency.
SYNOPSIS int tl_ath_measure_gate_pin_freq(pin, cycle, freq)
int pin;
int cycle;
double freq;
DESCRIPTION Measures the specified gate pin frequency to check if the pin is
connected to probe pin. If this function returns 1, you can
determine measured frequency or capacitance converted from
frequency using the following functions:
tl_ath_read_counter()—get frequency count
tl_ath_read_frequency()—get frequency
tl_ath_read_capacitance()—get capacitance
The following example checks the line frequency for pin number
1 using the rate 1/16:
func1()
{
extern int tl_ath_measure_gate_pin_freq();
extern double tl_ath_read_frequency();
double freq;
if (tl_ath_measure_gate_pin_freq(1, 5, 5000000.0) == 1)
freq = tl_ath_read_frequency();
}
IMAGE Solutions V8.3 26-151
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS pin—gate pin number
cycle—number of cycle to be counted. It must be between 0
and 15. 0 means 1/2 cycle.
freq—clock frequency, 5 MHz or 10 MHz
RETURN VALUE 1—success
0—parameter error, invalid parameter
-1—overflow, counter overflow
-2—timeout, 5 seconds passed
SIDE EFFECTS Clears the all latched data of GMUX.
SEE ALSO “tl_ath_read_counter”, “tl_ath_read_frequency”,
“tl_ath_read_capacitance”
tl_ath_read_capacitance
Get capacitance value.
SYNOPSIS double tl_ath_read_capacitance()
DESCRIPTION This function reads the line capacitance whose frequency is
measured by tl_ath_measure_[gate/data]_pin_freq().
ARGUMENTS None
RETURN VALUE Capacitance in PC
SEE ALSO “tl_ath_measure_gate_pin_freq”,
“tl_ath_measure_data_pin_freq”
tl_ath_read_counter
Get frequency counter value.
SYNOPSIS int tl_ath_read_counter()
DESCRIPTION This function reads the line frequency count measured by
tl_ath_measure_[gate/data]_pin_freq().
ARGUMENTS None
RETURN VALUE Current pin contact counter value
SEE ALSO “tl_ath_measure_gate_pin_freq”,
“tl_ath_measure_data_pin_freq”
tl_ath_read_frequency
Get frequency value.
SYNOPSIS double tl_ath_read_frequency()
IMAGE Solutions V8.3 26-152
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function reads the line frequency measured by
tl_ath_measure_[gate/data]_pin_freq().
ARGUMENTS None
RETURN VALUE Converted frequency
SEE ALSO “tl_ath_measure_gate_pin_freq”,
“tl_ath_measure_data_pin_freq”
tl_awg4800_max_fs_to_6400
Changes fsmax to 6400 MHz from 4800 MHz.
SYNOPSIS void tl_awg4800_max_fs_to_6400(int on)
DESCRIPTION Changes fsmax to 6400 MHz from 4800 MHz or back to 4800
MHz.
ARGUMENTS 1: fsmax = 6400 MHz.
0: fsmax = 4800 MHz.
RETURN VALUE None
tl_awg4800_vca_map_debug
Set VCA mapping debug flags.
SYNOPSIS void tl_awg4800_vca_map_debug( on )
int on;
DESCRIPTION Turn VCA mapping debug messages on or off.
ARGUMENTS on - debug message flag
1 - turn on messages.
0 - turn off messages.
RETURN VALUE None
tl_bbac_disable_clock_error_messages
Disable clock error messages when BBAC forces a clock.
SYNOPSIS void tl_bbac_disable_clock_error_messages()
DESCRIPTION Disables clock error messages alerting user of instruments
which may be affected when BBAC forces a clock.
ARGUMENTS None
RETURN VALUE None
IMAGE Solutions V8.3 26-153
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_bbac_disable_dut_connects
Disable connections to the DUT.
SYNOPSIS void tl_bbac_disable_dut_connects()
DESCRIPTION Disables connections to the DUT on BBAC hardware
(BBACSRC and BBACDIG). Connect statements will appear to
succeed, but relay connections to the DUT (channel card pogo
pins) will not be made. Any such relays already connected will
remain so, and disconnect syntax will operate normally. By
default, DUT connects are enabled.
ccgnd _\__
Relays closed by
| tl_bbac_disable_dut_connects
DC matrix _\__|
|
THADS Bus _\__|
|
Instrument HI _________\__|_____\____ HI pin to DUT
Instrument LO _________\__|_____\____ LO pin to DUT
|
ccgnd _\__|
|
DC matrix _\__|
|
THADS Bus _\__|
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_lfac_enable_dut_connects”, “tl_lfac_disable_dut_connects”,
“tl_bbac_enable_dut_connects”
tl_bbac_disable_linearity_corrections
Disable linearity corrections.
SYNOPSIS void tl_bbac_disable_linearity_corrections(pin)
int pin;
DESCRIPTION Disables the BBAC linearity corrections for the specified pin.
ARGUMENTS pin —Pinmap identifier
RETURN VALUE None
tl_bbac_enable_clock_error_messages
Enable clock error messages when BBAC forces a clock.
IMAGE Solutions V8.3 26-154
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS void tl_bbac_enable_clock_error_messages()
DESCRIPTION Re-enables clock error messages alerting user of instruments
which may be affected when BBAC forces a clock.
ARGUMENTS None
RETURN VALUE None
tl_bbac_enable_dut_connects
Enable connections to the DUT.
SYNOPSIS void tl_bbac_enable_dut_connects()
DESCRIPTION Re-enables connections to the DUT on BBAC hardware
(BBACSRC and BBACDIG). Connect statements will operate
normally. This is the default behavior.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_lfac_enable_dut_connects”, “tl_lfac_disable_dut_connects”,
“tl_bbac_disable_dut_connects”
tl_bbac_enable_linearity_corrections
Enable linearity corrections.
SYNOPSIS void tl_bbac_enable_linearity_corrections(pin)
int pin;
DESCRIPTION Enables the BBAC linearity corrections for the specified pin.
ARGUMENTS pin—Pinmap identifier
RETURN VALUE None
SIDE EFFECTS This function will trigger the re-calibration of both the PACS and
the BBAC instrument if the pin specified refers to a BBAC
capture channel and the BBAC has not been calibrated since
one of the following:
a) the job was loaded
b) the tester was re-initialized
c) mainframe loopback mode was used (checker only)
tl_begin_lot
Begin testing a new lot of devices.
IMAGE Solutions V8.3 26-155
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS tl_begin_lot(dumpflag)
int dumpflag;
DESCRIPTION Calling this function tells IMAGE that the current lot of devices is
complete and that a new lot should be started. When a new
device lot is started, the “parts tested” counters are reset and the
datalog streams are restarted if datalogging is enabled.
This function works by building a Master Information Record
(MIR), an STDF datalog record, and writing it to the datalog
buffer. If the parameter dumpflag is set (that is, nonzero), the
datalog buffer is dumped, causing the new lot to begin
immediately. If dumpflag is not set, the record is not sent
immediately but waits until the next time the datalog buffer is
dumped (presumably the end of the test program run).
For information on STDF records and their use in IMAGE, see
“Standard Test Data Format” on page 24-1 and the Standard Test
Data Format (STDF) Specification, Version 4.
ARGUMENTS dumpflag—controls whether MIR record is sent immediately
RETURN VALUE None
SIDE EFFECTS May dump the datalog buffer
Resets all per-run device binning information
Calls tl_read_prb_card()
tl_begin_new_lot
Begin testing a new lot of devices.
SYNOPSIS void tl_begin_new_lot();
DESCRIPTION Calling this function tells IMAGE that the current lot of devices is
complete, the previous (or current) lot should be closed, and a
new lot should be started. When a new device lot is started, the
“parts tested” counters are reset and the datalog streams are
restarted if datalogging is enabled.
This function first closes the previous lot, by performing an auto
endlot and then initializes the next lot by calling
tl_begin_lot(). tl_begin_lot is called in such a way that it
does not dump the datalog buffer for the new lot. Once
tl_begin_new_lot() is called, the test program can be exited
by calling exit() since this function does not perform the normal
housekeeping done for a test program run. When this function is
called, all housekeeping is done for the previous lot only.
If you call tl_begin_new_lot(), the tl_use_endlot() function
is called during endlot processing. Sometimes flags are reset
and are recognized by begin lot processing on the next iteration
IMAGE Solutions V8.3 26-156
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
of the test program. If the begin lot processing is before the call
to tl_begin_new_lot(), it is performed on the second iteration
of the test program following the new lot. The following code
example illustrates this:
if (first_run_of_lot) {
Begin lot processing
}
if (Time_for_endlot)
tl_begin_new_lot();
When tl_begin_new_lot() is called, the previous lot is closed
and a new lot is begun from the point where it is called. However,
because of the placement of the first if clause, the
first_run_of_lot code is executed during the second run of
the lot.
Be careful in structuring code when using this function.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Closes the previous lot and performs an auto summary.
Resets all per-run device binning information.
Calls tl_read_prb_card().
SEE ALSO “tl_begin_lot”
tl_bin_fail
Set the device bin to the fail bin.
SYNOPSIS void tl_bin_fail(failbin)
int failbin;
DESCRIPTION Adds a device fail bin to the list created by a device_bins
statement or modifies an existing device_bins entry to be a fail
bin. See “The device_bins Declaration” on page 15-13.
ARGUMENTS failbin—a bin number between 0 and MAXBIN (256)
RETURN VALUE None
tl_bin_pass
Set the device bin to the pass bin.
SYNOPSIS void tl_bin_pass(passbin)
int passbin;
DESCRIPTION Adds a device pass bin to the list created by a device_bins
statement or modifies an existing device_bins entry to be a
pass bin. See “The device_bins Declaration” on page 15-13.
IMAGE Solutions V8.3 26-157
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS passbin—a bin number between 0 and MAXBIN (256)
RETURN VALUE None
tl_cal_get_autocal_mode
Return autocal mode.
SYNOPSIS int tl_cal_get_autocal_mode()
DESCRIPTION This function returns the mode of autocal. Autocal can either be
on or off. In addition, calibration state (whether instruments’
calibration data is valid) can be ignored. When calibration state
is ignored, not only does autocal not calibrate instruments, but
the instruments continue to function even if calibration data
expires. When calibration is ignored, the calibration state of the
instrument remains whatever it was at the time the mode was set
to ignored.
NOTE
Operating a test system in IGNORED mode is not recommended. Instrument specs are not
guaranteed when operating in this mode.
Autocal can be set to check calibration validity and calibrate
instruments either before each test program execution or after
each test program execution.
Autocal can be set to force use of calibration files for instruments
which support them even if the calibration files are not valid
under current conditions. If the autocal mode indicates that
calibration files should be forced, all instruments load calibration
files regardless of validity. Otherwise, instruments which support
using calibration files use them only if they are valid.
NOTE
Operating a test system in FRC_CALFILE mode is not recommended. Instrument specs are
not guaranteed when operating in this mode.
The autocal mode can be interpreted using the following bit
masked flags:
TL_AUTOCAL_ON—autocal is turned on
TL_AUTOCAL_OFF—autocal is turned off
TL_AUTOCAL_IGNORED—error messages will be ignored
TL_AUTOCAL_NOT_IGNORED—error messages will not be ignored
TL_AUTOCAL_CAL_BEFORE—do an autocal before running test
IMAGE Solutions V8.3 26-158
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
program
TL_AUTOCAL_CAL_AFTER—do an autocal after running test
program
TL_AUTOCAL_CALFILE—use calfile
TL_AUTOCAL_NO_CALFILE—don’t use calfile
TL_AUTOCAL_FRC_CALFILE—force calfile to be read even if
invalid
TL_AUTOCAL_NO_FRC_CALFILE—do not force calfile to be read
TL_AUTOCAL_ALL_COPIES—calibrate every copy of the
instrument
TL_AUTOCAL_PINMAP_ONLY—calibrate only the ones defined in
pinmap
TL_AUTOCAL_CAL_REUSE—Allow the calibration wizard to re-use
data from the previous calibration as it sees fit.
TL_AUTOCAL_CAL_NOREUSE—Don’t use old data when
calibrating
TL_AUTOCAL_CAL_FLUSH—Flush the wizard’s data structures
By default, autocal mode is:
TL_AUTOCAL_OFF | TL_AUTOCAL_NOT_IGNORED |
TL_AUTOCAL_CAL_BEFORE | TL_AUTOCAL_CALFILE |
TL_AUTOCAL_ALL_COPIES | TL_AUTOCAL_NO_FRC_CALFILE |
TL_AUTOCAL_CAL_REUSE
ARGUMENTS None
RETURN VALUE [TL_AUTOCAL_ON | TL_AUTOCAL_OFF]
[TL_AUTOCAL_IGNORED | TL_AUTOCAL_NOT_IGNORED]
[TL_AUTOCAL_CAL_BEFORE | TL_AUTOCAL_CAL_AFTER]
[TL_AUTOCAL_CALFILE | TL_AUTOCAL_NO_CALFILE]
[TL_AUTOCAL_FRC_CALFILE | TL_AUTOCAL_NO_FRC_CALFILE]
[TL_AUTOCAL_ALL_COPIES | TL_AUTOCAL_PINMAP_ONLY]
[TL_AUTOCAL_CAL_REUSE | TL_AUTOCAL_CAL_NOREUSE]
[TL_AUTOCAL_FLUSH]
tl_cal_get_autocal_state
Flag indicating calibration state.
SYNOPSIS int tl_cal_get_autocal_state()
DESCRIPTION This flag indicates the global calibration state of the instruments
used in the current test program.
The flag has the following bitmasked values:
TL_AUTOCAL_UNCALIBRATED—All instruments in calibration
TL_AUTOCAL_CALIBRATED—One or more instruments not in
calibration
TL_AUTOCAL_THIS_RUN—One or more instruments calibrated
IMAGE Solutions V8.3 26-159
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Only one of TL_AUTOCAL_UNCALIBRATED and
TL_AUTOCAL_CALIBRATED is set at any given time.
TL_AUTOCAL_THIS_RUN is set only during execution of the test
program immediately following execution of one or more
calibration functions initiated by autocal.
—Undefined if global autocal off
—Uncalibrated if global autocal ignore
—Calibrated this run if all instruments are calibrated or invalid
and at least
one instrument ran calibration this run
—Uncalibrated this run if at least one instrument is
uncalibrated and at least one instrument ran calibration
this run
—Calibrated if all instruments are calibrated or invalid
—Uncalibrated if at least one instrument is uncalibrated
ARGUMENTS None
RETURN VALUE int [TL_AUTOCAL_UNCALIBRATED |
TL_AUTOCAL_CALIBRATED]
[TL_AUTOCAL_THIS_RUN]
SIDE EFFECTS Autocal state does not mean anything when autocal is not turned
on.
tl_cal_get_inst_crit
Get autocal criteria for an instrument.
SYNOPSIS void tl_cal_get_inst_crit(inst, cal_type,
crit_struct)
DESCRIPTION This function gets the calibration criteria for a specific instrument.
ARGUMENTS char *inst—The instrument name (from calibrate -usage)
char *cal_type—Calibration type (from calibrate -usage)
struct tl_cal_criteria *crit_struct—Returns calibration
criteria
double crit—Calibration criteria
int units—Macro from cal_resource.h for type of
calibration criteria (TL_AUTOCAL_TIME or
TL_AUTOCAL_TEMP)
RETURN VALUE None
tl_cal_get_inst_mode
Return autocal mode for an instrument.
SYNOPSIS int tl_cal_get_inst_mode(inst, cal_type)
IMAGE Solutions V8.3 26-160
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns the mode of autocal for a specific
instrument. Autocal can either be ON or OFF. In addition,
calibration state (whether the instruments’ calibration data is
valid) can be IGNORED. When calibration state is IGNORED, not
only does autocal not calibrate the instrument, but the instrument
continues to function even if calibration data expires.
NOTE
Operating a test system in IGNORED mode is not recommended. Instrument specs are not
guaranteed when operating in this mode.
Autocal can be set to ignore calibration files for those
instruments which support them. If the autocal mode indicates
that calibration files should not be used, all instruments ignore
their calibration files. Otherwise instruments which support using
calibration files use them if individually enabled.
Autocal can be set to force use of calibration files for instruments
which support them even if the calibration files are not valid
under current conditions. If the autocal mode indicates that
calibration files should be forced, all instruments load calibration
files regardless of validity. Otherwise, instruments which support
using calibration files use them only if they are valid.
NOTE
Operating a test system in FRC_CALFILE mode is not recommended. Instrument specs are
not guaranteed when operating in this mode.
The autocal mode can be interpreted using the following bit
masked flags:
TL_AUTOCAL_ON—autocal is turned on
TL_AUTOCAL_OFF—autocal is turned off
TL_AUTOCAL_IGNORED—error messages will be ignored
TL_AUTOCAL_NOT_IGNORED—error messages will not be ignored
TL_AUTOCAL_CALFILE—use calfile
TL_AUTOCAL_NO_CALFILE—don’t use calfile
TL_AUTOCAL_FRC_CALFILE—force calfile to be read even if
invalid
TL_AUTOCAL_NO_FRC_CALFILE—do not force calfile to be read
TL_AUTOCAL_CAL_REUSE—Allow the calibration wizard to re-use
data from the previous calibration as it sees fit.
TL_AUTOCAL_CAL_NOREUSE—Don’t use old data when
calibrating
IMAGE Solutions V8.3 26-161
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
By default, for all instruments, autocal mode is:
TL_AUTOCAL_ON | TL_AUTOCAL_CALFILE |
TL_AUTOCAL_NOT_IGNORED | TL_AUTOCAL_NO_FRC_CALFILE |
TL_AUTOCAL_CAL_REUSE
ARGUMENTS char *inst—The instrument name (from calibrate -usage)
char *cal_type—Calibration type (from calibrate -usage)
RETURN VALUE [TL_AUTOCAL_ON | TL_AUTOCAL_OFF]
[TL_AUTOCAL_IGNORED | TL_AUTOCAL_NOT_IGNORED]
[TL_AUTOCAL_CALFILE | TL_AUTOCAL_NO_CALFILE]
[TL_AUTOCAL_FRC_CALFILE | TL_AUTOCAL_NO_FRC_CALFILE]
[TL_AUTOCAL_CAL_REUSE | TL_AUTOCAL_CAL_NOREUSE]
tl_cal_get_inst_state
Flag indicating instrument calibration state.
SYNOPSIS int tl_cal_get_inst_state(inst, cal_type)
DESCRIPTION This flag indicates the global calibration state of the specified
calibration.
The value of the flag is a logical OR of one or more of the
following values:
TL_AUTOCAL_CALIBRATED—calibration valid
TL_AUTOCAL_UNCALIBRATED—calibration not valid
TL_AUTOCAL_THIS_RUN—calibrated this run
TL_AUTOCAL_INVALID—instrument does not exist
Only one of TL_AUTOCAL_UNCALIBRATED and
TL_AUTOCAL_CALIBRATED will be set at any given time.
TL_AUTOCAL_THIS_RUN is set only during the execution of the
test program immediately following the execution of the specified
calibration function initiated by autocal.
The possible values for this flag are:
•undefined if global autocal off, or global autocal ignore
•uncalibrated if inst autocal off, or inst autocal ignore
•calibrated and this run if calibration passed this run
•uncalibrated and this run if calibration failed this run
•invalid and this run if calibration invalid this run
•otherwise, one of calibrated/uncalibrated/invalid and not this
run
ARGUMENTS char *inst—The instrument name (from calibrate -usage)
char *cal_type—Calibration type (from calibrate -usage)
IMAGE Solutions V8.3 26-162
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE int [TL_AUTOCAL_UNCALIBRATED |
TL_AUTOCAL_CALIBRATED]
[TL_AUTOCAL_THIS_RUN]
SIDE EFFECTS The state of the instrument does not mean anything when
autocal is not turned on.
tl_cal_get_remaining
Get remaining time or temperature until calibration is required.
SYNOPSIS double tl_cal_get_remaining(inst, cal_type)
DESCRIPTION This function gets the remaining time or temperature from the
calibration criteria before calibration will be required for a specific
instrument. You must declare this fu nction as extern in your test
program.
ARGUMENTS char *inst—The instrument name (from calibrate -usage)
char *cal_type—Calibration type (from calibrate -usage)
RETURN VALUE double—time or temperature (or whatever) remaining. If the
instrument is uncalibrated, this function returns -1.
tl_cal_inst
Calibrate this instrument.
SYNOPSIS int tl_cal_inst(inst, cal_type)
DESCRIPTION This function causes the specified instrument to be calibrated.
ARGUMENTS char *inst—The instrument name (from calibrate -usage)
char *cal_type—Calibration type (from calibrate -usage)
RETURN VALUE int TL_AUTOCAL_UNCALIBRATED
TL_AUTOCAL_CALIBRATED
SIDE EFFECTS A reset all is executed before and after completion of calibration.
This is done to ensure that all instruments which may be used
during calibration are returned to a known state. This may
destroy existing test setups.
tl_cal_report
Print a report of autocal for all instruments.
SYNOPSIS void tl_cal_report()
DESCRIPTION This function prints a status report of the state of autocal for all
instruments in the station window.
ARGUMENTS None
IMAGE Solutions V8.3 26-163
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
tl_cal_set_autocal_mode
Change autocal mode (on/off/ignore).
SYNOPSIS void tl_cal_set_autocal_mode(mode)
DESCRIPTION This function changes the mode of autocal. Autocal can either be
ON or OFF. In addition, calibration state (whether an
instruments’ calibration data is valid) can be IGNORED. When
calibration state is IGNORED, not only does autocal not calibrate
instruments, but the instruments continue to function even if
calibration data expires. When calibration is IGNORED, the
calibration state of the instrument remains whatever it was at the
time the mode was set to IGNORED.
NOTE
Operating a test system in IGNORED mode is not recommended. Instrument specs are not
guaranteed when operating in this mode.
Autocal can be set to check calibration validity and calibrate
instruments either before each test program execution or after
each test program execution. Note that even when CAL_AFTER is
selected, the first calibration occurs immediately after program
load. When using this mode, long interruptions in testing may
result in instruments drifting out of calibration between the end of
the last program run and the beginning of the next.
Autocal can be set to ignore calibration files for instruments
which support them. If the autocal mode indicates that calibration
files should not be used, all instruments ignore their calibration
files. Otherwise, instruments which support using calibration files
use them if individually enabled.
Autocal can be set to force use of calibration files for instruments
which support them even if the calibration files are not valid
under current conditions. If the autocal mode indicates that
calibration files should be forced, all instruments load calibration
files regardless of validity. Otherwise, instruments which support
using calibration files use them only if they are valid.
NOTE
Operating a test system in FRC_CALFILE mode is not recommended. Instrument specs are
not guaranteed when operating in this mode.
IMAGE Solutions V8.3 26-164
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Autocal can be set to calibrate all copies of all instruments used
in the test program and referenced by IMAGE interactive debug
displays. Alternatively, autocal can be set to calibrate only
instruments referenced in the test program pinmap. This option
can be set only for all of calibration and is not selectable on an
instrument by instrument basis.
The autocal mode can be set using the following bit masked
flags:
TL_AUTOCAL_ON—autocal is turned on
TL_AUTOCAL_OFF—autocal is turned off
TL_AUTOCAL_IGNORED—error messages will be ignored
TL_AUTOCAL_NOT_IGNORED—error messages will not be ignored
TL_AUTOCAL_CAL_BEFORE—do an autocal before running test
program
TL_AUTOCAL_CAL_AFTER—do an autocal after running test
program
TL_AUTOCAL_CALFILE—use calfile
TL_AUTOCAL_NO_CALFILE—don’t use calfile
TL_AUTOCAL_FRC_CALFILE—force calfile to be read even if
invalid
TL_AUTOCAL_NO_FRC_CALFILE—do not force calfile to be read
TL_AUTOCAL_ALL_COPIES—calibrate every copy of the
instrument
TL_AUTOCAL_PINMAP_ONLY—calibrate only the ones defined in
pinmap
TL_AUTOCAL_CAL_REUSE—Allow the calibration wizard to re-use
data from the previous calibration as it sees fit.
TL_AUTOCAL_CAL_NOREUSE—Don’t use old data when
calibrating
TL_AUTOCAL_CAL_FLUSH—Flush the wizard’s data structures
By default, autocal mode is:
TL_AUTOCAL_OFF | TL_AUTOCAL_NOT_IGNORED |
TL_AUTOCAL_CAL_BEFORE | TL_AUTOCAL_CALFILE |
TL_AUTOCAL_ALL_COPIES | TL_AUTOCAL_NO_FRC_CALFILE |
TL_AUTOCAL_CAL_REUSE
ARGUMENTS int mode [TL_AUTOCAL_ON | TL_AUTOCAL_OFF]
[TL_AUTOCAL_IGNORED | TL_AUTOCAL_NOT_IGNORED]
[TL_AUTOCAL_CAL_BEFORE | TL_AUTOCAL_CAL_AFTER]
[TL_AUTOCAL_CALFILE | TL_AUTOCAL_NO_CALFILE]
[TL_AUTOCAL_FRC_CALFILE | TL_AUTOCAL_NO_FRC_CALFILE]
[TL_AUTOCAL_ALL_COPIES | TL_AUTOCAL_PINMAP_ONLY]
[TL_AUTOCAL_CAL_REUSE | TL_AUTOCAL_CAL_NOREUSE]
[TL_AUTOCAL_FLUSH]
RETURN VALUE None
IMAGE Solutions V8.3 26-165
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_cal_set_inst_crit
Change autocal criteria for an instrument.
SYNOPSIS void tl_cal_set_inst_crit(inst, cal_type, crit,
units)
DESCRIPTION This function changes the calibration criteria for a specific
instrument.
ARGUMENTS char *inst—The instrument name (from calibrate -usage)
char *cal_type—Calibration type (from calibrate -usage)
double crit—New calibration criteria
int units—Macro from cal_resource.h for type of calibration
criteria (TL_AUTOCAL_TIME or TL_AUTOCAL_TEMP)
NOTE
Be sure that the criteria you are passing is of type double. Otherwise, the arguments will not
be interpreted correctly, and you may get run-time error such as:
ERROR #11581 - autocal: Illegal unit type for this instrument: 0
RETURN VALUE None
tl_cal_set_inst_mode
Change autocal mode for instrument (on/off/ign).
SYNOPSIS void tl_cal_set_inst_mode(inst, cal_type, mode)
DESCRIPTION This function changes the autocal mode for a specific
instrument. Autocal can be ON or OFF. In addition, calibration
state (whether the instruments’ calibration data is valid) can be
IGNORED. When calibration state is IGNORED, autocal does
not calibrate the instrument, and the instrument continues to
function even if calibration data expires.
NOTE
Operating a test system in IGNORED mode is not recommended. Instrument specs are not
guaranteed when operating in this mode.
Autocal can be set to ignore calibration files for instruments
which support them. If the autocal mode indicates that calibration
files should not be used, all instruments ignore their calibration
files. Otherwise instruments which support using calibration files
use them if individually enabled.
IMAGE Solutions V8.3 26-166
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Autocal can be set to force use of calibration files for instruments
which support them even if the calibration files are not valid
under current conditions. If the autocal mode indicates that
calibration files should be forced, all instruments load calibration
files regardless of validity. Otherwise, instruments which support
using calibration files use them only if they are valid.
NOTE
Operating a test system in FRC_CALFILE mode is not recommended. Instrument specs are
not guaranteed when operating in this mode.
The autocal mode can be set using the following bit masked
flags:
TL_AUTOCAL_ON—autocal is turned on
TL_AUTOCAL_OFF—autocal is turned off
TL_AUTOCAL_IGNORED—error messages will be ignored
TL_AUTOCAL_NOT_IGNORED—error messages will not be ignored
TL_AUTOCAL_CALFILE—use calfile
TL_AUTOCAL_NO_CALFILE—don’t use calfile
TL_AUTOCAL_FRC_CALFILE—force calfile to be read even if
invalid
TL_AUTOCAL_NO_FRC_CALFILE—do not force calfile to be read
TL_AUTOCAL_CAL_REUSE—Allow the calibration wizard to re-use
data from the previous calibration as it sees fit.
TL_AUTOCAL_CAL_NOREUSE—Don’t use old data when
calibrating
By default, for all instruments, autocal mode is:
TL_AUTOCAL_ON | TL_AUTOCAL_CALFILE |
TL_AUTOCAL_NOT_IGNORED | TL_AUTOCAL_NO_FRC_CALFILE |
TL_AUTOCAL_CAL_REUSE
ARGUMENTS char *inst—the instrument name (from calibrate -usage)
char *cal_type—calibration type (from calibrate -usage)
int mode [TL_AUTOCAL_ON | TL_AUTOCAL_OFF]
[TL_AUTOCAL_IGNORED | TL_AUTOCAL_NOT_IGNORED]
[TL_AUTOCAL_CALFILE | TL_AUTOCAL_NO_CALFILE]
[TL_AUTOCAL_FRC_CALFILE | TL_AUTOCAL_NO_FRC_CALFILE]
[TL_AUTOCAL_CAL_REUSE | TL_AUTOCAL_CAL_NOREUSE]
RETURN VALUE None
tl_cal_set_uncal
Force instrument to be uncalibrated.
SYNOPSIS void tl_cal_set_uncal(inst, cal_type, onoff)
IMAGE Solutions V8.3 26-167
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function forces a given instrument to be uncalibrated, in
need of calibration. After the instrument is calibrated using
autocal, the instrument state is set to the current calibrated state.
ARGUMENTS char *inst—Chan type
char *cal_type—Calibration type
int onoff 1 uncalibrated
0 calibrated
RETURN VALUE None
SIDE EFFECTS When pinmap only mode is being used, every pin which
references a given instrument causes it to recalibrate. This can
cause a single copy of an instrument to recalibrate multiple times
if it is referenced in multiple pins and pinmap only mode is being
used. This does not happen when calibration expires or
becomes invalid normally, only when an instrument is set to
uncalibrated using tl_cal_set_uncal().
tl_cdig_set_cal_interval
Set the Serial Bus channel card calibration interval.
SYNOPSIS void tl_cdig_set_cal_interval(interval)
time_t interval;
DESCRIPTION Sets autocal timeout value for the Serial Bus channel card to the
number of seconds specified in interval.
ARGUMENTS interval—number of seconds before boards need
recalibration
RETURN VALUE None
SIDE EFFECTS Sets driver variable to new value.
tl_change_auto
Change the auto debug mode.
SYNOPSIS int tl_change_auto(auto_in)
int auto_in;
DESCRIPTION This function changes the flag for the auto mode of debug.
ARGUMENTS auto_in 1 turns auto on
0 turns auto off
any other returns
RETURN VALUE 1 if auto debug mode is on
0 if auto debug mode is off
IMAGE Solutions V8.3 26-168
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_change_datalog
Change the setup of the active datalogs.
SYNOPSIS int tl_change_datalog(unsigned int key...);
DESCRIPTION This function operates like the command datalog -change. If
datalogging is already set up and turned on, you can modify the
existing setup while datalogging is on. For example, you can
change the sample rate. To specify a complete datalogging
setup, use tl_set_datalog(TL_DLG_OFF, ...) instead.
Multiple variables can be changed in one
tl_change_datalog() call.
This function can be called after the first device is tested, but use
caution when doing so.
ARGUMENTS Variable number of arguments, generally in pairs <flag,
argument>. Arguments can be unsigned integer bit vectors,
unsigned integer arrays, or character strings. The entire
argument list must be terminated by NULL. For example:
err_code = tl_change_datalog(TL_DLG_TEST,
TL_DLG_ALL_TEST, TL_DLG_SAMP_RATE, 10, NULL);
See tl_set_datalog() for a complete list of arguments. Only
the following arguments are valid for tl_change_datalog():
TL_DLG_TEST
TL_DLG_TEST_LIST
TL_DLG_TEST_RNG
TL_DLG_TEST_FILE
TL_DLG_TEST_NAME
TL_DLG_SEQ_NAME
TL_DLG_SAMP_RATE
TL_DLG_SAMP_LIMIT
TL_DLG_WAFER_MAP
RETURN VALUE 0—An error occurred, either connecting to the data server or the
arguments were incorrectly specified or testing has already
begun on this lot.
1—Success, the command line was correct and the command
successfully processed.
SIDE EFFECTS Affects the state of datalog.
SEE ALSO “tl_set_datalog”, “tl_get_datalog”, “tl_add_datalog_output”,
“tl_remove_datalog_output”, handle_tl_datalog_commands()
tl_change_datatastream
Change the setup of the specified datastream
IMAGE Solutions V8.3 26-169
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_change_datastream(unsigned int key...);
DESCRIPTION tl_change_datastream operates like the
datastream -change command: if specified stream is already
active, you can modify the existing setup while datalogging is on.
For example, you could change the Sample Rate.
Multiple variables can be changed in one call to
tl_change_datastream.
ARGUMENTS Variable number of arguments, generally in pairs:
<flag, argument>
The arguments may be unsigned integer bit vectors, unsigned
integer arrays, or character strings. The entire argument list must
be terminated by NULL, and the argument list must contain
stream_id. For example:
err_code = tl_change_datastream(TL_DSTRM_ID,
"streamName" TL_DSTRM_TEST, TL_DSTRM_ALL_TEST,
TL_DSTRM_SAMP_RATE, 10, NULL);
See tl_add_datastream for complete list of arguments. Only
these arguments are valid for tl_change_datalog:
TL_DSTRM_LKG_STATE
TL_DSTRM_LKG_STATE
TL_DSTRM_OPEN_SHORT_STATE
TL_DSTRM_OPEN_SHORT_PINS
TL_DSTRM_TEST
TL_DSTRM_TEST_LIST
TL_DSTRM_TEST_RNG
TL_DSTRM_TEST_FILE
TL_DSTRM_TEST_NAME
TL_DSTRM_SEQ_NAME
TL_DSTRM_SAMP_RATE
TL_DSTRM_SAMP_LIMIT
TL_DSTRM_WAFER_MAP
RETURN VALUE 0 - There was an error either connecting to the data server, or the
arguments were incorrectly specified, or testing has already
begun on this lot.
1 - Success, the command line was correct and the command
successfully processed by the data server.
tl_change_site
Change the default debug display site number.
SYNOPSIS tl_change_site()
IMAGE Solutions V8.3 26-170
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function changes the number of the default debug display
site.
ARGUMENTS site_num—the default debug display site number
RETURN VALUE None
tl_close_mux
Close the mux.
SYNOPSIS void tl_close_mux();
DESCRIPTION Closes the mux.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Mux functions support four stations.
Programming station 4 on an A5 is not useful but also not
harmful.
tl_cmu_get_roi_height
Get height of ROI in CMU.
SYNOPSIS int tl_cmu_get_roi_height()
DESCRIPTION Get height of ROI in Color Monitoring Unit (CMU).
ARGUMENTS None
RETURN VALUE ROI height
tl_cmu_get_roi_width
Get width of ROI in CMU.
SYNOPSIS int tl_cmu_get_roi_width()
DESCRIPTION Get width of ROI in Color Monitoring Unit (CMU).
ARGUMENTS None
RETURN VALUE ROI width
tl_cmu_get_roi_x_pos
Get X position of first pixel in CMU.
SYNOPSIS int tl_cmu_get_roi_x_pos()
DESCRIPTION Get X position of first pixel in Color Monitoring Unit (CMU).
IMAGE Solutions V8.3 26-171
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS None
RETURN VALUE X position
tl_cmu_get_roi_y_pos
Get Y position of first pixel in CMU.
SYNOPSIS int tl_cmu_get_roi_y_pos()
DESCRIPTION Get Y position of first pixel in Color Monitoring Unit (CMU).
ARGUMENTS None
RETURN VALUE Y position
tl_create_tsr_for_ival
In the STDF output stream, create TSR records for intermediate values.
SYNOPSIS void tl_create_tsr_for_ival(int flag);
DESCRIPTION This function causes Test Synopsis Records (TSR) to be created
for intermediate values datalogged. If this function is not called,
TSRs are not created for intermediate values (the default).
If you enable creation of TSRs for intermediate values in the test
program, any intermediate value records datalogged from that
point on will have matching TSRs, but intermediate values
datalogged earlier will not. If you disable creation of TSRs for
intermediate values, no TSR records for intermediate values will
appear in the STDF file.
This function must be called from within a serial loop in the event
of multisite test.
ARGUMENTS flag—0 no longer create TSRs for intermediate values
1 create TSRs for intermediate values.
RETURN VALUE None
SIDE EFFECTS Causes TSR records to appear in the STDF file. This may cause
STDF files to grow slightly and will cause intermediate values to
appear in the summary report. These values will also be entered
into the FIRMS database.
Additionally, intermediate value records with matching TSRs will
appear in the IMAGE summaries.
SEE ALSO “Test Synopsis Record (TSR)” on page 3-35 in the STDF
Specification.
IMAGE Solutions V8.3 26-172
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_d_dump_all_patterns
Dump all digital patterns.
SYNOPSIS void tl_d_dump_all_patterns()
DESCRIPTION Initializes a station so that there are no patterns loaded in either
PRAM or SAM. Called by the "unload patterns" statement.
Replace calls to this function with "unload patterns".
RETURN VALUE None
tl_d_no_timing_reset
Flag to disable timing resets.
SYNOPSIS extern int tl_d_no_timing_reset;
DESCRIPTION Normally, the test system reset function called before each test
program run resets T0 and C0 dividers to defaults. In addition, a
software flag marks the channel edge values as “not
programmed” so they do not show up on the display.
If this flag is set to 1, the test system reset leaves all edge values
and T0 and C0 dividers intact between test program runs and
treats edge values as already programmed. This increases the
speed of the test program by not having to program timing every
run.
Note that this means a different station may reprogram the
timing, causing the program to execute incorrectly. Be sure to
only use this flag in a single-station environment.
Master clock frequency and An clock dividers are still reset and
must be reprogrammed every run.
ARGUMENTS None
RETURN VALUE None
tl_d_share_enable
Enable pattern sharing for digital subsystem.
SYNOPSIS void tl_d_share_enable(on_off)
int on_off;
DESCRIPTION Normally when patterns are loaded on two stations, they are
loaded twice and use double the pattern memory. If the same
patterns are loaded on both stations, the patterns can be shared
to reduce memory usage.
IMAGE Solutions V8.3 26-173
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
This function is called to turn on the pattern sharing feature. It
may only be called when no patterns are loaded on this station.
Violating this rule generates a run-time error.
ARGUMENTS on_off—ON to enable pattern sharing, OFF to disable it.
RETURN VALUE None
tl_databits_address_set_board
Set board address.
SYNOPSIS tl_databits_address_set_board(primary, secondary,
bd)
int primary;
int secondary;
int bd;
DESCRIPTION This function sets the board address of expansion databits in the
RTP slot. Default board addresses are:
databits 49 - 84: 0305 W1-W3
databits 85 - 120: 0305 W4-W6
databits 121 - 156: 0304 W1-W3
databits 157 - 192: 0304 W4-W6
ARGUMENTS primary—primary address
secondary—secondary address(1 or 4)
bd—0 - databits 49 - 84
1 - databits 85 - 120
2 - databits 121 - 156
3 - databits 157 - 192
RETURN VALUE None
tl_databits_unlock_code_set
Set unlock code of databits.
SYNOPSIS tl_databits_unlock_code_set(code)
int code;
DESCRIPTION This function sets unlock code of expansion databits in RTP slot.
ARGUMENTS code—!=0 unlock code
==0 disable
RETURN VALUE None
tl_databits_unlock_code_set_board
Set unlock code of databits.
IMAGE Solutions V8.3 26-174
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS tl_databits_unlock_code_set_board(code, bd)
int code;
int bd;
DESCRIPTION This function is used to set the unlock code of expansion databits
in the RTP slot.
Note that IMAGE probes using the following unlock code for
expansion SDB:
databits 49 - 84: 0105
databits 85 - 120: 0106
databits 121 - 156: 0107
databits 157 - 192: 0110
If another value is used, the confsim file for databits may not be
created correctly.
ARGUMENTS code—unlock code
bd— 0 - databits 49 - 84
1 - databits 85 - 120
2 - databits 121 - 156
3 - databits 157 - 192
RETURN VALUE None
tl_datalog_endseq_on_fail
Have IMAGE datalog (or not datalog) the EPS record for a sequencer with a failing test.
SYNOPSIS int tl_datalog_endseq_on_fail(int yesNo);
DESCRIPTION This function accepts an argument which it uses to set whether
the End Program Section (EPS) STDF record is written to the
STDF file or not. Currently, the EPS record for a sequencer with
a test that fails and bins will not be written.
If the value of the argument is nonzero, the record is written to
the datalog. If it is zero, it is not datalogged.
ARGUMENTS yesNo—If nonzero, EPS of sequencer with failing test that bins
is written to datalog. If zero, the record is not written (the default).
RETURN VALUE 0—EPS record will be written
nonzero—EPS record will not be written
SIDE EFFECTS May cause new EPS records to be written to datalog.
tl_datalog_ival
Datalog intermediate values.
IMAGE Solutions V8.3 26-175
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_datalog_ival(double result, int TestNumber,
char *VariableName, char *label, char *format);
DESCRIPTION This function is provided as an alternative to the datalog
statement for datalogging intermediate values. The function can
accept all its parameters through variables.
The function verifies that the VariableName, label, and format
arguments are of appropriate length, 256 characters or less. If
the VariableName or label are greater than 256 characters in
length, they are truncated. If the format is greater than 256
characters a runtime error is generated, and the value is not
datalogged.
The format argument is scanned, and, if it is not a proper format
string, a runtime error is generated. The value is not datalogged.
The TestNumber must be specified as an integer. The IMAGE
sequencer line or datalog statement of $TestNumber is invalid
in this case.
If any optional parameters are not used, (char *) NULL must
be passed as an argument to the function. Otherwise the results
are undefined.
In the following example both the label and format are
defaulted:
double Result = 5.2;
char *VarName = "ExampleVariable";
int Status,
TestNumber = 22;
Status = tl_datalog_ival(Result, TestNumber,
VarName, (char *) NULL, (char *) NULL);
where Status is an integer variable being set to the return value
of tl_datalog_ival();
ARGUMENTS result—value to be datalogged. During the run of the function,
this value is cast as a float. You must pass the value as
a double, but do not use greater precision than the float
type supports.
TestNumber—test number assigned to the value.
VariableName—Name of variable being datalogged.
label—Optional label string. If not provided the VariableName
is used as the default.
format—Optional. If no string is provided the format %5.2 is
used as the default.
RETURN VALUE 0 Error or data collection not on.
1 Success, intermediate value datalogged.
SIDE EFFECTS Datalogs an intermediate value.
IMAGE Solutions V8.3 26-176
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_datalog_start_new_device
Begin datalog for new device.
SYNOPSIS int tl_datalog_start_new_device()
DESCRIPTION Use this function for programs which test multiple devices within
a single run of the main() function, or those which generate
multiple devices worth of datalog data with a single run.
Call this function after a given testing sequence is complete, in
other words, after the execution of one or more sequencers and
a sort bin statement. When called, it re-enables testing (that is,
clears the current bin assignment and re-enables all sites),
dumps the datalog buffer for the completed device, and restarts
datalog for a new device. The following example generates 10
devices’ worth of data using a single execution of main():
main() {
int i;
for (i = 0; i < 10; i++) {
if (i != 0) tl_datalog_start_new_device();
first_sequencer();
second_sequencer();
sort bin;
}
}
Note that none of the code in this example will index a handler or
prober. Indexing takes place after main() is complete.
This function assumes that a sort bin statement has been
performed for the current test sequence. If a sort bin has not
been performed, it does not perform datalog reinitialization and
instead returns the value FALSE (0). If the operation succeeds,
it returns TRUE (1).
ARGUMENTS None
RETURN VALUE TRUE (1) reinitialization performed
FALSE (0) no operation performed due to no previous
sort bin
SIDE EFFECTS Flushes the datalog buffer, clears any bin assignments
tl_dccal_dump_constants
Dump DC calibration constants to a file.
SYNOPSIS void tl_dccal_dump_constants()
DESCRIPTION Entry point for dumping calibration constants to a file.
ARGUMENTS None
IMAGE Solutions V8.3 26-177
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
SIDE EFFECTS Creates
/image/tester/$HOSTNAME/cal/cal_<numeric_date> file
containing calibration constants.
tl_dccal_meter
Calibrate voltmeter.
SYNOPSIS int tl_dccal_meter(pany_failed)
int arg;
int *pany_failed;
DESCRIPTION Entry point for meter calibrator
ARGUMENTS arg—-1 = calibrate, no cal output setup
0 = calibrate, informational messages only
1 = calibrate, verbose messages to window
2 = calibrate, verbose messages to file
3 = calibrate, all messages via ckprintf
pany_failed—address of any_failed from tl_dccal_subr.
*pany_failed = 0 if not called from tl_dccal_subr().
RETURN VALUE CMD_OK = calibration passed
CMD_CAL_FAIL = meter calibration failed
tl_dc_cal_set_interval
Set the DC Subsystem calibration time interval.
SYNOPSIS void tl_dc_cal_set_interval(interval)
time_t interval;
DESCRIPTION Sets the amount of time the DC Subsystem calibration is
considered valid. This is used in the tl_dccal_time function.
ARGUMENTS interval—number of seconds. Normally set to 4 * 60 * 60 (four
hours).
RETURN VALUE None
tl_dccal_src
Calibrate a single source in the DC Subsystem.
SYNOPSIS int tl_dccal_src(arg, src)
int arg, src;
DESCRIPTION Entry point for DC calibrator (for a single source).
ARGUMENTS arg—0 = calibrate, informational messages only
1 = calibrate, verbose messages to window
IMAGE Solutions V8.3 26-178
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
2 = calibrate, verbose messages to file
3 = calibrate, all messages via ckprintf
src—1..MAX_NSRC = source number
RETURN VALUE CMD_OK = calibration passed
CMD_CAL_FAIL = something failed
CMD_CAL_ABORT = calibration aborted because:
AD212 missing or
AD330 missing or
AD330 data retention failed
SIDE EFFECTS Function does a reset all.
tl_dccal_status
Return the calibration status of each dc instrument.
SYNOPSIS int tl_dccal_status(inst)
int inst;
DESCRIPTION Returns the calibration status of each DC Subsystem instrument.
ARGUMENTS inst—selects DC subsystem instrument:
0 combined results of all instruments
1 src=1
2 src=2
3 src=3
4 src=4
5 src=5
6 dutsrc=1
7 dutsrc=2
8 dutsrc=3
9 dutsrc=4
10 voltmeter
RETURN VALUE 1 passed last calibration
-1 failed last calibration or bad parameter
0 calibrator not run since initialize
tl_dccal_subr
Calibrate DC Subsystem.
SYNOPSIS int tl_dccal_subr(arg)
int arg;
DESCRIPTION Entry point for DC calibrator.
ARGUMENTS 0 = calibrate, informational messages only
1 = calibrate, verbose messages to window
IMAGE Solutions V8.3 26-179
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
2 = calibrate, verbose messages to file
3 = calibrate, all messages using ckprintf
RETURN VALUE CMD_OK = calibration passed
CMD_CAL_FAIL = failure
CMD_CAL_ABORT = calibration aborted because:
AD212 missing or
AD330 missing or
AD330 data retention failed
SIDE EFFECTS Function does a reset all.
tl_dccal_time
Read time and result of last DC Subsystem calibration.
SYNOPSIS int tl_dccal_time()
DESCRIPTION Read time and result of last DC Subsystem calibration.
ARGUMENTS None
RETURN VALUE Minutes since last calibration, or
-1 if never calibrated or calibration constants cleared
tl_dc_meter_tsy_digitize
Digitize with DC meter and trigger switchyard.
SYNOPSIS int tl_dc_meter_tsy_digitize(sample_rate,
sample_size, data, trigger, timeout)
int sample_rate;
int sample_size;
int data[];
int trigger;
double timeout;
DESCRIPTION Runs a loop taking measurement with the DC Meter, and stores
them in the user’s array. Uses the Trigger Switchyard and
Programmable Clock to generate a stable sample rate, which
strobes the meter. A highly optimized inner loop can sustain
5000 samples/s; higher values may cause errors. The most
common error is a “premature” trigger. That is, the CPU was
delayed in reading a value out of the meter, and the next strobe
occurred while reading the previous values. Tests for this
condition, and for timeouts waiting for trigger edges, are
performed and an indication returned.
NOTE
All samples are uncalibrated, raw integers.
IMAGE Solutions V8.3 26-180
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS sample_rate—samples per second
sample_size—number of samples
data—array of int to hold samples
trigger—timeslot trigger [1..8]
timeout—seconds to wait for triggers
RETURN VALUE 0—no error
1—timeout waiting for trigger
2—premature trigger (meter strobe)
SIDE EFFECTS Sets trigger timeout with tl_set_trigger_timeout()
Programs pclock:counter, pclock=1, and trigger=given.
tl_dcvm_cal_status
Return cal status of dc voltmeter.
SYNOPSIS int tl_dcvm_cal_status()
DESCRIPTION Return calibration status of the dc voltmeter.
ARGUMENTS None
RETURN VALUE 1 = passed last calibration
-1 = failed last calibration or bad parameter
0 = calibrator not run since initialize
tl_debug_site
Get the number of the debug display site.
SYNOPSIS int tl_debug_site()
DESCRIPTION Returns the number of the current debug display site. It replaces
the global variable tl_display_site.
ARGUMENTS None
RETURN VALUE An integer holding the debug display number
tl_declare_event
Send a FIRMS event message to event manager.
SYNOPSIS int tl_declare_event(event, args)
char *event, *argstr;
DESCRIPTION This function provides a way to send FIRMS event messages
from within an IMAGE test program. For more information on
FIRMS events, see Standard Event Message Format (SEMF)
Specification, Teradyne part number 553–250–65.
IMAGE Solutions V8.3 26-181
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
When passed an event A and an argument string B, this function
constructs an event message of the form
A <nodename> <timesstamp> B
By varying the event name and argument string, you can send
any event message desired. For example, to generate an
operator log out event message, you could call
tl_declare_event() with arguments of t_operator_logout
and 2 fred. This would generate the event message:
t_operator_logout <hostname> 9-jun-88_20:47:13 2 fred
where <hostname> is the node name of the tester’s computer.
ARGUMENTS event—a string containing the type of event to be sent.
Example: t_alive
args—a string containing any arguments to the event.
Example: 2 abc
RETURN VALUE -1 an error occurred
-1 the function was unable to send the event
0 the event was sent but no event dispatcher
was running (example: FIRMS not installed).
SIDE EFFECTS May invoke a subprocess for sending the message. May
generate a tl error or print error message if event fails.
tl_delay
Execute a delay.
SYNOPSIS void tl_delay(wtime)
register int wtime;
DESCRIPTION Execute a delay. Minimum delay is about 10µs. Accurate to
within 3µs or 0.1%, whichever is less.
ARGUMENTS Time to wait in 10µs units
RETURN VALUE None
tl_dfc_disable
Disable Device Focused Checker execution.
SYNOPSIS void tl_dfc_disable();
DESCRIPTION This function tells IMAGE to disable the Device Focused
Checker utility.
ARGUMENTS None
RETURN VALUE None
IMAGE Solutions V8.3 26-182
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Disables DFC execution.
SEE ALSO “tl_dfc_enable”
tl_dfc_enable
Enable Device Focused Checkers.
SYNOPSIS void tl_dfc_enable();
DESCRIPTION This function tells IMAGE to enable the Device Focused Checker
utility.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Enables DFC utility.
SEE ALSO “tl_dfc_disable”
tl_dfc_fail_run
Return true if DFC failed at last execution.
SYNOPSIS int tl_dfc_fail_run();
DESCRIPTION This function returns the value of the fail_last flag. This flag is
set to true if any instrument failed during the last DFC execution.
It is cleared at the start of the DFC run.
ARGUMENTS None
RETURN VALUE True if any DFC instrument failed during the last execution.
tl_dfc_inst_status
Return instrument status.
SYNOPSIS TL_DFC_STATUS tl_dfc_inst_status (inst_key)
TL_DFC_INST inst_key;
DESCRIPTION This function returns the status (Pass, Fail, NotRun, or Error)
for the given instrument.
ARGUMENTS inst_key—instrument to check
RETURN VALUE TL_DFC_STATUS (Pass, Fail, NotRun, or Error)
tl_dfc_request
Request Device Focused Checker execution.
SYNOPSIS void tl_dfc_request()
IMAGE Solutions V8.3 26-183
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function tells IMAGE to execute the DFC utility at the next
run. If the DFC utility is disabled, it does nothing.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS If DFC is enabled, it executes on the next run.
tl_disable_hp_after_rte_off
Turn off autodisable of handler or prober on a run time error (RTE).
SYNOPSIS int tl_disable_hp_after_rte_off(void);
DESCRIPTION This function turns off the autodisable of a handler or prober
when a run time error is encountered. If a run time error is
encountered during testing, the handler or prober will continue
testing.
ARGUMENTS None
RETURN VALUE 0—Handler or prober will be disabled if a run time error is
encountered
1—Handler or prober will not be disabled if a run time error is
encountered
SIDE EFFECTS Enables the feature which automatically disables a handler or
prober if a run time error is encountered.
tl_disable_hp_after_rte_on
Turns on autodisable of handler or prober on a run time error (RTE).
SYNOPSIS int tl_disable_hp_after_rte_on(void);
DESCRIPTION If a run time error (any run time error not being ignored) is
encountered during the run of a test program the handler or
prober is automatically disabled. To re-enable the handler or
prober, you must issue a handlerconf -enable ... command
for that station.
ARGUMENTS None
RETURN VALUE 1—Handler/prober will be disabled if a run time error is
encountered
0—Handler/prober will not be disabled if a run time error is
encountered
SIDE EFFECTS Enables the feature which automatically disables a handler or
prober if a run time error is encountered.
IMAGE Solutions V8.3 26-184
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_disable_hp_after_rte_state
Return the state of autodisable of handler or prober if a run time error occurs during a run.
SYNOPSIS int tl_disable_hp_after_rte_state(void)
DESCRIPTION Returns the state of the autodisable of a handler or prober if a run
time error is encountered during the run of a test program.
ARGUMENTS None
RETURN VALUE 0—Handler or prober will not be automatically disabled if a run
time error occurs during a run
1—Handler or prober will be automatically disabled if a run time
error occurs during a run.
tl_display_autosum_setup
Displays autosummary setup in station window.
SYNOPSIS int tl_display_autosum_setup();
DESCRIPTION Queries IMAGE regarding the setup of the autosummary and
displays the information in the station window. The output of this
command matches the output of the setauto -show command.
For more information regarding the setauto command, see
“Automatic Summary Reports Using the setauto Command” on
page 6-96.
ARGUMENTS None
RETURN VALUE False—error retrieving autosummary setup.
True—success retrieving autosummary setup.
tl_dlg_endwafer
Datalog end of wafer.
SYNOPSIS void tl_dlg_endwafer()
DESCRIPTION Declare the end of wafer event and construct and send the Wafer
Results Record (WRR) to dataserv.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Declares end of wafer event and puts WRR into datalog buffer.
tl_dlg_startwafer
Datalog start of wafer.
SYNOPSIS void tl_dlg_startwafer()
IMAGE Solutions V8.3 26-185
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Creates a Wafer Information Record (WIR) and writes it to the
datalog buffer. If this function is called before any tests are
executed, it simply returns. The function which datalogs IMAGE
static data (Master Information Record, Pin Map Record, and
other lot records) is responsible for writing the first WIR. This
ensures that it arrives at the datserv process in the correct
sequence and is not lost.
This function does not write the datalog buffer when the record
is written. This must be done manually using tl_dump_data().
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Declares start of wafer event and writes WIR into the datalog
buffer.
tl_dps_set_hotswitch_protection
Set test head relay delay flag and two kelvin flag.
SYNOPSIS void tl_dps_set_hotswitch_protection(delay_flag,
two_kelvin_flag)
int delay_flag;
int two_kelvin_flag;
DESCRIPTION This function gives you control over whether IMAGE waits for the
test head relays to open after executing an DPS disconnect
statement. If the delay_flag value passed to this function is
TRUE, IMAGE issues a delay to be sure the test head relays
have opened and avoid a possible hot switch. The
two_kelvin_flag tells IMAGE to allow/disallow connects with
two points of kelvin. This can also avoid a hotswitch in certain
situations.
With every DPS reset, these flags are reset to the default
settings:
delay_flag—FALSE
two_kelvin_flag—TRUE
ARGUMENTS int delay_flag
1—Issue delay to wait for relays to open.
0—No delay, just open relays. This is the default behavior
and could result in hot switching.
int two_kelvin_flag
1—Allow connects with two kelvin points. This is the
default behavior and could result in hot switching.
0—Disallow connects with two kelvin points
RETURN VALUE None
IMAGE Solutions V8.3 26-186
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Sets internal flags
tl_dsp_check_mem
Report on the DSP buffer and memory usage.
SYNOPSIS tl_dsp_check_mem()
DESCRIPTION This function dumps the current memory and buffer usage for the
array processor.
ARGUMENTS None
RETURN VALUE None
tl_dsp_dump_info
Print DSP memory and buffer information.
SYNOPSIS tl_dsp_dump_info();
DESCRIPTION This function dumps information regarding the DSP environment
in regard to memory and buffer use.
The number of available buffer handles varies depending on the
DSP engine.
Perm buffer names are always displayed as handle numbers.
Equiv buffer offsets are not shown.
The following shows an example of the output of this command:
% imm "tl_dsp_dump_info();"
DSP engine: MC860 array processor
Free array processor memory size = 3228.00k bytes (100.00%)
Permanent buffers exist: total size = 2.06k bytes (0.06% of free memory)
Temporary buffers exist: total size = 3.27k bytes (0.10% of free memory)
Available memory = 3222.67k bytes (99.83% of free memory)
Total available buffer handles: 128
---
Total currently free: 121
Number of temporary buffers: 4
Number of equivalent buffers: 2
Number of permanent buffers: 1
Buffer report
Buffer Type Class Size
------ ---- ----- ----
# 23731 real permanent 511 owner: station 1
AP_a real temporary 1
AP_b real temporary 1
IMAGE Solutions V8.3 26-187
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
APrbuf real temporary 512
APmagsbuf real temporary 256
APequiv complex equivalent 256 to buffer APrbuf
APf0 real equivalent 1 to buffer APmagsbuf
ARGUMENTS None
RETURN VALUE None
tl_dsp_get_buffer_address
Get the real memory address of the DSP buffer.
SYNOPSIS (void*)tl_dsp_get_buffer_address()
DSP_BUFFER buf;
DESCRIPTION This function retrieves the real memory address of a buffer when
running under the simulator or with an MC860. An error results if
executed when a ZIP3232 is present. You are expected to cast
the returned pointer to the appropriate type.
NOTE
Take care in using this address. None of the error checking built into the DSP environment
is available when operating on data through its pointer.
Remember to use tl_dsp_get_buffer_address() to establish
the memory pointer each time the program runs. This is true
even for permanent buffers.
Use tl_dsp_sync() before accessing data with any of the
pointers created using tl_dsp_get_buffer_address(). This
ensures that the data you retrieve is correct.
ARGUMENTS buf—the DSP buffer handle
RETURN VALUE The base pointer to the actual position in memory where the
DSP buffer data is stored
tl_dsp_get_mem_size
Report the size of usable data memory in bytes.
SYNOPSIS unsigned tl_dsp_get_mem_size()
DESCRIPTION Report the amount of data memory available to the user. Does
not take into account user allocated permanent buffers. Memory
size is
mem_size = tom - bom - dts - rf;
where:
IMAGE Solutions V8.3 26-188
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tom specifies the top of user memory
bom specifies the bottom of user memory
dts specifies the default fftwts table size
rf specifies a rounding factor used internally
The result can be used to allocate a buffer which just fits into
memory. If user-created permanent buffers exist, the allocation
fails. Note that permanent buffers created by any station causes
a failure since they remain allocated until explicitly deleted.
ARGUMENTS None
RETURN VALUE Unsigned memory size in bytes
tl_dsp_query_ap_type
Determine the type of DSP engine.
SYNOPSIS int tl_dsp_query_ap_type();
DESCRIPTION Return a value as defined in dspuser.h which indicates the type
of DSP engine currently being used.
ARGUMENTS None
RETURN VALUE See dspuser.h in $IMAGEBIN/itlh
tl_dsp_sync
Synchronize the test program and Array Processor.
SYNOPSIS int tl_dsp_sync()
DESCRIPTION Wait until the Array Processor has completed an operation that
has been queued so that an asynchronous operation will happen
correctly. This function is called automatically by certain IMAGE
language statements such as DSP buffer create and move.
ARGUMENTS None
RETURN VALUE None
tl_dump_configuration
Writes valid configuration file to destination file.
NAME tl_dump_configuration
SYNOPSIS void tl_dump_configuration(filename)
char *filename;
DESCRIPTION This function creates a configuration file to the filename specified
which includes current licenses configuration.
IMAGE Solutions V8.3 26-189
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS char *filename—Destination of configuration file
RETURN VALUE None
SIDE EFFECTS User configuration file is created.
tl_dump_data
Dump datalog buffer.
SYNOPSIS tl_dump_data()
DESCRIPTION This function flushes datalog for a test program. Normally,
datalog output is only dumped at the end of a program run. This
function (usually called using the immediate window) flushes all
the datalog output accumulated from a partial run. It is usually
called after hitting a trap, aborting, or otherwise pausing in a test
program run before the buffer is dumped.
Using tl_dump_data() in multisite test programs causes
indeterminate output results in the datalog window or file.
ARGUMENTS None
RETURN VALUE Returns 0 for successful dump, else -1
tl_edge_binary_search
Edge binary search.
SYNOPSIS double tl_edge_binary_search(
char *pattern_name,
char *start_vector_label,
char *pin_list[],
char *edgeset_list[],
int edge,
double from,
double to,
double resolution
);
DESCRIPTION The binary search uses a divide-by-two approach, halving the
endpoint delta (difference) for each search step.
A binary search starts by running the test for both the from value
and the to value. If the test results the same at these values then
the search is terminated (because there is no transition point).
If the test results at the extremes are different, the transition point
(the point in the search interval at which the Pass-Fail transition
occurs) is sought by successive halving of the search interval
IMAGE Solutions V8.3 26-190
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
with the search proceeding in the half of the bisected interval in
which the transition is found to occur.
A binary search is preferred over a linear search since the
pass/fail boundary can be found in fewer steps. This saves
program execution time, especially if the device size is large or
the programmed search resolution is small.
For example:
char *pin_list[] = { "PIN3", "1", NULL };
char *edgeset_list[] = { "ES2", "3", "ES4", NULL };
double pass_value;
pass_value = tl_edge_binary_search("minitd", "start_nrz", pin_list,
edgeset_list, TL_D2, 0.0, 3.0e-9, 1.0e-10);
ARGUMENTS pattern_name—pattern name for search.
start_vector_label—start vector label. NULL if start from the
beginning of the pattern.
pin_list—list of pin names or numbers for search, terminated
by NULL.
edgeset_list—list of edgeset names or numbers for search,
terminated by NULL.
edge—edge to search. Use TL_* (see itlh/hsd50.h)
from—search start value.
to—search end value.
resolution—resolution of the search.
RETURN VALUE TL_S_INVALID_VALUE if search is invalid, point of search
convergence otherwise.
tl_edge_linear_search
Edge linear search.
SYNOPSIS double tl_edge_linear_search(
char *pattern_name,
char *start_vector_label,
char *pin_list[],
char *edgeset_list[],
int edge,
double from,
double top,
double resolution
);
IMAGE Solutions V8.3 26-191
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION A linear search starts at one boundary and steps by the specified
resolution until the stop condition changes state. The linear
search algorithm allows the stop condition to be approached
either way: until a passing device starts failing, or until a failing
device starts passing. Once the stop condition changes state,
the search loop is terminated. The last pass parameter value is
returned.
In a linear search, the parameter is varied linearly in a stepwise
fashion.
A linear search has some disadvantages which must be kept in
mind when using it. If the resolution is small, the search can be
time-consuming because of the number of steps required. If the
parameter changes over time (due to device heating or other
factors), an inaccurate reading can result. If the device is failing
(or passing) over a large range, the entire search loop must be
run for several different points to reach this conclusion. The
algorithms which are better for most applications are the binary
search.
For example:
char *pin_list[] = { "PIN3", "1", NULL };
char *edgeset_list[] = { "ES2", "3", "ES4", NULL };
double pass_value;
pass_value = tl_edge_linear_search("minitd", "start_nrz", pin_list,
edgeset_list, TL_D2, 0.0, 3.0e-9, 1.0e-10);
ARGUMENTS pattern_name—Pattern name for search.
start_vector_label—Start vector label. NULL if start from the
beginning of the pattern.
pin_list—List of pin names or numbers for search, terminated
by NULL.
edgeset_list—List of edgeset names or numbers for search,
terminated by NULL.
edge—Edge to search. Use TL_* (see itlh/hsd50.h)
from—Search start value.
to—Search end value.
resolution—Resolution of the search.
RETURN VALUE TL_S_INVALID_VALUE if search is invalid, point of search
convergence otherwise.
IMAGE Solutions V8.3 26-192
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_efd_is_enabled
Determine if Enhanced Functional Datalog setups exist.
SYNOPSIS int tl_efd_is_enabled(void);
DESCRIPTION Used to determine if any Enhanced Functional Datalog setups
are active.
ARGUMENTS None
RETURN VALUE 0 if no enhanced functional datalog setups are currently active.
Otherwise, the number of active enhanced functional datalog
setups are returned.
tl_endlot
Close out the current lot and start a new lot.
SYNOPSIS int tl_endlot()
DESCRIPTION This function has the same effect as issuing the summary -auto
command from a station window. It closes out the current lot,
causes a summary report to be printed for that lot, and then
increments the lot ID (if the lot ID is numeric).
Note that sending a summary report to the printer and to an
STDF file is the default action for the setauto command, but you
can instead write to an ASCII file. For more information on doing
this, see “Automatic Summary Reports Using the setauto
Command” on page 6-96. If no parts have been tested in the
current lot, the auto endlot signal is ignored and no action is
taken.
This function is equivalent to doing an endlot (summary -final,
summary -auto, or setauto) from a station window or pressing
the END LOT button on the Start Switch. It increments the lot (or
sublot) number (if one exists) and generates a final summary
report for lot just closed.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_begin_lot”
tl_error_user
Define a user error message.
SYNOPSIS tl_error_user(umess, acode)
char * umess;
int acode;
IMAGE Solutions V8.3 26-193
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function can be used to define your own errors and call an
error function from a test program. This has the same effect as if
the system was handling a predefined run-time error. When this
function is executed, the error message you specify appears in
the error region and the action you specify is taken.
ARGUMENTS umess—A pointer to an error message you have defined.
acode—Action code that indicates the action you want the
system to take. The action codes are:
ERROR_FORCE_BIN—Bin the device in the error bin.
ERROR_FORCE_FAIL—Force the current test to fail.
ERROR_IGNORE—Ignore this error.
RETURN VALUE None
tl_exch_comment
Write comment to simulator stimulus stream
SYNOPSIS void tl_exch_comment(fmt, va_alist)
char *fmt;
va_dcl
DESCRIPTION This function writes a printf-style arguments to the simulator.
Each line in caller’s text is preceded by the comment character,
“#”. The caller will typically supply the trailing CR, but if the last
character in the string is not a CR, this function will append one.
Note that the text will appear in the output stream wherever the
simulator interface happens to be at the time. Because of the
buffering of events which depend on the real time of the
simulation, there is no guarantee that the comments will appear
near the output code for the program statements near the
tl_exch_comment() call.
ARGUMENTS fmt—printf format string variable arguments
RETURN VALUE None
SIDE EFFECTS Writes to previously opened output stream
SEE ALSO tl_exch_output
tl_exch_is_dvx_mode
Determine if ExChange is in DVX mode.
SYNOPSIS int tl_exch_is_dvx_mode()
DESCRIPTION This function is called to determine if ExChange is in DVX (Digital
VX) mode. In this mode, ExChange does not simulate analog
instrumentation.
IMAGE Solutions V8.3 26-194
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 1 if ExChange is in DVX mode; 0 if ExChange is not in DVX
mode.
SEE ALSO tl_exch_is_enabled
tl_exch_is_enabled
Determine if ExChange is enabled.
SYNOPSIS int tl_exch_is_enabled()
DESCRIPTION This function returns 1 if ExChange is enabled or 0 if ExChange
is not enabled.
RETURN VALUE 1 if ExChange is enabled; 0 if ExChange is not enabled.
SEE ALSO tl_exch_is_dvx_mode
tl_fflush_nowait
Execute fflush without resetting nowait mode.
SYNOPSIS int tl_fflush_nowait(FILE *iop)
DESCRIPTION This function executes the standard fflush only. An fflush
executed within a test program normally resets character nowait
mode if set. This would be used in a loop waiting for a
tl_read_char_nowait when the test program must output text
without \n.
ARGUMENTS iop—file pointer to a stream to flush
RETURN VALUE Same as fflush
tl_force_jobstats
Force test program statistics even on handler runs.
SYNOPSIS tl_force_jobstats()
DESCRIPTION This function enables printing of the “statistics” line following a
test program run (the bin number, execution time, and so on).
The default for test program runs is to print these statistics. They
are suppressed during handler runs and when a test program is
looping in “no messages” mode. You can use this function to turn
statistics back on in either of these cases.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Leaves job statistics on for subsequent runs.
IMAGE Solutions V8.3 26-195
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_fvs_cal_dump
Dump the FVS calibration table.
SYNOPSIS void tl_fvs_cal_dump(unit)
int unit;
DESCRIPTION Displays the Floating Voltage Source calibration table in the
station window.
ARGUMENTS unit—the FVS instrument number
RETURN VALUE None
tl_get_autocal_on
Return TRUE if autocal is on, FALSE if off.
SYNOPSIS int tl_get_autocal_on()
DESCRIPTION This function returns TRUE (nonzero) if the IMAGE
autocalibration feature is enabled and FALSE (zero) if it is
disabled.
ARGUMENTS None
RETURN VALUE int nonzero if autocal enabled
zero if autocal disabled
tl_get_autosetup
Retrieves setup information from data server.
SYNOPSIS int tl_get_autosetup(unsigned int key,
...)
DESCRIPTION This function determines the state of the autosummary setup. It
uses the same flags and parameters as
tl_set_autosummary(), except that these flags must be
followed by either the address of an unsigned integer or the
address of a character array. Set the integer variable to 0 or 1
depending on the state of the parameter preceding it. The
character buffer sets to the value represented by the flag. The
following code is an example of using this function and
determining the state of the autosummary setup:
char *filename = (char *) NULL,
*formatter = (char *) NULL,
*printername = (char *) NULL;
unsigned int stdf = 0,
file = 0,
statwin = 0,
printer = 0,
IMAGE Solutions V8.3 26-196
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
all_tests = 0,
fail_tests = 0,
autosmy_off = 0;
tl_get_autosetup(SETAUTO_FILE, &file, SETAUTO_STDF, &stdf,
SETAUTO_STATWIN, &statwin,
SETAUTO_AUTOSUM_OFF, &autosmy_off,
SETAUTO_PRINTER, &printer,
SETAUTO_FAIL_TESTS_ONLY, &fail_tests,
SETAUTO_ALL_TESTS, &all_tests,
SETAUTO_FILE_NAME, &filename,
SETAUTO_PRINTER_NAME, &printername,
SETAUTO_SMY_FORMATTER, &formatter,
NULL);
if (autosmy_off)
printf("Autosummary disabled and off.\n");
if (file || *filename)
printf("Auto summary will be written to file %s\n",
filename ? filename : " ");
if (printer || *printername)
printf("Auto summary to printer %s\n",
printername ? printername : " ");
if (stdf)
printf("Auto summary will be written to STDF.\n");
if (statwin)
printf("Auto summary will be written to Station Window.\n");
if (*formatter)
printf("Summaries will be formatted by: %s\n", formatter);
if (fail_tests)
printf("Failing tests will appear on summary reports.\n");
if (all_tests)
printf("All tests will appear on summary reports.\n");
In the above example, all possible parameters are queried and
the results displayed to the operator. It is not necessary to query
all parameters. You can also determine the state of only the
parameters which are of interest to you. For example, you could
determine whether the autosummary is on or off by the following
function call:
tl_get_autosetup(SETAUTO_AUTOSUM_OFF, &autosmy_off, NULL);
if (autosmy_off)
printf("Autosummary disabled and off.\n");
else
printf("Autosummary enabled.\n");
To determine whether autosummaries will be written to the
station window, use the following function call:
tl_get_autosetup(SETAUTO_STATWIN, &statwin, NULL);
IMAGE Solutions V8.3 26-197
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
if (statwin)
printf("Auto summary output to Station Window.\n");
ARGUMENTS The following table summarizes the type of argument which must
follow each parameter. The argument must be terminated by
NULL.
Parameter Argument Type
--------------- ----------------------
SETAUTO_STATWIN unsigned int *
SETAUTO_STDF unsigned int *
SETAUTO_FILE unsigned int *
SETAUTO_FILE_NAME char **
SETAUTO_PRINTER unsigned int *
SETAUTO_PRINTER_NAME char **
SETAUTO_SMY_FORMATTER char **
SETAUTO_AUTOSUM_OFF unsigned int *
SETAUTO_FAIL_TESTS_ONLY unsigned int *
RETURN VALUE 0 false—error getting autosummary setup. 1 true—
autosummary setup successfully retrieved.
SEE ALSO “tl_set_autosummary”, “tl_display_autosum_setup”
tl_get_burn_tim
Get the burn-in time of the parts being tested.
SYNOPSIS int tl_get_burn_tim()
DESCRIPTION This function returns the burn-in time of the parts being tested
and returns them as an integer representing the number of
minutes the parts were burnt in.
ARGUMENTS None
RETURN VALUE Integer number of minutes of burn-in time.
tl_get_cabl_id
Get the interface cable ID of the parts being tested.
SYNOPSIS char * tl_get_cabl_id(s)
char s[];
DESCRIPTION This function returns the interface cable ID of the parts being
tested as a string.
ARGUMENTS An array in which to place the interface cable ID string
RETURN VALUE Its argument (the interface cable ID string)
IMAGE Solutions V8.3 26-198
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_get_cabl_typ
Get the interface cable type of the parts being tested.
SYNOPSIS char * tl_get_cabl_typ(s)
char s[];
DESCRIPTION This function returns the interface cable type of the parts being
tested as a string.
ARGUMENTS An array in which to place the interface cable type string
RETURN VALUE Its argument (the interface cable type string)
tl_get_cont_id
Get the contactor ID of the parts being tested.
SYNOPSIS char * tl_get_cont_id(s)
char s[];
DESCRIPTION This function returns the contactor ID of the parts being tested as
a string.
ARGUMENTS An array in which to place the contactor ID string
RETURN VALUE Its argument (the contactor ID string)
tl_get_cont_typ
Read the contactor type of the parts being tested.
SYNOPSIS char * tl_get_cont_typ(s)
char s[];
DESCRIPTION This function returns the contactor type of the parts being tested
as a string.
ARGUMENTS An array in which to place the contactor type string
RETURN VALUE Its argument (the contactor type string)
tl_get_data_collection_state
Return the state of data collection.
SYNOPSIS int tl_get_data_collection_state()
DESCRIPTION This function evaluates the current state of data collection and
returns a value based on this state. It returns the appropriate
values regardless of what form of data collection is being used—
datalog, datastream, or histogram. Be careful in placing the call
to this function. For example, if you place this function in a test
function following a call to set testf_cond: datalog:
IMAGE Solutions V8.3 26-199
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
disable, this function returns a value indicating that data
collection is disabled. This return may be misleading since data
collection will only be disabled for the current test function and
may be enabled elsewhere.
ARGUMENTS None
RETURN VALUE 0 Data collection is off. For example by using datalog -off
(or datastream -on...) or by never having turned anything on
in the first place.
1 Data collection is on and enabled.
2 Data collection is disabled. This can be done by disabling
data collection by either using the set
testf_cond:datalog:enable | disable statement in a test
function or by calling tl_set_dlg_enable() and passing it a
value disabling datalogging.
SEE ALSO set testf_cond statement (“Changing the Default Behavior of
a Test Statement” on page 14-21) and “tl_set_dlg_enable”
tl_get_data_collection_streams
Get names/IDs of currently enabled data collection streams.
SYNOPSIS char **tl_get_data_collection_streams()
DESCRIPTION This function uses the list of currently enabled data collection
streams returned by tl_update_data_collection_state() to
create an array of pointers to the names/IDs of the streams.
Datalog streams are identified by the following macros:
TL_DATALOG_STATWIN—datalog to station window
TL_DATALOG_DATAWIN—datalog to datalog window
TL_DATALOG_STDF—datalog to STDF file
TL_DATALOG_FILE—datalog to text file
TL_DATALOG_PRINTER—datalog to printer
TL_HISTOGRAMMING—histogram stream
Note that these macros represent character strings and must be
compared using string comparison functions, such as strcmp()
or strncmp().
In the case of data streams, stream ID is returned.
Do not free the memory associated with the return. The memory
will be freed on subsequent function calls.
ARGUMENTS None
RETURN VALUE (char **) NULL—if no streams are enabled or
tl_update_data_collection_state() has not been called or
a memory allocation error occurred.
IMAGE Solutions V8.3 26-200
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
If successful, this function returns a NULL terminated array of
pointers to character strings, which are the stream names/IDs.
SIDE EFFECTS Creates an array of stream names.
tl_get_datalog
Get information regarding setup of datalog.
SYNOPSIS int tl_get_datalog(unsigned int key, ...)
DESCRIPTION This function accepts a variable number of arguments which
consist of keyword and address pairs. Each keyword indicates
the type of information requested and each address is a pointer
to a character string, a pointer to an unsigned integer variable, or
a pointer to an array of either type. The list of arguments must be
NULL terminated. That is, the last element must be zero. When
this value is read processing stops.
The table in the ARGUMENTS section shows each flag valid for
tl_get_datalog() and the value of the argument that should
accompany it.
Each time this function is called, a command is sent to IMAGE
for the test plan and the datalog information is updated. When
using this function only call it once per set of options requested.
That is, do not make two separate calls to get datalog criteria and
datalog output. Do this in one call. For example:
unsigned int datalog_crit, datalog_output;
Do not do this:
tl_get_datalog(TL_DLG_OUTPUT, &datalog_output, NULL);
tl_get_datalog(TL_DLG_TEST, &datalog_crit, NULL);
Do this:
tl_get_datalog(TL_DLG_OUTPUT, &datalog_output,
TL_DLG_TEST, &datalog_crit, NULL);
Although unlikely, the datalog setup can change between
tl_get_datalog() calls. In the first example, this could occur if
someone is changing datalog criteria, using the datalog display
or the datalog command, when the commands are executed.
If IMAGE is busy (that is, processing data from the previous test
program run) this function waits until IMAGE is free.
The flag returned by TL_DLG_TEST can be used to determine
what testing criteria is being used and also to determine if some
options have been selected:
Test list used
List of test names used
IMAGE Solutions V8.3 26-201
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
List of sequencer names used
Test range or limits selected
Wafer map sample datalog selected
The list of test names and sequencer names if used can be
retrieved using TL_DLG_TEST_NAME and TL_DLG_SEQ_NAME.
Pass the address of a pointer to type (char **, which can be
thought of as an array of pointers) to tl_get_datalog() and if
test names or sequencer names are being used the pointer
returned will be non-NULL. Never use the memory returned for
anything other than getting names and do not free it. IMAGE
manages this memory.
Likewise, do not free any other memory returned or use it for any
purpose other than viewing the name. The contents of the
memory (and the memory itself) are valid until the next call to
tl_get_datalog().
ARGUMENTS A variable number of argument pairs consisting of a keyword and
a pointer. The pointer can be a pointer to an unsigned int, a
pointer to an unsigned int array, a pointer to a character string,
or a pointer to an array of character strings. The argument list
must be terminated by NULL.
Keyword Data Type Macros to Access
------------ ------------------ ------------------------
TL_DLG_STATE unsigned int * TL_DLG_ON
TL_DLG_OFF
TL_DLG_OUTPUT unsigned int * TL_DLG_O_STATWIN
TL_DLG_O_DWIN
TL_DLG_O_STDF
TL_DLG_O_FILE
TL_DLG_O_PRINTER
TL_DLG_O_HISTO
TL_DLG_TEST unsigned int * TL_DLG_PASS_TEST
TL_DLG_FAIL_TEST
TL_DLG_ALL_TEST
TL_DLG_ANALOG_TEST
TL_DLG_DIGITAL_TEST
TL_DLG_TEST_LIST_SEL
TL_DLG_TEST_FILE_SEL
TL_DLG_TEST_RNG_SEL
TL_DLG_TEST_NAME_SEL
TL_DLG_SEQ_NAME_SEL
TL_DLG_SAMP_RATE_SEL
TL_DLG_SAMP_LIMIT_SEL
TL_DLG_WAFER_MAP_SEL
IMAGE Solutions V8.3 26-202
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
TL_DLG_PIN_OUTPUT unsigned int * TL_DLG_PIN_NAMES
TL_DLG_PIN_NUMBERS
TL_DLG_TEST_RNG unsigned int **
TL_DLG_TEST_LIST unsigned int **
TL_DLG_TEST_NAME char ***
TL_DLG_SEQ_NAME char ***
TL_DLG_STDF_NAME char **
TL_DLG_FILE_NAME char **
TL_DLG_PRINTER_NAME char **
TL_DLG_SAMP_RATE unsigned int *
TL_DLG_SAMP_LIMIT unsigned int *
TL_DLG_OUTPUT_FMT char **
RETURN VALUE 0—Error. Any values returned through the argument list are
considered invalid.
1—Success. Values returned through the argument list can be
valid depending on datalog setup.
SIDE EFFECTS Sends a command to IMAGE to retrieve the datalog setup.
SEE ALSO Description of tl_get_datalog in “Retrieving Datalog Setup
Information” on page 6-68 and “tl_set_datalog”
tl_get_datalog_directory
Get the name of the directory which dataserv is writing datalog files to.
SYNOPSIS char *tl_get_datalog_directory(int update);
DESCRIPTION The first time this function is called it sends a command to
dataserv and retrieves the default directory where datalog and
datastream files are being written. This is the general default. It
will not return the directory a specific file is being written to if you
specified a full path name.
Once the directory is established, the function returns a pointer
to static storage containing the directory. This memory must not
be freed.
You can force the function to override the datalog directory set
by a previous call by passing in a non-zero argument. If this
argument is nonzero, a command is sent to dataserv which gets
the latest information, in the event the production datalog
directories were modified during the program run.
If tl_update_data_collection_state() was called before
this function, the argument passed in can be 0, since the datalog
directory is already set.
IMAGE Solutions V8.3 26-203
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS update—if this variable is nonzero, it forces sending a command
to dataserv to update the datalog directory.
RETURN VALUE (char *) NULL—Errors getting directory from dataserv
otherwise a pointer to the default datalog directory.
SIDE EFFECTS Sets datalog directory.
tl_get_datalog_directory_for_stream
Get directory a stream is writing a file to.
SYNOPSIS char * tl_get_datalog_directory_for_stream
(char *sname);
DESCRIPTION This function looks at the filename associated with a file based
stream (either text or STDF) and returns NULL if the stream does
not exist or the stream is not writing a file.
The stream filename is parsed and the directory path associated
with it, if any, is returned. If the filename is not fully rooted, the
default datalog directory is returned, which is where the file is
written if not fully rooted.
If this information must be saved, be sure to copy it to some other
storage, as subsequent calls to this function will overwrite the
memory returned.
ARGUMENTS sname—stream name.
RETURN VALUE char * NULL—stream does not exist or is not file-based.
tl_get_datastream
Get information regarding setup of datastream
SYNOPSIS int tl_get_datastream(unsigned int key, ...);
DESCRIPTION This function will accept a variable number of arguments which
consist of keyword and address pairs. Each keyword indicates
the type of information requested and each address is a pointer
to a character string, a pointer to an unsigned integer variable, or
a pointer to an array of either type.
The list of arguments must be NULL terminated, that is the last
element must be zero. When this value is read processing will
stop.
The table in the ARGUMENTS section show each flag that is
valid for tl_get_datastream() and the value of the argument that
should accompany it.
IMAGE Solutions V8.3 26-204
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Each time the tl_get_datastream() function is called, a command
is sent to the dataserv for the test plan and the stream
information is updated. When using this function it should only be
called once per set of options requested. That is, don't make two
separate calls to get datastream criteria and datastream
program name . Do this in one call. For example:
unsigned int stream_crit;
char *program_name;
Instead of:
tl_get_datastream(TL_DSTRM_ID, "streamname",
TL_DSTRM_PROG_NAME, &program_name, NULL);
tl_get_datastream(TL_DSTRM_ID, "streamname",
TL_DSTRM_TEST, &stream_crit, NULL);
do:
tl_get_datastream(TL_DSTRM_ID, "streamname",
TL_DSTRM_PROG_NAME, &program_name, TL_DSTRM_TEST,
&stream_crit, NULL);
Although unlikely, it is possible for the datastream setup to
change between tl_get_datastream calls. In the first example,
this could occur if someone is changing datastream criteria,
using the datalog display or the datastream command, when
the commands are executed.
If the data server is busy, that is processing data from the
previous test program run, this function waits until the data
server is free.
The flag returned by TL_DSTRM_TEST can be used to determine
what testing criteria is being used, and also to determine if some
options have been selected:
- Test list used
- List of test names used
- List of sequencer names used
- Test range or limits selected
- Wafer map sample datalog selected
The list of test names and sequencer names if used can be
retrieved using: TL_DSTRM_TEST_NAME and
TL_DSTRM_SEQ_NAME.
Pass the address of a pointer to type (char **, which can be
thought of as an array of pointers) to tl_get_datastream and if
test names or sequencer names are being used the pointer
IMAGE Solutions V8.3 26-205
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
returned will be non-NULL. Under any circumstances, do not use
the memory returned for anything other than getting the names
and do not free it. IMAGE manages this memory.
Likewise, any other memory returned should not be freed or
used for any purpose other than viewing the name. The contents
of the memory (and the memory itself) will be valid until the next
call to tl_get_datastream.
ARGUMENTS A variable number of argument pairs consisting of a keyword and
a pointer. The pointer can be a pointer to an unsigned int, a
pointer to an unsigned int array, a pointer to a character string,
or a pointer to an array of character strings.
The argument list must be terminated by NULL and must contain
TL_DSTRM_ID.
Table 26-4 lists the arguments to the tl_get_datastram
command.
Table 26-4. Arguments to the tl_get_datastream command
Keyword Data Type Macros to Access
TL_DLG_FILE_NAME char **
TL_DLG_PRINTER_NAME char **
TL_DSTRM_ID char *
TL_DSTRM_LKG_PINS unsigned int TL_DSTRM_LKG_ALL_PINS
TL_DSTRM_LKG_FAIL_PINS
TL_DSTRM_LKG_STATE unsigned int TL_DSTRM_LKG_OFF
TL_DSTRM_LKG_ALL
TL_DSTRM_LKG_FAIL
TL_DSTRM_OPEN_SHORT_PINS unsigned int TL_DSTRM_OPEN_SHORT_ALL_PINS
TL_DSTRM_OPEN_SHORT_FAIL_PINS
TL_DSTRM_OPEN_SHORT_STATE unsigned int TL_DSTRM_OPEN_SHORT_OFF
TL_DSTRM_OPEN_SHORT_ALL
TL_DSTRM_OPEN_SHORT_FAIL
TL_DSTRM_SAMP_LIMIT unsigned int *
TL_DSTRM_SAMP_RATE unsigned int *
TL_DSTRM_SEQ_NAME char ***
TL_DSTRM_STATE unsigned int * TL_DSTRM_ON
TL_DSTRM_OFF
IMAGE Solutions V8.3 26-206
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Table 26-4. Arguments to the tl_get_datastream command (Continued)
Keyword Data Type Macros to Access
TL_DSTRM_STDF_MODE unsigned int * TL_DSTRM_S_MODE_LIGHT
TL_DSTRM_S_MODE_HEAVY
TL_DSTRM_S_MODE_XLIGHT
TL_DSTRM_STDF_NAME char **
TL_DSTRM_TEST unsigned int * TL_DSTRM_PASS_TEST
TL_DSTRM_FAIL_TEST
TL_DSTRM_ALL_TEST
TL_DSTRM_ANALOG_TEST
TL_DSTRM_DIGITAL_TEST
TL_DSTRM_TEST_LIST_SEL
TL_DSTRM_TEST_FILE_SEL
TL_DSTRM_TEST_RNG_SEL
TL_DSTRM_TEST_NAME_SEL
TL_DSTRM_SEQ_NAME_SEL
TL_DSTRM_SAMP_RATE_SEL
TL_DSTRM_SAMP_LIMIT_SEL
TL_DSTRM_WAFER_MAP_SEL
TL_DSTRM_TEST_LIST unsigned int **
TL_DSTRM_TEST_NAME char ***
TL_DSTRM_TEST_RNG unsigned int **
RETURN VALUE 0 - Error: Any values returned through the argument list are
considered invalid.
1 - Success: Values returned through the argument list may be
valid depending on datalog setup.
SIDE EFFECTS Sends a command to the data server to retrieve the datastream
setup.
SEE ALSO “Data Collection” on page 6-1, tl_add_datastream,
tl_set_datalog.
tl_get_degrees_d
Convert a double value from radians to degrees.
SYNOPSIS double tl_get_degrees_d(radian)
double radian;
DESCRIPTION This function takes any double precision value representing
radians and returns the equivalent value in degrees.
ARGUMENTS radian—the value in radians to be converted to degrees
IMAGE Solutions V8.3 26-207
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE A double from 0 through 360 representing degrees
tl_get_degrees_f
Convert a float value from radians to degrees.
SYNOPSIS float tl_get_degrees_f(radian)
float radian;
DESCRIPTION This function takes any floating point value representing radians
and returns the equivalent value in degrees.
ARGUMENTS radian—the value in radians to be converted to degrees
RETURN VALUE A floating point number from 0 through 360 representing degrees
tl_get_dib_id
Get the DIB board type of the parts being tested.
SYNOPSIS char * tl_get_dib_id(s)
char s[];
DESCRIPTION This function returns the DIB ID of the parts being tested as a
string.
NOTE
For this function to return a meaningful value, one of the following must first occur:
-The first part has been datalogged.
-The program explicitly has called tl_read_and_set_dib_info().
-The program explicitly has called tl_set_dib_id().
If the IMAGE Behavior Chooser option
IBC_ACCURATE_EEPROM_STRINGS is disabled, this function
returns a pointer to a NULL string.
ARGUMENTS An array in which to place the DIB ID string
RETURN VALUE Its argument (the DIB ID string)
SEE ALSO “tl_get_dib_typ”, “tl_read_and_set_dib_info”, “tl_set_dib_id”
tl_get_dib_typ
Get the DIB board type of the parts being tested.
SYNOPSIS char * tl_get_dib_typ(s)
char s[];
IMAGE Solutions V8.3 26-208
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns the DIB board type of the parts being tested
as a string.
ARGUMENTS An array in which to place the DIB board type string
RETURN VALUE Its argument (the DIB board type string)
SEE ALSO “tl_get_dib_id”, “tl_read_and_set_dib_info”
tl_get_dsgn_rev
Get the device design revision of the parts being tested.
SYNOPSIS char * tl_get_dsgn_rev(s)
char s[];
DESCRIPTION This function returns the design revision of the parts being tested
as a string.
ARGUMENTS An array in which to place the design revision string.
RETURN VALUE Its argument (the design revision string)
tl_get_eng_id
Get the engineering lot ID of the parts being tested.
SYNOPSIS char * tl_get_eng_id(s)
char s[];
DESCRIPTION This function returns the engineering lot ID of the parts being
tested as a string.
ARGUMENTS An array in which to place the engineering lot ID string
RETURN VALUE Its argument (the engineering lot ID string)
tl_get_extr_id
Read the extra equipment ID of the parts being tested.
SYNOPSIS char * tl_get_extr_id(s)
char s[];
DESCRIPTION This function reads the extra equipment ID of the parts being
tested as a string.
ARGUMENTS An array in which to place the extra equipment ID string
RETURN VALUE Its argument (the extra equipment ID string)
tl_get_extr_typ
Get the extra equipment type of the parts being tested.
IMAGE Solutions V8.3 26-209
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS char * tl_get_extr_typ(s)
char s[];
DESCRIPTION This function returns the extra equipment type of the parts being
tested as a string.
ARGUMENTS An array in which to place the extra equipment type string
RETURN VALUE Its argument (the extra equipment type string)
tl_get_facil_id
Get the test facility ID of the parts being tested.
SYNOPSIS char * tl_get_facil_id(s)
char s[];
DESCRIPTION This function returns the test facility ID of the parts being tested
as a string.
ARGUMENTS An array in which to place the testing facility ID string
RETURN VALUE Its argument (the testing facility ID string)
tl_get_famly_id
Get the device family ID of the parts being tested.
SYNOPSIS char * tl_get_famly_id(s)
char s[];
DESCRIPTION This function returns the device family ID of the parts being
tested as a string.
ARGUMENTS An array in which to place the device family ID string
RETURN VALUE Its argument (the device family ID string)
tl_get_floor_id
Get the test floor ID of the parts being tested.
SYNOPSIS char * tl_get_floor_id(s)
char s[];
DESCRIPTION This function returns the test floor ID of the parts being tested as
a string.
ARGUMENTS An array in which to place the test floor ID string
RETURN VALUE Its argument (the test floor ID string)
IMAGE Solutions V8.3 26-210
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_get_flow_id
Get the test_flow ID of the parts being tested.
SYNOPSIS char * tl_get_flow_id(s)
char s[];
DESCRIPTION This function returns the test flow ID of the parts being tested as
a string.
ARGUMENTS An array in which to place the test flow ID string
RETURN VALUE Its argument (the test flow ID string)
tl_get_hbin_device_count
Return the device count for the desired hardware bin.
SYNOPSIS int tl_get_hbin_device_count(hbin)
int hbin;
DESCRIPTION This function returns the device count of the given hardware bin
as of the last device(s) tested. It does not include the current
device(s), even if it is used after the sort bin statement.
ARGUMENTS hbin—Hardware bin for device count
RETURN VALUE Number of devices in the specified bin.
SEE ALSO “tl_get_sbin_device_count”
tl_get_hp_name
Get the name of the handler or prober.
SYNOPSIS int tl_get_hp_name(char * name)
DESCRIPTION Returns the name of the handler or prober being used in the
current lot using the function argument. Unless set using
tl_set_hp_name(), this is the name used in the last
handlerconf -connect <handler_name> command.
ARGUMENTS name—A pointer to a character buffer. It is the caller’s
responsibility to allocate enough memory to accommodate the
entire length of the handler or prober name. If the name has not
been set or you have set the value to NULL, the return is a NULL
string. That is, the first element of the character buffer is a NULL
character (\0).
RETURN VALUE 0—failure, the argument is NULL
1—name successfully copied
SIDE EFFECTS May copy name to user’s buffer.
SEE ALSO “tl_set_hp_name”, “tl_set_hp_type”, “tl_get_hp_type”
IMAGE Solutions V8.3 26-211
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_get_hp_type
Get the name of the handler or prober.
SYNOPSIS int tl_get_hp_type(char * type)
DESCRIPTION This function returns the name of the handler or prober being
used in the current lot using the function argument. Unless set
using tl_set_hp_type(), this is e the name used in the last
handlerconf -connect <handler_name> command.
ARGUMENTS type—A pointer to a character buffer. It is the caller’s
responsibility to allocate enough memory to accommodate the
entire length of the handler or prober name. If the name has not
been set or you have set the value to NULL, the return is a NULL
string. That is, the first element of the character buffer is a NULL
character (\0).
RETURN VALUE 0—failure, the argument is NULL
1—name successfully copied
SIDE EFFECTS May copy type to user’s buffer.
SEE ALSO “tl_set_hp_type”, “tl_set_hp_name”, “tl_get_hp_name”
tl_get_hsd_type
Return type of digital subsystem.
SYNOPSIS int tl_get_hsd_type()
DESCRIPTION This function returns the setup type of the digital subsystem or -
1 if there is no digital subsystem or its type could not be
determined.
ARGUMENTS None
RETURN VALUE One of the macros defined in hsd50.h for this function.
Commonly used values include:
TL_HSD50_25 HSD25 (HSD50 architecture with 25 MHz
clock)
TL_HSD50_50 Standard HSD50
TL_CAT_100 Standard Catalyst digital
If none of these is correct -1 is returned.
tl_get_inker
Retrieve the inker number to fire when a bin result is received on a site.
SYNOPSIS int tl_get_inker(int stn, int site, int bin)
IMAGE Solutions V8.3 26-212
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function references the inker map for stn and returns the
inker number to fire when a particular bin result bin is received
on site. If no inker map is created, a 0, is returned. This result
will not fire any inker.
ARGUMENTS stn—Station number
site—site number
bin—bin result
RETURN VALUE Inker number to fire.
tl_get_lasr_id
Get the laser ID of the parts being tested.
SYNOPSIS char * tl_get_lasr_id(s)
char s[];
DESCRIPTION This function reads the laser ID of the parts being tested as a
string.
ARGUMENTS An array in which to place the laser ID string
RETURN VALUE Its argument (the laser ID string)
tl_get_lasr_typ
Get the laser_type of the parts being tested.
SYNOPSIS char * tl_get_lasr_typ(s)
char s[];
DESCRIPTION This function returns the laser type of the parts being tested as a
string.
ARGUMENTS An array in which to place the laser type string
RETURN VALUE Its argument (the laser type string)
tl_get_last_seq_bin
Get bin number for last sequencer.
SYNOPSIS int tl_get_last_seq_bin();
DESCRIPTION This function returns the bin assignment in the last sequencer by
either a fail or pass clause (f() or p()). If called from within a
sequencer, it returns the bin assignment from that sequencer.
The value returned is not affected by the test results from any
previously called sequencers. If there are bin assignments in a
sequencer, the returned value is the bin number of the first
assignment. In a multisite test program, call this function only
from inside a serial block.
IMAGE Solutions V8.3 26-213
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS None
RETURN VALUE The first bin number assigned by the last sequencer.
NO_BINNING is returned if no bin number was assigned by the
last sequencer.
SEE ALSO “tl_get_seq_bin”
tl_get_load_id
Get the load board ID of the parts being tested.
SYNOPSIS char * tl_get_load_id(s)
char s[];
DESCRIPTION This function returns the load board ID of the parts being tested
as a string.
ARGUMENTS An array in which to place the load board ID string
RETURN VALUE Its argument (the load board ID string)
tl_get_load_path
Convert a filename into a full path name.
SYNOPSIS char * tl_get_load_path(<filename>)
char * filename;
DESCRIPTION Use this function to reference files without embedding full path
names in test programs. By mentioning the filename in a .load
file, this function constructs the full path name by adding the path
portion of the .load file name.
For example, you load a test program using a .load file in the
directory /usr/hrod/mpq and the .load file includes
data/values.dat. tl_get_load_path("values.dat")
returns:
/usr/hrod/mpq/data/values.dat
ARGUMENTS filename—the name of a file (usually without a leading path)
RETURN VALUE Full path of filename—if filename was mentioned in .load file
filename—if not mentioned in .load file
NULL—if filename includes a leading path component and there
is a conflict between that and the path name from the .load file
tl_get_load_typ
Get the load board type of the parts being tested.
SYNOPSIS char * tl_get_load_typ(s)
char s[];
IMAGE Solutions V8.3 26-214
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns the load board type of the parts being tested
as a string.
ARGUMENTS An array in which to place the load board type string
RETURN VALUE Its argument (the load board type string)
tl_get_number_of_testheads
Get the number of test heads.
SYNOPSIS int tl_get_number_of_testheads();
DESCRIPTION Returns the number of test heads on the system. When running
on a tester, this is the number of test heads the system controls.
When running on a simulator,
tl_get_number_of_testheads() returns the maximum
number of test heads for the type of tester being simulated.
ARGUMENTS None.
RETURN VALUE The number of test heads on the system.
tl_get_oper_frq
Get the test operation frequency of the parts being tested.
SYNOPSIS char * tl_get_oper_frq(s)
char s[];
DESCRIPTION This function returns the test operation frequency of the parts
being tested as a string.
ARGUMENTS An array in which to place the test operation frequency string
RETURN VALUE Its argument (the test operation frequency string)
tl_get_part_datalogged
Returns if the current set of parts will be datalogged in the standard datalog outputs.
SYNOPSIS int tl_get_part_datalogged()
DESCRIPTION This function returns 1 (TRUE) if the current set of parts for this
run of the test program will be datalogged in the standard datalog
outputs. It returns 0 (FALSE) if the current set of parts will not be
datalogged. Datastreams set up using the datastream
command or from the datastream setup window are not covered
by this function.
ARGUMENTS None
RETURN VALUE 1 (TRUE) if the current set of parts will be datalogged
0 (FALSE) if the current set of parts will not be datalogged
IMAGE Solutions V8.3 26-215
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “tl_set_part_datalogged”
tl_get_pkg_typ
Get the package type of the parts being tested.
SYNOPSIS char * tl_get_pkg_typ(s)
char s[];
DESCRIPTION This function returns the package type of the parts being tested
as a string.
ARGUMENTS An array in which to place the package type string
RETURN VALUE Its argument (the package type string)
tl_get_prb_card
Get the probe card ID of the parts being tested.
SYNOPSIS char * tl_get_prb_card(s)
char s[];
DESCRIPTION This function returns the probe card ID of the parts being tested
as a string.
Note: For this function to return a meaningful value, one of the
following must first occur:
-The first part has been datalogged.
-The program explicitly has called
tl_read_and_set_prb_info().
-The program explicitly has called tl_set_prb_card().
If the IMAGE Behavior Chooser option
IBC_ACCURATE_EEPROM_STRINGS is disabled, this function
returns a pointer to a NULL string.
ARGUMENTS An array in which to place the probe card ID string
RETURN VALUE Its argument (the probe card ID string)
SEE ALSO “tl_get_prb_typ”, “tl_read_and_set_prb_info”, “tl_get_prb_card”
tl_get_prb_typ
Get the probe card type of the parts being tested.
SYNOPSIS char * tl_get_prb_typ(s)
char s[];
DESCRIPTION This function returns the probe card type of the parts being
tested as a string.
ARGUMENTS An array in which to place the probe card type string
IMAGE Solutions V8.3 26-216
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Its argument (the probe card type string)
SEE ALSO “tl_read_and_set_prb_info”, “tl_set_prb_card”
tl_get_prog_nam_fullpath
Get the fully rooted path name of the test program.
SYNOPSIS int tl_get_prog_nam_fullpath(char *)
DESCRIPTION Copies the full path name of the test program to the storage
pointed to by argument and returns an error code.
ARGUMENTS Pointer to storage for test program with full path name. Allocate
MAXPATHLEN bytes for storage. MAXPATHLEN is defined in
<sys/param.h>.
RETURN VALUE 0 Unsuccessful
1 Successful
tl_get_radians_d
Convert a double value from degrees to radians.
SYNOPSIS double tl_get_radians_d(degree)
double degree;
DESCRIPTION This function takes any double precision value representing
degrees and returns the equivalent value in radians.
ARGUMENTS degree—the value in degrees to be converted to radians
RETURN VALUE A double from 0 through 2π representing radians
tl_get_radians_f
Convert a float value from degrees to radians.
SYNOPSIS float tl_get_radians_f(degree)
float degree;
DESCRIPTION This function takes any floating point value representing degrees
and returns the equivalent value in radians.
ARGUMENTS degree—the value in degrees to be converted to radians
RETURN VALUE A floating point number from 0 through 2π representing radians
tl_get_sbin_device_count
Return the device count for the desired software bin.
SYNOPSIS int tl_get_sbin_device_count(sbin)
int sbin;
IMAGE Solutions V8.3 26-217
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns the device count of the given software bin
as of the last device(s) tested. It does not include the current
device(s) even if it is used after the sort bin statement.
ARGUMENTS int sbin—Software bin for device count
RETURN VALUE Number of devices in the specified bin.
SEE ALSO “tl_get_hbin_device_count”
tl_get_seq_bin
Get the sequencer bin number for a site.
SYNOPSIS int tl_get_seq_bin();
DESCRIPTION This function returns the bin number assigned, if any, in a
sequencer by either a fail or pass clause (f() or p()). Fail bins
override pass bins, so if a failure occurs, this will be the first
failure in the test program. However, executing a set
site_enable allows a subsequent pass or fail to reassign a bin
number.
The bin number returned by this function is the same as the bin
that would be assigned if a sort bin statement were to be
executed at that point in the test program.
Example:
<start of program>
tl_get_seq_bin() returns NO_BINNING
SEQUENCER ... <test passes> p(1)
tl_get_seq_bin() returns 1
SEQUENCER ... <test fails> f(2)
tl_get_seq_bin() returns 2
SEQUENCER ... <test passes> p(1)
tl_get_seq_bin() returns 2
set site_enable_all;
tl_get_seq_bin() returns 2
SEQUENCER ... <test passes> p(1)
tl_get_seq_bin() returns 1
SEQUENCER ... <test fails> f(3)
tl_get_seq_bin() returns 3
SEQUENCER ... <test fails> f(4)
tl_get_seq_bin() returns 3
In a multisite test program, call this function only from inside a
serial block. In a multisite test program, the bin number for a
disabled site can only be obtained by re-enabling the site using
the set site_enable statement.
ARGUMENTS None
IMAGE Solutions V8.3 26-218
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE The current bin assignment
NO_BINNING is returned if no bin number has been assigned.
NO_BINNING is also returned inside a serial loop in a multisite test
program for the site which was just disabled and is no longer
active.
SEE ALSO “tl_get_last_seq_bin”
tl_get_setup_id
Get the test setup ID of the parts being tested.
SYNOPSIS char * tl_get_setup_id(s)
char s[];
DESCRIPTION This function returns the test setup ID of the parts being tested
as a string.
ARGUMENTS An array in which to place the test setup ID string
RETURN VALUE Its argument (the test setup ID string)
tl_get_slot_from_pin
Return test head slot number from pin.
SYNOPSIS int tl_get_slot_from_pin(pinnum);
DESCRIPTION This function returns the test head slot of the first analog
instrument behind the pin number pinnum as described in the
IMAGE pinmap. This function supports multisite test and will
return the slot of the analog instrument associated with the first
instrument behind the pin of the currently active site.
This function is valid in test programs for mixed signal, advanced
mixed-signal, and advanced linear (including PATH) test stations
only. This function is valid for analog instruments only.
ARGUMENTS int pinnum pin number of pin from pinmap
RETURN VALUE int slot test head slot of instrument
-1 error
tl_get_sort_bin
Get bin number assigned in sort bin statement.
SYNOPSIS int tl_get_sort_bin();
DESCRIPTION This function returns the software bin number assigned by the
sort bin statement. In a multisite test program, call this function
only from inside a serial block. In a multisite test program, the
software bin number assigned to a disabled site can only be
IMAGE Solutions V8.3 26-219
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
obtained by re-enabling the site. Generally, execute a set
site_enable_all statement before the serial block containing
the tl_get_sort_bin function call.
ARGUMENTS None
RETURN VALUE The last bin number assigned.
NO_BINNING is returned if no bin number has been assigned.
NO_BINNING is also returned in a multisite test program if the site
is no longer active.
tl_get_sort_hbin
Get handler bin assigned in sort bin statement.
SYNOPSIS int tl_get_sort_hbin();
DESCRIPTION This function returns the handler bin number assigned by the
sort bin statement. In a multisite test program, call this function
only from inside a serial block. In a multisite test program, the
handler bin number assigned to a disabled site can only be
obtained by re-enabling the site. Generally, execute a set
site_enable_all statement before the serial block containing
the tl_get_sort_hbin function call.
ARGUMENTS None
RETURN VALUE The last handler bin number assigned.
NO_BINNING is returned if no bin number has been assigned.
NO_BINNING is also returned in a multisite test program if the site
is no longer active.
tl_get_spec_nam
Get the test spec. name of the parts being tested.
SYNOPSIS char * tl_get_spec_nam(s)
char s[];
DESCRIPTION This function returns the test spec. name of the parts being
tested as a string.
ARGUMENTS An array in which to place the test spec. name string
RETURN VALUE Its argument (the test spec. name string)
tl_get_spec_ver
Get the test spec. version of the parts being tested.
SYNOPSIS char * tl_get_spec_ver(s)
char s[];
IMAGE Solutions V8.3 26-220
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns the test spec. version of the parts being
tested as a string.
ARGUMENTS An array in which to place the test spec. version. string
RETURN VALUE Its argument (the test spec. version string)
tl_getstdftimeofday
Get the current time of day.
SYNOPSIS int tl_getstdftimeofday()
DESCRIPTION Gets the STDF notion of the current time of day. This time is the
GMT time of day, adjusted for local time (not including daylight
savings time). Explicitly, it is the timeval.tv_sec field returned
by:
gettimeofday() - (timezone.tz_minuteswest * 60);
ARGUMENTS None
RETURN VALUE Integer value representing the number of seconds since Jan. 1,
1970.
tl_get_stream_criteria
Get test criteria for the given stream.
SYNOPSIS int tl_get_stream_criteria(char *sname,
struct tl_tlist_element **lptr,
int *num_list_elements);
DESCRIPTION This function searches the list of currently enabled streams (both
datalog and datastream) searching for the stream identified by
sname.
If the stream name does not match any currently enabled data
streams, the function returns a value of Notexist. Otherwise, it
returns an enumerated value from the following list.
Before using this function,
tl_update_data_collection_state() must have been called
at least once to make sure the data collection state information
has been set.
If the tl_tlist_element argument is NULL, no test list
processing or return occurs. The memory associated with the
lists must not be freed. It is handled by subsequent calls to this
function. Subsequent calls to this function modify the test list.
Therefore, if the information is needed, copy it to more
permanent storage.
IMAGE Solutions V8.3 26-221
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
If the argument is non-NULL, the return is an array of test list
elements.
The following is a definition of the test list structure:
#define TL_MAXNAME 50
struct tl_setup_type {
TL_TEST_NUM, TL_TEST_RANGE, TL_TEST_NAME,
TL_SEQ_NAME
};
struct tl_tlist_element {
enum tl_setup_type type;
unsigned int test_num, last_test;
char name[TL_MAXNAME+1];
}
The type field discriminates between what sort of element this
test is an enumerated type which describes if this is a test
number (TEST_NUMBER), in which case the test_num and
last_test elements will contain the test number. If the element
is for a range, the type will equal TEST_RANGE (list_element-
>type == TEST_RANGE) and the test_num field will contain the
starting test number in the range and the last_test field will
contain the last test number in the range. If type equals
TEST_NAME or SEQ_NAME, the name field will contain either the test
function name or the sequencer name.
ARGUMENTS sname—stream name
lptr—address of a pointer to tl_tlist_element
num_list_elements—number of test list elements being
returned
For datastream streams, this is the stream ID specified in the
datastream command that is returned by
tl_get_data_collection_streams(). For datalog streams, it
is a stream name accessed through the following macros:
TL_DATALOG_STATWIN—datalog to station window
TL_DATALOG_DATAWIN—datalog to datalog window
TL_DATALOG_STDF—datalog to STDF file
TL_DATALOG_FILE—datalog to text file
TL_DATALOG_PRINTER—datalog to text file
TL_HISTOGRAMMING—histogram stream
See “tl_get_data_collection_streams” on page 26-200 for more
information on using these macros. In general, they represent
character strings.
RETURN VALUE Integer value accessed by the following macros:
TL_NOTEXIST—Stream does not exist
TL_PASS—Passing tests
TL_FAIL—Failing tests
IMAGE Solutions V8.3 26-222
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
TL_ALL—All tests
TL_PASSANALOG—Passing analog tests
TL_FAILANALOG—Failing analog tests
TL_PASSDIGITAL—Passing digital tests
TL_FAILDIGITAL—Failing digital tests
SEE ALSO “tl_get_data_collection_streams”
tl_get_stream_filename
Return the name of the file the datalog stream is writing.
SYNOPSIS char *tl_get_stream_filename(char *sname);
DESCRIPTION This function first checks to see whether sname exists and
returns the name, if any, of the filename being written. This
function only applies to datalog streams to STDF and text files.
If no file is being written or the stream is not found, the function
returns NULL. This function returns the file name by a pointer to
static storage. If the name must be saved, it must be copied to
user allocated memory. Otherwise, it may be overwritten by a
subsequent call to this function.
Before using this function,
tl_update_data_collection_state() must have been called
at least once to make sure the data collection state information
has been set.
ARGUMENTS sname—name of data collection stream
RETURN VALUE (char *) NULL—error, stream does not exist or the stream in
question is not writing a file.
(char *)—name of file
SIDE EFFECTS Resets static storage used for filename with information in latest
call.
tl_get_stream_sample_info
Return streams sampling rate.
SYNOPSIS int tl_get_stream_sample_info(char *sname,
int *srate, int *slimit);
DESCRIPTION Looks up the stream whose name matches sname, if any, and
returns the sampling rate and sample limit through the
arguments list.
Before using this function,
tl_update_data_collection_state() must have been called
IMAGE Solutions V8.3 26-223
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
at least once to make sure the data collection state information
has been set.
ARGUMENTS sname—character string with the stream name
srate—pointer to integer which will be set to sample rate.
slimit—pointer to integer which will be set to sample limit.
RETURN VALUE 0—stream not found.
1—Success
tl_get_tester_number
Read current tester number.
SYNOPSIS int tl_get_tester_number();
DESCRIPTION This function returns the tester number which the test program is
currently loaded into. This number is computed from the
TESTER_NUMBER environment variable.
ARGUMENTS None
RETURN VALUE Current tester number
tl_get_tst_temp
Get the testing temperature of the parts being tested.
SYNOPSIS char * tl_get_tst_temp(s)
char s[];
DESCRIPTION This function returns the testing temperature of the parts being
tested as a string.
ARGUMENTS An array in which to place the testing temperature string.
RETURN VALUE Its argument (the test temperature string)
tl_get_user_power
Read the current state of the user power relay.
SYNOPSIS tl_get_user_power();
DESCRIPTION Read the status of user power. Non-zero return indicates power
on and zero indicates power off.
ARGUMENTS None
RETURN VALUE int state of user power—Nonzero power on, zero power off
SEE ALSO “tl_set_user_power”
IMAGE Solutions V8.3 26-224
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_get_wavefile_sample_size
Get the sample size from a waveform file.
SYNOPSIS int tl_get_wavefile_sample_size(filename);
DESCRIPTION This function opens the specified wavefile and gets the number
of samples. You must include the file libapps.a in the .load file
for the test program.
ARGUMENTS filename—name of the file to be read
RETURN VALUE >0 Number of samples in the file
≤0 Error
tl_gigadig_report_ac_corr_spectrum
Return error correction spectrum.
SYNOPSIS void tl_gigadig_report_ac_corr_spectrum (int pin,
freq_band_type freq_list, double *err_array)
DESCRIPTION User function to return the AC error correction spectrum at the
specified frequency points for the specified GigaDig. A valid vrng
setting *must* be set before calling this routine.
ARGUMENTS pin—Pin number or pin name of GigaDig to be adjusted
freq_list—Descriptions of the frequency band
err_array—Array to fill with results
RETURN VALUE None
SIDE EFFECTS Fills err_array with the AC error correction spectrum calls
tl_gigadig_report_error_spectrum to do calculations
tl_gigadig_report_chan_mismatch_data
Report mismatch data between channels.
SYNOPSIS void tl_gigadig_report_chan_mismatch_data(ref_pin,
skew_p, offset_p, gain_p)
int ref_pin;
double * skew_p;
double * offset_p;
double * gain_p;
DESCRIPTION This routine reports the gain, clock skew and offset mismatches
between the two undersampling channels. Such mismatches
arise when user switches from one channel to another w/o
issuing any "set gigadig" statement in between two captures.
User *must* have programmed the instrument with the final
"vrng" and "level_freq" settings for the captures when calling this
function.
IMAGE Solutions V8.3 26-225
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS ref_pin—Pin name/number corresponding to the *FIRST*
capture
skew_p—Amount of skew between the two captures. A positive
number indicates that user needs to add delay to the *FIRST*
capture to align the timing of the two captures. A negative
number indicates that user needs to add delay to the *SECOND*
capture.
offset_p—Amount of offset (in volts) that needs to be
subtracted from the *SECOND* capture.
gain_p—Gain correction factor that needs to be multiplied to the
*SECOND* capture
RETURN VALUE None
SIDE EFFECTS None
tl_gigadig_report_err
Report error at a single frequency.
SYNOPSIS double tl_gigadig_report_err(int pin, double freq)
DESCRIPTION Uses information gathered during autocal to calculate and return
the error at a given frequency. Used for manual calibration of the
GigaDig, when the FIR filter is bypassed. The user can correct
an uncalibrated measurement at a single frequency by
multiplying it by the output of this function.
ARGUMENTS pin —Pin number or pin name of GigaDig to use
freq— Frequency of interest
RETURN VALUE Known instrument error at the given frequency point, or 0 if any
error.
SIDE EFFECTS Selects specified instrument.
tl_gigadig_skew_clock
Skew GigaDig capture clock.
SYNOPSIS int tl_gigadig_skew_clock(int pin, double skew_val)
DESCRIPTION User function to adjust the relative timing of the GigaDig capture
clock by the specified amount clock skew for the specified
GigaDig pin.
ARGUMENTS pin—Pin number or pin name of GigaDig to be adjusted
skew_val— Desired clock skew (-5 ns to +5 ns; positive skew for
delayed clock)
IMAGE Solutions V8.3 26-226
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Selects specified instrument.
RETURN VALUE TRUE if succeeded, FALSE if failed
tl_gpib_dump_bus_info
Dump information about the GPIB.
SYNOPSIS int tl_gpib_dump_bus_info()
DESCRIPTION Debug function to dump the current state of the GPIB bus. Gives
such information as to who is a talker and listener as well as the
last data string sent over the bus.
ARGUMENTS None
RETURN VALUE None
tl_gpib_dump_gpibcap_info
Dump the driver’s copy of gpibcap.
SYNOPSIS int tl_gpib_dump_gpibcap_info()
DESCRIPTION Function to dump the test program’s copy of the GPIB
capabilities database.
ARGUMENTS None
RETURN VALUE None
tl_gpib_get_ifc_at_reset
Read whether IFC is asserted during reset.
SYNOPSIS int tl_gpib_get_ifc_at_reset()
DESCRIPTION This function returns whether the GPIB IFC is asserted during
test program resets. It returns FALSE (0) if IFC during reset is
turned off for all test programs. It returns TRUE (non-zero) if IFC
during reset is turned on for all loaded test programs.
ARGUMENTS None
RETURN VALUE None
tl_gpib_set_ifc_at_reset
Set whether IFC is asserted during reset.
SYNOPSIS void tl_gpib_set_ifc_at_reset(int ifc_on_reset)
DESCRIPTION This function sets whether the GPIB IFC is asserted during test
program resets. If passed FALSE (0), then IFC during reset is
IMAGE Solutions V8.3 26-227
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
turned off for all test programs. If passed TRUE (non-zero) then
IFC during reset is turned on for all loaded test programs.
ARGUMENTS int ifc_on_reset - Integer noting new state of IFC at reset:
TRUE (non-zero) - turn IFC at reset on
FALSE (zero) - turn IFC at reset off
RETURN VALUE None
SIDE EFFECTS This function changes the IFC at reset behavior for all test
programs.
tl_h50_channel_to_pin
Convert HSD channel number to pin.
SYNOPSIS int tl_h50_channel_to_pin(chan)
int chan;
DESCRIPTION This function takes the given HSD channel number, searches the
pinmap for the first DUT pin mapped to this channel, and returns
the pin number.
ARGUMENTS chan—The channel number to find (1 to system max)
RETURN VALUE Pin number (1 to the highest pin number in the pinmap), or zero
if no pin was found mapped to that channel.
tl_h50_check_pattern_running
Check if pattern is running.
SYNOPSIS int tl_h50_check_pattern_running (which_scm)
int which_scm;
DESCRIPTION Checks whether a pattern is running on the specified SCM. Don’t
call flush_recv_pipe if we know we’re in KA.
ARGUMENTS which_scm
TL_FIRST_SCM for 1st SCM
TL_SECOND_SCM for 2nd SCM
TL_ALL_SCM for both SCMs
RETURN VALUE 1 if pattern is running, 0 otherwise.
SIDE EFFECTS Flushes receive pipeline if pattern not running
tl_h50_check_pattern_running_or_in_ka
Check if pattern is running.
SYNOPSIS int tl_h50_check_pattern_running (which_scm)
int which_scm;
IMAGE Solutions V8.3 26-228
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Checks whether a pattern is running or in keepalive on the
specified SCM.
ARGUMENTS which_scm
TL_FIRST_SCM for 1st SCM
TL_SECOND_SCM for 2nd SCM
TL_ALL_SCM for both SCM’s
RETURN VALUE 1 if pattern is running, 0 otherwise.
tl_h50_debug_pmtrc
Set the debug state variable for parametric testing.
SYNOPSIS void tl_h50_debug_pmtrc(state)
int state;
DESCRIPTION This function sets the state of the internal flag governing the
switch states during open_short and leakage testing.
ARGUMENTS state—
TRUE: the following switches are set when performing
open_short and leakage testing:
open: cal
close: ppmu
close: parametric;
FALSE: the following switches are set when performing
open_short and leakage testing:
open: dc_force
open: functional
open: dc_sense
open: cal
close: dut
close: ppmu
close: parametric;
RETURN VALUE None
SIDE EFFECTS Sets internal flag h50_debug to the desired state.
tl_h50_define_scan_headers
Set count of variable headers.
SYNOPSIS int tl_h50_define_scan_headers(name)
char *name;
DESCRIPTION The HSD50 pattern loader calls this function when loading a
pattern that defines or refers to symbols of the type
SCAN_HDR_VAR or SCAN_TLR_VAR. The function is given the
IMAGE Solutions V8.3 26-229
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
name of a symbol and returns the count; the loader patches the
pattern to implement the specified count.
The IMAGE library has a default version of this function which
always returns 2. A test program should replace the library
version by defining a function with the same name.
ARGUMENTS name—The string name of the symbol.
RETURN VALUE The desired total cycle count for the header, from 0 to 32769
tl_h50_dsim_roundtrip_delay_time
Set or get the DSim round trip time.
SYNOPSIS double tl_h50_dsim_roundtrip_delay_time(timeval)
double timeval;
DESCRIPTION This function sets and/or gets the round trip delay value for
DSim. If passed in value is < 0, only the current setting is
returned. The round trip delay value is used to detect conflicts
between the R2 and D0 edges on a channel caused by the time
required for signals to travel from the dut to the channel receiver.
NOTE
The value passed in must be of double type. Passing in an integer will result in problems.
To avoid problems with passing arguments of the wrong type,
use type casting for the argument. For example:
double current_val;
current_val =
tl_h50_dsim_roundtrip_delay_time((double) -1);
ARGUMENTS timeval—If timeval >= 0.0 set value used when checking
round trip delay time to timeval seconds.
if timeval < 0.0 only return current setting.
RETURN VALUE The current minimum separation between R2 and D0 in
seconds.
tl_h50_get_pin_name
Look up DUT pin name from number.
SYNOPSIS char *tl_h50_get_pin_name(pin)
unsigned short pin;
IMAGE Solutions V8.3 26-230
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Takes a DUT pin number, such as that returned by
read_hsd50_results(), and returns a pointer to the pin’s
name. Works for all types of pinmap pins.
ARGUMENTS pin—DUT pin number from the pinmap
RETURNS Pointer to pin name string, or 0 if specified pin number was not
found in the pinmap.
tl_h50_get_site_from_chan
Get HSD channel site.
SYNOPSIS int tl_h50_get_site_from_chan(chan)
int chan;
DESCRIPTION This function takes the given HSD channel number, and return
its site.
ARGUMENTS chan—The channel number to find (1 to system max)
RETURN VALUE Channel site number, or -1 if this channel is not in the pinmap.
tl_h50_highest_chan
Get highest channel number
SYNOPSIS int tl_h50_highest_chan()
DESCRIPTION Returns the highest HSD50 channel number in the system.
ARGUMENTS None
RETURN VALUE Highest channel number: maximum 192 for Advanced Mixed-
Signal (HSD50), 384 for Catalyst .
tl_h50_mcfreq
Get value of HSD50 master clock frequency.
SYNOPSIS double tl_h50_mcfreq(clk)
int clk;
DESCRIPTION Returns the currently programmed value of the requested
master clock.
ARGUMENTS clk—which master clock, 0 = m_clk, 1 = m_clk_alt, 2 =
ac_clk_aux1, 3 = ac_clk_aux2
RETURN VALUE The requested frequency or 0 if clock is not present.
tl_h50_pin_to_channel
Get HSD channel number for a pin.
IMAGE Solutions V8.3 26-231
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_h50_pin_to_channel(pin)
int pin;
DESCRIPTION Returns the digital channel number for the specified pin. If the pin
is not mapped to a digital channel, a runtime error is issued.
When used in a multisite test program, this function must be
called within a serial loop if the pin is not defined as a shared
resource in the pinmap.
ARGUMENTS pin—pin number
RETURN VALUE Channel number from 1 to max, or 0 if the current site is disabled.
tl_h50_read_dmc_divider
Read back DMC divider value.
SYNOPSIS int tl_h50_read_dmc_divider(scm, tset, clock)
int scm;
int tset;
int clock;
DESCRIPTION Reads back the t0 or c0 divider value for the specified SCM and
tset number. Converts the raw hardware value to user terms
before returning it.
ARGUMENTS scm—TL_FIRST_SCM to read value from first SCM,
TL_SECOND_SCM to read from second SCM.
tset—tset number from 1 to 1023.
clock—0 for t0 divider, 1 for c0 divider.
RETURN VALUE Programmed divider value, or 0 if value could not be read back.
tl_h50_supclk_to_dc
(Dis)connect supclk and matrix.
SYNOPSIS #include <itlh/h50scl.h>
void tl_h50_supclk_to_dc(inst, operation, src_var)
int inst;
int operation;
int src_var;
DESCRIPTION This function connects or disconnects the specified matrix
instrument to (from) the specified Superclock instrument. The
connection is made as far as the matrix relay on the SCL board.
The matrix pseudo relay is not affected. Note that there is no
hotswitch protection when connecting a DC src; the user must
make sure this is done with DC power off.
IMAGE Solutions V8.3 26-232
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tlp puts out calls to this function when the user programs a set
<pinlist> supclk connect: or set <pinlist> supclk
disconnect: statement.
ARGUMENTS inst—The supclk number.
operation—OPEN or CLOSE (from imagedefs.h)
src_var—Variable src number; one based (either a dc source
number from 1 thru 5 or one of the following:
6—dcgnd
7—dcvm1
8—dcvm2)
RETURN VALUE None
tl_handlerprober_exec_action
When using the GPIB interface, tell IMAGE to execute an action.
SYNOPSIS int tl_handlerprober_exec_action(char *action_name);
DESCRIPTION Formats the response from the handler or prober callback
function so that action_name is returned to IMAGE. When
IMAGE receives this response, it searches the command file for
the definition of this action. If found it is executed. Otherwise,
IMAGE prints an error message and continues along the
execution path it would have otherwise taken.
There cannot be a return from the calling function of
TL_H_RESONSE_DISABLE_POLL, TL_H_RESPONSE_DISABLE,
TL_H_RESPONSE_ERROR. Otherwise a runtime error occurs. The
text is:
"Incompatible handler/prober callback function return"
The action is then ignored.
Only call this function once whenever a callback function is
invoked. Each successive call overrides the previous one.
ARGUMENTS char *action_name—Name of action to call
RETURN VALUE 0 Error
1 on success
tl_hcps_connect_pinmap
Connect or disconnect HCPS.
SYNOPSIS tl_hcps_connect_pinmap(mode)
DESCRIPTION This function will connect/disconnect hcps channels,
enable/disable the DIB Absent Shutdown and enable/disable the
Open Kelvin 1 Alarm for all the hcps channels in the pinmap.
IMAGE Solutions V8.3 26-233
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS int mode— Connect mode/disconnect mode
:- HCPS_CONNECT(1) or HCPS_DISCONNECT(0)
RETURN VALUE None
SIDE EFFECTS
tl_hcps_debug_kelvin_pin
Utility to debug kelvin alarms.
SYNOPSIS int tl_hcps_debug_kelvin_pin(pin,range)
unsigned short pin;
int range;
DESCRIPTION For each hchan/pgid specified the following measurements are
made and the results printed to the screen along with the alarm
the measurement relates to:
DIB Sense Low - Force Low (Open Kelvin 2)
Force High - DIB Sense High (Open Kelvin 2)
Force High - Sense High (Open Kelvin 1)
Sense Low - Force Low (Open Kelvin 1)
ARGUMENTS unsigned short pin—A single pin (merged or single). NOTE:
A pin field or pin list is not valid.
int range - 0 : +-500mV
1 : +8/-2V
RETURN VALUE 0 : Error
1 : Success
SIDE EFFECTS None
SEE ALSO
tl_hcps_set_connect_ilim
Set current ilim for connection.
SYNOPSIS void tl_hcps_set_connect_ilim(ilim)
double ilim;
DESCRIPTION This function sets the current ilim during the connection of HCPS
channels in the pinmap using tl_hcps_connect_pinamp. The
ilim is restored to the original state (state before the
tl_hcps_connect_pinmap call) once the channel connection is
completed.
ARGUMENTS double ilim— Ilim during connections [Range:2A <= ilim <=
8A]. (default i.e. if this function is not called before a
tl_hcps_connect_pinmap is 8A)
IMAGE Solutions V8.3 26-234
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
SIDE EFFECTS
tl_hcucal_src
Calibrate a single HCU source.
SYNOPSIS int tl_hcucal_src(arg, number)
int arg, number;
DESCRIPTION Entry point for HCU calibrator (for a single source).
ARGUMENTS arg—0 = calibrate, informational messages only
1 = calibrate, verbose messages to window
2 = calibrate, verbose messages to file
3 = calibrate, all messages via ckprintf
number—1..NHCU_MAX = HCU number
RETURN VALUE CMD_OK = calibration passed
CMD_CAL_FAIL = something failed
CMD_CAL_ABORT = calibration aborted because:
AD212 missing or
AD330 missing or
AD330 data retention failed
SIDE EFFECTS Function does a reset all.
tl_hcu_override
Overrides the High Current Unit (HCU) protection.
SYNOPSIS void tl_hcu_override(flag)
int flag;
DESCRIPTION This function is used to override the protection between HCU
and THADS connection. The reset all; statement sets the
value back to the default state.
ARGUMENTS int flag—1 for override, 0 for default
int data—Data to write
RETURN VALUE None
tl_hfdig_report_err
Report error at a single frequency.
SYNOPSIS double tl_hfdig_report_err(pin, freq)
int pin;
double freq;
IMAGE Solutions V8.3 26-235
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Uses information gathered during autocal to calculate and return
the error at a given frequency. This function is used for VHFDIG
manual calibration when the FIR filter is bypassed. You can
correct an uncalibrated measurement at a single frequency by
multiplying it by the output of this function. This function always
returns 1.0 if used on an HFDIG.
ARGUMENTS pin—Pin number or pin name of HFDIG to use
freq—Frequency of interest
RETURN VALUE Known instrument error at the given frequency point, or 0 if any
error
SIDE EFFECTS Selects specified instrument if instrument is a VHFDIG.
tl_hfsc_ramp_cal
Perform ramp calibration.
SYNOPSIS tl_hfsc_ramp_cal()
DESCRIPTION Perform hardware specific ramp calibration
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Initializes the ramp calibration internal correction table. Also
leaves the HSD deskewed in a way other than what the user may
have intended. Other system resources affected.
tl_hp_abort_probing
Stop probing, break device contact.
SYNOPSIS int tl_hp_abort_probing();
DESCRIPTION This command stops probing. The Z stage is lowered to break
contact with the wafer, and the XY motor is left wherever it is.
ARGUMENTS None
RETURN VALUE 1 (TRUE) for success
-1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error.
tl_hp_assign_good_die_bins
Define what bin codes are considered “good” and what bin codes are “bad” die.
SYNOPSIS int tl_hp_assign_good_die_bins(goodbins)
int goodbins[];
IMAGE Solutions V8.3 26-236
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Defines what bin codes are considered “good” and what bin
codes are “bad” die. This does not have anything to do with
inking. “Good” and “bad” are used in accumulating die total
counts. The first value in the array goodbins should contain the
number of valid elements to follow. Each of the following
elements should be the number of a bin to be considered a
“good” bin. All others will be considered fails.
ARGUMENTS goodbins[20]—Good bin values array
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_assign_logical_ink
Define what inkers are fired in response to a particular bin when a die is tested
SYNOPSIS int tl_hp_assign_logical_ink(inkbins)
int inkbins[];
DESCRIPTION Defines what inkers are fired in response to a particular bin when
a die is tested. The first value in the array inkbins should
contain the number of valid elements to follow. Each of the
following elements is the inking code for each bin, starting with
bin 0. The inking codes are defined as shown in table 26-5.
Table 26-5. Inking Codes
Code Inkers Code Inkers
0 no ink 8 4
1 1 9 1,4
2 2 10 2,4
3 1,2 11 1,2,4
4 3 12 3,4
5 1,2 13 1,3,4
6 2,3 14 2,3,4
7 1,2,3 15 1,2,3,4
For example, to define bin 0 to fire inker 1, bin 15 to fire inker 2,
and all other bins to fire inkers 3 and 4, inkbins would be set to:
16,1,12,12,12,12,12,12,12,12,12, 12,12,12,12,12,2
These values are inkbins[0] to inkbins[16].
IMAGE Solutions V8.3 26-237
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS inkbins[20]—Array with ink values for each bin
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_bin_to_category
Send binning command to handler or prober.
SYNOPSIS int tl_hp_bin_to_category(bins, idnumbers)
int bins[];
int idnumbers[];
DESCRIPTION This function sends a bin command to the peripheral at the
current test station. The bin information to be used is placed into
the parameter bins, which is an array of integers, with sites[N]
containing the bin number for site N. The parameter idnumbers
is an array of integers, giving an optional device ID for each of
the sites. You can omit this parameter by passing a 0 in its place,
as in
tl_hp_bin_to_category(bins, 0);
If omitted, the device ID number defaults to 1. This function
returns -1 on an error or the number of sites binned for a
successful operation.
For multisite test programs, use a serial loop to bin only the sites
which were enabled for the given run. An example of this is as
follows:
int bins[TL_SYS_MAX_SITES];
...calls to sequencers...
..."sort bin" statement...
serial {
bin[tl_site] = tl_get_sort_hbin();
}
tl_hp_bin_to_category(bins, 0);
ARGUMENTS bins—Array of bin numbers (per site)
idnumbers—Array of DUT ID numbers (per site)
RETURN VALUE Number of sites binned, or -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_break_device_contact
Open handler jaws at specified site.
SYNOPSIS tl_hp_break_device_contact(site);
int site;
IMAGE Solutions V8.3 26-238
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function commands the attached handler to open the
contactors at the specified site, breaking the contact between the
tester and the device.
For single site programs, pass this function a 0, indicating that
only site 0 should be affected. For multisite test programs, the
best way to use this function is to pass the value of the variable
tl_site to select the site currently being tested. For example, a
typical use for this command might to be break device contact on
the site currently being tested if a given test fails. In this case, the
code might look something like:
serial { * test each enabled site in serial *
...make measurement...
if (<test failed>)
tl_hp_break_device_contact(tl_site);
}
For multisite test programs, when not in a serial block, tl_site
is set to select all currently enabled sites. As a result, the
following call will break device contact at all enabled sites:
tl_hp_break_device_contact(tl_site);
ARGUMENTS site—Site number to break contact at
RETURN VALUE 1 if operation succeeded
-1 if operation failed
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_clear_alarm
Clear alarm on the handler or prober.
SYNOPSIS int tl_hp_clear_alarm()
DESCRIPTION This function turns off the audible or visual alarm on the handler
or prober.
ARGUMENTS None
RETURN VALUE 1 operation succeeded
-1 operation failed
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_get_prober_info
Get status information from current prober over the RS232 interface.
SYNOPSIS int tl_hp_get_prober_info(data)
DESCRIPTION This function gets status information from the prober.
IMAGE Solutions V8.3 26-239
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS data—An array of four integers passed to the function. The
following value is placed in each location:
data[0] = wafer complete? 0=no, 1=yes
data[1] = input cassette empty? 0=no, 1=yes
data[2] = current x coordinate
data[3] = current y coordinate
For multisite test programs, the x/y coordinates will be those of
the primary site.
RETURN VALUE 1 operation succeeded
-1 operation failed
SIDE EFFECTS May set the handler/prober error number.
tl_hp_gpib_sendcmd
Send a command to a handler or prober over the GPIB.
SYNOPSIS int tl_hp_gpib_sendcmd(char *command, char *reply,
int replysize)
DESCRIPTION This is a user function designed to send a command to a handler
or prober connected to a station over the GPIB. This function
assumes only one GPIB connection from a handler or prober to
the station.
The function first determines if a handler or prober is connected
to the station over the GPIB. If one is not connected, an error
message is printed to the console and the function returns an
error.
Next, the function determines whether the command is valid, that
is, that the command exists in the command file. If the command
is not valid, a message is printed on the console and an error is
returned from the function.
Finally, if a prober is connected to the station over the GPIB and
the command is valid, the syntax for the command is sent to over
the bus to the handler or prober.
When the reply is received, IMAGE checks to see if the reply
received matches any of the replies in the command file. Any
error conditions specified for the reply are flagged if a match is
found. The reply is returned to the user through the second
argument without further processing. It is the caller’s
responsibility to parse the response further. It is also the caller’s
responsibility to make sure that enough memory is allocated to
hold the reply and a NULL terminator. The reply is automatically
NULL terminated.
IMAGE Solutions V8.3 26-240
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
If the expected reply is by return from a serial poll, the status byte
value is returned in the first byte of reply, reply[0]. Again, the
value is NULL terminated.
If no reply is expected from the command, you can pass a (char
*) NULL for the reply argument and 0 for the replysize
argument.
ARGUMENTS char *command—Pointer to a valid command to send.
char *reply—Pointer to memory to hold handler or prober
response.
int replysize—Size of the reply buffer in bytes.
RETURN VALUE 1 Success
0 Error
SIDE EFFECTS May set error conditions, depending on reply.
tl_hp_gpib_sendvarcmd
Send a command to the handler or prober over the GPIB, replacing any C format strings in
the command.
SYNOPSIS int tl_hp_gpib_sendvarcmd(char *command,
char *reply, int replysize, ...)
DESCRIPTION This function sends a command to a handler or prober
connected to the station over the GPIB. It assumes only one
GPIB connection from a handler or prober to the station.
The function first determines if a handler or prober is connected
to the station over the GPIB. If one is not connected, an error
message is printed to the console and the function returns an
error.
Next the function determines whether the command is valid (that
the command exists in the command file). If the command is not
valid, a message is printed on the console and an error is
returned from the function.
Any C format specifiers in the command (such as %c or %d or %s)
are replaced in the string resulting in the final command to be
sent to the prober. Arguments after replysize are used to
replace the format specifiers. This is much like calling printf. It
is the caller’s responsibility to make sure there are enough
trailing arguments to fill in the format specifiers in the command.
See the man page for fprintf for more information on format
specifiers.
Finally, if a prober is connected to the station over the GPIB and
the command is valid, the modified command, with all format
IMAGE Solutions V8.3 26-241
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
specifiers replaced, is sent to over the bus to the handler or
prober.
When the reply is received IMAGE checks to make sure that the
reply received matches any of the possible replies in the
command file. Any error conditions specified for the reply are
flagged if a match is found. The reply is returned to the user
through the second argument without further processing. It is the
caller’s responsibility to parse the response further. It is also the
caller’s responsibility to make sure enough memory is allocated
to hold the reply and a NULL terminator. The reply is
automatically NULL terminated.
If the expected reply is by return from serial poll, the status byte
value is returned in the first byte of reply, reply[0]. Again, the
value is NULL terminated.
If no reply is expected from the command, you can pass in a
(char *) NULL for the reply argument and 0 for the replysize
argument.
ARGUMENTS command—Pointer to a valid command to send.
reply—Pointer to memory to hold handler or prober response.
replysize—Size of the reply buffer in bytes.
RETURN VALUE 1 Success
0 Error
SIDE EFFECTS May set error conditions, depending upon reply.
tl_hp_handlerconf_flags
Show handler setup with handcap information.
SYNOPSIS tl_hp_handlerconf_flags()
DESCRIPTION This function prints a summary of the handler or prober
connected for each test station as well as information on the
options enabled by the handcap entry for the handlers or probers
connected. For example, if the currently connected handler has
end of lot event distribution enabled using the eol_dist option
in the handcap entry, this function displays that fact. This function
is useful for debugging handcap entries (that is, making sure that
all the options in a handcap entry were read correctly). An
example of output:
Test head selected: 1
TH 1 prober eg2001p: EOLDIST
TH 2 disconnected
TH 3 disconnected
TH 4 disconnected
ARGUMENTS None
IMAGE Solutions V8.3 26-242
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
SIDE EFFECTS Prints information in station window
tl_hp_handlerconf_show
Print information on current handlers or probers.
SYNOPSIS tl_hp_handlerconf_show()
DESCRIPTION This function prints a summary of the handler or prober
connected for each test station, similar to the information printed
by the handlerconf -show command.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Prints information in station window
tl_hp_handler_isconnected
Detect if the handler is connected.
SYNOPSIS tl_hp_handler_isconnected()
DESCRIPTION This function returns a nonzero value if a handler is connected
(using handlerconf -connect) to the current station, or 0 if no
handler is connected.
ARGUMENTS None
RETURN VALUE Nonzero for handler connected, 0 otherwise
tl_hp_handler_isenabled
Detect if the handler is enabled.
SYNOPSIS tl_hp_handler_isenabled()
DESCRIPTION This function returns a nonzero value if a handler is connected at
the current station and polling for starts is enabled (using
handlerconf -enable), or 0 if no handler is connected.
ARGUMENTS None
RETURN VALUE Nonzero for handler enabled, 0 otherwise
tl_hp_input_empty_status
Determine which input tubes are empty.
SYNOPSIS int tl_hp_input_empty_status(inputs)
int inputs[];
IMAGE Solutions V8.3 26-243
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This command polls the handler to determine which input tubes
are empty and returns the resulting information in the array
inputs. The first element of inputs is set to the number of
empty tubes. The following elements contain the numbers of the
empty tubes.
ARGUMENTS int inputs[20]—Integer array for empty inputs
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error.
tl_hp_is_handler
Detect if peripheral is handler.
SYNOPSIS tl_hp_is_handler()
DESCRIPTION This function returns a nonzero value if a handler (as opposed to
a prober) is connected at the current station. Zero is returned if
no peripheral is connected or a prober is connected.
ARGUMENTS None
RETURN VALUE Nonzero for handler, 0 for prober or no connection
tl_hp_is_prober
Detect if peripheral is a prober.
SYNOPSIS tl_hp_is_prober()
DESCRIPTION This function returns a nonzero value if a prober (as opposed to
a handler) is connected at the current station. Zero is returned if
no peripheral is connected or a handler is connected.
ARGUMENTS None
RETURN VALUE Nonzero for handler, 0 for prober or no connection
tl_hp_load_setup
Load the handler or prober setup from file.
SYNOPSIS int tl_hp_load_setup(filename)
char filename[];
DESCRIPTION This command requests the prober or handler to load all its setup
parameters from a file located within its own file system. Specify
the name of the file using the parameter filename, which must
be a null-terminated string.
ARGUMENTS filename—Name of file in handler or prober to use
IMAGE Solutions V8.3 26-244
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 1 operation succeeded
-1 operation failed
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_load_wafer
Unload the current wafer on the prober chuck.
SYNOPSIS int tl_hp_load_wafer()
DESCRIPTION Unloads the current wafer on the prober chuck (if there is one),
loads and aligns a new wafer, and moves the first die under the
probes. After this command is complete, the Z stage is left out of
contact with the wafer.
ARGUMENTS None
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_make_device_contact
Close handler jaws at specified site.
SYNOPSIS tl_hp_make_device_contact(site);
int site;
DESCRIPTION This function commands the attached handler to close the
contactors at the specified site, creating contact between the
tester and the device.
For single site programs, pass this function a 0, indicating that
only site 0 should be affected. For multisite test programs, the
best way to use this function is to pass the value of the variable
tl_site to select all sites currently being tested.
ARGUMENTS site—Site number to make contact at
RETURN VALUE 1 operation succeeded
-1 operation failed
SIDE EFFECTS May set global variable tl_hp_errno if error
SEE ALSO “tl_hp_break_device_contact”
tl_hp_move_absolute_die
Move prober to absolute <x,y> coordinates.
SYNOPSIS int tl_hp_move_absolute_die(x, y)
int x, y;
IMAGE Solutions V8.3 26-245
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION The Z stage on the prober is lowered, the motor is moved to die
coordinate (x,y) in the prober’s coordinate system, and the Z
stage is raised again. The motor moves only in whole die steps,
not parts of a die.
ARGUMENTS int x—x coordinate of die to move to
int y—y coordinate of die to move to
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_move_relative_die
Move prober to <x,y> coordinates relative to current location.
SYNOPSIS int tl_hp_move_relative_die(x, y)
int x, y;
DESCRIPTION The Z stage on the prober is lowered, the prober steps x die
positions on the X axis, y positions on the Y axis, and the Z stage
is raised again (if it was up when the command was initiated).
The motor moves only in whole die steps, not parts of a die. If x
and y are positive, movement is in the direction in which the
coordinates increase. If x and y are negative, movement is in the
decreasing x/z direction.
ARGUMENTS int x—x offset to move
int y—y offset to move
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_move_relative_machine
Move prober <x,y> steps relative to current location in 0.1 mil steps.
SYNOPSIS int tl_hp_move_relative_machine(x, y)
int x, y;
DESCRIPTION The Z stage on the prober is lowered, the prober moves x 0.1 mil
steps on the X axis, y 0.1 mil steps on the Y axis, and the Z stage
is raised again (if it was up when the command was initiated).
See the specific prober manual for a description of coordinate
directions.
ARGUMENTS x—x offset to move
y—y offset to move
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
IMAGE Solutions V8.3 26-246
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_hp_move_z_down
Move the Z stage of prober down (out of contact with the probes).
SYNOPSIS int tl_hp_move_z_down()
DESCRIPTION If the Z stage of the prober is up, it is moved down (that is, out of
contact with the probes). At the completion of this function the
probe tips are no longer in contact with the die.
ARGUMENTS None
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_move_z_to_given_height
Move Z stage to specified height.
SYNOPSIS int tl_hp_move_z_to_given_height(z)
int z;
DESCRIPTION The Z stage moves to the height specified by z where z is the
height in 0.1 mil increments. After the command is successfully
executed, the prober considers the Z stage to be in the “up”
position, no matter the actual height.
ARGUMENTS z—z height to move to
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_move_z_up
Move the Z stage of prober up (into contact with the probes).
SYNOPSIS int tl_hp_move_z_up()
DESCRIPTION If the Z stage of the prober is down, it is moved up (that is, into
contact with the probes). At the completion of this function the
probe tips are in contact with the die.
ARGUMENTS None
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_output_full_status
Determine which output tubes are full.
IMAGE Solutions V8.3 26-247
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_hp_output_full_status(outputs)
int outputs[];
DESCRIPTION This command polls the handler to determine which output tubes
are full and returns the resulting information in the array
outputs. The first element of outputs is set to the number of full
tubes. The following elements contain the numbers of the full
tubes.
ARGUMENTS outputs[20]—Integer array for full outputs
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_parallel_clear_all_start
Clear any latched start, retest, and reject signals on the parallel handler/prober interface.
SYNOPSIS void tl_hp_parallel_clear_all_start(unsigned port)
DESCRIPTION This function clears any latched start, retest, and reject signals
on a parallel interface. Any of the signals cleared using this
function will not be seen by the handler/prober polling software.
ARGUMENTS int port—Parallel handler/prober port on which to clear the
start, retest, and reject signals
RETURN VALUE None
SEE ALSO “tl_hp_parallel_clear_start”, “tl_hp_parallel_clear_autosum”,
“tl_hp_parallel_clear_reject”
tl_hp_parallel_clear_autosum
Clear a latched auto summary signal on the parallel handler/prober interface.
SYNOPSIS void tl_hp_parallel_clear_autosum(unsigned port)
DESCRIPTION This function clears any latched auto summary signals on a
parallel interface. Any auto summary signal cleared by this
function will not be seen by the handler/prober polling software.
ARGUMENTS int port—Parallel handler prober port on which to clear the
auto summary signal
RETURN VALUE None
SEE ALSO “tl_hp_parallel_clear_start”, “tl_hp_parallel_clear_reject”,
“tl_hp_parallel_clear_all_start”
tl_hp_parallel_clear_reject
Clear a reject signal latched on the parallel handler/prober interface.
IMAGE Solutions V8.3 26-248
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS void tl_hp_parallel_clear_reject(unsigned port)
DESCRIPTION This function clears any latched reject signals on a parallel
interface. Any reject signal cleared by this function will not be
seen by the handler/prober polling software.
ARGUMENT int port—Parallel handler/prober port on which to clear the
reject signal
RETURN VALUE None
SEE ALSO “tl_hp_parallel_clear_autosum”, “tl_hp_parallel_clear_start”,
“tl_hp_parallel_clear_all_start”
tl_hp_parallel_clear_start
Clear any latched start and retest signals on the parallel handler/prober interface.
SYNOPSIS void tl_hp_parallel_clear_start(unsigned port)
DESCRIPTION This function clears any latched start and retest signals on a
parallel interface. Any start or retest cleared here will not be seen
by the handler/prober polling software.
ARGUMENTS int port—Parallel handler/prober port on which to clear the
start and retest signals
RETURN VALUE None
SEE ALSO “tl_hp_parallel_clear_autosum”, “tl_hp_parallel_clear_reject”,
“tl_hp_parallel_clear_all_start”
tl_hp_parallel_read_alarm
Read the current state of the handler alarm line.
SYNOPSIS int tl_hp_parallel_clear_alarm(unsigned port)
DESCRIPTION This function returns the current state of the parallel
handler/prober interface alarm line. Note that this line is not a
latched line like the other parallel handler/prober lines.
ARGUMENTS int port—Parallel handler/prober port on which to check the
alarm line
RETURN VALUE 1 (TRUE) if alarm line is high
0 (FALSE) if alarm line is low
tl_hp_parallel_read_all_start
Get the state of any latched start, retest, reject, alarm, and auto summary signals.
SYNOPSIS void tl_hp_parallel_read_all_start(unsigned port,
unsigned * start,
IMAGE Solutions V8.3 26-249
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
unsigned * retest,
unsigned * autosum,
unsigned * reject, unsigned * alarm);
DESCRIPTION This function reads the state of all parallel interface
handler/prober lines for given port associated with a normal start.
These lines are the start, retest, auto summary, reject, and alarm
lines. A valid pointer value for all arguments must be provided,
otherwise an error will occur.
ARGUMENTS port—Handler number (0 - 3)
The following return:
1 for active or “ON”
0 for inactive or “OFF”
start—Pointer to an integer to place the state of the start line
retest—Pointer to an integer to place the state of the retest line
autosum—Pointer to an integer to place the state of the auto
summary line
reject—Pointer to an integer to place the state of the reject line
alarm—Pointer to an integer to place the state of the alarm line
RETURN VALUE None
SIDE EFFECTS Alarms are strobed, the previously strobed value is lost.
tl_hp_parallel_set_eos
Set the current state of the parallel handler/prober interface EOS line.
SYNOPSIS void tl_hp_parallel_set_eos(unsigned port,
unsigned value)
DESCRIPTION This function sets the state of the EOS line. Whether a value of
1 (TRUE) sets the line to Hi or Lo depends on how the port was
previously set up.
ARGUMENTS port—Handler number (0 - 3)
value—1 (TRUE) to set to “ON” state
0 (FALSE) to set to “OFF” state
RETURN VALUE None
tl_hp_probe_wafer
Begin probing the wafer on the chuck.
SYNOPSIS int tl_hp_probe_wafer();
IMAGE Solutions V8.3 26-250
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This command assumes that the first die is under the probes.
When executed, the prober begins probing the wafer on the
chuck.
ARGUMENTS None
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_request_dut_id
Request DUT ID from handler or prober.
SYNOPSIS int tl_hp_request_dut_id(id_str, id_len)
char id_str[];
int id_len;
DESCRIPTION This function reads the ID string for the device currently being
tested and copies it into the array id_str, up to a maximum of
id_len characters. For probers, this corresponds to the wafer
ID.
ARGUMENTS id_str—Array to place ID into
id_len—Length of array
RETURN VALUE 1 operation succeeded
-1 operation failed
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_request_error_code
Get current handler or prober error code.
SYNOPSIS tl_hp_request_error_code()
DESCRIPTION This function returns the error code if an error condition is
present. If no error condition is present, the error code returned
is the constant ERR_HAND_NOERR. The error code can only be
read once. When it is read, it is reset. Errors range from cockpit
errors, such as attempting to request a start from a disabled
peripheral, to various peripheral-specific errors. If an error is
generated by the handler or prober, and the software cannot
classify the error (which is often the case), the error code is set
to ERR_HAND_MISCERR. In this case, you must use the function
tl_hp_request_error_msg to actually poll the peripheral for
the text of the error message. Error number macro definitions
can be accessed by including the file <itlh/tlerror.h>.
ARGUMENTS None
RETURN VALUE Error code for current handler or prober software error condition
IMAGE Solutions V8.3 26-251
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_request_error_msg
Get current handler or prober error message.
SYNOPSIS tl_hp_request_error_msg(estr, elen)
char estr[];
int elen;
DESCRIPTION This function returns a textual error message if an error condition
is present. The message is copied into the string passed as a
parameter. The error message can only be read once. When it is
read, the error code is reset. Errors range from cockpit errors,
such as attempting to request a start from a disabled peripheral,
to various peripheral-specific errors. In the case of an error
generated by the handler or prober (ERR_HAND_MISCERR), this
function polls the peripheral for the text of the error message.
ARGUMENTS estr—String to place error message into
elen—Maximum number of chars to copy into above string
RETURN VALUE 1 operation succeeded
-1 operation failed
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_request_peripheral_id
Read ID of handler or prober.
SYNOPSIS tl_hp_request_peripheral_id(istr, ilen)
char istr[];
int ilen;
DESCRIPTION This function reads back an ASCII identifying string from the
currently attached peripheral into the array passed as a
parameter. This function writes the ID into the array istr, up to
a maximum of ilen characters, and null terminates the array.
ARGUMENTS istr—Array to write handler or prober ID to
ilen—Maximum number of characters to write to istr
RETURN VALUE 1 operation succeeded
-1 operation failed
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_request_start
Poll handler or prober for start signal.
IMAGE Solutions V8.3 26-252
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_hp_request_start;
DESCRIPTION This function polls the current handler or prober for a start at the
given test head. If an error is encountered, a -1 is returned, and
the error code is placed in the variable tl_hp_errno, where it
can be accessed later. Otherwise, the number of sites with starts
is returned. Note that if the handler is not ready to start on any
sites, this function returns a 0, indicating that no sites are ready
to start.
For a multisite test program, the specific sites returned by the
handler or prober must agree with the number of sites supported
by the test program and with the current set of sites enabled
using the sites command.
In addition, this function also returns a set of flags in the array
parameter condition. The elements of the array are interpreted
as follows:
condition[0]—1 if peripheral is requesting a retest, 0
otherwise
condition[1]—1 if peripheral is signalling end-of-lot, 0
otherwise
condition[2]—1 if peripheral is signalling a reject, 0 otherwise
These condition flags are only set when using certain types of
interfaces. Some interfaces may be unable to return this status
every time a request-to-start is read.
ARGUMENTS condition—Described above
RETURN VALUE -1 error
0 no start
N N sites read to start
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hp_send_command
Send RS232 command to handler or prober.
SYNOPSIS int tl_hp_send_command(cmd)
char cmd[];
DESCRIPTION This function is provided as a generic way of sending commands
to RS232-based handlers or probers which support an IEEE
P849 command set. The parameter cmd must be a null-
terminated string containing the command to be sent. The
specified command is framed correctly according to the P849
protocol and sent out to the peripheral. The maximum length is
200 characters excluding the null terminator.
IMAGE Solutions V8.3 26-253
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
You can only use this function for commands which do not
require a response from the handler. A command which
generates a response from the peripheral requires the function
tl_hp_send_request. The main use of this function is to send
a command not already supported by the handler library.
For example, the following code sends the command AB1 to the
current handler or prober:
int success;
success = tl_hp_send_command("AB1");
Take care when using this command. Sending the wrong
command (that is, one requiring a response) may cause
unpredictable behavior in later operations.
ARGUMENTS cmd—Null terminated string containing command to send
RETURN VALUE 1 operation succeeded
-1 operation failed
tl_hp_send_request
Send a request to handler or prober and get a reply.
SYNOPSIS tl_hp_send_request(cmd, reply)
char cmd[], reply[];
DESCRIPTION This function provides a generic way to send requests to RS232-
based handlers or probers which support an IEEE P849 style
command set. The parameter cmd must be a null-terminated
string containing the command to be sent. The specified
command is framed correctly according to the P849 protocol and
sent out to the peripheral. The maximum length is 200
characters excluding the null terminator. The parameter reply
must be a character string large enough to read the response
sent back from the peripheral.
You can only use this function with commands which require the
peripheral to send back a response; for commands which do not
cause a response to be sent, use the function
tl_hp_send_command. The main use of this function is to send
a request not already supported by the handler library.
For example, to send a request to an Electroglas 2001X to return
the current wafer ID use
int success;
char reply[512];
success = tl_hp_send_request("CI", reply);
Take care when using this command. Sending the wrong
command (one which does not generate a response) may cause
the system to hang.
IMAGE Solutions V8.3 26-254
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS cmd—String to send to handler or prober
reply—String to place response into
RETURN VALUE 1 operation succeeded
-1 operation failed
tl_hp_unload_wafer
Unload the current wafer on the prober chuck.
SYNOPSIS int tl_hp_unload_wafer();
DESCRIPTION Unloads the current wafer on the prober chuck without loading a
new wafer.
ARGUMENTS None
RETURN VALUE 1 for success and -1 for failure
SIDE EFFECTS May set global variable tl_hp_errno if error
tl_hpd_user_fprintf
Print to the hpmonitor display and a stream simultaneously.
SYNOPSIS int tl_hpd_user_fprintf(FILE *stream, char * format,
...)
DESCRIPTION Formats the string as per fprintf, and then prints to the stream
and the Handler/prober Monitor display. The string always goes
out to the stream, but the function only tries to send the string to
the hpmonitor if the hpmonitor display is running.
ARGUMENTS FILE * stream—Stream to print to, usually stdout or stderr
char * format—Format string.
...—Format args.
RETURN VALUE As per fprintf
tl_hpd_user_printf
Print to the hpmonitor display and station window stdout simultaneously.
SYNOPSIS int tl_hpd_user_printf(char * format, ...)
DESCRIPTION Formats the string as per printf, and then prints the string in the
station window and the Handler/prober Monitor display. The
string always goes to the station, but the function only tries to
send the string to the hpmonitor if the hpmonitor display is
running.
ARGUMENTS char * format—Format string as per printf
...—Format args as per printf
IMAGE Solutions V8.3 26-255
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE As per printf
tl_hpm_reset
Reset the High Power Matrix.
SYNOPSIS tl_hpm_reset(unit)
int unit;
DESCRIPTION Sets the High Power Matrix (HPM) clear bit.
ARGUMENTS unit—The instrument number
RETURN VALUE None
tl_hsd50_calibrate_all
Calibrate calsets that need it.
SYNOPSIS void tl_hsd50_calibrate_all(force)
int force;
DESCRIPTION This function is called from the autocal environment every
h50_cal_env_interval. It checks if the environment has
changed and it runs calibration for all sets that require it.
NOTE: this function is NOT needed if you (user) run with autocal.
ARGUMENTS int force
0—Check the environment and calibrate sets that need to be
calibrated.
1—Force recalibration of all cal sets.
2—Calibrate sets that need to be calibrated, bypassing
environment check.
RETURN VALUE calibration status. CAL_PASSED, CAL_FAILED, ...
tl_hsd_connect_pin_to_thads
Connect the THADs to a digital chan.
SYNOPSIS void tl_hsd_connect_pin_to_thads(pin)
int pin;
DESCRIPTION Connects the THADS bus to the digital channel behind the pin
passed to the function.
Changing the cal tree outside of this function will affect the
connection
Running Calibration will re-set this connection
ARGUMENTS pin—Pin number
IMAGE Solutions V8.3 26-256
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
SIDE EFFECTS Sets the THS relays 22 and 23 closed. Connects TDR to
channel.
SEE ALSO “tl_hsd_disconnect_pin_from_thads”
tl_hsd_disconnect_pin_from_thads
Disconnect the THADs from TDR.
SYNOPSIS void tl_hsd_disconnect_pin_from_thads()
DESCRIPTION Disconnects the THADS bus from the TDR by resetting the THS
relays to the default position.
Running calibration should accomplish the same result
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Sets the THS relays 22 and 23 to open.
tl_hsd_flush_stat_cache
Flush the stat system call cache when using load path in pattern name.
SYNOPSIS void tl_hsd_flush_stat_cache()
DESCRIPTION This function is applicable only if tl_h50_use_load_path(ON)
was executed since the last program load on a station.
When sharing patterns between stations (for example, for dual
test heads), executing tl_h50_use_load_path(ON) allows two
test programs to load patterns with the same name but with
different paths. The execution tells the pattern loader to use the
path in the load file as part of the pattern name.
The path in the load file thus resolves the ambiguity in mapping
pattern name to actual pattern file. This lets test programs stay
generic and defers binding of pattern name to actual pattern file
to test program load time.
This binding is a discovery process that requires examining the
status of candidate paths to the actual pattern file. The stat
system call obtains this status for each pattern file needed.
This can take a long time for a large number of pattern files. The
stat system call cache alleviates this slow execution problem by
caching information from stat calls. If a subsequent stat call is for
the same path whose information has already been cached, no
additional stat call is executed and the cached information is
reused.
IMAGE Solutions V8.3 26-257
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
The current function flushes this stat_cache to a prejob reset
state that ensures cache miss on next use of the stat_cache.
This allows a stat system call to be executed for REAL (and not
just returning cached information).
If the directory structures to the pattern files or those in the load
file have changed, the current function should be executed.
This function is also called from prejob reset which is used by
checkers to return everything to a known state before the
program run. It is also called indirectly from the compiler output
code if you do a reset hsd50 or a reset hsd in a test program.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Leaves stat system call cache (stat_cached) in prejob reset
state
SEE ALSO “tl_h50_use_load_path” on page 67-132 in the Catalyst
Instrumentation Manual
tl_hw_settle
Wait for hardware relays to settle.
SYNOPSIS int tl_hw_settle()
DESCRIPTION Waits for the settling timer to count down and for hardware busy.
ARGUMENTS None
RETURN VALUE 0 if timeout error
1 if successful
tl_i2c_construct_msg
Write specified Inter-IC Control bus (I2C) information.
SYNOPSIS tl_i2c_construct_msg(msg, cdig_slot)
char * msg[];
int cdig_slot;
DESCRIPTION Writes the specified message tokens. These include start,
stop, read_byte, write_byte= (followed by byte to be written),
write_bit_zero, write_bit_one, read_bit_zero, and
read_bit_one. Timing, levels, and timeout value must already
have been set. SCL is on cdig_clk pin and SDA is on cdig_io1
pin. A maximum of 4096 message tokens can be sent in one
function call.
Description of message tokens:
IMAGE Solutions V8.3 26-258
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
start—This drives the clock line high if it is not already high,
then drives the data line low, and then drives the clock line low.
stop—This drives the data line low, then drives the clock line
high, and then drives the data line high.
read_byte—The next eight vectors of data appearing on the I2C
bus are read back and placed in the array ReceivedData[].
Multiple reads may be placed in a message. A write_bit_zero
or a write_bit_one command must follow if a master
acknowledge to the DUT is to be sent.
write_byte=<n>—This is used for primary and secondary
addresses and data. Multiple writes can be placed in a message.
<n> should be an 8 bit integer (0 ≤ n ≤ 255). A read_bit_zero
or a read_bit_one should follow if the state of the acknowledge
from the DUT is to be tested. A write_bit_one should be sent
if the state of the acknowledge will not be tested, but a clock
pulse is to be sent as a position holder.
write_bit_zero, write_bit_one—Use these to write the
master acknowledge after a read and to write individual bits
during a write message.
read_bit_zero, read_bit_one—These are used to test the
state of the acknowledge from the DUT after a write of address
or data. These message tokens cause the PASS flag to be set to
FALSE if there is not a match between each of the read_bit
values and the state of the corresponding acknowledge from the
DUT.
ARGUMENTS msg[]—Array of up to 4096 message tokens, null terminated
cdig_slot—Test head slot in which Serial Bus channel card is
located
RETURN VALUE Pointer to a structure with PASS/TIMEOUT set to either TRUE or
FALSE and ReceivedData as an array of integer values. Pattern
data is pointed to by Clock_Leading, Clock_Trailing, Drive_Pat,
and Receive_Pat.
SIDE EFFECTS Other SBCC channels on the board will be hi-Z during burst. A
pattern named data_test_pat is created, or modified if it
already exists. A segment named data_test is created, or
modified if it already exists.
tl_i2c_construct_msg_burst
Write specified Inter-IC Control bus (I2C) information.
SYNOPSIS tl_i2c_construct_msg_burst(name);
char *name;
IMAGE Solutions V8.3 26-259
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Writes the message tokens set up using the call to
tl_i2c_construct_msg_setup(<name>). SCL is on cdig_clk
pin and SDA is on cdig_io1 pin. A maximum of 4096 message
tokens can be sent in a single function call.
ARGUMENTS msg[]—Array of up to 4096 message tokens, null terminated
cdig_slot—Test head slot in which Serial Bus channel card is
located
RETURN VALUE Pointer to a structure with PASS/TIMEOUT set to either TRUE or
FALSE and ReceivedData as an array of integer values. Pattern
data is pointed to by Clock_Leading, Clock_Trailing,
Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other SBCC channels on the board will be hi-Z during burst.
SEE ALSO “tl_i2c_construct_msg”, “tl_i2c_construct_msg_setup”,
“tl_i2c_construct_msg_burst”
tl_i2c_construct_msg_pin
Writes specified I2C information
SYNOPSIS tl_i2c_construct_msg_pin(msg, cdig_pin)
char * msg[];
int cdig_pin;
DESCRIPTION Writes the specified message tokens. These include start,
stop, read_byte, write_byte= (followed by byte to be written)
write_bit_zero, write_bit_one, read_bit_zero,
read_bit_one. Timing, levels, and timeout value must already
have been set. SCL is on cdig_clk pin and SDA is on cdig_io1
pin. A maximum of 4096 message tokens can be sent in a single
function call.
Message tokens include:
start—Drives the clock line high if it is not already high, drives
the data line low, and then drives the clock line low.
stop—Drives the data line low, drives the clock line high, and
then drives the data line high.
read_byte—The next eight vectors of data appearing on the I2C
bus are read back and placed in the array ReceivedData[].
Multiple reads can be placed in a message. A write_bit_zero
or a write_bit_one command must follow if a master
acknowledge to the DUT is to be sent.
write_byte=<n>—Used for primary and secondary addresses
and data. Multiple writes can be placed in a message. <n>
should be an 8 bit integer (0 ≤ n ≤ 255). A read_bit_zero or a
read_bit_one should follow if the state of the acknowledge from
IMAGE Solutions V8.3 26-260
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
the DUT is to be tested. A write_bit_one should be sent if the
state of the acknowledge will not be tested, but a clock pulse is
to be sent as a position holder.
write_bit_zero, write_bit_one—Use these to write the
master acknowledge after a read and to write individual bits
during a write message.
read_bit_zero, read_bit_one—Use these to test the state of
the acknowledge from the DUT after a write of address or data.
These message tokens cause the PASS flag to be set to FALSE
if there is no match between each of the read_bit values and
the state of the corresponding acknowledge from the DUT.
ARGUMENTS msg[]—Array of up to 4096 message tokens, null terminated
cdig_pin—Pin number in front of the desired CDIG slot
RETURN VALUE Pointer to a structure with PASS/TIMEOUT set to either TRUE or
FALSE and ReceivedData as an array of integer values. Pattern
data is pointed to by Clock_Leading, Clock_Trailing,
Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst. A
pattern named data_test_pat is created or modified if it
already exists. A segment named data_test is created or
modified if it already exists.
tl_i2c_construct_msg_setup
Write specified Inter-IC Control bus (I2C) information.
SYNOPSIS tl_i2c_construct_msg_setup(msg, cdig_slot, name)
char * msg[];
int cdig_slot;
char * name;
DESCRIPTION Sets up a pattern which writes the specified message tokens.
The setup can be referenced using <name> when calling the
burst function. The tokens include start, stop, read_byte,
write_byte= (followed by byte to be written), write_bit_zero,
write_bit_one, read_bit_zero, and read_bit_one.
This function only creates and stores the pattern and related
information. The actual burst happens during the call to
tl_i2c_construct_msg_burst(name). A maximum of 4096
message tokens can be sent in a single function call.
Description of message tokens:
start—This will drive the clock line high if it is not already high,
then drive the data line low, and then drive the clock line low.
IMAGE Solutions V8.3 26-261
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
stop—This will drive the data line low, then drive the clock line
high, and then drive the data line high.
read_byte—The next eight vectors of data appearing on the I2C
bus will be read back and placed in the array ReceivedData[].
Multiple reads can be placed in a message. A write_bit_zero
or a write_bit_one command must follow if a master
acknowledge to the DUT is to be sent.
write_byte=<n>—This is used for primary and secondary
addresses and data. Multiple writes can be placed in a message.
<n> should be an eight bit integer (0 ≤ n ≤ 255). A
read_bit_zero or a read_bit_one should follow if the state of
the acknowledge from the DUT is to be tested. A
write_bit_one should be sent if the state of the acknowledge
will not be tested, but a clock pulse is to be sent as a position
holder.
write_bit_zero, write_bit_one—Use these to write the
master acknowledge after a read and to write individual bits
during a write message.
read_bit_zero, read_bit_one—These are used to test the
state of the acknowledge from the DUT after a write of address
or data. These message tokens cause the PASS flag to be set to
FALSE if there is not a match between each of the read_bit
values and the state of the corresponding acknowledge from the
DUT.
ARGUMENTS msg[]—Array of up to 4096 message tokens, null terminated
cdig_slot—Test head slot in which Serial Bus channel card is
located
name—Name to use for future reference to this setup
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT
FALSE. The ADDRESSES field is invalid for this function. The
pattern data created for this check is returned in the fields
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat. The only valid information returned by this setup
function is the pattern data.
SIDE EFFECTS Pattern named <name> and segment named <name>_seg are
redefined. Previously returned setup structure is overwritten.
tl_i2c_construct_msg_setup_pin
Write specified I2C information.
SYNOPSIS tl_i2c_construct_msg_setup_pin(msg, cdig_pin, name)
char * msg[];
IMAGE Solutions V8.3 26-262
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int cdig_pin;
char * name;
DESCRIPTION Sets up a pattern which writes the specified message tokens.
The setup can be referenced by using <name> when calling the
burst function. The tokens include start, stop, read_byte,
write_byte= (followed by byte to be written) write_bit_zero,
write_bit_one, read_bit_zero, read_bit_one.
This function only creates the pattern and stores the pattern and
related information. The actual burst occurs during the call to
tl_i2c_construct_msg_burst(name). A maximum of 4096
message tokens can be sent in a single function call.
Message tokens include:
start—Drives the clock line high if it is not already high, drives
the data line low, and then drives the clock line low.
stop—Drives the data line low, drives the clock line high, and
then drives the data line high.
read_byte—The next eight vectors of data appearing on the I2C
bus are read back and placed in the array ReceivedData[].
Multiple reads can be placed in a message. A write_bit_zero
or write_bit_one command must follow if a master
acknowledge to the DUT is to be sent.
write_byte=<n>—Used for primary and secondary addresses
and data. Multiple writes can be placed in a message. <n>
should be an 8 bit integer (0 <= n <= 255). A read_bit_zero or
read_bit_one should follow if the state of the acknowledge from
the DUT is to be tested. A write_bit_one should be sent if the
state of the acknowledge will not be tested but a clock pulse is to
be sent as a position holder.
write_bit_zero, write_bit_one—Use these to write the
master acknowledge after a read and to write individual bits
during a write message.
read_bit_zero, read_bit_one—Use these to test the state of
the acknowledge from the DUT after a write of address or data.
These message tokens cause the PASS flag to be set to FALSE
if there is no match between each of the read_bit values and
the state of the corresponding acknowledge from the DUT.
ARGUMENTS msg[]—Array of up to 4096 message tokens, null terminated
cdig_pin—Pin number in front of the desired CDIG slot
name—Name to use for future reference to this setup
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT
FALSE. The ADDRESSES field is invalid for this function. The
pattern data created for this check is returned in the fields
IMAGE Solutions V8.3 26-263
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat. The only valid information returned by this setup
function is the pattern data.
SIDE EFFECTS Pattern <name> and segment <name>_seg are redefined.
Previously returned setup structure is overwritten.
tl_i2c_data_test
Write Inter-IC Control bus (I2C) data and check for acknowledge.
SYNOPSIS tl_i2c_data_test(primary, secondary, data,
cdig_slot)
int primary, secondary, data[];
int cdig_slot;
DESCRIPTION Writes the specified data to the specified I2C address. Checks for
address and data acknowledge and timeout. Returns a structure
indicating PASS, FAIL, or TIMEOUT. Timing, levels, and timeout
value must already have been set. SCL is on cdig_clk pin and
SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address (including r/w bit)
secondary—Secondary I2C address if applicable, otherwise -1
data[]—Array of bytes of data to be written terminated in -1
cdig_slot—Test head slot in which Serial Bus channel card is
located
RETURN VALUE Pointer to a structure with
PASS/AddressFAIL/DataFAIL/TIMEOUT set to either TRUE or
FALSE. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board will be hi-Z during burst. A
pattern named data_test_pat is created, or modified if it
already exists. A segment named data_test is created, or
modified if it already exists.
tl_i2c_data_test_burst
Burst pattern and check for fail.
SYNOPSIS tl_i2c_data_test_burst(name)
char *name;
DESCRIPTION Executes the tl_i2c_data_test using the setup with the
specified name. Name is used to look up the parameters for this
burst.
Checks if any vectors failed. If a nonzero value was passed in for
the fast argument, only the AFR is checked rather than reading
back per-vector failure information.
IMAGE Solutions V8.3 26-264
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS name—Name of a setup created using
tl_i2c_data_test_setup.
RETURN VALUE Pointer to a structure with
PASS/AddressFAIL/DataFAIL/TIMEOUT set to TRUE/FALSE.
Pattern data is invalid.
SIDE EFFECTS Other CDIG channels on the board will be hi-Z during burst.
tl_i2c_data_test_pin
Writes data and checks for acknowledge.
SYNOPSIS tl_i2c_data_test_pin(primary, secondary, data,
cdig_pin)
int primary, secondary, data[];
int cdig_pin;
DESCRIPTION Writes the specified data to the specified I2C address. Checks for
address and data acknowledge, and timeout. Returns a structure
indicating PASS, FAIL, or TIMEOUT. Timing, levels, and timeout
value must already have been set. SCL is on cdig_clk pin and
SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address (including r/w bit)
secondary—Secondary I2C address if applicable, otherwise -1
data[]—Array of bytes of data to be written terminated in -1
cdig_pin—Pin number in front of the desired CDIG card
RETURN VALUE Pointer to a structure with
PASS/AddressFAIL/DataFAIL/TIMEOUT set to either TRUE or
FALSE. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst. A
pattern data_test_pat is created or modified if it already exists.
A segment data_test is created or modified if it already exists.
tl_i2c_data_test_setup
Set up pattern for acknowledge.
SYNOPSIS tl_i2c_data_test_setup(primary, secondary, data,
cdig_slot, name, fast)
int primary, secondary, data[];
int cdig_slot;
char *name;
int fast;
DESCRIPTION Creates and loads a pattern named <name> (<name> is the string
that was passed in). The pattern has a segment named
<name>_seg containing the vectors which produce the specified
IMAGE Solutions V8.3 26-265
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
data for the specified I2C address. For example, if dtest1 is the
string passed in for the argument <name>, a segment named
dtest1_seg is created and used to define a pattern named
dtest1.
If a nonzero value is passed in for the fast argument, only the
AFR is checked rather than per-vector failure information.
Returns a structure that shows the vector strings used to create
the segment. Other fields in the structure are invalid.
SCL is on the cdig_clk pin and SDA is on the cdig_io1 pin.
ARGUMENTS primary—Primary I2C address (including r/w bit)
secondary—Secondary I2C address if applicable, otherwise -1
data[]—Array of bytes of data to be written terminated in -1
cdig_slot—Test head slot in which Serial Bus channel card is
located
name—Name to use when referring to this setup
fast—0 for failure details
1 for simple PASS/FAIL
RETURN VALUE Pointer to a structure with
PASS/AddressFAIL/DataFAIL/TIMEOUT set to FALSE. Pattern
data returned in fields Clock_Leading, Clock_Trailing,
Drive_Pat, and Receive_Pat.
SIDE EFFECTS Pattern <name> and segment <name>_seg are redefined with
new information. Previously returned setup structure is
overwritten.
tl_i2c_data_test_setup_pin
Set up pattern for acknowledge.
SYNOPSIS tl_i2c_data_test_setup_pin(primary, secondary, data,
cdig_pin, name, fast)
int primary, secondary, data[];
int cdig_pin;
char *name;
int fast;
DESCRIPTION Creates and loads a pattern named <name> (<name> is the string
that was passed in). The pattern has a segment named
<name>_seg containing the vectors which produce the specified
data for the specified I2C address. For example, if dtest1 is the
string passed in for the argument <name>, a segment named
dtest1_seg is created and used to define a pattern named
dtest1.
If a nonzero value is passed in for the fast argument, only the
AFR is checked rather than per vector failure information.
IMAGE Solutions V8.3 26-266
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Returns a structure that shows the vector strings used to create
the segment. Other fields in the structure are invalid.
SCL is on the cdig_clk pin and SDA is on the cdig_io1 pin.
ARGUMENTS primary—Primary I2C address (including r/w bit)
secondary—Secondary I2C address if applicable, otherwise -1
data[]—Array of bytes of data to be written terminated in -1
cdig_pin—Pin number in front of the desired CDIG card
name—Name to use when referring to this setup
fast—0 for failure details
1 for simple PASS/FAIL
RETURN VALUE Pointer to a structure with
PASS/AddressFAIL/DataFAIL/TIMEOUT set to FALSE. Pattern
data returned in fields Clock_Leading, Clock_Trailing,
Drive_Pat, and Receive_Pat.
SIDE EFFECTS Pattern <name> and segment <name>_seg are redefined with
new information. Previously returned setup structure is
overwritten.
tl_i2c_extended_addr_check
Write Inter-IC Control bus (I2C) addresses and check for acknowledge.
SYNOPSIS tl_i2c_extended_addr_check(addresses, cdig_slot)
int addresses[], cdig_slot;
DESCRIPTION Sends all extended addresses from 0xF000 to 0xF7FF. Each
address is preceded by a start and followed by a stop bit. Tests
that only the specified addresses are acknowledged. Returns a
structure indicating PASS, FAIL, or TIMEOUT, and the
ADDRESSES that failed, if any. Timing, levels, and timeout value
must already have been set. SCL is on cdig_clk pin and SDA
is on cdig_io1 pin.
ARGUMENTS addresses[]—Array of 16 bit addresses (in the range of 0xF000
to 0xF7FF), terminated in -1
cdig_slot—Test head slot in which Serial Bus channel card is
located
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values, terminated in -1. Pattern data is pointed to by
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board will be hi-Z during burst. A
pattern named data_test_pat is created, or modified if it
IMAGE Solutions V8.3 26-267
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
already exists. A segment named data_test is created, or
modified if it already exists.
tl_i2c_extended_addr_check_pin
Write Inter-IC Control bus (I2C) addresses and check for acknowledge.
SYNOPSIS tl_i2c_extended_addr_check_pin(addresses, cdig_pin)
int addresses[], cdig_pin;
DESCRIPTION Sends all extended addresses from 0xF000 to 0xF7FF. Each
address is preceded by a start and followed by a stop bit. Tests
that only the specified addresses are acknowledged. Returns a
structure indicating PASS, FAIL, or TIMEOUT and the
ADDRESSES that failed, if any. Timing, levels, and timeout value
must already have been set. SCL is on cdig_clk pin and SDA
is on cdig_io1 pin.
ARGUMENTS addresses[]—Array of 16 bit addresses (in the range of 0xF000
to 0xF7FF), terminated in -1
cdig_pin—Pin number in front of the desired CDIG card
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values, terminated in -1. Pattern data is pointed to by
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst. A
pattern named data_test_pat is created, or modified if it
already exists. A segment named data_test is created, or
modified if it already exists.
tl_i2c_free_string_memory
Free string memory used by Inter-IC Control bus (I2C) functions.
SYNOPSIS void tl_i2c_free_string_memory();
DESCRIPTION Clears temporary string storage space used by I2C functions to
build patterns. Normally, this memory is resized as needed
during each call to the I2C functions.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS The pattern string pointers in the result structure returned by all
the I2C functions becomes invalid after this function is called.
IMAGE Solutions V8.3 26-268
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_i2c_rcv_data_rpt_test
Read Inter-IC Control bus (I2C) data and check for acknowledge.
SYNOPSIS tl_i2c_rcv_data_rpt_test(primary, secondary, num,
cdig_slot)
int primary, secondary, num;
int cdig_slot;
DESCRIPTION Reads the specified number of bytes from the given I2C address.
The stop bit is not sent, and the last byte is acknowledged by the
master receiver. Checks for address acknowledge and timeout.
Returns a structure indicating PASS, FAIL or TIMEOUT, and the
data read. Timing, levels, and timeout value must already have
been set. Maximum number of bytes read is 8000. SCL is on
cdig_clk pin and SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_slot—Test head slot in which Serial Bus Channel Card is
located
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ReceivedData as an array of integer
values. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other SBCC channels on the board will be hi-Z during burst. A
pattern named data_test_pat is created, or modified if it
already exists. A segment named data_test is created, or
modified if it already exists.
SEE ALSO “tl_i2c_rcv_data_test”
tl_i2c_rcv_data_rpt_test_burst
Sets up rpt_test_setup patterns.
SYNOPSIS tl_i2c_rcv_data_rpt_test_burst(name)
char *name;
DESCRIPTION Executes the tl_i2c_rcv_data_rpt_test created with the
name.
ARGUMENTS name—name of a setup created using
tl_i2c_rcv_data_rpt_test_setup.
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ReceivedData as an array of integer
values. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
IMAGE Solutions V8.3 26-269
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Other CDIG channels on the board will be hi-Z during burst.
SEE ALSO “tl_i2c_rcv_data_test”, “tl_i2c_rcv_data_test_burst”
tl_i2c_rcv_data_rpt_test_pin
Reads data and checks for acknowledge.
SYNOPSIS tl_i2c_rcv_data_rpt_test_pin(primary, secondary,
num, cdig_pin)
int primary, secondary, num;
int cdig_pin;
DESCRIPTION Reads the specified number of bytes from the given I2C address.
The stop bit is not sent, and the last byte is acknowledged by the
master receiver. Checks for address acknowledge and timeout.
Returns a structure indicating PASS, FAIL, or TIMEOUT and the
data read. Timing, levels, and timeout value must already have
been set. Maximum number of bytes read is 8000. SCL is on
cdig_clk pin and SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_pin—Pin number in front of the desired CDIG board
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ReceivedData as an array of integer
values. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst. A
pattern named data_test_pat is created or modified if it
already exists. A segment named data_test is created or
modified if it already exists.
SEE ALSO “tl_i2c_rcv_data_test”
tl_i2c_rcv_data_rpt_test_setup
Sets up rpt_test_setup patterns.
SYNOPSIS tl_i2c_rcv_data_rpt_test_setup(primary, secondary,
num, cdig_slot, name)
int primary, secondary, num;
int cdig_slot;
char *name;
DESCRIPTION Reads the specified number of bytes from the given I2C address.
The stop bit is not sent, and the last byte is acknowledged by the
master receiver. Checks for address acknowledge, and timeout.
Returns a structure indicating PASS, FAIL or TIMEOUT, and the
IMAGE Solutions V8.3 26-270
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
data read. Timing, levels, and timeout value must already have
been set. Maximum number of bytes read is 8000. SCL is on
cdig_clk pin and SDA is on cdig_io1 pin.
Creates a setup named <name> which has a record of the
parameters passed to this function for use during the
subsequent bursts.
ARGUMENTS primary—Primary I2C address
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_slot—Test head slot in which Serial Bus channel card is
located
name—Reference name for this setup, also used as the basis for
the names used in creating segment and pattern.
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ReceivedData as an array of integer
values. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Pattern named <name> and segment named <name>_seg are
redefined. Previously returned setup structure is overwritten.
SEE ALSO “tl_i2c_rcv_data_test”, “tl_i2c_rcv_data_test_burst”
tl_i2c_rcv_data_rpt_test_setup_pin
Sets up rpt_test_setup patterns.
SYNOPSIS tl_i2c_rcv_data_rpt_test_setup_pin(primary,
secondary, num, cdig_pin, name)
int primary, secondary, num;
int cdig_pin;
char *name;
DESCRIPTION Reads the specified number of bytes from the given I2C address.
The stop bit is not sent, and the last byte is acknowledged by the
master receiver. Checks for address acknowledge and timeout.
Returns a structure indicating PASS, FAIL, or TIMEOUT and the
data read. Timing, levels, and timeout value must already have
been set. Maximum number of bytes read is 8000. SCL is on
cdig_clk pin and SDA is on cdig_io1 pin.
Creates a setup named <name> which has a record of the
parameters passed to this function for use during the
subsequent bursts.
ARGUMENTS primary—Primary I2C address
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_pin—Pin number in front of the desired CDIG slot
IMAGE Solutions V8.3 26-271
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
name—Reference name for this setup, also used as the basis for
the names used in creating segment and pattern
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ReceivedData as an array of integer
values. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Pattern <name> and segment <name>_seg are redefined.
Previously returned setup structure is overwritten.
SEE ALSO “tl_i2c_rcv_data_test”, “tl_i2c_rcv_data_test_burst”
tl_i2c_rcv_data_test
Read Inter-IC Control bus (I2C) data and check for acknowledge.
SYNOPSIS tl_i2c_rcv_data_test(primary, secondary, num,
cdig_slot)
int primary, secondary, num;
int cdig_slot;
DESCRIPTION Reads the specified number of bytes from the given I2C address.
Checks for address acknowledge and timeout. Returns a
structure indicating PASS, FAIL or TIMEOUT, and the data read.
Timing, levels, and timeout value must already have been set.
Maximum number of bytes read is 8000. SCL is on cdig_clk pin
and SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_slot—Test head slot in which Serial Bus Channel Card is
located
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ReceivedData as an array of integer
values. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other SBCC channels on the board will be hi-Z during burst. A
pattern named data_test_pat is created, or modified if it
already exists. A segment named data_test is created, or
modified if it already exists.
SEE ALSO “tl_i2c_rcv_data_rpt_test”
tl_i2c_rcv_data_test_burst
Burst pattern and return read data.
IMAGE Solutions V8.3 26-272
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS tl_i2c_rcv_data_test_burst(name)
char *name;
DESCRIPTION Executes the tl_i2c_rcv_data_test setup with the specified
name.
Bursts pattern that reads a specified number of bytes from the
given I2C address. Checks for address acknowledge and
timeout. Returns a structure indicating PASS, FAIL or TIMEOUT,
and the data read. Timing, levels, and timeout value must
already have been set.
Maximum number of bytes read is 8000. SCL is on cdig_clk pin
and SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address (including r/w bit)
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_slot—Test head slot in which Serial Bus channel card is
located
name—Name of pattern given to
tl_i2c_rcv_data_test_setup()
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
FALSE. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst.
SEE ALSO “tl_i2c_rcv_data_test_setup”
tl_i2c_rcv_data_test_pin
Reads data and checks for acknowledge.
SYNOPSIS tl_i2c_rcv_data_test_pin(primary, secondary, num,
cdig_pin)
int primary, secondary, num
int cdig_pin;
DESCRIPTION Reads the specified number of bytes from the given I2C address.
Checks for address acknowledge and timeout. Returns a
structure indicating PASS, FAIL, or TIMEOUT and the data read.
Timing, levels, and timeout value must already have been set.
Maximum number of bytes read is 8000. SCL is on cdig_clk pin
and SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address (including r/w bit)
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_pin—Pin number in front of the desired CDIG card
IMAGE Solutions V8.3 26-273
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ReceivedData as an array of integer
values. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst. A
pattern data_test_pat is created or modified if it already exists.
A segment data_test is created or modified if it already exists.
SEE ALSO “tl_i2c_rcv_data_rpt_test”
tl_i2c_rcv_data_test_setup
Set up, read data, and check.
SYNOPSIS tl_i2c_rcv_data_test_setup(primary, secondary, num,
cdig_slot, name)
int primary, secondary, num
int cdig_slot;
char *name;
DESCRIPTION Creates segment and pattern that reads the specified number of
bytes from the given I2C address. The pattern will also check for
address acknowledge and timeout. Returns a structure that has
zero for PASS, FAIL or TIMEOUT, and the data read.
Maximum number of bytes read is 8000. SCL is on cdig_clk pin
and SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address (including r/w bit)
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_slot—Test head slot in which SBCC channel card is
located
name—Name to use when creating segment and pattern
RETURN VALUE Pointer to a structure with AddressFAIL/TIMEOUT set FALSE.
Pattern data is pointed to by Clock_Leading, Clock_Trailing,
Drive_Pat, and Receive_Pat.
SIDE EFFECTS Pattern <name> and segment <name>_seg are redefined.
Previously returned setup structure is overwritten.
SEE ALSO “tl_i2c_rcv_data_test”, “tl_i2c_rcv_data_test_burst”
tl_i2c_rcv_data_test_setup_pin
Set up, read data, and check.
SYNOPSIS tl_i2c_rcv_data_test_setup_pin(primary, secondary,
num, cdig_pin, name)
int primary, secondary, num
IMAGE Solutions V8.3 26-274
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int cdig_pin;
char *name;
DESCRIPTION Creates segment and pattern that reads the specified number of
bytes from the given I2C address. The pattern will also check for
address acknowledge and timeout. Returns a structure that has
zero for PASS, FAIL, or TIMEOUT and the data read.
Maximum number of bytes read is 8000. SCL is on cdig_clk pin
and SDA is on cdig_io1 pin.
ARGUMENTS primary—Primary I2C address (including r/w bit)
secondary—Secondary I2C address if applicable, otherwise -1
num—Number of bytes of data to be read, 8000 max
cdig_pin—The pin number in front of the desired CDIG card
name—Name to use when creating segment and pattern
RETURN VALUE Pointer to a structure with AddressFAIL/TIMEOUT set FALSE.
Pattern data is pointed to by Clock_Leading, Clock_Trailing,
Drive_Pat, and Receive_Pat.
SIDE EFFECTS Pattern <name> and segment <name>_seg are redefined.
Previously returned setup structure is overwritten.
SEE ALSO “tl_i2c_rcv_data_test”, “tl_i2c_rcv_data_test_burst”
tl_i2c_single_addr_check
Write Inter-IC Control bus (I2C) addresses and check for acknowledge.
SYNOPSIS tl_i2c_single_addr_check(addresses, cdig_slot)
int addresses[], cdig_slot;
DESCRIPTION Sends all extended addresses from 0x00 to 0xFF. Each address
is preceded by a start and followed by a stop condition. Tests that
only the specified addresses are acknowledged. Returns a
structure indicating PASS, FAIL, or TIMEOUT, and the
ADDRESSES that failed, if any. Timing, levels, and timeout value
must already have been set. SCL is on cdig_clk pin and SDA
is on cdig_io1 pin.
ARGUMENTS addresses[]—Array of primary addresses terminated in -1
cdig_slot—Test head slot in which Serial Bus Channel Card is
located
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values, terminated in -1. Pattern data is pointed to by
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat.
SIDE EFFECTS Other SBCC channels on the board will be hi-Z during burst.
IMAGE Solutions V8.3 26-275
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_i2c_single_addr_check_burst
Write addresses and check for acknowledge.
SYNOPSIS tl_i2c_single_addr_check_burst(addresses,
cdig_slot)
int addresses[], cdig_slot;
DESCRIPTION Bursts pattern created by tl_i2c_single_addr_check_setup.
That pattern sends all addresses from 0x00 to 0xFF. Each
address is preceded by a start and followed by a stop condition.
Returns a structure indicating PASS, FAIL or TIMEOUT, and the
ADDRESSES that failed, if any. Timing, levels, and timeout value
must already have been set. SCL is on cdig_clk pin and SDA
is on cdig_io1 pin.
tl_i2c_single_addr_check_setup combined with
tl_i2c_single_addr_check_burst performs the same
function as tl_i2c_single_addr_check without the overhead
of recreating and loading the pattern for every address check.
ARGUMENTS addresses[]—Array of primary addresses, terminated in -1
cdig_slot—Test head slot in which SBCC channel card is
located
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values, terminated in -1. Pattern data is invalid upon return from
this function, since no patterns were created.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst
SEE ALSO “tl_i2c_single_addr_check_setup”
tl_i2c_single_addr_check_burst_pin
Write addresses and check for acknowledge.
SYNOPSIS tl_i2c_single_addr_check_burst_pin(addresses,
cdig_pin)
int addresses[], cdig_pin;
DESCRIPTION Bursts pattern created by tl_i2c_single_addr_check_setup.
That pattern sends all addresses from 0x00 to 0xFF. Each
address is preceded by a start and followed by a stop condition.
Returns a structure indicating PASS, FAIL, or TIMEOUT and the
ADDRESSES that failed, if any. Timing, levels, and timeout value
must already have been set. SCL is on cdig_clk pin and SDA
is on cdig_io1 pin.
tl_i2c_single_addr_check_setup combined with
tl_i2c_single_addr_check_burst performs the same
IMAGE Solutions V8.3 26-276
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
function as tl_i2c_single_addr_check without the overhead
of recreating and loading the pattern for every address check.
ARGUMENTS addresses[]—Array of primary addresses, terminated in -1
cdig_pin—Pin number in front of the desired CDIG card
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values, terminated in -1. Pattern data is invalid upon return from
this function, since no patterns were created.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst
SEE ALSO “tl_i2c_single_addr_check_setup”
tl_i2c_single_addr_check_pin
Writes addresses and checks for acknowledge.
SYNOPSIS tl_i2c_single_addr_check_pin(addresses, cdig_pin)
int addresses[], cdig_pin;
DESCRIPTION Sends all addresses from 0x00 to 0xFF. Each address is
preceded by a start and followed by a stop condition. Tests that
only the specified addresses are acknowledged. Returns a
structure indicating PASS, FAIL, or TIMEOUT and the
ADDRESSES that failed, if any. Timing, levels and timeout value
must already have been set. SCL is on cdig_clk pin and SDA
is on cdig_io1 pin.
ARGUMENTS addresses[]—Array of primary addresses terminated in -1
cdig_pin—Pin number in front of the desired CDIG card
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values, terminated in -1. Pattern data is pointed to by
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst
tl_i2c_single_addr_check_rcv
Write addresses and check for acknowledge.
SYNOPSIS tl_i2c_single_addr_check_rcv(addresses, cdig_slot)
int addresses[], cdig_slot;
DESCRIPTION Sends all addresses from 0x00 to 0xFF. Each address is
preceded by a start and followed by a stop condition unless it is
a receive address listed in addresses[], in which case, a byte
is read after the address is sent. Tests that only the specified
IMAGE Solutions V8.3 26-277
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
addresses are acknowledged. Returns a structure indicating
PASS, FAIL, or TIMEOUT, and the ADDRESSES that failed, if
any. Timing, levels, and timeout value must already have been
set.
SCL is on cdig_clk pin and SDA is on cdig_io1 pin.
ARGUMENTS addresses[]—Array of primary addresses, terminated in -1
cdig_slot—Test head slot in which SBCC channel card is
located
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values, terminated in -1. Pattern data is pointed to by
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat.
SIDE EFFECTS Other SBCC channels on the board will be hi-Z during burst A
pattern named data_test_pat is created, or modified if it
already exists. A segment named data_test is created, or
modified if it already exists.
tl_i2c_single_addr_check_rcv_burst
Write addresses and check for acknowledge.
SYNOPSIS tl_i2c_single_addr_check_rcv_burst(name)
char *name;
DESCRIPTION Bursts setup created using
tl_i2c_single_addr_check_rcv_setup. Timing, levels, and
timeout value must already have been set. SCL is on cdig_clk
pin and SDA is on cdig_io1 pin.
tl_i2c_single_addr_check_rcv_setup combined with
tl_i2c_single_addr_check_rcv_burst performs the same
function as tl_i2c_single_addr_check_rcv without the
overhead of recreating and loading the pattern every time the
function is run.
ARGUMENTS addresses[]—Array of primary addresses, terminated in -1
cdig_slot—Test head slot in which SBCC channel card is
located
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values, terminated in -1. Pattern data is invalid upon return from
this function, since no patterns were created.
SIDE EFFECTS Other SBCC channels on the board will be hi-Z during burst.
SEE ALSO “tl_i2c_single_addr_check_setup”
IMAGE Solutions V8.3 26-278
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_i2c_single_addr_check_rcv_pin
Writes addresses and checks for acknowledge.
SYNOPSIS tl_i2c_single_addr_check_rcv_pin(addresses,
cdig_pin)
int addresses[], cdig_pin;
DESCRIPTION Sends all addresses from 0x00 to 0xFF. Each address is
preceded by a start and followed by a stop condition unless it is
a receive address listed in addresses[], in which case a byte is
read after the address is sent. Tests that only the specified
addresses are acknowledged. Returns a structure indicating
PASS, FAIL, or TIMEOUT and the ADDRESSES that failed, if
any. Timing, levels, and timeout value must already have been
set. SCL is on cdig_clk pin and SDA is on cdig_io1 pin.
ARGUMENTS addresses[]—Array of primary addresses terminated in -1
cdig_pin—Pin number in front of the desired CDIG card
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
either TRUE or FALSE and ADDRESSES as an array of integer
values terminated in -1. Pattern data is pointed to by
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat.
SIDE EFFECTS Other CDIG channels on the board are hi-Z during burst. A
pattern data_test_pat is created or modified if it already exists.
A segment data_test is created or modified if it already exists.
tl_i2c_single_addr_check_rcv_setup
Write addresses and check for acknowledge.
SYNOPSIS tl_i2c_single_addr_check_rcv_setup(addresses,
cdig_slot, name)
int addresses[], cdig_slot;
char *name;
DESCRIPTION Creates and loads a pattern which sends all addresses from
0x00 to 0xFF. Each address is preceded by a start and followed
by a stop condition unless it is a receive address listed in
addresses[], in which case, cycles for the read byte are
included after the address is sent. The pattern will only test that
only the specified addresses are acknowledged.
A call to this function creates a setup with the name passed in as
the argument. This setup can be referenced in a call to
tl_i2c_single_addr_check_rcv_burst, which will burst the
pattern on the hardware.
IMAGE Solutions V8.3 26-279
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_i2c_single_addr_check_rcv_setup combined with
tl_i2c_single_addr_check_rcv_burst performs the same
function as tl_i2c_single_addr_check_rcv without the
overhead of recreating and loading the pattern every time the
function is run.
ARGUMENTS addresses[]—Array of primary addresses, terminated in -1
cdig_slot—Test head slot in which Serial Bus channel card is
located
name—The name of the setup to create
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
FALSE. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Pattern named <name> and segment named <name>_seg are
defined if they do not exist and redefined if they do. Previously
returned setup structure is overwritten.
tl_i2c_single_addr_check_rcv_setup_pin
Write addresses and check for acknowledge.
SYNOPSIS tl_i2c_single_addr_check_rcv_setup_pin(addresses,
cdig_pin, name)
int addresses[], cdig_pin;
char *name;
DESCRIPTION Creates and loads a pattern which sends all addresses from
0x00 to 0xFF. Each address is preceded by a start and followed
by a stop condition unless it is a receive address listed in
addresses[], in which case, cycles for the read byte are
included after the address is sent. The pattern will only test that
only the specified addresses are acknowledged.
A call to this function creates a setup with the name passed in as
the argument. This setup can be referenced in a call to
tl_i2c_single_addr_check_rcv_burst, which will burst the
pattern on the hardware.
tl_i2c_single_addr_check_rcv_setup combined with
tl_i2c_single_addr_check_rcv_burst performs the same
function as tl_i2c_single_addr_check_rcv without the
overhead of recreating and loading the pattern every time the
function is run.
ARGUMENTS addresses[]—Array of primary addresses, terminated in -1
cdig_pin—Pin number in front of the desired CDIG card
name—Name of the setup to create
IMAGE Solutions V8.3 26-280
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT set to
FALSE. Pattern data is pointed to by Clock_Leading,
Clock_Trailing, Drive_Pat, and Receive_Pat.
SIDE EFFECTS Pattern <name> and segment <name>_seg are defined if they do
not exist and redefined if they do. Previously returned setup
structure is overwritten.
tl_i2c_single_addr_check_setup
Set up pattern for address check.
SYNOPSIS tl_i2c_single_addr_check_setup(cdig_slot)
int cdig_slot;
DESCRIPTION Creates and loads a general purpose single address check
pattern into the SBCC in slot cdig_slot. (This is the same
pattern created by tl_i2c_single_addr_check().)
The pattern is composed of 256 sequences of start, address,
acknowledge check, and stop for each of the 256 possible read
and write addresses in 7 bit addressing mode. The pattern is set
up so that every address is expected to be acknowledged. This
is so that the same pattern can be used for any set of expected
addresses.
When tl_i2c_single_addr_check_burst is run, failures are
compared against the list of expected failures, and false positive
and false negative responses are reported.
The pattern created is named
tl_i2c_single_addr_check_pat and it is composed of one
segment, tl_i2c_single_addr_check_seg.
tl_i2c_single_addr_check_setup combined with
tl_i2c_single_addr_check_burst performs the same
function as tl_i2c_single_addr_check without the overhead
of recreating and loading the pattern for every address check.
ARGUMENTS cdig_slot—Test head slot in which SBCC channel card is
located
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT
FALSE. The ADDRESSES field is invalid for this function. The
pattern data created for this check is returned in the fields
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat. The only valid information returned by this setup
function is the pattern data.
SIDE EFFECTS A 3328 vector pattern named tl_i2c_single_addr_check_pat
with segment tl_i2c_single_addr_check_seg is created and
IMAGE Solutions V8.3 26-281
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
loaded into the SBCC in slot cdig_slot. Previously returned
setup structure is overwritten.
SEE ALSO “tl_i2c_single_addr_check_burst”, “tl_i2c_single_addr_check”
tl_i2c_single_addr_check_setup_pin
Set up pattern for address check.
SYNOPSIS tl_i2c_single_addr_check_setup_pin(cdig_pin)
int cdig_pin;
DESCRIPTION Creates and loads a general purpose single address check
pattern into the SBCC in slot behind the given pin number. (This
is the same pattern created by tl_i2c_single_addr_check().)
The pattern is composed of 256 sequences of start, address,
acknowledge check, and stop for each of the 256 possible read
and write addresses in 7 bit addressing mode. The pattern is set
up so that every address is expected to be acknowledged. This
is so that the same pattern can be used for any set of expected
addresses.
When tl_i2c_single_addr_check_burst is run, failures are
compared against the list of expected failures and false positive
and false negative responses are reported.
The pattern created is named
tl_i2c_single_addr_check_pat and it is composed of one
segment, tl_i2c_single_addr_check_seg.
tl_i2c_single_addr_check_setup combined with
tl_i2c_single_addr_check_burst performs the same
function as tl_i2c_single_addr_check without the overhead
of recreating and loading the pattern for every address check.
ARGUMENTS cdig_pin—Pin number in front of the desired CDIG card
RETURN VALUE Pointer to a structure with PASS/AddressFAIL/TIMEOUT
FALSE. The ADDRESSES field is invalid for this function. The
pattern data created for this check is returned in the fields
Clock_Leading, Clock_Trailing, Drive_Pat, and
Receive_Pat. The only valid information returned by this setup
function is the pattern data.
SIDE EFFECTS A 3328 vector pattern named tl_i2c_single_addr_check_pat
with segment tl_i2c_single_addr_check_seg is created and
loaded into the SBCC in slot pin. Previously returned setup
structure is overwritten.
SEE ALSO “tl_i2c_single_addr_check_burst”, “tl_i2c_single_addr_check”
IMAGE Solutions V8.3 26-282
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_init
Initialize a test program.
SYNOPSIS tl_init()
{
<user statements>
}
DESCRIPTION If this function exists within a test program, any statements
located in the body of the function are executed immediately
following test program loading. This occurs before the first time
the test program is run.
tl_init provides a way to execute statements that only need to
executed once after a test program is loaded, such as
statements to define ac source waveforms and permanent DSP
buffers.
This function is not called as part of the initialize station window
or background menu commands.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_prod_init”
tl_input_adjust
Find an appropriate input given an output.
SYNOPSIS enum Ia_returns
tl_input_adjust(adjust_func, lo_limit, hi_limit,
output_target, resolution, polarity,
max_loop_count, answer)
double (*adjust_func)();
double lo_limit;
double hi_limit;
double output_target;
double resolution;
enum Ia_adjust_polar_values polarity;
int max_loop_count;
double *answer;
DESCRIPTION Given an output value, this function finds an appropriate input
through a modified binary search algorithm.
ARGUMENTS adjust_func—user-written test function to test inputs
lo_limit—low limit for input search
hi_limit—high limit for input search
output_target—the target output
resolution—the search resolution. When the difference
IMAGE Solutions V8.3 26-283
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
between successive tests on the input is less than this value the
search is abandoned.
polarity—flag indicating search direction:
IA_POSITIVE_POLAR: input and output are expected to be
proportional.
IA_NEGATIVE_POLAR: input and output are expected to be
inversely proportional.
IA_AUTO_POLAR: program determines search direction.
max_loop_count—max number of iterations to find input.
answer—the answer: the input appropriate for output is written
here.
RETURN VALUE Returns an enumerated value. The enumerators and their values
are as follows:
enum Ia_returns{
IA_INVALID_ARGUMENT = -1,/* bad args */IA_RETURN_OK = 0,/* solution found */
IA_RETURN_NO_RESOLUTION = 1,/* exhausted search by max_loops tries */
IA_RETURN_INPUT_TOO_LOW = 2,/* lo_limit was too high */
IA_RETURN_INPUT_TOO_HIGH = 3};/* 'input' is above hi_limit */
tl_job_is_in_debug
Determine if test program is running in debug mode.
SYNOPSIS int tl_job_is_in_debug();
DESCRIPTION Determines if a test program is currently in debug mode.
ARGUMENTS None
RETURN VALUE 0—Test program is not in debug mode
1—Test program is in debug mode
SEE ALSO “tl_read_mode_cod”
tl_legal_pin_array
Determine if variable is a legal pin number.
SYNOPSIS tl_legal_pin_array(var)
void *var;
DESCRIPTION This function returns nonzero if the passed argument is a legal
pin array (that is, null-terminated, unsigned short, all of whose
elements are legal pin numbers).
ARGUMENTS var—Possible pin array
RETURN VALUE Nonzero for True, 0 for False.
SEE ALSO “tl_legal_pin_number”
IMAGE Solutions V8.3 26-284
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_legal_pin_number
Determine if variable is a legal pin number.
SYNOPSIS tl_legal_pin_number(var)
void *var;
DESCRIPTION This function returns nonzero if the passed argument is a legal
pin number (that is, one currently defined in the pinmap).
ARGUMENTS var—Possible pin number
RETURN VALUE Nonzero for True, 0 for False.
SEE ALSO “tl_legal_pin_array”
tl_lfacd_02_move_alarm_bit
Control whether alarm bit is moved.
SYNOPSIS void tl_lfacd_02_move_alarm_bit(setting)
int setting;
DESCRIPTION If called with TRUE, 18 bits are moved to include the alarm bit
with each sample. By default, or if called with FALSE, only the 16
bits of data are moved. This only affects the 949-660-02
LFACDIG.
ARGUMENTS setting—TRUE to cause alarm bit to be moved
SIDE EFFECTS Moves are slightly slower when the alarm bit is moved as well.
tl_lfacdig_set_precharge_time
Set the time for the precharge
SYNOPSIS double tl_lfacdig_set_precharge_time
(cap_charge_time)
DESCRIPTION With the Dual LFAC channel card, there is an optional AC
coupling for the digitizer input, which puts a 4.7nF capacitor in
series. This function lets you control the time that the precharge
relay is kept closed to charge or discharge this capacitor. You
can use this control in cases where the impedance of the DUT is
reasonably high so that the capacitor must be fully charged or
discharged.
If the specified capacitor charge time is within the valid range of
10µs to 25.5ms inclusive, the function rounds it up to the next
multiple of 10µs (if the value is already a multiple of 10µs, the
function does not change it). If the value is out of range, the
function issues a fatal error and uses the range limit nearest to
the specified value (that is, it uses the saturation time). It stores
IMAGE Solutions V8.3 26-285
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
the result in the variable tl_lfacdig_cap_charge_wait_time
that is used for keeping the relay closed. This variable is also
returned to the caller.
Note that this single number is global to all LFAC digitizers, so
the pin specification is not used. This number is also a minimum
number - the actual capacitor charge time is a few microseconds
longer than this due to computational delays. This wait time is set
to the default of 200µs by the reset lfacdig; statement.
ARGUMENTS double cap_charge_time;
where cap_charge_time is the desired minimum time to wait,
given in seconds.
RETURN VALUE Wait time for the capacitor to charge (a multiple of 10µs).
tl_lfac_disable_dut_connects
Disable connections to the DUT.
SYNOPSIS void tl_lfac_disable_dut_connects()
DESCRIPTION Disables connections to the DUT. Connect statements will
appear to succeed, but relay connections to the DUT (channel
card Pogo pins) will not be made. tl_enable_dut_connects
and tl_disable_dut_connects also control these relay
connections.
When either tl_disable_dut_connects or
tl_lfac_disable_dut_connects or both have disabled, the
DUT relays will not be closed. Initial condition is that
tl_lfac_enable_dut_connects has effectively enabled.
ccgnd __
| Relays closed by
DC matrix
__| tl_lfac_disable_dut_connects
|
THADS Bus __|
|
Instrument HI __________|________ HI pin to DUT
Instrument LO __________|________ LO pin to DUT
|
ccgnd __|
|
DC matrix __|
|
THADS Bus __|
ARGUMENTS None
IMAGE Solutions V8.3 26-286
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
SEE ALSO tl_enable_dut_connects, tl_disable_dut_connects,
“tl_lfac_enable_dut_connects”
tl_lfac_enable_dut_connects
Enable connections to the DUT.
SYNOPSIS void tl_lfac_enable_dut_connects
DESCRIPTION Enable connections to the DUT. From now on, connect
statements are allowed to close the relay connections to the DUT
(channel card Pogo pins). tl_enable_dut_connects and
tl_disable_dut_connects also control these relay
connections.
Only when both tl_enable_dut_connects and
tl_lfac_enable_dut_connects have enabled will the DUT
relays be closed. Initial condition is that
tl_lfac_enable_dut_connects has effectively enabled.
ccgnd__
|
DC matrix__| __These are the "DUT" relays in question
| |
THADS Bus__| v
|
Instrument HI__________|________HI pin to DUT
Instrument LO__________|________LO pin to DUT
|
ccgnd__|
|
DC matrix__|
|
THADS Bus__|
Connections to the DUT can be disabled using the function
tl_lfac_disable_dut_connects().
This function, tl_lfac_enable_dut_connects(), also re-
enables these connections.
ARGUMENTS None
RETURN VALUE None
SEE ALSO tl_enable_dut_connects, tl_disable_dut_connects,
“tl_lfac_disable_dut_connects”
IMAGE Solutions V8.3 26-287
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_lfacs_conn_deltabus
Connect LFACSRC output to delta bus.
SYNOPSIS int tl_lfacs_conn_deltabus(on_off, pin)
int on_off;
int pin;
DESCRIPTION Connects or disconnects LFACSRC output to the delta bus
through the wave bus. Connection is made differentially. Sets the
delta input to bus on connect.
ARGUMENTS on_off
RETURN VALUE 1 if successful, 0 if not.
tl_lfacs_get_wave_fs
Read back Fs of an LFACSRC waveform.
SYNOPSIS double tl_lfacs_get_wave_fs(wavename)
char *wavename;
DESCRIPTION Given the name of an LFACSRC waveform, this function
determines and returns the sampling frequency for which this
waveform was created.
ARGUMENTS wavename—The user-visible name of the waveform.
RETURN VALUE 0 if error, otherwise, Fs for specified waveform.
tl_lfacs_multitone_ac_crest_factor
Get LFACSRC crest factor.
SYNOPSIS double tl_lfacs_multitone_ac_crest_factor()
DESCRIPTION Returns AC crest factor (ratio of peak to RMS value, not
accounting for any baseline offset) of the last LFACSRC
multitone waveform created for this instrument type. When a
particular RMS value is desired, this function is used to
determine the amp value to specify, with ampunit:vpk.
ARGUMENTS None
RETURN VALUE Crest factor (-1.0 if no LFACSRC multitone waveform has been
created or if any of the components have identical frequency)
tl_lfacsrc_get_grow_dir
Get LFACSRC segment growth direction.
SYNOPSIS int tl_lfacsrc_get_grow_dir(pinnumber)
int pinnumber;
IMAGE Solutions V8.3 26-288
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Return the code for the segment growth direction.
ARGUMENTS pinnumber—LFACSRC pin number
RETURN VALUE Segment growth direction in memory. The valid “growth” codes
are 1 for down and 0 for up.
LFACSRC_MEM_GROWTH_DIR_NOT_FOUND (999) is returned if it
does not work.
SIDE EFFECTS Selects specified instrument if instrument is an LFACSRC.
tl_lfacs_sinxx_amp
Calculate sin x/x corrected amplitude of an LFACSRC waveform.
SYNOPSIS double tl_lfacs_sinxx_amp(fund_freq, wavename,
desired_amp)
double fund_freq;
char *wavename;
double desired_amp;
DESCRIPTION Calculates sin x/x corrected amplitude for an LFACSRC
waveform. Given the signal fundamental frequency, the
wavename, and the desired amplitude, this function returns the
amplitude that must be programmed to get the desired
amplitude.
ARGUMENTS fund_freq—The signal fundamental frequency
wavename—The user-visible name of the waveform.
desired_amp—The desired amplitude
RETURN VALUE 0 if error, otherwise, the amplitude to be programmed.
SEE ALSO “tl_sinxx_amp”
tl_matrix_bank_force
Override auto open and close of bank relays.
SYNOPSIS void tl_matrix_bank_force(state,bank)
unsigned state;
unsigned bank;
DESCRIPTION Overrides the automatic opening and closing of the line to bank
relays.
ARGUMENTS unsigned state—1 means keep the lines closed to this bank
0 means open and close the banks automatically
unsigned bank—Bank affected by this call
RETURN VALUE None
IMAGE Solutions V8.3 26-289
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Forcing closed closes all line to bank switches. Re-enabling the
automatic function opens the switches for all unused lines.
tl_mcfd_clear_counter
Reset maximum consecutive failing device (MCFD) count for site.
SYNOPSIS int tl_mcfd_clear_counter();
DESCRIPTION Clears the MCFD counters for all sites, that is resets all current
counts to 0. This function can be called from within a serial block
to clear counters for specific sites.
To clear MCFD counters for all sites use:
tl_mcfd_clear_counter();
To clear counters for only a specific site use:
serial {
if (site_to_clear == tl_site)
tl_mcfd_clear_counter();
}
where site_to_clear is the number of some site whose
counter is to be cleared.
ARGUMENTS None
RETURN VALUE 0—Failure
1—Success counter cleared
SIDE EFFECTS Clears the current MCFC counts.
tl_mcfd_disable_site
Disable maximum consecutive failing device monitoring on one or more sites.
SYNOPSIS int tl_mcfd_disable_site()
DESCRIPTION Disables MCFD monitoring for all test sites. The trigger and
count for sites are cleared and, before MCFD can be monitored,
tl_mcfd_init() must be called.
This function is particularly useful for multisite test programs
which may, for some reason, stop monitoring MCFD on a
particular site. To turn off MCFD on a site-by-site basis, you must
call this function from within a serial block.
Unlike tl_mcfd_switch_off(), this function clears the MCFD
trigger count as well as the current count.
This function also checks if, after disabling a site, any sites are
initialized for MCFD. If no sites remain initialized for MCFD, the
IMAGE Solutions V8.3 26-290
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
initialization is set to FALSE, indicating MCFD must be initialized
and the state of MCFD is turned off.
To disable MCFD at all sites use:
tl_mcfd_disable_site();
To disable MCFD for only a specific site use:
serial {
if (site_to_disable == tl_site)
tl_mcfd_disable_site();
}
where site_to_disable is the number of some site where
MCFD is to be disabled.
ARGUMENTS None
RETURN VALUE 0 on error
1 on success
SIDE EFFECTS Sets the trigger and count values for all sites or a particular site
to 0, disabling MCFD for a site. May reinitialize all of MCFD and
turn off MCFD.
SEE ALSO “tl_mcfd_init”
tl_mcfd_init
Initialize maximum consecutive failure levels.
SYNOPSIS int tl_mcfd_init(int count);
DESCRIPTION Initializes the maximum consecutive failing device counters for
all sites. The initialization can be done for individual sites by
calling this function from within a serial block.
This function must be called at least once before any other
functions used to interface to the Maximum Consecutive Failing
Devices (MCFD) feature.
Note that this function accepts a value of 0 for the trigger value,
which effectively disables MCFD monitoring at a particular site.
You are not warned.
To set all sites to trigger the MCFD run time error after five
consecutive failing devices use:
tl_mcfd_init(5);
To set some sites to trigger after different numbers of
consecutive failing devices use:
serial {
switch (tl_site) {
case 0: tl_mcfd_init(1);
IMAGE Solutions V8.3 26-291
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
break;
case 1: tl_mcfd_init(2);
break;
case 2: tl_mcfd_init(3);
break;
case 3: tl_mcfd_init(4);
break;
}
}
ARGUMENTS int count—Number of consecutive failures which will trigger
alarm.
RETURN VALUE 0—Indicates error or user has initialized an alarm to trigger after
0 failures, does nothing
>0—Indicates success and is the number of consecutive failing
devices which will trigger an alarm for that site
SIDE EFFECTS Initializes MCFD counters for a particular site, enabling MCFD to
be monitored for a site.
tl_mcfd_monitor_hbin
Monitor hardware bins for maximum consecutive device failure.
SYNOPSIS void tl_mcfd_monitor_hbin(void);
DESCRIPTION Informs the MCFD software that hardware bins are to be
monitored. Monitoring hardware bins is the default. This function
only needs to be called if software bins were previously being
monitored. MCFD counts for all sites are cleared when this
function is called.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Hardware bins are monitored and clears the current counts, for
all sites.
tl_mcfd_monitoring_on
Return the state (on or off) of maximum consecutive failing device (MCFD). monitoring.
SYNOPSIS int tl_mcfd_monitoring_on();
DESCRIPTION Returns the state of MCFD monitoring.
ARGUMENTS None
RETURN VALUE TRUE if MCFD monitoring is turned on.
FALSE if MCFD monitoring has not been turned on.
IMAGE Solutions V8.3 26-292
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_mcfd_monitor_sbin
Monitor software bins for maximum consecutive device failure.
SYNOPSIS void tl_mcfd_monitor_sbin(void);
DESCRIPTION Tells the MCFD software to monitor software bins. Monitoring
hardware bins is the default. This function must be called to
monitor software bins. MCFD counts for all sites are cleared
when this function is called.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Software bins are monitored and clears the current counts, for all
sites.
tl_mcfd_switch_off
Turn off maximum consecutive failing devices (MCFD) monitoring.
SYNOPSIS int tl_mcfd_switch_off(void)
DESCRIPTION Turns off MCFD monitoring. MCFD alarms will not be triggered
and MCFD counts will not be incremented.
ARGUMENTS None
RETURN VALUE Current state of MCFD monitoring. Usually 0. Any other value
indicates a serious system error.
SIDE EFFECTS Turns off MCFD monitoring.
SEE ALSO “tl_mcfd_switch_on”
tl_mcfd_switch_on
Turn on maximum consecutive failing devices monitoring.
SYNOPSIS int tl_mcfd_switch_on(void);
DESCRIPTION This function is used to activate Maximum Consecutive Failing
Devices (MCFD) monitoring. It first verifies the initialization
function has been called previously. It then returns the current
state of MCFD.
ARGUMENTS None
RETURN VALUE 0—MCFD monitoring is off. This indicates an error.
1—MCFD monitoring is on. This indicates success.
SIDE EFFECTS May turn on MCFD monitoring.
SEE ALSO “tl_mcfd_switch_off”
IMAGE Solutions V8.3 26-293
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_measure_calibrate
Calibrate Low Current Ammeter raw measurement samples.
SYNOPSIS double tl_measure_calibrate(raw);
int raw;
DESCRIPTION Calibrates a single raw sample.
ARGUMENTS raw—Integer raw sample.
RETURN VALUE Calibrated measurement.
SIDE EFFECTS Depends on last move measurement statement.
SEE ALSO “tl_measure_calibrate_n”
Use tl_measure_calibrate_n() for calibrating integrating
Low Current Ammeter measurements, as current depends on
the slope of the raw values, which is 0 in the case of a single-
point measurement.
tl_measure_calibrate_n
Calibrate N raw samples for Low Current Ammeter.
SYNOPSIS int tl_measure_calibrate_n(raw, cal, sample_size);
int *raw;
double *cal;
int sample_size;
DESCRIPTION Calibrates an array of raw samples of length sample_size,
writing its output into the passed array of doubles. Uses the
calibration factors and algorithm for the most recently named
measurable in a move measurement statement.
ARGUMENTS raw—Pointer to input array of integer raw samples.
cal—Pointer to output array of double measurements.
sample_size—Number of elements in raw[].
RETURN VALUE Number of elements written to cal.
cal array is filled with calibrated measurements.
Either sample_size values, or fewer values, depending on the
mode of the measurable, may be written. (LCA in integrate mode
writes a scalar in cal[0] and returns 1.)
SIDE EFFECTS Depends on last move measurement statement.
tl_measure_sample_period
Return adjusted sample period.
SYNOPSIS double tl_measure_sample_period();
IMAGE Solutions V8.3 26-294
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Returns the actual sample period, per measurable, that resulted
from the last set measure statement, adjusted to the resolution
of the selected clock.
ARGUMENTS None
RETURN VALUE Actual sample period.
tl_memman_recompact_off
Turn off memory recompaction.
SYNOPSIS int tl_memman_recompact_off();
DESCRIPTION Disable recompaction of memory when insufficient contiguous
space available. The default state is memory recompaction off.
RETURN VALUE Old setting:
1—was enabled
0—was disabled
SEE ALSO “tl_memman_recompact_on”
tl_memman_recompact_on
Turn on memory recompaction.
SYNOPSIS int tl_memman_recompact_on();
DESCRIPTION Enable recompaction of memory when insufficient contiguous
space available. Option currently implemented only on HSD50
memory types.
This function compacts memory when it runs out of contiguous
space and there is enough free space to fit the pattern being
loaded. If there is not enough free space, the function does not
recompact memory.
This function may move modified patterns loaded on other
stations. The modifications may be lost. This occurs only when:
–Pattern memory compaction is enabled.
–Two test stations are used.
–Patterns are modified on the test station not currently running.
–Pattern memory is fragmented, causing memory to be
recompacted.
–The modified pattern is moved during recompaction.
To avoid losing modifications, load patterns which will be
modified first in the test program. The compaction algorithm
moves patterns toward the ends of memory. If the pattern is
already at the end of memory, the pattern is not moved.
IMAGE Solutions V8.3 26-295
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Old setting:
1—was enabled
0—was disabled
SEE ALSO “tl_memman_recompact_off”
tl_memman_recompact_pattern
Recompact pattern memory.
SYNOPSIS int tl_memman_recompact_pattern(newsize, mem_type)
register int newsize;
TL_MEMMAN_TYPE mem_type;
DESCRIPTION When pattern memory becomes fragmented, it is necessary to
recompact memory so that more patterns can fit in contiguous
memory.
ARGUMENTS newsize—Size of pattern to be inserted
mem_type—Type of memory to be recompacted
RETURN VALUE 0 if successful, -1 if not enough pattern memory.
SIDE EFFECTS Many
tl_meter_ave_time_and_n
Return average and number of readings over time.
SYNOPSIS double tl_meter_ave_time_and_n(t, n);
double t;
int *n;
DESCRIPTION This function averages the meter over time. It reads the A/D
repeatedly during the specified duration and averages the
results. The meter is read at least once. The specified time must
be a positive number greater than zero. If the duration is so long
that the counter (unsigned integer) rolls over, the accumulator is
reset at the same time. Sets n to the number of readings
averaged.
ARGUMENTS t—Time in seconds
n—Pointer to a variable to be filled in
RETURN VALUE Average reading
tl_meter_filter_info
Return the status of the meter’s filter.
SYNOPSIS int tl_meter_filter_info()
IMAGE Solutions V8.3 26-296
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns the current status of the DC voltmeter's
filter. 1 indicates on, 0 indicates off.
ARGUMENTS None
RETURN VALUE Status of filter, 0 or 1.
tl_opamp_read_loop_alarm
Read the status of Quad Opamp channel card loop alarm.
SYNOPSIS int tl_opamp_read_loop_alarm(slot_num, inst_nbr)
int slot_num, inst_nbr;
DESCRIPTION This function accepts a slot/instrument specification. The alarm
register is read on the opamp channel specified, and if the alarm
bit is set a 1 is returned. If the bit is not set a 0 is returned.
ARGUMENTS int slot_num—Slot number in the test head
int inst_nbr—Instrument number on the card (0...3)
RETURN VALUE 0 if OK
1 if alarm
tl_opamp_read_osc_alarm
Read the status of Quad Opamp channel card osc alarm.
SYNOPSIS int tl_opamp_read_osc_alarm(slot_num, inst_nbr)
int slot_num, inst_nbr;
DESCRIPTION This function accepts a slot/instrument specification. The alarm
register is read on the opamp channel specified, and if the alarm
bit is set a 1 is returned. If the bit is not set a 0 is returned.
ARGUMENTS int slot_num—Slot number in the test head
int inst_nbr—Instrument number on the card (0...3)
RETURN VALUE 0 if OK
1 if alarm
tl_open_mux
Open the multiplexer.
SYNOPSIS void tl_open_mux();
DESCRIPTION Opens the multiplexer.
ARGUMENTS None
RETURN VALUE None
IMAGE Solutions V8.3 26-297
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Mux functions support four stations. Programming station 4 is
only useful for a bulkheaded tester, as a test headed tester has
the circuitry at the test head.
tl_ovi_alarm_disable
Disable specified alarms for OVI channel.
SYNOPSIS int tl_ovi_alarm_disable(channel, alarm, disable)
int channel;
int alarm;
int disable;
DESCRIPTION Disables or enables specified alarms for OVI channel.
ARGUMENTS channel—1-based OVI channel alarm - logical OR or alarm
types to disable or enable. Use the following macros (from
ovi_drv.h) to encode an integer that will specify which alarms
are to be enabled or disabled:
OVI_OPEN_KELVIN_ALM
OVI_SENSE_CURRENT_ALM
OVI_MODE_ALM
OVI_OPEN_LOOP_ALM
disable—1 to disable specified alarms, 0 to enable specified
alarms
RETURN VALUE 0 if failure, 1 if successful.
SIDE EFFECTS Sets tl_ovi_selected
tl_ovi_local_meter_reset
Reset local meters.
SYNOPSIS void tl_ovi_local_meter_reset(channel, meter)
int channel;
int meter;
DESCRIPTION Resets the specified local meters for a single OVI channel or all
OVI channels in the test system.
ARGUMENTS channel—1- based channel number or 0 for all OVI channels
meter—Meter to be reset. Use the following macros from
ovi_drv.h:
OVI_NONE do not reset either OVI meter
OVI_VM reset OVI local voltmeter
OVI_AMM reset OVI local ammeter
OVI_VM_AMM reset OVI local voltmeter and ammeter
RETURN VALUE None
IMAGE Solutions V8.3 26-298
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Sets tl_ovi_selected
tl_ovi_set_hotswitch_protection
Set test head relay delay flag and two Kelvin flag.
SYNOPSIS void tl_ovi_set_hotswitch_protection(delay_flag,
two_kelvin_flag)
int delay_flag;
int two_kelvin_flag;
DESCRIPTION Controls whether IMAGE waits for the test head relays to open
after executing an OVI disconnect statement. If delay_flag is
TRUE, IMAGE issues a delay to be sure the test head relays
have opened and avoid a possible hot switch. The
two_kelvin_flag tells IMAGE to allow or disallow connects
with two points of Kelvin. This can also avoid a hotswitch in
certain cases.
With every OVI reset, these flags are reset to the default
settings:
delay_flag = FALSE
two_kelvin_flag = TRUE
ARGUMENTS delay_flag—1= Issue delay to wait for relays to open
0= No delay, just open relays. This is the default behavior and
could result in hot switching in some cases.
two_kelvin_flag—1= Allow connects with two Kelvin points.
This is the default behavior and could result in hot switching in
some cases.
0= Disallow connects with two Kelvin points
RETURN VALUE None
SIDE EFFECTS Sets internal flags.
tl_ovi_set_thads_atten
Set THADS bus attenuation.
SYNOPSIS int tl_ovi_set_thads_atten(slot, thads, atten)
DESCRIPTION Sets the attenuation value for the CCBUS to THADS connection
of a particular OVI Disconnect Channel Card (DCC).
ARGUMENTS int slot—Slot number of DCC
int thads—OVI THADS bus, 1 or 2
double atten—25.0, 100.0, 200.0, or 1.0 (AC).
RETURN VALUE None
IMAGE Solutions V8.3 26-299
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_ovi_set_wave_gain
Set gain for wave programming.
SYNOPSIS void tl_ovi_set_wave_gain(channel, gain);
int channel;
double gain;
DESCRIPTION Sets the gain applied to the voltage on the wave bus, used to
modulate the output of an Octal V/I. Valid values for gain are
10.0, 1.0, and 0.1.
ARGUMENTS channel—Channel of Octal V/I to program (1 based)
gain—Gain to apply to wave bus
RETURN VALUE None
SIDE EFFECTS Selects an Octal V/I channel.
Fills in tl_ovi_selected->wave_gain.
tl_pacs2_cal_debug_flag
Set the PACS II calibration debug flag.
SYNOPSIS void tl_pacs2_cal_debug_flag(state)
int state;
DESCRIPTION Sets the PACS II clock calibration debug flag.
ARGUMENTS state—debug state desired:
0 = debug messages disabled.
1 = print diagnostic information for all
calibration types and all hardware options.
2 = print diagnostic information for selected
calibration types and hardware
4 = run only selected calibration types
8 = perform clk100-to-amc cal with finest scan resolution
RETURN VALUE Previous state of the calibration debug flag
SEE ALSO tl_pacs2cal_debug_check_mode()
tl_pacs2cal_dump_cal_tables
Print PACS II calibration table to station.
SYNOPSIS void tl_pacs2cal_dump_cal_tables(cage)
int cage;
DESCRIPTION Prints the calibration table for the specified cage to station
window.
ARGUMENTS cage—PACS II cage number whose calibration constants are of
interest. Valid cage numbers range from 1 <= x <= 4.
IMAGE Solutions V8.3 26-300
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
tl_pacs2_clk_cal
Perform PACS II clock calibration.
SYNOPSIS int tl_pacs2_clk_cal(msg_dest)
int msg_dest;
DESCRIPTION Perform PACS II three different clock calibrations.
ARGUMENTS msg_dest—Determine where to send the tl_cal_printf()
output as defined by macros in checker.h
RETURN VALUE TL_AUTOCAL_CALIBRATED—Calibration passed
TL_AUTOCAL_UNCALIBRATED—Calibration failed
TL_AUTOCAL_INVALID—Calibration invalid
tl_pacs2_fetch_cal_val
Get PACS II calibration constants.
SYNOPSIS double tl_pacs2_fetch_cal_val(type, cage, amc,
mfslot, An, Seq, freq_index)
int type, cage, amc, mfslot, An, Seq, freq_index;
DESCRIPTION Gets a value from the PACS II calibration table.
ARGUMENTS type—value type indicator:
0 = returns PACS2_NUM_AMC_CAL_VALS_HW.
1 = returns the amc-to-clk100 frequency value for the
specified freq_index.
2 = returns the amc-to-clk100 cal value for the specified
cage and amc
3 = returns the amc-to-clk100 start slope value for the
specified cage and amc
4 = returns the amc-to-clk100 start yintercept value for the
specified cage and amc
5 = returns the amc-to-clk100 end slope value for the
specified cage and amc
6 = returns the amc-to-clk100 end yintercept value for the
specified cage and amc
7 = returns the clk500 cal value for the specified cage
8 = returns the coarse wcclk cal value (wcclk@An rate) for
the specified slot, amc, and An
9 = returns the fine wcclk cal value (wcclk@An rate) for the
specified slot, amc, and An
10 = returns the coarse wcclk cal value (wcclk@T0 rate)
for the specified slot, amc, An, and Seq
11 = returns the fine wcclk cal value (wcclk@T0 rate) for
the specified slot, amc, An, and Seq
IMAGE Solutions V8.3 26-301
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
cage—PACS cage number, 1 to 4.
amc—AMC number, 0 to 3.
mfslot—PACS slot number, 1 to 7
An—An clock (0 to 3)9
Seq—HSD sequencer (0 or 1).
freq_index—frequency index into
amc_clk100_cal_freq[] array, value range from 0 to
PACS2_NUM_AMC_CAL_VALS_HW.
RETURN VALUE The value from the calibration table for the specified type.
tl_pacs2_set_cal_datalog
Enable or disable datalog during PACS II calibration.
SYNOPSIS void tl_pacs2_set_cal_datalog(on_off)
int on_off;
DESCRIPTION Enables or disables datalog during PACS II calibration.
ARGUMENTS on_off—Flag indicating whether to enable or disable datalog.
1 = enable
0 = disable
RETURN VALUE None
tl_pacs_sinxx_amp
Calculate sin x/x corrected amplitude.
SYNOPSIS double tl_pacs_sinxx_amp(freq, clock, cage, amp)
double freq;
int clock;
int cage;
double amp;
DESCRIPTION Function used to calculate sin x/x corrected amplitude for the
Precision AC Subsystem. Given the signal fundamental
frequency, the A(n) clock number, the PACS cage, and the
desired amplitude, this function returns the amplitude that must
be programmed to get the desired amplitude.
ARGUMENTS freq—The signal fundamental frequency
clock—Integer 0, 1, 2, or 3 to indicate which An clock is being
used
cage—Integer to indicate which PACS cage is being used
amp—The desired amplitude
RETURN VALUE The amplitude to be programmed.
IMAGE Solutions V8.3 26-302
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_pause_data_collection
Pause data collection.
SYNOPSIS int tl_pause_data_collection()
DESCRIPTION Pauses data collection. That is, this function stops sending
datalog data to IMAGE, but still sends summary data. It turns off
all data collection, datalog, and data stream.
ARGUMENTS None
RETURN VALUE 1—(TRUE) Datalog was paused.
0—(FALSE) Datalog could not be paused. This may mean that
data collection is not on in the first place.
SIDE EFFECTS No datalog data is written to selected outputs until datalogging is
resumed.
SEE ALSO “tl_resume_data_collection”
tl_pgu_change_repeat
tl_pgu_change_loop
Change PGU repeat number, change PGU loop number
SYNOPSIS void tl_pgu_change_repeat(pattern, label, rep_num)
char *pattern;
char *label;
int rep_num;
void tl_pgu_change_loop(pattern, label, loop_num)
char *pattern;
char *label;
int loop_num;
DESCRIPTION These functions directly set the number of repeat and loop to the
register.
ARGUMENTS pattern— Pattern file name
label —Global label
rep_num —Number of repeat (from 1 to 4095)
loop_num— Number of loop (from 2 to 4095)
RETURN VALUE None
SIDE EFFECTS None
SEE ALSO None
tl_pgu_read_repeat, tl_pgu_read_loop
Read PGU repeat number, read PGU loop number
IMAGE Solutions V8.3 26-303
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_pgu_read_repeat(pattern, label)
char *pattern;
char *label;
int tl_pgu_read_loop(pattern, label)
char *pattern;
char *label;
DESCRIPTION These functions directly read back the number of repeat and
loop from the register.
ARGUMENTS pattern—Pattern file name
label — Global label
RETURN VALUE 0—Error
other—Number of repeat or loop
SIDE EFFECTS None
SEE ALSO None
tl_pgu_pattern_memory_size
Return the PGU pattern memory size.
SYNOPSIS int tl_pgu_pattern_memory_size();
DESCRIPTION This function returns the size of the Pattern Generator Unit
(PGU) pattern memory in vectors. The PGU supports either a 4K
vector or 16K vector pattern memory. The actual size of the
pattern memory is determined by the PGU software during
IMAGE initialization. The pattern memory manager is initialized
with the size of the PGU pattern memory when the test program
is loaded the first time.
ARGUMENTS None
RETURN VALUE Size of PGU pattern memory (number of vectors).
tl_pin_for_pin_id
Translate an alphanumeric pin ID into a pinmap index.
SYNOPSIS int tl_pin_for_pin_id(char *pin_id)
DESCRIPTION This function searches the tl_pinmap_pin_ids array for the
desired pin ID. When found, it returns the index into the
tl_pinmap_pin_ids array, which is the pin number, and so also
the index into tl_pinmap_array[].
ARGUMENTS pin_id—Alphanumeric pin ID
RETURN VALUE 0: not found; else: the index into the array
IMAGE Solutions V8.3 26-304
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_pin_id_for_pin
Get alphanumeric pin ID for pin number.
SYNOPSIS char *tl_pin_id_for_pin(pinnum)
int pinnum;
DESCRIPTION This function matches the passed pin number in the user’s
pinmap and returns the associated alphanumeric pin ID.
ARGUMENTS pinnum—Pin number to match
RETURN VALUE Pointer to pin name from tl_pinmap_pin_ids. Returns NULL if
pin is not in the array or has no name or structure does not exist
(which may be the case if not using the DIBView pinmap).
SIDE EFFECTS Returns pointer into system data structure. Be careful using this
function.
tl_pinmap_name_for_dchan
Get pin name for passed digital channel.
SYNOPSIS char *tl_pinmap_name_for_dchan(chan_num)
int chan_num;
DESCRIPTION This function searches a pinmap for the passed channel number
of type digital (for any digital subsystem on any test head) and
returns the name found in the pinmap for the first matching pin.
ARGUMENTS chan_num—Digital channel number
RETURN VALUE Pointer to pin name in pinmap. Returns NULL if channel is not
matched, no pinmap, no pin name.
SEE ALSO “tl_pinmap_name_for_pin”
tl_pinmap_name_for_pin
Get pin name for pin number.
SYNOPSIS char *tl_pinmap_name_for_pin(pinnum)
int pinnum;
DESCRIPTION This function matches the passed pin number in a pinmap and
returns the associated name.
ARGUMENTS pinnum—Pin number to match
RETURN VALUE Pointer into pin name in pinmap structure. Returns NULL if pin is
not in pinmap or has no name or there is no pinmap.
SIDE EFFECTS Returns pointer into system data structure. Be careful.
SEE ALSO “tl_pinmap_name_for_dchan”
IMAGE Solutions V8.3 26-305
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_plfd_cal_interval
Set the calibration interval for the Precision Low Frequency Digitizer.
SYNOPSIS void tl_plfd_cal_interval(amt)
int amt;
DESCRIPTION Sets the calibration interval for the Precision Low Frequency
Digitizer.
ARGUMENTS amt—Time interval
RETURN VALUE None
tl_plfd_set_optimization
Runs PLFDIG in optimized setup mode.
SYNOPSIS void tl_plfd_set_optimization(on_off)
DESCRIPTION Function to set optimization flag. When TRUE, IMAGE avoids
reprogramming certain parameters if their value in the set ...
plfdig statement is not different from the current software
image. This function also sets the digital filter settling time
optimization on.
ARGUMENTS int on_off
RETURN VALUE None
tl_plfs_cal_interval
Set the calibration interval for the Precision Low Frequency Source.
SYNOPSIS void tl_plfs_cal_interval(amt)
int amt;
DESCRIPTION Sets the calibration interval for the Precision Low Frequency
Source.
ARGUMENTS amt—Time interval
RETURN VALUE None
tl_plfs_conn_deltabus
Connects PLFSRC output to the delta bus.
SYNOPSIS void tl_plfs_conn_deltabus(on_off)
int on_off;
DESCRIPTION Connects and disconnects PLFSRC output to the delta bus
through the wave bus. Connection is made differentially.
ARGUMENTS on_off
IMAGE Solutions V8.3 26-306
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
tl_plfs_get_amp_filt
Apply filter correction to given amplitude for the PLFSRC.
SYNOPSIS double tl_plfs_get_amp_filt(amp, freq)
double amp, freq;
DESCRIPTION Applies the filter correction to a given amplitude given a
frequency for the Precision Low Frequency Source.
Use this function to improve the accuracy of the amplitude
setting for the Precision Low Frequency AC Source (PLFSRC).
This function is used with a set...plfsrc statement. The
set...plfsrc statement has a parameter named amp for setting
the amplitude of the Precision Low Frequency AC Source signal.
If the signal is filtered, the actual amplitude of the output signal
deviates slightly from its programmed value (amp).
Preferably, the amplitude of the output signal could be adjusted
for the effects of the filter; that is, if you want a 5 V sine wave, the
plfsrc should output a 5 V sine wave. tl_plfs_get_amp_filt
does exactly that. Give this function the amplitude and frequency
of the desired output waveform and it returns to you the amp
value required to produce this output waveform.
For example, to make the PLFSRC output a 1kHz sine wave with
a 5.0 Vpk, you would first call this function with the values of
5Vpk for amp and 1kHz for freq. The function would then return
an amplitude value, such as 5.34, that would correct for the
anticipated filter passband ripple characteristics.
The corrected value (in this case, amp=5.34) as specified in a
set plfsrc statement causes the PLFSRC to output a 1 kHz
sine wave at 5 Vpk. Following is an example set plfsrc
statement:
set pin=1 plfsrc:
amp = tl_plfs_get_amp_filt(5.0, 1.0khz)
ampunit: vpk
lpfilt = 2khz
... ;
ARGUMENTS amp—The desired waveform amplitude (cannot exceed 7.24
Vpk)
freq—The desired waveform frequency
RETURN VALUE The corrected amplitude value for programming the Precision
Low Frequency AC Source.
CONFLICTS To select a low-pass filter other than 2kHz when using
tl_plfs_get_amp_filt, you must use two set pin statements
IMAGE Solutions V8.3 26-307
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
to work around a software conflict. The problem is that when
tl_plfs_get_amp_filt and the lpfilt parameter are
specified in the same set pin statement,
tl_plfs_get_amp_filt is always executed first.
tl_plfs_get_amp_filt uses the current filter selection
information to determine the proper amplitude correction factor.
Therefore, when tl_plfs_get_amp_filt and the lpfilt
parameter are specified in the same set pin statement,
tl_plfs_get_amp_filt always calculates a correction factor
based on a 2kHz filter. The following example illustrates the
problem:
set pin=1 plfsrc:
lpfilt = 20kHz
amp = tl_plfs_get_amp_filt(1.0, 2kHz)
amprange = 1.28vpk
ampunit: vpk;
In the example, tl_plfs_get_amp_filt(1.0, 2kHz) is
evaluated first and the reset state value of 2kHz is assumed for
the low-pass filter. Later, when set pin=1 plfsrc: is executed
and the filter selection is changed to 20kHz, the amplitude
correction factor is still that which was calculated for a 2 kHz
filter. The workaround is:
set pin=1 plfsrc:
lpfilt = 20kHz;
set pin=1 plfsrc:
lpfilt = 20kHz
amp = tl_plfs_get_amp_filt(1.0, 2kHz)
amprange = 1.28vpk
ampunit: vpk;
tl_plfs_get_amp_filt uses the correct filter selection to
determine the proper amplitude correction factor.
SEE ALSO “tl_plfs_undo_amp_filt”
tl_plfs_get_amp_filt_spec
Apply filter correction to given amplitude for the PLFSRC.
SYNOPSIS double tl_plfs_get_amp_filt_spec(amp, freq,
filter_spec)
double amp, freq, filter_spec;
DESCRIPTION Applies the filter correction to a given amplitude given a
frequency for the Precision Low Frequency Source.
ARGUMENTS amp—Desired output amplitude level
freq—Frequency of the sine wave
filter_spec—Filter specified
IMAGE Solutions V8.3 26-308
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_plfs_undo_amp_filt
Undo filter correction to given amplitude for the PLFSRC.
SYNOPSIS double tl_plfs_undo_amp_filt(amp, freq)
double amp, freq;
DESCRIPTION Undo the filter correction to amplitude for a given frequency for
the Precision Low Frequency Source.
ARGUMENTS amp—Desired output amplitude level
freq—Frequency of the sine wave
RETURN VALUE Uncorrected amplitude value to program the PLFSRC
tl_plfs_undo_amp_filt_spec
Undo filter correction to given amplitude for the PLFSRC.
SYNOPSIS double tl_plfs_undo_amp_filt_spec(amp, freq,
filter_spec)
double amp, freq, filter_spec;
DESCRIPTION Undo the filter correction to amplitude for a given frequency for
the Precision Low Frequency Source.
ARGUMENTS amp—Desired output amplitude level
freq—Frequency of the sine wave
filter_spec—Filter specified
RETURN VALUE Uncorrected amplitude value to program the PLFSRC
tl_plfsrc_get_type_slot
Returns PLFSRC type given slot number.
SYNOPSIS int tl_plfsrc_get_type_slot(thSlot)
int thSlot;
DESCRIPTION Given a testhead slot number, return plfsrc type.
ARGUMENTS thSlot - Testhead slot number.
RETURN VALUE 0 - Not a plfsrc.
1 - PLFSRC w/ 64k of memory.
2 - PLFSRC w/ 1M of memory.
tl_powerup
Variable indicating first execution since powerup.
SYNOPSIS int tl_powerup
IMAGE Solutions V8.3 26-309
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This global integer variable indicates (nonzero) the first test
program execution since the program was loaded or since power
was cycled. If tl_powerup == 0, the program has been
executed at least once since load or test system power cycle.
(See “Initializing Memory-Dependent Data” on page 26-539.)
ARGUMENTS None
RETURN VALUE None
tl_prod_init
Initialize a test program.
SYNOPSIS tl_prod_init() { <user statements> }
DESCRIPTION If this function exists within a test program, any statements
located in the body of the function are executed immediately
following test program loading. This occurs before the first time
the test program is run, and this function is called before
tl_init.
tl_prod_init provides a way to execute statements that check
for valid test program run conditions, such as correct test system
configuration.
This function is not called as part of the initialize station window
or background menu commands.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_init”
tl_profile_end
Close out last bin during custom profiling.
SYNOPSIS void tl_profile_end()
DESCRIPTION Call this function when using the custom profiling feature to
declare the end of the last bin. You can also use the function to
skip sections where profiling is not desired (time from the
tl_profile_end call to the next tl_profile_mark call is
skipped). This function does nothing when profiling sequencers
is enabled.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_profile_mark”
IMAGE Solutions V8.3 26-310
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_profile_mark
Specify a mark for custom profiling.
SYNOPSIS void tl_profile_mark(bin, name)
int bin;
char *name;
DESCRIPTION Calls to this function are placed in a test program to profile it. At
each call, the elapsed time since the previous call is added to the
previous call’s bin number. Call the function tl_profile_end()
at the end of the area being profiled to close out the last bin. If
omitted, all the time up to the tl_profile_print call is added
to the last bin.
This function does nothing when profiling sequencers rather than
custom is enabled.
ARGUMENTS bin—An arbitrary numerical profiling bin number. Multiple calls
with the same bin number accumulate time in a single bin.
name—String describing the bin, used in printout.
RETURN VALUE None
SEE ALSO “tl_profile_end”
tl_psrr_lfacsrc_slot
Set LFACSRC amp and connect to waveform bus.
SYNOPSIS tl_psrr_lfacsrc_slot(slotnum, gain, connect)
int slotnum;
DESCRIPTION Connects the LFACSRC to the waveform bus.
ARGUMENTS slotnum—Channel card slot number
gain—LFACSRC amp. Table 26-6 shows the relationship of gain
and amplitude.
Table 26-6. LFACSRC Gain vs. Amplitude
Gain Amp
≤2700 gain/3000
2701-3000 1.1
3001-4000 1.2
>4000 1.3
IMAGE Solutions V8.3 26-311
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
connect 1—connect
0—disconnect
RETURN VALUE None
tl_psrr_plfsrc_slot
Set PLFSRC amp and connect to waveform bus.
SYNOPSIS tl_psrr_plfsrc_slot(slotnum, gain, connect)
DESCRIPTION Connects the PLFSRC to the waveform bus.
ARGUMENTS slotnum—Card slot number
gain—Sets amp on PLFSRC. Table 26-7 shows the relationship
of gain and amplitude.
Table 26-7. PLFSRC Gain vs. Amplitude
Gain Amp
≤2700 gain/3000
2701-3000 1.1
3001-4000 1.2
>4000 1.3
connect 1—connect
0—disconnect
RETURN VALUE None
NOTE
Before IMAGE V6.4, a signal amplitude inconsistency existed when a UB V/I was
modulated with a signal from the wave bus. This behavior caused amplitude differences in
the modulated signal depending upon the programming order of the connections made to
the wave bus for the modulation source and the UB V/I. For example, when the AC source
was connected to the wave bus before the UB V/I, the gain of the modulated signal from the
UB V/I was half of that expected.
In IMAGE V6.4 and later, this behavior has changed so that the modulated amplitude is
consistent regardless of programming order. An IMAGE Behavior Chooser (IBC) exists to
disable the fix and revert to the inconsistent behavior. See the IMAGE Quick Help file for a
description of the IBC called ubvi_wavebus_gain_consistency.
tl_psrr_plfsrc_to_wave
Connect an AC Source to the waveform bus or Delta bus
IMAGE Solutions V8.3 26-312
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS tl_psrr_plfsrc_to_wave(slot, conn)
int slot, conn;
DESCRIPTION Connects PLFSrc or LFACSrc to the waveform bus (on Catalyst)
or Delta bus (on AMS).
ARGUMENTS slot: Slot number containing the PLFSrc to connect
conn: Action
1: Connect
0: Disconnect
RETURN VALUE None.
tl_ptr_r
Read from pointer into Terabus space.
SYNOPSIS unsigned short tl_ptr_r(ptr)
unsigned short *ptr;
DESCRIPTION This function reads back the data at the specified virtual address.
ARGUMENTS ptr—Virtual address, in Terabus space. This value is typically
obtained by calling (ADDR) or by adding an offset (a Terabus
address) to the return value of tl_tbase_addr(0).
RETURN VALUE Data at address
tl_ptr_w
Write to pointer into Terabus space.
SYNOPSIS void tl_ptr_w(ptr, data)
unsigned short *ptr;
unsigned short data;
DESCRIPTION This function writes the data into the specified virtual address.
ARGUMENTS ptr—Virtual address, in Terabus space. This value is typically
obtained by calling tl_tbase_addr(ADDR), or by adding an
offset (a Terabus address) to the return value of
tl_tbase_addr(0).
data—Data value to be written
RETURN VALUE None
tl_qsc_map_dump
Dump synthesizer mapping to the station window.
SYNOPSIS struct tl_qsc_synth_info tl_qsc_map_dump();
IMAGE Solutions V8.3 26-313
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Dumps the one-to-one synth/AD944/source mapping to the
station window.
ARGUMENTS None
RETURN VALUE None
tl_qsc_state
Dump synthesizer state to the station window.
SYNOPSIS void tl_qsc_state(source, unit)
int source, unit;
DESCRIPTION Dumps the synthesizer frequency, amplitude, and other
information to the station window.
ARGUMENTS source—Source indicator
unit—Unit number of the source
RETURN VALUE None
tl_qvs_alarm_disable
Disable specified alarms for QVS channel.
SYNOPSIS int tl_qvs_alarm_disable(channel, alarm, disable)
int channel;
int alarm;
int disable;
DESCRIPTION Disables/enables specified alarms for QVS channel.
ARGUMENTS channel—1-based QVS channel
alarm—Logical OR or alarm types to disable/enable. Use the
macros below (from qvs_drv.h) to encode an integer that will
specify which alarms are to be enabled/disabled.
QVS_OPEN_KELVIN_ALM
QVS_SENSE_CURRENT_ALM
QVS_MODE_ALM
QVS_OPEN_LOOP_ALM
disable—1 to disable specified alarms, 0 to enable specified
alarms
RETURN VALUE 0 if failure
1 if successful
SIDE EFFECTS Sets tl_qvs_selected
tl_qvs_combine
Combine two QVS channels into one.
IMAGE Solutions V8.3 26-314
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_qvs_combine(userdef_pin, combine_value)
int userdef_pin;
unsigned short combine_value;
DESCRIPTION Sets up the software to define a QVS combination channel.
Note - Call this function only from a tl_init(). If not, this
function will run every time the program is run and cause a run-
time error.
Only call this function when the two pins are actually hardwired
together in some way on the DIB. Check to make sure that this
connection is made before attempting to use this function.
ARGUMENTS int userdef_pin—Pin number - user specified - located in
pinmap, that user wants to combine another channel to
unsigned short combine_value—This will always be
TL_QVS_2_COMBO (value used to combine)
RETURN VALUE None
SIDE EFFECTS Changes tl_qvs_selected to the force:i channel
tl_qvs_set_hotswitch_protection
Set test head relay delay flag and two kelvin flag.
SYNOPSIS void tl_qvs_set_hotswitch_protection(delay_flag,
two_kelvin_flag)
int delay_flag;
int two_kelvin_flag;
DESCRIPTION This function gives you control over whether IMAGE waits for the
test head relays to open after executing an QVS disconnect
statement. If the delay_flag value passed to this function is
TRUE, IMAGE issues a delay to be sure the test head relays
have opened and avoid a possible hot switch. The
two_kelvin_flag tells IMAGE to allow/disallow connects with
two points of kelvin. This can also avoid a hotswitch in certain
situations.
With every QVS reset, these flags will be reset to the default
settings:
delay_flag—FALSE
two_kelvin_flag—TRUE
ARGUMENTS int delay_flag
1—Issue delay to wait for relays to open.
0—No delay, just open relays. This is the default behavior
and could result in hot switching.
IMAGE Solutions V8.3 26-315
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int two_kelvin_flag
1—Allow connects with two kelvin points. This is the
default behavior and could result in hot switching.
0—Disallow connects with two kelvin points
RETURN VALUE None
SIDE EFFECTS Sets internal flags
tl_read_and_set_dib_info
Read and set the DIB ID and DIB type.
SYNOPSIS int tl_read_and_set_dib_info(enum
Eeprom_string_format format)
DESCRIPTION This function reads the DIB ID and DIB type, and sets them into
global variables. How this function works depends on two
factors: the test system type, and the format parameter.
For Linear test systems, the DIB ID and type are meaningless,
and the DIB ID is set to the Null String, and the DIB type is set to
the string 0.
For Mixsig test systems, the DIB ID will be set to the Null String,
and the DIB type will be set to a string representing a decimal
number from 0-511.
For Advanced Linear, Advanced Mixed-Signal, and Catalyst test
systems, this function actually queries the EEPROM and stores
the information it reads. The format of the DIB type string is
determined by the format parameter. If format ==
EEPROM_LONG_STRING, the string contains the board type, the
company ID, and the revision code (for example, 876-543-21
(5445[TE]) 9701-B.P1). If format == EEPROM_SHORT_STRING,
it contains the 8-character (hex) DIB type, with no hyphens (for
example, 87654321).
Calling this function not only sets the global variables, but also
causes these values to be written to the datalog. The variables
are stored in the Site Description Record, in the fields SDR,
dib_id, and SDR.dib_typ.
This function can only be called before testing actually begins.
Once the first part has started testing, this function returns an
error code of -1 and will not set the global variables nor affect the
datalog.
ARGUMENTS enum Eeprom_string_format format—
EEPROM_LONG_STRING—Format the DIB type string in long
format. Example: 876-543-21 (5445[TE]) 9701-B.P1
IMAGE Solutions V8.3 26-316
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
EEPROM_SHORT_STRING—Format the DIB type string in short
format. Example: 87654321
RETURN VALUE 1 = Success (Will always return 1 on a simulator)
0 = Failure (unable to read EEPROM)
-1 = Failure (sequencer has started, request rejected)
SIDE EFFECTS If successful, writes the STDF fields SDR.dib_id and
SDR.dib_typ.
SEE ALSO “tl_set_dib_typ”, “tl_set_dib_id”, “tl_get_dib_typ”, “tl_get_dib_id”
tl_read_and_set_prb_info
Read and set the probe card ID and type.
SYNOPSIS int tl_read_and_set_prb_info(enum
Eeprom_string_format format)
DESCRIPTION This function reads the probe card ID and probe card type, and
sets them into global variables. How this function works depends
on two factors: the test system type, and the format parameter.
For Linear and Mixsig test systems, the probe card ID and type
are meaningless, and the probe card ID is set to the Null String,
and the probe card type is set to the string "0".
For Advanced Linear, Advanced Mixed-Signal, and Catalyst test
systems, this function actually queries the EEPROM and stores
the information it reads. The format of the probe card type string
is determined by the format parameter.
If format == EEPROM_LONG_STRING, the string contains the
board type, the company ID, and the revision code (for example,
876-543-21 (5445[TE]) 9701-B.P1).
If format == EEPROM_SHORT_STRING, it simply contains the 8-
character (hex) probe card type, with no hyphens (for example,
87654321).
Calling this function not only sets the global variables, but also
causes these values to be written to the datalog.
The variables are stored in the Site Description Record, in the
fields SDR.card_id and SDR.card_typ.
This function can only be called before testing actually begins.
Once the first part has started testing, this function returns an
error code of -1, and will not set the global variables nor affect
the datalog.
ARGUMENTS enum Eeprom_string_format format—
IMAGE Solutions V8.3 26-317
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
EEPROM_LONG_STRING—Format the probe card type string in
long format. For example: 876-543-21 (5445[TE]) 9701-B.P1
EEPROM_SHORT_STRING—Format the probe card type string in
short format. For example: 87654321.
RETURN VALUE 1 == Success (will always return 1 on a simulator)
0 == Failure (unable to read EEPROM)
-1 == Failure (sequencer has started, request rejected.)
SIDE EFFECTS If successful, the STDF fields SDR.card_id and SDR.card_typ
get written.
SEE ALSO “tl_set_prb_typ”, “tl_set_prb_card”, “tl_get_prb_typ”,
“tl_get_prb_card”
tl_read_cmod_cod
Read the value of the command mode code.
SYNOPSIS char tl_read_cmod_cod()
DESCRIPTION This function reads the command mode code for the current lot.
The default value is a blank space.
The mode code is a string sent to the datalogger to describe the
mode that the tester is running in. The operating mode is set to
E (engineering) or P (production) when the test program is
loaded or when you change the mode of the workstation
environment. When setting the mode, a job_station_mode
event is issued.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 and the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS None
RETURN VALUE char—The character representing the current operating mode of
the station.
tl_read_datnum
Read the datalog (test) number.
SYNOPSIS int tl_read_datnum()
DESCRIPTION Reads the datalog (test) number for the test currently being
executed. This function is illegal outside of a TESTF. Example:
{
int tnum;
tnum = tl_read_datnum();
}
IMAGE Solutions V8.3 26-318
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS None
RETURN VALUE The test number for the currently executing TESTF (return
value>0). Function not called from within a TESTF; returns (-2).
tl_read_device
Read the value of the current DUT.
SYNOPSIS int tl_read_device()
DESCRIPTION Returns the number of the current device under test. Returns 0
if called from outside a serial loop in a test program using
multisite test. Also returns 0 if the part has been binned.
Example:
{
printf("Now Testing Device %d\n", tl_read_device());
}
ARGUMENTS None
RETURN VALUE The device number of the current DUT as an integer value, or 0
if no sites are enabled.
tl_read_device_site
Read the value of the DUT of given site
SYNOPSIS int tl_read_device(int site);
DESCRIPTION Returns the number of the device under test of the given site. Will
return 0 if given site is not valid.
ARGUMENTS int site
RETURN VALUE The device number of the DUT of the given site as an integer
value.
tl_read_dib_type_int
Read back DIB Type code as integer.
SYNOPSIS int tl_read_dib_type_int()
DESCRIPTION Reads back the state of the ID jumpers on the DIB board. The
jumpers are weighted in the following way:
DIBID # grounded 8 7 6 5 4 3 2 1
Value in readback 128 64 32 16 8 4 2 1
The DIBID-9 is reserved for Teradyne DIBs. Therefore a
customer DIB should always return a number less that 256 while
Teradyne DIB ID’s are 256 or greater.
IMAGE Solutions V8.3 26-319
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Example: if DIBID jumpers 6 and 3 are grounded,
tl_read_dib_type_int() returns 36.
ARGUMENTS None
RETURN VALUE Bit-mapped ID number from 0 to 511.
tl_read_disp_cod
Read the lot disposition code.
SYNOPSIS char tl_read_disp_cod()
DESCRIPTION Reads back the value of the lot disposition code as a character.
The default value is “ ” (space). Example:
{
printf("The status of the lot is: '%c'.\n",
tl_read_disp_cod());
}
ARGUMENTS None
RETURN VALUE The lot disposition code as a char.
SEE ALSO “tl_set_disp_cod”
tl_read_exec_typ
Return the name of the test executive.
SYNOPSIS char *tl_read_exec_typ(s);
DESCRIPTION Receives a pointer to a character string as an argument and
copies the name of the tester executive into it. Example:
{
char text[S_STDF_STRING+1];
printf("The exec is: %s\n",tl_read_exec_typ(text));
}
ARGUMENTS char *s—A pointer to user-allocated memory which will have
the name of the tester executive written to it. It is your
responsibility to allocate sufficient memory.
RETURN VALUE A character string containing the name of the executive, through
the argument. For IMAGE users, this is always the string IMAGE.
tl_read_format
Read the datalog format for the current test.
SYNOPSIS int tl_read_format(s)
char *s;
IMAGE Solutions V8.3 26-320
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Copies the format string for the current test into the user-
provided string, *s. Memory for this string must have been
allocated before this function was called and must be at least
S_FMT + 1 characters long. If this function is called from outside
a TESTF, it returns an error. The text of the error message will be:
"tl_read_label illegal outside of a TESTF"
Example:
{
char fstr[25];
tl_read_format(fstr);
printf("The format string is: '%s' \n",fstr);
}
ARGUMENTS None
RETURN VALUE The format of the current test as a character string through the
argument. As a function return:
0—for successful copy
-2—if an error occurred
tl_read_gigadig_hpfilt_slot
Returns status of hpfilt setting.
SYNOPSIS int tl_read_gigadig_hpfilt_slot(int slot)
DESCRIPTION Returns status of hpfilt setting for the gigadig specified.
ARGUMENTS slot—Testhead slot number of the GigaDig in question.
RETURN VALUE 1 if the hpfilt is on
0 if the hpfilt is off
tl_read_hand_id
Return the value of the handler id(obsolete).
SYNOPSIS char *tl_read_hand_id( s );
DESCRIPTION Receives a pointer to a character string as an argument and
copies into it the handler id.
ARGUMENTS char *s—A pointer to user allocated memory which will have
the handler id written to it. It is the users responsibility to allocate
sufficient memory.
RETURN VALUE A character string containing the handler id, via the argument.
SIDE EFFECTS None
SEE ALSO
IMAGE Solutions V8.3 26-321
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_read_hbin_is_pass
Is a hardware bin is a pass bin or a fail bin?
SYNOPSIS int tl_read_hbin_is_pass(bin)
int bin;
DESCRIPTION The function determines whether a specified hardware bin is a
pass bin or fail bin as defined in the device_bins declaration. By
default bin 1 is a pass bin and all other bins are fail bins.
ARGUMENTS bin—A hardware bin number between 0 and MAXBIN (256).
RETURN VALUE TRUE if the bin is a pass bin,
FALSE if the bin is a fail bin.
SEE ALSO “tl_read_sbin_is_pass”
tl_read_hfdig_hpfilt
Return status of the HFDIG hpfilt setting.
SYNOPSIS int tl_read_hfdig_hpfilt(pin)
int pin;
DESCRIPTION Returns status of the hpfilt setting for the HFDIG specified.
ARGUMENTS pin—Pin number or pin name associated with the HFDIG in
question
RETURN VALUE 1—If the hpfilt is on
0—If the hpfilt is off
tl_read_hfdig_hpfilt_slot
Return status of the HFDIG hpfilt setting.
SYNOPSIS int tl_read_hfdig_hpfilt_slot(slot)
int slot;
DESCRIPTION Returns status of the hpfilt setting for the HFDIG specified.
ARGUMENTS slot—Test head slot number of the HFDIG in question
RETURN VALUE 1—if the hpfilt is on
0—if the hpfilt is off
tl_read_highlim
Return value of upper test limit.
SYNOPSIS int tl_read_highlim(highlimit)
double *highlimit;
IMAGE Solutions V8.3 26-322
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Reads the value of current test’s high limit. This function must be
called from within the TESTF whose high limit value is desired.
Example:
{
double high_limit;
if (tl_read_highlim(&high_limit) == 0)
printf("The high limit for test %d is:
%g \n",tl_read_datnum(), high_limit);
}
ARGUMENTS highlimit—A pointer to double which will contain the high limit.
RETURN VALUE The value of the high limit is returned through the argument. The
function return will indicate if any errors occurred.
0—Success
-1—No valid high limit for this test
-2—Errors
SEE ALSO “tl_read_lowlim”, “tl_write_lowlim”, “tl_write_highlim”
tl_read_ids
Read lot and sublot IDs.
SYNOPSIS char * tl_read_ids(s)
char s[];
DESCRIPTION Get a concatenation of the lot and sublot IDs. If the sublot ID is
set it returns:
<lot ID>:<sublot ID>
If the sublot ID is not set, it returns the lot ID. Example:
{
char IDS[S_STDF_STRING+1];
printf("The entire lot ID is: '%s' \n"
tl_read_ids(IDS));
}
ARGUMENTS [The address of] An array in which to place the lot ID string.
RETURN VALUE Its argument.
SEE ALSO “tl_read_lot_id”, “tl_read_sblot_id”, “tl_begin_lot”,
“tl_write_lot_id”, “tl_write_sblot_id”, “tl_write_lot_ids”
tl_read_job_nam
Return the name of the currently loaded test program.
SYNOPSIS char *tl_read_job_nam(s);
DESCRIPTION Receives a pointer to a character string as an argument and
copies the test program name into it. The name is set when the
IMAGE Solutions V8.3 26-323
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
test program is loaded. It is set by extracting the name portion
(removing directory path and extension) from the full path
specification of the name given to the load command. Example:
{
char progname[S_STDF_STRING+1];
printf("This test program is: %s\n",
tl_read_job_nam(progname));
}
ARGUMENTS char *s—A pointer to user-allocated memory which will have
the test program name written to it. It is your responsibility to
allocate sufficient memory.
tl_job_nam is defined in stdf_globals.h as of size
STDF_MAX_STR+1. In stdf.h that is defined as 0x100 (256).
You should allow a buffer of at least 257 characters.
RETURN VALUE A character string containing the test program name, through the
argument.
SEE ALSO “tl_read_lot_id”, “tl_read_sblot_id”, “tl_begin_lot”,
“tl_write_lot_id”, “tl_write_sblot_id”, “tl_write_lot_ids”
tl_read_job_rev
Return the test program revision.
SYNOPSIS char *tl_read_job_rev(s);
DESCRIPTION Receives a pointer to a character string as an argument and
copies into it the test program revision. The test program revision
should have been previously set using tl_set_job_rev().
Example:
{
char txt[S_STDF_STRING+1];
printf("The Test program revision ID is:
'%s' \n",tl_read_job_rev(txt));
}
ARGUMENTS char *s—A pointer to user-allocated memory which will have
the test program revision written to it. It is your responsibility to
allocate sufficient memory.
tl_job_nam is defined in stdf_globals.h as of size
STDF_MAX_STR+1. In stdf.h that is defined as 0x100 (256). So
allow a buffer of at least 257 characters.
RETURN VALUE A character string containing the test program revision, through
the argument.
SEE ALSO “tl_set_job_rev”
IMAGE Solutions V8.3 26-324
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_read_label
Returns the label assigned to the current test.
SYNOPSIS int tl_read_label(s);
char *s;
DESCRIPTION Copies the label for the current test into the user provided string,
*s. If this function is called from outside a TESTF it will return an
error. The text of the error message will be:
tl_read_label illegal outside of a TESTF.
ARGUMENTS s—A pointer to the buffer into which this function will write the
label. Memory for this string must have been allocated before
this function is called and must be at least size of the label being
read + 1 characters long. To determine the size of the label, call:
tl_read_label_size()
RETURN VALUE The label of the current test as a character string via the
argument. As a function return: 0 for successful copy, -2 if an
error occurred.
SIDE EFFECTS If the buffer passed in is not long enough to hold the label being
read, a memory overwrite will occur. Memory overwrites will
cause serious problems with the stability of the test program
calling this function.
tl_read_label_size
Return the size of the label assigned to the current test.
SYNOPSIS int tl_read_label_size();
DESCRIPTION Returns the length of the label string assigned to the current test.
The buffer allocated for the function tl_read_label must be at
least one byte longer than this length.
If this function is called from outside a TESTF it returns an error.
The text of the error message is:
tl_read_label illegal outside of a TESTF.
ARGUMENTS None
RETURN VALUE The size in bytes of the label of the current test. -2 if an error
occurred.
tl_read_label_truncate
Return the label assigned to the current test. Truncate it if necessary.
IMAGE Solutions V8.3 26-325
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_read_label_truncate(s, len);
char *s;
int len;
DESCRIPTION Copies the label for the current test into the user provided string,
*s. If this function is called from outside a TESTF it will return an
error. The text of the error message will be:
tl_read_label illegal outside of a TESTF.
ARGUMENTS s—A pointer to the buffer into which this function will write the
label. Memory for this string must have been allocated before
this function is called and must be at least len+1.
len—The label read will be truncated to this length.
RETURN VALUE The label of the current test as a character string via the
argument. As a function return: 0 for successful copy, -2 if an
error occurred.
tl_read_lot_id
Read the value of the current lot ID.
SYNOPSIS char *tl_read_lot_id(char *s);
DESCRIPTION This function copies the current lot ID into memory pointed to by
the argument. It is your responsibility to allocate sufficient
memory. No checking is performed to assure that this condition
is met. The lot ID is set using the lot command. (See “Setting
the Lot and Sublot” on page 6-3.) Initially its value is \0 (null).
Example:
{
char lotid[S_STDF_STRING+1];
printf("The Lot ID is: '%s' \n",
tl_read_lot_id(lotid));
}
ARGUMENTS Accepts a pointer to a character string. It is assumed that
memory has already been allocated.
RETURN VALUE A character string pointing to the current lot ID, through the
argument.
SEE ALSO “tl_read_sblot_id”, “tl_read_lot_id”, “tl_begin_lot”,
“tl_write_lot_id”, “tl_write_sblot_id”, “tl_write_lot_ids”
tl_read_lowlim
Return value of lower test limit.
SYNOPSIS int tl_read_lowlim(lowlimit)
double *lowlimit;
IMAGE Solutions V8.3 26-326
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Reads the value of current test’s low limit. This function must be
called from within the TESTF whose low limit value is desired.
ARGUMENTS lowlimit—A pointer to double which will contain the low limit.
RETURN VALUE The value of the low limit is returned through the argument. The
function return will indicate if any errors occurred.
0—Success
-1—No valid low limit for this test
-2—Errors
SEE ALSO “tl_read_highlim”, “tl_write_lowlim”, “tl_write_highlim”
tl_read_meter_n_wmd_set
Set tl_read_meter_n_wmd to value.
SYNOPSIS void tl_read_meter_n_wmd_set(value)
double value;
DESCRIPTION The global variable tl_read_meter_n_wmd is used when doing
a read_meter_n (actually in function tl_meter_ave_by_n) to
add a delay before each meter reading in the series of n
readings. It should only be set by this function.
ARGUMENTS value—What to set tl_read_meter_n_wmd to, in seconds.
RETURN VALUE None
SIDE EFFECTS Sets variable.
SEE ALSO “read_meter_n”, “read_measurement_n”
tl_read_mode_cod
Read the operational mode code for the current lot.
SYNOPSIS char tl_read_mode_cod();
DESCRIPTION This function reads the operating mode code for the current lot.
The mode code is a string sent to the datalogger to describe the
mode the tester is running in.
The operating mode is set to E (engineering) or P (production)
when the test program is loaded or when you change the mode
of the workstation environment. A job_station_mode event is
issued when setting the mode. Example:
{
char mode;
mode = tl_read_mode_cod();
printf("The station is in mode: %c \n", mode);
}
IMAGE Solutions V8.3 26-327
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 and the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS None
RETURN VALUE char—Character representing the current operating mode of the
station.
SEE ALSO “tl_set_mode_cod”, “tl_job_is_in_debug”
tl_read_node_nam
Read the tester (network) node name.
SYNOPSIS char * tl_read_node_nam(s)
char s[];
DESCRIPTION Reads the tester (network) node name. This name is obtained
from the test system when the test program is loaded and cannot
be changed. Example:
{
char noden[S_STDF_STRING+1];
printf("The tester node is: %s\n",
tl_read_node_nam(noden));
}
ARGUMENTS [The address of] An array in which to place the node name.
RETURN VALUE The argument (node name)
tl_read_oper_nam
Return the name of the current operator.
SYNOPSIS char *tl_read_oper_nam(s);
DESCRIPTION Receives a pointer to a character string as an argument and
copies the name of the operator into it. The operator name is set
automatically (to the login name) when a test program is loaded.
It can also be set or changed using the operator command.
(See “Setting Lot and Sublot Using the lot Command” on page
6-9.) If changed in this way, the new name will not take effect until
the next lot is started (that is, the next startlot). Example:
{
char opn[S_STDF_STRING+1];
printf("The operator is: %s\n",
tl_read_oper_nam(opn));
}
IMAGE Solutions V8.3 26-328
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS char *s—A pointer to user-allocated memory which will have
the operator name written to it. It is your responsibility to allocate
sufficient memory.
RETURN VALUE A character string containing the operator name, through the
argument.
SEE ALSO “tl_set_oper_nam”
tl_read_part_cnt
Read the number of parts tested for a lot.
SYNOPSIS unsigned int tl_read_part_cnt()
DESCRIPTION Reads back the number of parts tested for the current lot. This
number is incremented each time a sort bin statement with a
valid bin number (0-256) is executed for a device. Example:
{
printf("There have been %d parts tested.\n",
tl_read_part_cnt());
}
ARGUMENTS None
RETURN VALUE The number of parts tested for the current lot.
tl_read_part_id
Read the device number (or other ID) for the DUT.
SYNOPSIS char * tl_read_part_id(s)
char s[];
DESCRIPTION Reads back the device number (or other ID) for the DUT as a text
string. Unless specifically set using tl_set_device, IMAGE
assigns part IDs using a serial integer counter. This function
always reads back the value of that serial counter. Example:
{
char dutid[S_STDF_STRING+1];
printf("The DUT is device '%s'.\n",
tl_read_part_id(dutid));
}
ARGUMENTS [The address of] An array in which to place the part ID string.
RETURN VALUE Its argument (the part ID string) or 0 if no sites are enabled.
SIDE EFFECTS A runtime error is generated if called from a multisite test
program and not in a serial loop.
SEE ALSO “tl_read_device”
IMAGE Solutions V8.3 26-329
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_read_part_typ
Read the Part Type text string.
SYNOPSIS char *tl_read_part_typ (s)
char s[];
DESCRIPTION Reads the Part Type text string. The default value for this field
is \0 (null). Example:
{
char pt[S_STDF_STRING+1];
printf("The part type is: '%s' \n",
tl_read_part_typ(pt));
}
ARGUMENTS [The address of] An array in which to place the part type string.
RETURN VALUE Its argument (part type).
SEE ALSO “tl_read_device”
tl_read_proc_id
Read the process ID of the parts being tested.
SYNOPSIS char * tl_read_proc_id(s)
char s[];
DESCRIPTION Reads the process ID of the parts being tested as a string.
Example:
{
char txt[S_STDF_STRING+1];
printf("The process ID is: '%s' \n",
tl_read_proc_id(txt));
}
ARGUMENTS (The address of) An array in which to place the process ID string.
RETURN VALUE Its argument (the process ID).
tl_read_prot_cod
Read the value of the data protection code.
SYNOPSIS char tl_read_prot_cod()
DESCRIPTION This function returns the value of the data protection code as a
character. Example:
{
char pcode;
pcode = tl_read_prot_cod();
printf("The data protection code is: '%c' \n",pcode);
}
IMAGE Solutions V8.3 26-330
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS None
RETURN VALUE The “data protection code” as a character. (Default value is “ ”
<space>)
tl_read_rtst_cod
Read the value of the retest code.
SYNOPSIS char tl_read_rtst_cod()
DESCRIPTION Reads the single character lot retest code. Example:
{
char tcode;
tcode = tl_read_rtst_cod();
printf("Test retest code is: %c \n",tcode);
}
ARGUMENTS None
RETURN VALUE The “retest code” as a character. (Default value is \0.)
tl_read_sbin_is_pass
Is a software bin is a pass bin or a fail bin?
SYNOPSIS int tl_read_sbin_is_pass(bin)
int bin;
DESCRIPTION The function determines whether a specified software bin is a
pass bin or fail bin as defined in the device_bins declaration. By
default bin 1 is a pass bin and all other bins are fail bins.
ARGUMENTS bin—A software bin number between 0 and MAXBIN (256).
RETURN VALUE TRUE if the bin is a pass bin,
FALSE if the bin is a fail bin.
SEE ALSO “tl_read_hbin_is_pass”
tl_read_sblot_id
Return the value of the sublot ID.
SYNOPSIS char *tl_read_sblot_id(s);
DESCRIPTION Receives a pointer to a character string as an argument and
copies into it the current setting of the sublot ID. This ID is set
using the lot command. (See “Setting the Lot and Sublot” on
page 6-3.) Initially its value is \0 (null). Example:
{
char sblotid[S_STDF_STRING+1];
printf("The Sublot ID is: '%s'\n",
IMAGE Solutions V8.3 26-331
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_read_sblot_id(lsbotid));
}
ARGUMENTS char *s—A pointer to user-allocated memory which will have
the sublot ID written to it. It is your responsibility to allocate
sufficient memory.
RETURN VALUE A character string containing the sublot ID, through the
argument.
SEE ALSO “tl_read_lot_id”, “tl_read_ids”, “tl_begin_lot”, “tl_write_lot_id”,
“tl_write_sblot_id”, “tl_write_lot_ids”
tl_read_setup_t
Read the value of the setup time variable.
SYNOPSIS unsigned int tl_read_setup_t()
DESCRIPTION Reads the time the test program was loaded as an integer which
represents the number of seconds since January 1, 1970 in
(GMT seconds - “seconds west of GMT” [adjusted for local time
zone]). This setup time is automatically set when the test
program is loaded and cannot be changed. Example:
#include <sys/time.h>
{
struct timeval tp;
struct timezone tzp;
unsigned int current_time;
extern char *ctime();
/* Get local timezone info */
gettimeofday(&tp, &tzp);
/*Get the setup time and 'make it local'*/
current_time = tl_read_setup_t() +
(tzp.tz_minuteswest * 60);
printf("Test program was loaded at:
%s",ctime(¤t_time));
}
ARGUMENTS None
RETURN VALUE Test program setup time as a four byte unsigned int.
tl_read_start_t
Read the start time.
SYNOPSIS unsigned int tl_read_start_t()
IMAGE Solutions V8.3 26-332
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Reads the time that the lot was started, as an integer which
represents the number of seconds since January 1, 1970 in
(GMT seconds - “seconds west of GMT” [adjusted for local time
zone]). Example:
#include <sys/time.h>
{
struct timeval tp;
struct timezone tzp;
unsigned int current_time;
extern char *ctime();
/* Get local timezone info */
gettimeofday(&tp, &tzp);
/* Get the setup time and 'make it local' */
current_time = tl_read_start_t() +
(tzp.tz_minuteswest * 60);
printf("The device lot was started at:
%s",ctime(¤t_time));
}
ARGUMENTS None
RETURN VALUE Number of seconds since January 1, 1970 in (GMT seconds -
“seconds west of GMT”)
tl_read_station_num
Read the current station number.
SYNOPSIS int tl_read_station_num()
DESCRIPTION This function returns the station number the test program is
currently loaded into. This number can be distinct from the test
head number, since a test program can be loaded into an
auxiliary station and that station can then be switched to a
different test head. See “Choosing Test-Head Type When
Loading an Auxiliary Station” on page 5-10.
ARGUMENTS None
RETURN VALUE Current station number
tl_read_supr_nam
Return the current supervisor name.
SYNOPSIS char *tl_read_supr_nam(s);
DESCRIPTION Receives a pointer to a character string as an argument and
copies the name of the supervisor into it. The supervisor name
IMAGE Solutions V8.3 26-333
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
should have been previously set using tl_set_supr_nam().
The supervisor name has a default setting of \0 (null). Example:
{
char text[S_STDF_STRING+1];
printf("The Supervisor is: '%s'\n",
tl_read_supr_nam(text));
}
ARGUMENTS char *s—A pointer to user-allocated memory which will have
the supervisor’s name written to it. It is your responsibility to
allocate sufficient memory.
RETURN VALUE A character string containing the operator name, through the
argument.
SEE ALSO “tl_set_supr_nam”
tl_read_test_cod
Read the test code.
SYNOPSIS char * tl_read_test_cod(s)
char s[3];
DESCRIPTION Reads a three character test condition set using the testcond
command. (See “Setting Test Conditions Using the testcond
Command” on page 6-10.) Example:
{
char tcode[3];
tl_read_test_cod(tcode);
printf("Test code is: %c %c %c\n",tcode[0],
tcode[1],tcode[2]);
}
ARGUMENTS (The address of) A three character array to be filled in.
RETURN VALUE Its argument (that is, s)
tl_read_tja
Read measurement value from DARRAY
SYNOPSIS double tl_read_tja(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the appropriate
measurement value.
NOTE: This function should ONLY be called from within a
compute block.
Also note that this function calls tl_tja_read_timestamps().
IMAGE Solutions V8.3 26-334
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS DARRAY raw_data —Darray handle
RETURN VALUE Returns the measurement value in the appropriate units.
tl_read_tja_array
Read measurement array from DARRAY
SYNOPSIS void tl_read_tja_array(raw_data, array, array_size)
DARRAY raw_data;
double array[];
int array_size;
DESCRIPTION Given a DARRAY, this function returns the appropriate
measurement array.
NOTE: This function should ONLY be called from within a
compute block.
Also note that this function calls tl_tja_read_timestamps().
ARGUMENTS DARRAY raw_data—Darray handle
double array[]—Array that will contain the values
int array_size—Size of the array
RETURN VALUE None.
tl_read_tmscal_status
Return the calibration state of the Advanced Time Measurement Subsystem.
SYNOPSIS int tl_read_tmscal_status()
DESCRIPTION This function determines the status of the most recent ATMS
calibration attempt. This protects the user (or checker writer)
from going into shared memory for the results. This functions
checks the calibration status in shared memory for the current
station and also verifies the time stamp against the current time.
This means that if called twice during the same test program run
the calibration status may change.
ARGUMENTS None
RETURN VALUE -2 Last calibration attempt passed but has now expired.
-1 Last calibration attempt failed.
0 Uncalibrated, ATMS has not been calibrated since last
initialize.
1 Last calibration attempt passed and is still valid.
tl_read_tstr_typ
Read the tester type.
IMAGE Solutions V8.3 26-335
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS char * tl_read_tstr_typ(s)
char s[];
DESCRIPTION Reads the tester type (such as A550 or A530). The tester type is
automatically set when the test program is loaded and cannot be
changed. Example:
{
char text[S_STDF_STRING+1];
printf("The tester is: %s\n",
tl_read_tstr_typ(text));
}
ARGUMENTS (The address of) An array in which to place the tester type text.
RETURN VALUE Its argument.
tl_read_user_eeprom_all_data
Read all data from HUC ID PROM.
SYNOPSIS int tl_read_user_eeprom_all_data(which, buf)
EEPROM_ENUM_TYPE which;
unsigned short *buf;
DESCRIPTION Reads all data (16 words x 16 bits/word) from one of four ID
EEPROMS on the HUC. The argument which determines which
EEPROM is read from. The data is stored in a 16 element array
of unsigned short pointed to by the argument buf.
ARGUMENTS which—Determines which ID EEPROM on the HUC is read
from:
CONFIGA—Configuration Board A
CONFIGB—Configuration Board B
DIB—Device Interface Board (DIB)
TLDUT—Device Under Test (DUT)
buf—Points a 16 element array of unsigned short in which to
store the data
RETURN VALUE 1—Operation successful
0—Operation failed
tl_read_user_eeprom_id_data
Read coded data from HUC ID PROM.
SYNOPSIS int tl_read_user_eeprom_id_data(which, buf)
EEPROM_ENUM_TYPE which;
TER_EEPROM_ID *buf;
DESCRIPTION Reads Teradyne configuration data from one of four ID
EEPROMS on the HUC. The argument which determines which
IMAGE Solutions V8.3 26-336
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
EEPROM is read from. The data is stored in the structure of type
TER_EEPROM_ID pointed to by the argument buf.
ARGUMENTS which—Determines which ID EEPROM on the HUC is read
from:
CONFIGA—Configuration Board A
CONFIGB—Configuration Board B
DIB—Device Interface Board (DIB)
TLDUT—Device Under Test (DUT)
buf—Points a structure of type TER_EEPROM_ID in which to store
the data
RETURN VALUE 1—Operation successful
0—Operation failed
tl_read_usr_desc
Read the user description.
SYNOPSIS char * tl_read_usr_desc(s)
char s[];
DESCRIPTION Reads back the “user description” text string for the lot. The
default value is a null string. Example:
{
char desc[S_STDF_STRING+1];
printf("Lot Description: '%s'.\n",
tl_read_usr_desc(desc));
}
ARGUMENTS (The address of) An array in which to place the description string.
RETURN VALUE Its argument.
tl_read_uwrecv_digslot
Read back which slot of the digitizer the Microwave Receiver is using.
SYNOPSIS int tl_read_uwrecv_digslot(pin)
int pin;
DESCRIPTION Read back the digitizer slot the Microwave Receiver (UWRECV)
is using.
ARGUMENTS pin—Pin the UWRECV is behind
RETURN VALUE 0—No digital slot
non-0—Digital slot
SEE ALSO “tl_read_uwrecv_digslot_slot”
IMAGE Solutions V8.3 26-337
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_read_uwrecv_digslot_slot
Read back which slot of the digitizer the UWRECV is using.
SYNOPSIS int tl_read_uwrecv_digslot_slot(slot, schan)
int slot;
int schan;
DESCRIPTION Read back the slot of the digitizer the Microwave Receiver
(UWRECV) is using.
ARGUMENTS slot—Slot the UWRECV is in
schan—Schan of the UWRECV
RETURN VALUE 0—No digital slot
non-0—Digital slot
SEE ALSO “tl_read_uwrecv_digslot”
tl_read_uwrecv_thads
Read back which THADS the Microwave Receiver is using.
SYNOPSIS int tl_read_uwrecv_thads(pin)
int pin;
DESCRIPTION Read back the THADS the Microwave Receiver (UWRECV) is
using.
ARGUMENTS pin—Pin the UWRECV is behind
RETURN VALUE 0—THADS not in use
1—THADS 1 in use
2—THADS 2 in use
SEE ALSO “tl_read_uwrecv_thads_slot”
tl_read_uwrecv_thads_slot
Read back which THADS the UWRECV is using.
SYNOPSIS int tl_read_uwrecv_thads_slot(slot, schan)
int slot;
int schan;
DESCRIPTION Read back the THADS the Microwave Receiver (UWRECV) is
using.
ARGUMENTS slot—Slot the UWRECV is in
schan—Schan of the UWRECV
RETURN VALUE 0—THADS not in use
1—THADS 1 in use
2—THADS 2 in use
IMAGE Solutions V8.3 26-338
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “tl_read_uwrecv_thads”
tl_read_wafer
Read back wafer coordinates, if set.
SYNOPSIS int tl_read_wafer(xptr, yptr)
int *xptr, *yptr;
DESCRIPTION This function reads back the wafer die coordinates which have
been sent to the datalogger previously by the IMAGE software or
by a prior call to the function tl_set_device_info(). It expects
to be passed the addresses of two integer variables, into which
it will write the coordinates. Example:
int xc, yc;
tl_read_wafer(&xc, &yc);
ARGUMENTS xptr—Pointer to integer into which x coordinate will be stored
yptr—Pointer to integer into which y coordinate will be stored
RETURN VALUE 0—If coordinates have been set
-1—If no wafer coordinates for this device
SEE ALSO “tl_set_device”
tl_read_wafer_mapping_ink_bin
Return the value of the ink bin.
SYNOPSIS unsigned short tl_read_wafer_mapping_ink_bin()
DESCRIPTION This function returns the value of the ink bin variable.
ARGUMENTS None
RETURN VALUE Unsigned short value of the SECS ink bin.
tl_remove_datalog_output
Remove an output stream from datalog.
SYNOPSIS int tl_remove_datalog_output(unsigned int key...);
DESCRIPTION This function is like the datalog -remove_output command. If
datalogging is already set up and turned on, you can remove an
output, for instance the STDF file, from the existing datalogging.
To shut down all datalogging, use
tl_set_datalog(TL_DLG_OFF, ...) instead.
Multiple streams can be removed in one call. You must call this
function before the first device is tested. Once the program has
run, calls to tl_remove_datalog_output() are rejected.
IMAGE Solutions V8.3 26-339
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS Variable number of arguments, generally in pairs <flag,
argument>. Arguments can be unsigned integer bit vectors,
unsigned integer arrays, or character strings. The entire
argument list must be terminated by NULL, for example:
err_code =tl_remove_datalog_output
(TL_DLG_OUTPUT, TL_DLG_O_STDF,NULL);
See tl_set_datalog() for complete list of arguments. Only
these arguments are valid for tl_remove_datalog_output():
TL_DLG_OUTPUT
TL_DLG_FILE_NAME
TL_DLG_STDF_NAME
TL_DLG_DWIN_DISP
RETURN VALUE 0—An error occurred, either connecting to the data server or the
arguments were incorrectly specified, or testing has already
begun on this lot.
1—Success, the command line was correct and the command
successfully processed.
SIDE EFFECTS Affects the state of datalog.
SEE ALSO “tl_set_datalog”, “tl_get_datalog”, “tl_add_datalog_output”,
“tl_change_datalog”
tl_remove_datastream
Remove a data stream
SYNOPSIS int tl_remove_datastream(char * stream_id);
DESCRIPTION tl_remove_datastream operates like the datastream -off
command. If datastream is already enabled, it can be closed
using this command.
ARGUMENTS stream_id of type char * is the only argument required.
RETURN VALUE 0 - There was an error either connecting to the data server, or the
arguments were incorrectly specified, or testing has already
begun on this lot.
1 - Success, the command line was correct and the command
successfully processed by the data server.
tl_reprobing_device
Report whether the current set of devices under test are being reprobed.
SYNOPSIS int tl_reprobing_device()
DESCRIPTION This function returns 1 if the test program is currently reprobing
the tested devices. Since reprobe occurs for either all or none of
IMAGE Solutions V8.3 26-340
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
the running sites for a test program, site number does not play
any role in the return value of this function. If the current device
is not being reprobed, it returns 0.
ARGUMENTS None
RETURN VALUE 1 (True) if the current set of devices are being reprobed
0 (False) if the current set of devices are not being reprobed.
tl_restore_site_state
Restore a saved site state.
SYNOPSIS void tl_restore_site_state(tl_site_state_buffer
*restore_buffer)
DESCRIPTION This function restores the site state variables from the provided
site state buffer structure pointer argument.
ARGUMENTS struct site_state_buffer * restore_buffer—Site state
buffer to use to restore the set of site related variables.
RETURN VALUE None
SEE ALSO tl_save_site_state
tl_resume_data_collection
Resume data collection if it was paused.
SYNOPSIS int tl_resume_data_collection(void)
DESCRIPTION This function can be used to restart data collection once it has
been paused. Data collection may have been paused using the
datalog command, the datalog display, or by calling
tl_pause_data_collection(), from the test program.
ARGUMENTS None
RETURN VALUE 1—Data collection has been resumed.
0—Data collection has not been resumed. This is probably
because it was not on.
SIDE EFFECTS Turns the flow of data back on.
SEE ALSO “tl_pause_data_collection”
tl_retesting_device
Report whether the current set of devices under test are being retested.
SYNOPSIS int tl_retesting_device()
IMAGE Solutions V8.3 26-341
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function returns 1 if the test program is currently retesting or
reprobing a device. Since retest occurs for either all or none of
the running sites for a test program, site number does not affect
the return value of this function. If the current device is not being
retested or reprobed, it returns 0.
ARGUMENTS None
RETURN VALUE 1 (True) if the current set of devices are being retested or
reprobed.
0 (False) if the current set of devices are not under retest or
reprobe.
tl_retrieve_d
Retrieve the value of a variable of type double.
SYNOPSIS double tl_retrieve_d(name)
char * name;
DESCRIPTION This function is used in multisite test programs to retrieve the site
specific value of a variable previously saved using a save ddata
statement. It is similar to the retrieve ddata statement, but
returns the value of the variable instead of setting the variable to
the value. Example:
test read_meter() - tl_retrieve_d("offset");
See also “Global Variables in Multisite Test Programs” on page
17-17.
ARGUMENTS name—The name of the double variable (in quotes).
RETURN VALUE The value of the double variable previously saved for the
currently active site. If no site is active, 0.0 is returned.
tl_retrieve_i
Retrieve the value of an integer variable.
SYNOPSIS int tl_retrieve_i(name)
char * name;
DESCRIPTION This function is used in multisite test programs to retrieve the site
specific value of a variable previously saved using a save idata
statement. It is similar to the retrieve idata statement, but
returns the value of the variable instead of setting the variable to
the value. Example:
num_samples = new_samples + tl_retrive_i("old_samples");
See also “Global Variables in Multisite Test Programs” on page
17-17.
IMAGE Solutions V8.3 26-342
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS name—Name of the integer variable (in quotes).
RETURN VALUE The value of the integer variable previously saved for the
currently active site. If no site is active, 0 is returned.
tl_rs232_close
Close a device specified by device handle.
SYNOPSIS int tl_rs232_close(int devHandle);
DESCRIPTION This function closes a device previously opened by
tl_rs232_open() and frees all IMAGE and UNIX sources used.
ARGUMENTS devHandle—Handle of device returned by tl_rs232_open()
RETURN VALUE 0 on success
1 on failure
SIDE EFFECTS Frees IMAGE resources used by the device corresponding to
handle and the UNIX file descriptor.
SEE ALSO “tl_rs232_open” and UNIX close() function
tl_rs232_open
Open a tty (RS232) device.
SYNOPSIS int tl_rs232_open(char *devName);
DESCRIPTION This function opens a tty device. In this function, the name of the
device can be fully rooted (/some/hath/device_name) or only
the device name (device_name) as it appears in the /dev
directory. If the name is not a full path name, /dev/ is assumed.
For example, to open /dev/ttyb you can use:
int ttyb_fh;
ttyb_fh = tl_rs232_open("ttyb");
if (ttyb_fh < 0) {
<Perform error processing>
}
For a full path name, you can use:
ttyb_fh = tl_rs232_open("/dev/ttyb");
if (ttyb_fh < 0) {
<Perform error processing>
}
If the device is a link, the link is resolved and the device the link
pointed to is opened.
IMAGE RS232 functions can be used to support a maximum of
10 tty (RS232) devices simultaneously. Once devices are no
IMAGE Solutions V8.3 26-343
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
longer needed, call tl_rs232_close() to free IMAGE
resources.
Only call this function once per device being opened. Once a
device is opened, do not call this function again unless the
device has been closed using tl_rs232_close().
ARGUMENTS NULL terminated character string containing the device to open.
The name of the device should not be fully extended, However,
it is assumed the device being opened resides in the /dev
directory.
RETURN VALUE -1 on error, otherwise a handle to an IMAGE RS232 device. This
handle should be used in all other RS232 function calls such as
tl_rs232_read(), tl_rs232_write(), and
tl_rs232_close().
Possible errors may result from trying to open more than 10
devices at one time, in improperly specified device name.
SIDE EFFECTS Opens an RS232 device.
SEE ALSO Return values for the UNIX open() function
tl_rs232_open_remote_port
Open remote RS232 port.
SYNOPSIS tl_rs232_open_remote_port(port,test_computer)
int port;
char *test_computer;
DESCRIPTION This function will only operate on rs232 ports that are accessible
either directly or remotely. This currently includes the resident
cpu tty ports and ports provided via the terminal server option.
Note that ports that are bound to the CPU refer to those of the
calling computer. Care should be taken in regard to utilizing this
function on the system computer in a dual computer environment
since /dev/ttyb is used by the IMAGE software.
The ALM1 and ALM2 specified ports are not accessible if they
are not resident.
To create a stand-alone program which can access rs232 ports
(other than from a test program), use the following compile line:
cc -o foo foo.c /image/bin.rls/librs232.a /image/bin.rls/lib/libsys.a
where "foo" is the name of your program.
Note: the use of an rs232cap file is required. Remember that this
file must live in /image/tester/<host> and that the
test_computer parameter, above, corresponds to the <host> in
the path.
IMAGE Solutions V8.3 26-344
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
The result of a call to this routine is the same as that for
tl_rs232_open_port(), the call that is used to access rs232 ports
from within a test program (on the test computer).
ARGUMENTS port—The port as specified by the PORT parameter in the
rs232cap file.
test_computer—A string representing the name of the test
computer whose rs232cap file will be the basis for determining
how to open the connection to the specified port.
RETURN VALUE Integer file descriptor with a value > 0 if the open succeeded, or
-1 if it failed. If a -1 is returned, the user may query errno directly
or via perror() to determine the specific cause of failure. Note that
ENXIO is returned if there is no PORT entry in the rs232cap file
that matches the requested port, or, if the rs232cap file can not
be found. The value EINTR is returned if the connection timed
out.
SIDE EFFECTS The hardware mapped to the port is activated and made ready
for i/o.
tl_rs232_read
Read from a tty (RS232) device.
SYNOPSIS int tl_rs232_read(int devHandle,
char *buf, int bufSize);
DESCRIPTION This function reads characters from a device previously opened
using tl_rs232_open(). This function waits for a user-specified
timeout period (specified in microseconds) for input to appear on
the device opened by tl_rs232_open(). If no timeout is
specified, this function may block indefinitely. As soon as data is
detected, it is read and returned to the user.
ARGUMENTS devHandle—Device handle returned by tl_rs232_open()
char *buf—Character buffer to write to
bufSiz—Size of buf
timeout—Timeout value in seconds to wait for characters to
appear.
RETURN VALUE -1 on error, otherwise the number of characters actually read.
SIDE EFFECTS May block indefinitely if timeout not specified.
SEE ALSO “tl_rs232_open”, UNIX read()
tl_rs232_write
Write a to a tty (RS232) device.
IMAGE Solutions V8.3 26-345
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_rs232_write(int devHandle, char *buffer,
int bufSize);
DESCRIPTION Before this function can be used, tl_rs232_open() must first
be called to open the port. This function is called to write a string
of characters to a tty device. Normally, this function returns the
number of characters actually written.
ARGUMENTS devHandle—tty device handle returned by tl_rs232_open()
char *buffer—Information to write to device
bufSize—Number of characters to write
RETURN VALUE -1 on error, otherwise the number of characters written.
SEE ALSO “tl_rs232_open”, UNIX write()
tl_send_to_SECS_GEM
Send a string to SECS/GEM
SYNOPSIS int tl_send_to_SECS_GEM(char * message);
DESCRIPTION This routine is used to send arbitrary message strings to GEMsl,
the SECS/GEM Socket Listener. SECS/GEM then uses these
strings to keep track of various activities taking place within the
tester.
ARGUMENTS message—pointer to the character string to be sent
RETURN VALUE 0 -- Success
n -- errno for failure
tl_set_alarm_msg_mode
Set destination for alarm messages.
SYNOPSIS enum TL_MSG_MODE tl_set_alarm_msg_mode(newmode)
enum TL_MSG_MODE newmode;
DESCRIPTION Sets the destination of alarm message to a destination separate
from other error messages. Typically, error and alarm messages
are written to the same destination, however, you may want them
written to different destinations. If this function is not called (and
the IMAGE Properties are not modified) the default it to have
error and alarm messages sent to the same destination.
This function can be called with the following values:
MSG_MODE_ALRM_MSGS_DEFAULT—Return to default, that is
alarm messages are sent to the same destination as error
messages.
IMAGE Solutions V8.3 26-346
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
MSG_MODE_PRINT_ALRM_MSGS—Write alarm messages to
screen.
MSG_MODE_LOG_ALRM_MSGS—Write alarm message to log file.
MSG_MODE_PRINT_AND_LOG_ALRM_MSGS—Write alarm
messages to screen and log file.
MSG_MODE_IGNORE_ALRM_MSGS—Do not write alarm messages
anywhere. This loses all record of an alarm ever having
occurred.
MSG_MODE_SHOW—No change. Return value of current alarm
message destination only.
ARGUMENTS newmode—New message mode to use
RETURN VALUE Returns value of type enum TL_MSG_MODE
SIDE EFFECTS Changes the output of alarm messages.
SEE ALSO “tl_set_msg_mode”
tl_set_autocal_onoff
Turn autocal on or off.
SYNOPSIS void tl_set_autocal_onoff(flag)
DESCRIPTION This function enables or disables the IMAGE autocalibration
feature.
ARGUMENTS int flag 0—turn autocal off
1—turn autocal on
RETURN VALUE None
tl_set_autosummary
Sets autosummary from a test program.
SYNOPSIS int tl_set_autosummary
DESCRIPTION This function controls the setup of autosummaries from a test
program. You can use this function instead of using
tl_system() to invoke the setauto command. If the data
server is busy this function waits until the data server is free to
accept commands.
The arguments and parameters accepted by this function
correspond to the parameters and values accepted by the
setauto command. For example the FILE argument
corresponds to the -file parameter for the setauto command.
This function accepts two types of arguments:
IMAGE Solutions V8.3 26-347
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
flags—Indicate an on or off state for a particular parameter or
that a value is provided as the next argument. These correspond
to the flag values for the setauto command.
values—These arguments are the value for a particular
parameter and must immediately follow the parameter (flag)
being used.
Table 26-8 shows the corresponding tl_set_autosummary and
setauto command parameters.
Table 26-8. tl_set_autosummary Equivalents in setauto Command
Parameter Type setauto
SETAUTO_STATWIN flag setauto -statwin
SETAUTO_STDF flag setauto -stdf
SETAUTO_FILE flag setauto -file
SETAUTO_FILE_NAME char * setauto -file <name>
SETAUTO_PRINTER flag setauto -lpr
SETAUTO_PRINTER_NAME char * setauto -printer <name>
SETAUTO_SMY_FORMATTER char * setauto -format <fmt>
SETAUTO_AUTOSUM_OFF flag setauto -autosum_off
SETAUTO_FAIL_TESTS_ONLY flag setauto -fail_tests_only
SETAUTO_ALL_TESTS flag setauto -all_tests
SETAUTO_STDF_OFF flag setauto -stdf_off
When this function is called it sets the auto summary setup to the
criteria used in the most recent call of the function.
There are two restrictions when using this function:
-AUTOSUM_OFF flag must be used alone, as in:
tl_set_autosummary(AUTOSUM_OFF, NULL)
-FAIL_TESTS_ONLY and ALL_TESTS flags cannot be used at the
same time
Beyond these two exceptions, there are no restrictions on the
use of arguments.
The SMY_FORMATTER will apply to formatted (ASCII) outputs.
These are:
IMAGE Solutions V8.3 26-348
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
FILE,
STATWIN
PRINTER
The SMY_FORMATTER argument must be specified for formatted
(ASCII) outputs; it does not default to sumfmt as it does when
using the setauto command does.
Examples:
Enable autosummary to the station window, file, and printer
using printer name speedy and summary formatting process
my_formatter:
err = tl_set_autosummary(SETAUTO_FILE,SETAUTO_STATWIN,
SETAUTO_PRINTER_NAME, "speedy",
SETAUTO_SMY_FORMATTER, "my_formatter",
NULL);
Because the printer name for the summary is being specified, it
is not necessary to use the SETAUTO_LPR argument.
Enable autosummary to an ASCII file called my_ascii_file and
to the default printer for failing tests only:
err = tl_set_autosummary(SETAUTO_FILE_NAME,
"my_ascii_file", SETAUTO_LPR,
SETAUTO_SMY_FORMATTER, "sumfmt",
SETAUTO_FAIL_TESTS_ONLY, NULL);
Because the name of the ASCII file for the summary is specified,
the SETAUTO_FILE parameter is unnecessary.
ARGUMENTS Variable number of arguments, generally in pairs <flag,
argument>. The arguments can be unsigned integer flags or
character strings. The entire argument list library must be
terminated by NULL.
RETURN VALUE 0— Failure—an error occurred because of conflicting
parameters or connection to the data server was not possible.
1— Success—auto summary set up.
SEE ALSO For more information regarding the setauto command, see
“Automatic Summary Reports Using the setauto Command” on
page 6-96.
SIDE EFFECTS Changes the setup of the auto summary.
tl_set_burn_tim
Set burn-in time for the current lot.
SYNOPSIS int tl_set_burn_tim(i)
int i;
IMAGE Solutions V8.3 26-349
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Sets the burn-in time in units of minutes for the current lot being
tested.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the burn-in time for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2, and/or
the Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS i—Burn-in time in minutes for the current lot.
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_cabl_id
Set interface cable ID for the current lot.
SYNOPSIS int tl_set_cabl_id(s)
char *s;
DESCRIPTION This function sets the interface cable ID for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the interface cable id for
the current lot, you must call this function before execution of the
first sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2, and/or
the Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing interface cable ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_cabl_typ
Set interface cable type for the current lot.
SYNOPSIS int tl_set_cabl_typ(s)
char *s;
DESCRIPTION Sets the interface cable type for the current lot.
IMAGE Solutions V8.3 26-350
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the interface cable type for
the current lot, you must call this function before execution of the
first sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2, and/or
the Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing interface cable type
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_cmod_cod
Set command mode code for the current lot.
SYNOPSIS int tl_set_cmod_cod(c)
char c;
DESCRIPTION Sets the command mode code for the current lot. The command
mode code is a single-character, user-defined field sent to the
datalogger as part of the lot setup information.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the command mode code
for the current lot, you must call this function before execution of
the first sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS c—Single character containing command mode code
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_cont_id
Set contactor ID for the current lot.
SYNOPSIS int tl_set_cont_id(s)
char *s;
DESCRIPTION Sets the contactor ID for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the contactor ID for the
IMAGE Solutions V8.3 26-351
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing the contactor ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_cont_typ
Set contactor type for the current lot.
SYNOPSIS int tl_set_cont_typ(s)
char *s;
DESCRIPTION This function sets the contactor type for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the contactor type for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing contactor type
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_datalog
Controls datalog from a test program.
SYNOPSIS int tl_set_datalog(unsigned int key...);
DESCRIPTION Controls datalog from the test program. Use this function rather
than calling the datalog command from the test program using
the tl_system() function. If IMAGE is busy (that is, processing
data from the previous test program run) this function waits until
IMAGE is free.
Use of this function is similar to using the datalog command.
You must minimally specify the state for datalog (on or off), the
datalog criteria (such as passing, failing, or all) and one or more
IMAGE Solutions V8.3 26-352
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
outputs. This function takes a variable number of arguments.
The arguments are of two types:
flags: Indicate what function you are trying to perform. These are
represented by macros. They are analogous to -on, -test,
-samprate, and -file. Some flags accept a value. Others can
be used by themselves.
values: These arguments are values to a particular flag and must
immediately follow the particular flag they are used with. Values
are of four types:
–Unsigned integer array which is terminated by 0, that is the last
element is 0.
–Unsigned integer bit vector
–NULL terminated character string
–Unsigned integer
No value can equal zero. Specifying sample rate and sample
limits of 0 effectively turns writing datalog data to the output, but
leaves all of the overhead. Test lists and ranges cannot be zero.
Table 26-9 describes the macros used for flags and their values.
In the case of flags that accept bit vectors for arguments, the
macros used are listed. In general, value macros cannot be used
as flags. TL_DLG_ON and TL_DLG_OFF are exceptions. They can
be used as values to TL_DLG_STATE or standalone. Flags with no
corresponding entry in the Value column can be used without
arguments.
Table 26-9. tl_set_datalog Flags and Possible Values
Flag Value
TL_DLG_STATE TL_DLG_ON
TL_DLG_OFF
TL_DLG_ON No value
TL_DLG_OFF No value
TL_DLG_OUTPUT TL_DLG_O_DWIN
TL_DLG_O_STATWIN
TL_DLG_O_FILE
TL_DLG_O_STDF
TL_DLG_O_PRINTER
IMAGE Solutions V8.3 26-353
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Table 26-9. tl_set_datalog Flags and Possible Values (Continued)
Flag Value
TL_DLG_TEST TL_DLG_ALL_TEST
TL_DLG_PASS_TEST
TL_DLG_FAIL_TEST
TL_DLG_ANALOG_TEST
TL_DLG_DIGITAL_TEST
TL_DLG_PIN_OUTPUT TL_DLG_PIN_NAMES
TL_DLG_PIN_NUMBERS
TL_DLG_TEST_LIST unsigned int array, each element a test number
TL_DLG_TEST_RNG unsigned int array, where pairs of elements specify the start
and end of a range.
TL_DLG_TEST_FILE char *—path of file containing test list info.
TL_DLG_TEST_NAME char *—Name of test
TL_DLG_SEQ_NAME char *—Name of SEQUENCER
TL_DLG_FILE_NAME char *—Name for datalog text file for ASCII datalog output
TL_DLG_STDF_NAME char *—Name for datalog STDF file.
TL_DLG_PRINTER_NAME char *—Name of datalog printer.
TL_DLG_OUTPUT_FMT char *—Name of datalog format process to use for ASCII
datalog
TL_DLG_DWIN_DISP char *—Hostname to on which to display datalog window
TL_DLG_SAMP_RATE unsigned int—sample rate
TL_DLG_SAMP_LIMIT unsigned int—sample limit
TL_DLG_WAFER_MAP No value. Get X/Y data for all devices in sample datalog
tl_set_datalog() must be called before the first device is
tested. Once the program has run, calls to tl_set_datalog()
are rejected.
ARGUMENTS Variable number of arguments, generally in pairs <flag,
argument>. Arguments can be unsigned integer bit vectors,
unsigned integer arrays, or character strings. The entire
argument list must be terminated by NULL. For example:
err_code = tl_set_datalog(TL_DLG_ON, TL_DLG_OUTPUT,
TL_DLG_O_DWIN, TL_DLG_TEST,
TL_DLG_ALL_TEST, NULL);
IMAGE Solutions V8.3 26-354
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 0—An error occurred, either connecting to IMAGE or the
arguments were incorrectly specified, or testing has already
begun on this lot.
1—Success, the command line was correct and the command
successfully processed by IMAGE.
SIDE EFFECTS Affects the state of datalog.
SEE ALSO “Controlling Datalog From a Test Program” on page 6-57,
“tl_get_datalog”, “tl_remove_datalog_output”,
“tl_add_datalog_output”, “tl_change_datalog”
tl_set_datalog_disk_usage
Set expected datalog disk usage for the Disk Monitor.
SYNOPSIS int tl_set_datalog_disk_usage
(int amount);
DESCRIPTION This function tells dataserv the expected amount of KB/s worth
of datalog output generated by the test program.
ARGUMENTS amount—Expected number of KB/s
RETURN VALUE int 0: command failed. Either Disk Monitor not active or bad
arguments.
int 1: command succeeded
tl_set_device
Set device ID for current run.
SYNOPSIS int tl_set_device(id)
int id;
DESCRIPTION This function sets the part ID for the device currently being
tested. A legal part ID number is a positive integer.
You must call this function before the start of any testing or
datalogging within a run of a program. In other words, if you want
to change the device ID for a given run of the test program, the
call to this function must come before any sequencers are called
and before any information is sent to the datalogger. A TL error
will result if this function not called before these events.
This function is provided mainly to allow you to override the value
which the IMAGE test system software fills in by default. By
default, IMAGE will start the part ID number at 1 and increment
the number with each run of the test program.
In a multisite test program, this function must be called within a
serial loop. Even when called from within a serial loop, this
IMAGE Solutions V8.3 26-355
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
function always sets the device id for the lowest numbered site,
typically site 0. All other sites are incrementally set relative to the
lowest numbered site.
ARGUMENTS id—Integer containing device ID number
RETURN VALUE -1—All sites have been disabled
SIDE EFFECTS Can generate a runtime error if called incorrectly.
tl_set_dib_id
Set DIB ID for the current lot.
SYNOPSIS int tl_set_dib_id(s)
char *s;
DESCRIPTION This function sets the DIB ID for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the DIB board type for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
If the IMAGE Behavior Chooser option
IBC_ACCURATE_EEPROM_STRINGS is disabled, this function has
no effect.
ARGUMENTS s—String containing DIB ID
RETURN VALUE -1—error return if lot already started
0—status return if IBC_ACCURATE_EEPROM_STRINGS is disabled
1—successful return code
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
SEE ALSO “tl_set_dib_typ”, “tl_read_and_set_dib_info”
tl_set_dib_typ
Set DIB board type for the current lot.
SYNOPSIS int tl_set_dib_typ(s)
char *s;
DESCRIPTION Sets the DIB board type for the current lot.
IMAGE Solutions V8.3 26-356
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the DIB board type for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing the DIB board type
RETURN VALUE -1—error return if lot already started
1—successful return code
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
SEE ALSO “tl_set_dib_id”, “tl_read_and_set_dib_info”
tl_set_disp_cod
Set the disposition code for the current lot.
SYNOPSIS int tl_set_disp_cod(c)
char c;
DESCRIPTION This function sets the disposition code for the current lot. The
disposition code is a single character sent to the datalogger
which allows you to set the status of the lot.
Unlike many other tl_set_ functions, this function can be called
at any time until the lot is closed using a final summary or auto
endlot. If this function is called more than once during a lot, only
the disposition code from the last call is used.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS c—Character containing lot disposition code
RETURN VALUE None
tl_set_dlg_enable
Enable or disable datalog.
SYNOPSIS int tl_set_dlg_enable(state)
int state;
IMAGE Solutions V8.3 26-357
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Enables or disables data collection from within a test program. If
the state is 0, data collection is temporarily disabled. Tests
executed while the state is 0 will not appear on datalog output or
summaries. If the state is set to 1, data collection is enabled.
ARGUMENTS state—Integer containing data collection state desired. 0 to
disable; 1 to enable.
RETURN VALUE The previous datalogging state (0 or 1).
SIDE EFFECTS Enables or disables data collection.
tl_set_dsgn_rev
Set the device design revision for the current lot.
SYNOPSIS int tl_set_dsgn_rev(s)
char *s;
DESCRIPTION Sets the device design revision string for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the device design revision
for the current lot, you must call this function before execution of
the first sequencer of the first run of the test program.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing device design revision string
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_efd_datalog
Provides user control of EFD (Enhanced Functional Datalog)
SYNOPSIS int tl_set_efd_datalog(unsigned int key...);
DESCRIPTION tl_set_efd_datalog() operates like the "datalog -add_efd"
command if datalogging is already set up & turned on, you can
modify the existing setup while datalogging is on. For example,
you could change the Sample Rate. If you want to specify a
complete datalogging setup, use tl_set_datalog(TL_DLG_OFF,
...) instead. tl_change_datalog() may be called after the first
device is tested, but caution should be used when doing so.
IMAGE Solutions V8.3 26-358
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS Variable number of arguments, generally in pairs <flag,
argument>. The arguments may be unsigned integer bit vectors,
unsigned integer arrays, or character strings. The entire
argument list MUST be terminated by 'NULL', for example:
err_code = tl_set_efd_datalog(TL_DLG_EFD_ADD, "efd_setup_8",
TL_DLG_EFD_FAIL_VECT,
TL_DLG_EFD_NUM_FAIL_VECT, 4,
TL_DLG_EFD_VECT_BEF_FAIL, 2,
TL_DLG_EFD_VECT_AFT_FAIL, 1,
TL_DLG_EFD_PIN_LIST, plist,
NULL);
See tl_set_efd_datalog() for complete list of arguments.
RETURN VALUE 0 - There was an error either connecting to the data server, or the
arguments were incorrectly specified, or testing has already
begun on this lot.
1 - Success, the command line was correct and the command
successfully processed by the data server.
SIDE EFFECTS Will affect the state of EFD datalog.
SEE ALSO Data collection section of Base IMAGE Manual, and
tl_set_datalog(), tl_get_datalog(),
tl_change_datalog(), tl_add_datalog_output(),
tl_remove_datalog_output(),
handle_tl_datalog_commands().
tl_set_eng_id
Set the engineering lot ID for the current lot.
SYNOPSIS int tl_set_eng_id(s)
char *s;
DESCRIPTION Sets the engineering lot ID for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the engineering lot ID for
the current lot, you must call this function before execution of the
first sequencer of the first run of the test program.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing the engineering lot ID.
RETURN VALUE None
IMAGE Solutions V8.3 26-359
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_extr_id
Set extra equipment ID for the current lot.
SYNOPSIS int tl_set_extr_id(s)
char *s;
DESCRIPTION Sets the extra equipment ID for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the extra equipment ID for
the current lot, you must call this function before execution of the
first sequencer of the first run of the test program.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing extra equipment ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_extr_typ
Set extra equipment type for the current lot.
SYNOPSIS int tl_set_extr_typ(s)
char *s;
DESCRIPTION Sets the extra equipment type for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the extra equip. type for
the current lot, you must call this function before execution of the
first sequencer of the first run of the test program.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing the extra equipment type
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
IMAGE Solutions V8.3 26-360
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_set_facil_id
Set the test facility ID for the current lot.
SYNOPSIS int tl_set_facil_id(s)
char *s;
DESCRIPTION Sets the test facility ID for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test facility ID for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing test facility ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_famly_id
Set device family ID for the current lot.
SYNOPSIS int tl_set_famly_id(s)
char *s;
DESCRIPTION This function sets the device family ID for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the device family ID for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing family ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
IMAGE Solutions V8.3 26-361
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_set_floor_id
Set test floor ID for the current lot.
SYNOPSIS int tl_set_floor_id(s)
char *s;
DESCRIPTION Sets the test floor ID string for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test floor ID for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing test floor ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_flow_id
Set test flow ID for the current lot.
SYNOPSIS int tl_set_flow_id(s)
char *s;
DESCRIPTION Sets the test flow ID for the current lot. The test flow ID is a string
sent to the datalogger to identify the name of the test program
flow used to test the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test flow ID for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on information recorded by the IMAGE datalogger in
STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing test flow ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
IMAGE Solutions V8.3 26-362
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_set_hand_id
Set handler id for the current lot (obsolete)
SYNOPSIS int tl_set_hand_id(s)
char *s;
DESCRIPTION This routine sets the handler id for the current lot. The handler id
is a string sent to the datalogger to record the name of the
handler used to test the lot. This routine MUST be called before
any testing or datalogging is done for the lot. In other words, in
order to set the handler id for the current lot, you must call this
routine prior to the execution of the first sequencer of the first run
of the test program.
For more details on the information recorded by the IMAGE
datalogger in ".stdf" files, see Appendix "D" of the User's Manual,
entitled "Standard Test Data Format", and the Standard Test
Data Format Specification, version 4, part number 555-611-01.
ARGUMENTS s—String containing the handler id
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called. May generate a TL error
if called after testing has begun.
tl_set_hp_name
Set the handler or prober ID string.
SYNOPSIS int tl_set_hp_name(char * hp_name)
DESCRIPTION Sets the handler or prober ID string in the STDF file. It appears
in the HAND_ID field of the Site Description Record (SDR). If the
argument is NULL the handler ID is set to a NULL string (that is,
a zero length string) and does not appear in the SDR HAND_ID
field. Calling the function with no argument rather than a NULL
argument is different. If called with no argument, what is written
to the STDF is undefined and will probably cause problems.
The handler name (or ID) is the name used to distinguish
individual devices of a particular model or type. This can be the
serial number or any other identifier used on the production floor
to distinguish between devices of a particular model.
This function cannot be called after testing for a lot has begun,
that is, after any SEQUENCER statements are called, after an
new lot has begun. If called after testing for a lot has begun, a
runtime error is generated.
ARGUMENTS char * hp_name—A character string containing the name (or ID
string) of a particular handler or prober. If this string is NULL the
IMAGE Solutions V8.3 26-363
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
no name is written to the STDF file, and the SDR HAND_ID field
is NULL.
RETURN VALUE 0—lot already begun, could not update name
1—success
SIDE EFFECTS If called after testing has begun, a runtime error is generated.
If successful, the handler name is written to the SDR HAND_ID
field, and the datalog buffer is dumped.
SEE ALSO “tl_get_hp_name”, “tl_set_hp_type”, “tl_get_hp_type”
tl_set_hp_type
Set the handler or prober type.
SYNOPSIS int tl_set_hp_type(char *hp_type)
DESCRIPTION Stores the handler type and writes it to the HAND_TYP field for the
Site Description Record (SDR). The argument is a character
string pointer containing the type of handler or prober. By default
this is the name used when issuing a handlerconf -connect
<hp_name> command. In this case, hp_name, is the handler type.
If value of the argument is NULL (char * 0), it sets the handler
type to NULL and, in turn, the SDR HAND_TYP field is NULL.
Calling the function with no argument rather than a NULL
argument is different. If called with no argument, what is written
to the STDF is undefined and will probably cause problems.
You must call this function before any testing for a lot has begun
(before any SEQUENCERs are entered). Otherwise, a runtime
error occurs.
ARGUMENTS char *hp_type—Pointer to character string containing handler
or prober type.
RETURN VALUE 1—success
0—name could not be copied testing has begun
SIDE EFFECTS May generate an error if called after testing has begun. If
successful, it changes the value of handler type and dumps the
datalog buffer when called.
SEE ALSO “tl_get_hp_type”, “tl_set_hp_name”, “tl_get_hp_name”
tl_set_inker_map
Create a mapping of inker to site and define which bin numbers will cause the inker to fire.
SYNOPSIS int tl_set_inker_map(int stn, int site, int inker,
int *bins);
IMAGE Solutions V8.3 26-364
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function creates a mapping of an inker, referenced by the
inker number, to a site. The bins argument defines which bin
numbers cause the inker to fire. The bins argument is an array
of bin numbers whose last element must be set to -1.
When using the RS232 interface for multisite test, the bin results
are used to determine which inker number to return with the RDP
BA command. If an inker is not specified for a site and bin
number, 0 is passed to the prober, causing no inker to fire.
You can call this function multiple times for as many site/inker/bin
relationships as are needed. The function does not allow an
inker to be mapped to another site. This assumes that for a given
test program/probe card, inker numbers are statically assigned
to sites and one inker cannot support more than one site.
If you assign an inker to an incorrect site, use the function
tl_unmap_inker_from_site() to clear the site.
If you set a bin number to incorrectly fire an inker, you can call
this function passing the site, the incorrect bin number, and a 0
for inker number. For example, assume that for site 0, bin
number 3 is incorrectly set to fire inker 1. Bin number 3 should
fire inker 2. Call this function as follows:
int bins[5];
Set bins 1, 2, and 3 to fire inker 1:
bins[0] = 1;
bins[1] = 2;
bins[2] = 3;
bins[3] = -1;
err = tl_set_inker_map(station_num, 0, 1, bins);
The error is discovered. To correct it, use:
bins[0] = 3;
bins[1] = -1;
err = tl_set_inker_map(station_num, 0, 2, bins);
ARGUMENTS stn—Station number
site—Site to map inker:bin number to
inker—Inker number to map to site:bin
bins—List of bin numbers which fire inker. Terminated by -1.
RETURN VALUE FALSE—either station number is invalid or memory allocation
problem for inker map.
TRUE—site:inker association formed as well as bin numbers
which will fire inker.
SIDE EFFECTS May allocate memory for inker map, and sets up site:inker:bins
association.
IMAGE Solutions V8.3 26-365
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_set_job_nam
Set program name for the current lot.
SYNOPSIS int tl_set_job_nam(s)
char *s;
DESCRIPTION This function is identical to tl_set_prog_nam().
ARGUMENTS s—String containing program name
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
SEE ALSO “tl_set_prog_nam”
tl_set_job_rev
Set the test program revision for the current lot.
SYNOPSIS int tl_set_job_rev(s)
char *s;
DESCRIPTION This function sets the test program revision for the current lot.
The test program revision is a string sent to the datalogger to
identify which revision of the program was used to test the lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test program revision
for the current lot, you must call this function before execution of
the first sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing job plan or test program revision
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_lasr_id
Set laser ID for the current lot.
SYNOPSIS int tl_set_lasr_id(s)
char *s;
DESCRIPTION Sets the laser ID for the current lot.
IMAGE Solutions V8.3 26-366
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the laser ID for the current
lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing laser ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_load_id
Set load board ID for the current lot.
SYNOPSIS int tl_set_load_id(s)
char *s;
DESCRIPTION Sets the load board ID for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the load board id for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing the load board ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_load_typ
Set load board type for the current lot.
SYNOPSIS int tl_set_load_typ(s)
char *s;
DESCRIPTION Sets the load board type for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the load board type for the
IMAGE Solutions V8.3 26-367
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing load board type
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_lot_id
Set the lot ID for the current lot.
SYNOPSIS int tl_set_lot_id(s)
char *s;
DESCRIPTION This function sets the lot ID for the current lot. The lot ID is a
string sent to the datalogger to identify the lot being tested.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the lot ID for the current
lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing lot ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_lot_ids
Set both lot and sublot ID for the current lot.
SYNOPSIS int tl_set_lot_ids(s)
char *s;
DESCRIPTION This function sets the lot and sublot for the current lot. The lot ID
and sublot ID are strings used to identify a particular lot.
IMAGE Solutions V8.3 26-368
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
The argument to this function should be a string containing first
the lot ID, then a “:” separator, and then the sublot ID. Example:
boat9:wafer12.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the lot IDs for the current
lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS s—String containing lot and sublot IDs
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
SEE ALSO “tl_set_lot_id”, “tl_set_sblot_id”
tl_set_mode_cod
Set mode code for the current lot.
SYNOPSIS int tl_set_mode_cod(c)
char c;
DESCRIPTION This function sets the “mode code” for the current lot. The mode
code is a string sent to the datalogger to describe the mode that
the tester is running in (for example, engineering or production).
IMAGE automatically calls this function to set the mode code to
E when in engineering mode and P for production mode.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the mode code for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4, part
number 555-611-01.
ARGUMENTS c—Single character containing mode
RETURN VALUE None
SIDE EFFECTS Changes datalog information for the current lot.
Updates the station monitor if present.
May generate a TL error if called after testing has begun.
IMAGE Solutions V8.3 26-369
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_set_msg_mode
Set destination for error or alarm messages.
SYNOPSIS enum TL_MSG_MODE tl_set_msg_mode(newmode)
enum TL_MSG_MODE newmode;
DESCRIPTION This function controls the destination to which error and alarm
messages are sent. The argument to the function determines
where the messages are sent:
MSG_MODE_PRINT_MSGS—print messages in station window
MSG_MODE_LOG_MSGS—log messages to file
MSG_MODE_PRINT_AND_LOG_MSGS—print and log messages
MSG_MODE_SHOW—no change; return value only
By default, error messages are sent to the station window. When
error messages are directed to a log file, IMAGE writes to the
directory /image/tester/<hostname>/errlog, where
<hostname> is the name of the tester computer (if the test
system has a dual-computer architecture).
The IMAGE Properties window includes an option (under the
category PRODUCTION SETUP) that allows you to set a default
error destination for programs loaded in production mode. (The
defaults option does not apply for Engineering mode.)
The function returns the new value of the message destination.
If the value MSG_MODE_SHOW is passed as the argument to this
function, the current message destination is only returned, not
changed.
ARGUMENTS newmode—New mode to use or MSG_MODE_SHOW
RETURN VALUE Value of type enum TL_MSG_MODE
tl_set_next_device
Set device ID for next run.
SYNOPSIS int tl_set_next_device(id)
int id;
DESCRIPTION This function sets the part ID for the next device to be tested. A
legal part ID number is a positive integer.
If this function is used with the function tl_set_device, the call
to this function must follow the call to tl_set_device. This is
because a call to tl_set_device(N) implicitly sets the device
ID for the next run to N+1.
This function is provided mainly to allow you to override the value
which IMAGE fills in by default. By default, IMAGE starts the part
IMAGE Solutions V8.3 26-370
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ID number at 1 and increments the number with each run of the
test program.
In a multisite test program, this function must be called within a
serial loop to as to select a given site. This function always sets
the device number for the lowest numbered site of the next test
run. All other device numbers for other sites are set relative to the
lowest numbered site.
ARGUMENTS id—Integer containing device ID number
RETURN VALUE -1—all sites have been disabled
SIDE EFFECTS May generate a runtime error if called incorrectly.
SEE ALSO “tl_set_device”
tl_set_ONLY_test_condition
Set the test condition for the current lot without changing the test_cod field.
SYNOPSIS int tl_set_ONLY_test_condition(tc);
int tc;
DESCRIPTION This function does the same thing as tl_set_test_condition
but you can call it during a lot. It is similar to
tl_set_test_condition_during_lot except that this function
never changes the test_cod field of the MIR.
ARGUMENTS tc - The name of a test condition or 0 to deselect a test condition
(that is, to use default limits in sequencers).
RETURN VALUE 1 if successful
0 if test condition not found
SEE ALSO “tl_set_test_condition”, “tl_set_test_condition_during_lot”
tl_set_oper_frq
Set the testing operation frequency for the current lot.
SYNOPSIS int tl_set_oper_frq(s)
char *s;
DESCRIPTION Sets the testing operation frequency for the current lot. The
testing operation frequency is the sort frequency or step for the
current lot as a string.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the operation frequency for
the current lot, you must call this function before execution of the
first sequencer of the first run of the test program.
IMAGE Solutions V8.3 26-371
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing testing operation frequency string.
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_oper_nam
Set operator name for the current lot.
SYNOPSIS int tl_set_oper_nam(s)
char *s;
DESCRIPTION This function sets the operator name for the current lot. The
operator name is a string sent to the datalogger to identify the
person operating the tester while the lot was tested.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the operator name for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing operator name
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_part_datalogged
Set whether or not the current set of parts will be datalogged in the standard datalog outputs.
SYNOPSIS void tl_set_part_datalogged(int datalogged)
DESCRIPTION Sets whether or not the current set of parts will be datalogged in
the standard datalog outputs. If given an argument whose value
is nonzero (TRUE), the current set of parts for this run of the test
program will be datalogged in the standard datalog outputs.
If given a 0 (FALSE), the current set of parts will not be
datalogged. Datastreams set up using the datastream
command or from the datastream setup window are not affected
IMAGE Solutions V8.3 26-372
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
by this function. You must call this function before any
sequencers are executed, or a run time error will occur.
ARGUMENTS datalogged—Nonzero to have the current set of parts
datalogged.
RETURN VALUE None
tl_set_part_fix
Set user-defined part fix string.
SYNOPSIS int tl_set_part_fix(num_bytes, s, site)
unsigned char num_bytes;
char *s;
int site;
DESCRIPTION This function sets the user-defined part fix string in the Part
Results Record (PRR) for each device for each site being used.
A check is first made to make sure the site does not exceed the
maximum allowable number of sites.
ARGUMENTS num_bytes—Unsigned number of bytes of data
s—String containing information to write to datalogger
site—Site number this corresponds to
RETURN VALUE 1 No errors
-1 Errors
SIDE EFFECTS Sets the global variable holding the part_fix string.
tl_set_part_typ
Set part type for the current lot.
SYNOPSIS int tl_set_part_typ(s)
char *s;
DESCRIPTION This function sets the part type for the current lot. The part type
is a string (defined by the user) sent to the datalogger to describe
the type of part being tested.
You must call this function before testing or datalogging a lot. In
other words, to set the part type for the current lot, you must call
this function before execution of the first sequencer of the first
run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing part type
IMAGE Solutions V8.3 26-373
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_pkg_typ
Set the package type for the current lot.
SYNOPSIS int tl_set_pkg_typ(s);
char *s;
DESCRIPTION Sets the package type for current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the package type for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing package type.
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_plfdig_legacy_filter_settling_times
Set or clear a flag to use the old PLFDIG filter settling times.
SYNOPSIS void tl_set_plfdig_legacy_filter_settling_times
(filt_flag)
DESCRIPTION Set or clear a flag to use the old plfdig filter settling times. If
cleared, the newly calculated filter settling times will be used. If
set, the times will be set as they have been in previous versions
of the code. The default is to have the flag cleared, and use the
new settings.
ARGUMENTS filt_flag—0 indicates use new settings, non-zero indicates
use of the older calculations.
RETURN VALUE None.
tl_set_prb_card
Set probe card ID for the current lot.
IMAGE Solutions V8.3 26-374
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_set_prb_card(s)
char *s;
DESCRIPTION This function sets the probe card ID for the current lot. The probe
card ID is a string sent to the datalogger to identify which probe
card was used to test the lot of parts.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the probe card ID for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing probe card ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_prb_typ
Set probe card type for the current lot.
SYNOPSIS int tl_set_prb_typ(s)
char *s;
DESCRIPTION Sets the probe card type for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the probe card type for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing the probe card type
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
SEE ALSO “tl_set_prb_card”, “tl_read_and_set_prb_info”
tl_set_proc_id
Set process ID for the current lot.
IMAGE Solutions V8.3 26-375
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_set_proc_id(s)
char *s;
DESCRIPTION This function sets the process ID for the current lot. The process
ID (not to be confused with the UNIX process ID) is a string sent
to the datalogger to identify the name of the manufacturing
process used to produce the lot being tested.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the process ID for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing process ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_prog_nam
Set program name for the current lot.
SYNOPSIS int tl_set_prog_nam(s)
char *s;
DESCRIPTION This function sets the program name for the current lot. The
program name is a string sent to the datalogger to identify the
test program used to generate the test data. This affects only the
name of the program that appears in any STDF file generated for
during the lot. This function will not alter the name of the file or
the module that the program resides in.
This function is called automatically by IMAGE when a test
program is loaded. It is provided mainly to allow you to override
the name set by IMAGE in the STDF file.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the program name for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing program name
RETURN VALUE None
IMAGE Solutions V8.3 26-376
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_prot_cod
Set protection code for the current lot.
SYNOPSIS int tl_set_prot_cod(c)
char c;
DESCRIPTION This function sets the protection code for the current lot. The
protection code is a single-character field sent to the datalogger
which can be used to record a protection level for the test data in
a lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the protection code for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS c—Single character containing protection code
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_rom_cod
Set the ROM code id for the current lot.
SYNOPSIS int tl_set_rom_cod(s)
char *s;
DESCRIPTION This function sets the ROM code ID for the current lot. The ROM
code is in a string format and sent to the datalogger to be
recorded by IMAGE in an .stdf file.
You must call this function before you do any testing or
datalogging for the lot. In other words, in order to set the tester
serial number for the current lot, you must call this function
before the execution of the first sequencer of the first run of the
test program.
For more details on the information recorded by the IMAGE
datalogger in .stdf files, see “Standard Test Data Format” on
page 24-1 and/or the Standard Test Data Format (STDF)
Specification, Version 4.
IMAGE Solutions V8.3 26-377
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS s—String containing ROM code ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_rtst_cod
Set the retest code for the current lot.
SYNOPSIS int tl_set_rtst_cod(c)
char c;
DESCRIPTION This function sets the retest code for the current lot. The retest
code is a single-character field sent to the datalogger which
records whether the lot is a retest of a previous lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the retest code for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS c—Character containing retest code
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_sblot_id
Set sublot ID for the current lot.
SYNOPSIS int tl_set_sblot_id(s)
char *s;
DESCRIPTION This function sets the sublot ID for the current lot. The sublot ID
is a string sent to the datalogger which is used (in addition to the
lot ID) to identify the lot being tested.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the sublot ID for the current
lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
IMAGE Solutions V8.3 26-378
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS s—String containing sublot ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_serl_num
Set the tester serial number for the current lot.
SYNOPSIS int tl_set_serl_num(s)
char *s;
DESCRIPTION This function sets the tester serial number for the current lot. The
tester serial number (found on each Teradyne tester) is input in
a string format and sent to the datalogger to be recorded by
IMAGE in an .stdf file.
You must call this function before you do any testing or
datalogging for the lot. In other words, in order to set the tester
serial number for the current lot, you must call this function
before the execution of the first sequencer of the first run of the
test program.
For more details on the information recorded by the IMAGE
datalogger in .stdf files, see “Standard Test Data Format” on
page 24-1 and/or the Standard Test Data Format (STDF)
Specification, Version 4.
ARGUMENTS s—String containing tester serial number
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_setup_id
Set setup ID for the current lot.
SYNOPSIS int tl_set_setup_id(s)
char *s;
DESCRIPTION Sets the test setup ID for the current lot. The test setup ID is a
string sent to the datalogger to identify the name of the testing
setup used to test the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test setup ID for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
IMAGE Solutions V8.3 26-379
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing test setup ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_spec_nam
Set test specification name for the current lot.
SYNOPSIS int tl_set_spec_nam(s);
char *s;
DESCRIPTION Sets the test specification name for the current lot being tested.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test specification name
for the current lot, you must call this function before execution of
the first sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing test specification name
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_spec_ver
Set test specification version for the current lot.
SYNOPSIS int tl_set_spec_ver(s)
char *s;
DESCRIPTION Sets the test specification version for the current lot being tested.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test specification
version for the current lot, you must call this function before
execution of the first sequencer of the first run of the test
program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
IMAGE Solutions V8.3 26-380
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS s—String containing test specification version
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_supr_nam
Set supervisor name for the current lot.
SYNOPSIS int tl_set_supr_nam(s)
char *s;
DESCRIPTION Sets the supervisor name for the current lot. The supervisor
name is a string sent to the datalogger to identify the person
supervising during the time the lot was tested.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the supervisor name for
the current lot, you must call this function before execution of the
first sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing supervisor name
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_test_cod
Set test code for the current lot.
SYNOPSIS int tl_set_test_cod(c)
char c[3];
DESCRIPTION This function sets the test code for the current lot. The test code
is a three-character field sent to the datalogger which records the
conditions under which the lot was tested. (The
test_conditions command provides a more complete system
of test conditions. See “Declaring Test Conditions” on page
15-27 for information on the test_conditions command.)
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test code for the current
lot, you must call this function before execution of the first
sequencer of the first run of the test program.
IMAGE Solutions V8.3 26-381
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS c—Character array containing a maximum of 255 characters
followed by a NULL terminator.
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_test_condition
Set the test condition for a lot.
SYNOPSIS int tl_set_test_condition(tc)
int tc;
DESCRIPTION This function can only be called before executing the first
sequencer during the first run after starting a new lot.
The function sets the test condition to be used in testing the
current lot of devices. The test condition specified as a
parameter to this function must have been declared using a
test_conditions declaration. The test condition affects the test
limits used in a sequencer. For example:
tl_set_test_condition(HOT);
ARGUMENTS tc—Name of a test condition or 0 to deselect a test condition
(that is, to use default limits in sequencers).
RETURN VALUE 1 successful
0 test condition not found
tl_set_test_condition_during_lot
Set the test condition for a lot. Can be called during the lot.
SYNOPSIS int tl_set_test_condition_during_lot(int tc)
DESCRIPTION This function does the same thing as tl_set_test_condition
but you can call it during a lot.
Note that this function does not change the test_cod member
of the MIR if you call this function during a lot. Otherwise, if you
call this function after the end of one lot and before the beginning
of the next lot, the function changes the test_cod member of the
MIR.
ARGUMENTS tc—The name of a test condition or 0 to de-select a test
condition (that is, to use default limits in sequencers).
IMAGE Solutions V8.3 26-382
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 1 if successful
0 if test condition not found.
SIDE EFFECTS If you change the test conditions during the run of a lot,
datalogging for the remainder of the lot switches to Heavy mode.
This ensures that the datalog includes the correct set of limits for
each test.
tl_set_tmode
Set program termination mode.
SYNOPSIS enum Tmode tl_set_tmode(tmode)
enum Tmode tmode;
DESCRIPTION This function allows you to set the termination mode of a test
program or to return the current termination mode. The
termination mode controls whether the program will stop
execution for failures or runtime errors or both. (See “Setting
Program Termination Modes” on page 5-24.)
ARGUMENTS tmode—one of the following constants:
TMODE_STOP_ON_FAIL
TMODE_CONT_ON_FAIL
TMODE_CONT_ON_ERROR
TMODE_SHOW (returns the current termination mode)
RETURN VALUE The new setting of the termination mode
SIDE EFFECTS None
tl_set_tsr_test_tim
Set the Average Test Time Field in the Test Synopsis Record.
SYNOPSIS int tl_set_tsr_test_tim(int testnumber,
float test_time)
DESCRIPTION This function sets the TEST_TIM field for a specified test, which
will be written to the Test Synopsis Record (TSR) for that test in
the STDF file. Note that there is only one TSR per test, so if this
function is called multiple times for the same test, the last value
will be the one written.
ARGUMENTS int testnumber—The test number. When called from inside a
TESTF, you can use tl_read_datnum() as the first argument.
When called from outside a TESTF, call tl_read_datnum()
inside the TESTF and save the test number in a variable.
float test_time—The value you want to set as the TSR
TEST_TIM value for this test.
IMAGE Solutions V8.3 26-383
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 1 for Success, 0 for Failure
tl_set_tst_temp
Set the testing temperature for the current lot.
SYNOPSIS int tl_set_tst_temp(s)
char *s;
DESCRIPTION Sets the testing temperature for the current lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the test temperature for the
current lot, you must call this function before execution of the first
sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing testing operation frequency string
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_user_power
Turn user power on and off.
SYNOPSIS int tl_set_user_power(onoff);
DESCRIPTION Set user power to the indicated value, TRUE for power on and
FALSE for power off. Returns new value of power setting.
ARGUMENTS int onoff—TRUE for power on, FALSE for power off
RETURN VALUE int new value of power setting—TRUE for power on, FALSE for
power off
tl_set_usr_desc
Set user-defined lot information string.
SYNOPSIS int tl_set_usr_desc(s)
char *s;
DESCRIPTION Sets a user-defined string which is sent to the datalogger for
each lot. The user-defined string is placed into the USR_DESC
field of the Master Results Record (MRR) which appears at the
end of every STDF file.
IMAGE Solutions V8.3 26-384
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing information to write to datalogger
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
tl_set_wafer
Set wafer coordinates for current device.
SYNOPSIS int tl_set_wafer(x, y)
int x, y;
DESCRIPTION This function is used in wafer probing applications to set the
wafer coordinates which are sent to the datalogger for the device
being tested. This information is then sent to the IMAGE
datalogger for inclusion in the datalog files.
You must call this function before the start of any testing or
datalogging within a run of a program. In other words, to change
the wafer coordinates for a given run of the test program, the call
to this function must come before any sequencers are called and
before any information is sent to the datalogger. A TL error
results if this function not called before these events.
By default, IMAGE only sets the wafer coordinates by default if
the tester is being run in combination with an RS232-based
wafer prober which supports reading of wafer coordinates. In this
case, the system reads back the die coordinates into the test
program before each run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS x, y—Integers containing current X and Y die coordinates
RETURN VALUE Returns -1 on error, or nonzero for success.
SIDE EFFECTS Sets tl_is_wafer to 1.
tl_set_wafer_id
Set wafer ID for the current wafer.
SYNOPSIS void tl_set_wafer_id(char *wafer_id)
IMAGE Solutions V8.3 26-385
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Sets the wafer ID for the current wafer. You must call this function
before a devices is tested for the current lot. The Wafer
Information Record is constructed using the wafer ID when the
first sequencer in a new lot is entered.
ARGUMENTS char *wafer_id—The new wafer ID.
RETURN VALUE None
SIDE EFFECTS Sets a global variable which holds the current wafer ID and
appends a null terminator. This information will appear in the
Wafer Information Record.
tl_set_wafer_mapping_ink_bin
Set the bin number for the ink bin.
SYNOPSIS void tl_set_wafer_mapping_ink_bin(bin_num)
unsigned short bin_num;
DESCRIPTION This function sets the ink bin variable. It assumes that you are
using the wafer mapping software and have designated certain
dice on the wafer as INK die.
ARGUMENTS unsigned short bin_num—Bin number to be used for inking
RETURN VALUE None
SIDE EFFECTS Sets the SECS ink bin variable.
tl_set_wait
Set a retriggerable wait time.
SYNOPSIS void tl_set_wait(delay_time)
double delay_time;
DESCRIPTION Set up a timer to wait at least delay_time. The timer is set to
delay_time and starts to count down to zero. If a new delay time
is sent while the timer is still running, the counter is increased if
the new time is longer than time remaining. This allows
concurrence of overlapping settle waits.
The precision of the timer is 1 µs. All delay times are rounded up
to the next 1 µs.
The minimum delay time is 50 µs. Behavior is undefined if a
shorter delay is specified.
Note that there is no upper bound on delay times, but a timeout
period is built in to the tl_wait_wait() function.
ARGUMENTS delay_time—Time to wait in seconds (rounded to next highest
1 µs)
IMAGE Solutions V8.3 26-386
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
SEE ALSO “tl_set_wait_timeout”, “tl_wait_wait”
tl_set_wait_timeout
Set user retriggerable wait timeout.
SYNOPSIS void tl_set_wait_timeout(timeout)
DESCRIPTION Set the timeout for the wait of the user retriggerable wait feature
(tl_set_wait()/tl_wait_wait()). tl_wait_wait()
calculates how much wait time remains and issues a run time
error if this wait time exceeds the timeout. The default timeout is
2 minutes.
ARGUMENTS double timeout—Timeout in seconds
RETURN VALUE None
SEE ALSO “tl_set_wait”, “tl_wait_wait”
tl_simwave_name
Set the filename for the AC wave source simulator.
SYNOPSIS void tl_simwave_name(char *format, ...)
DESCRIPTION This function sets a global variable, which will be used as the
filename for the IMAGE AC source simulator. When the test
program executes an AC source start statement, the IMAGE
simulator generates a wave file which contains one execution of
the programmed wave segment. The wave file has a default
name of the form simwave_<instr><num>.wav. The function
tl_simwave_name allows you to change the name of this output
file.
ARGUMENTS format—String for file name or printf-style format
string—If format is printf-style format string, the printf-style
arguments follows
RETURN VALUE None
SIDE EFFECTS Sets global in IMAGE AC source simulator for next file write.
Causes run time error if string pointer is not valid pointer, or if file
name will not be a valid UNIX file name, (for example, contains
nonprinting or shell-reserved characters).
tl_sinxx_amp
Calculate sin x/x corrected amplitude.
IMAGE Solutions V8.3 26-387
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS double tl_sinxx_amp(freq, clock, amp)
double freq;
int clock;
double amp;
DESCRIPTION Calculates sin x/x corrected amplitude. Given the signal
fundamental frequency, the A(n) clock number, and the desired
amplitude, this function returns the amplitude that must be
programmed to get the desired amplitude.
For the Precision AC Subsystem (PACS), this function uses the
frequency for the analog clock in cage #1.
ARGUMENTS freq—The signal fundamental frequency
clock—Integer 0, 1, 2, or 3 to indicate which An clock is being
used
amp—The desired amplitude
RETURN VALUE The amplitude to be programmed
tl_site
Global variable indicating current site number.
SYNOPSIS int tl_site;
DESCRIPTION This global integer variable indicates which site is currently being
tested in a multisite test program inside a serial block. tl_site
takes on the value of each active site, one at a time. Sites are
numbered 0, 1, 2, and so on. When outside a serial block in a
multisite test program, tl_site normally has the value
TL_SITES_ALL. tl_site may also take on the value
TL_SITES_NONE. This means that the site has failed and testing
is no longer taking place on that site. In a nonmultisite test
program tl_site only takes on the values 0 and
TL_SITES_NONE.
The value of tl_site can be interrogated in test programs, but
should never be modified directly. Instead, use the sites
command to specify the active sites. In a test program, the
following language statements can be used to influence the
value of tl_site: serial, set site_enable, and set
site_disable.
tl_site_active
Determine if sites are still qualified.
SYNOPSIS int tl_site_active();
DESCRIPTION Use this function to determine whether or not testing has
stopped on a site by the site being disqualified. In a nonmultisite
IMAGE Solutions V8.3 26-388
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
test program, the function returns FALSE if testing has stopped
because the part failed in stop_on_fail mode. If testing has not
stopped, the function returns TRUE.
In a multisite test program, this function returns information on
one site, the site specified by tl_site, if called from inside a
serial block. If called from outside a serial block, the function
returns FALSE only if testing has stopped on all sites.
ARGUMENTS None
RETURN VALUE TRUE if site specified by tl_site is still active. FALSE otherwise.
tl_site_shutdown
Call user function when site fails.
SYNOPSIS void tl_site_shutdown()
DESCRIPTION If this function exists in a test program, any statements located in
the body of the function are executed after a device fails, or at
the end of the test program for a passing device. In a multisite
test program, it is called once for each site.
This function is especially useful in a multisite test program. If
one site fails, it is not programmed by subsequent set
statements. Problems may still occur, however. If the device is
shorted, for example, it may be heating up the wafer or drawing
current on a common supply channel. Using
tl_site_shutdown() when a site fails to specify that certain
resources to that site are to be shut down, can avoid this
problem.
tl_site_shutdown() is called immediately after a site failure or
whenever set site_disable is called. It does not wait for
completion of a serial loop. It is also called immediately after a
test program has finished running to shut down any remaining
active sites, being called once per site. Within
tl_site_shutdown(), tl_site is equal to the specific site
being shut down.
ARGUMENTS None
RETURN VALUE None
tl_smem_read_wave_sample_max
Return the wave sample size maximum.
SYNOPSIS int tl_smem_read_wave_sample_max()
IMAGE Solutions V8.3 26-389
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Returns the maximum sample size which can be displayed by
the Wave Display.
ARGUMENTS None
RETURN VALUE The maximum sample size which can be displayed by the Wave
Display.
tl_smem_set_wave_sample_max
Set the wave sample size maximum
SYNOPSIS int tl_smem_set_wave_sample_max(new_sample_size)
int new_sample_size;
DESCRIPTION Programs the maximum sample size to be displayed by the
Wave Display as specified by new_sample_size. The default
sample size is 100 * 1024 samples.
ARGUMENTS new_sample_size—The new sample size to be displayed.
RETURN VALUE None
tl_sps_ammeter_connect
Set the HVA connect bit.
SYNOPSIS tl_sps_ammeter_connect(unit,connect)
int unit, connect;
DESCRIPTION Sets the HVA connect bit.
ARGUMENTS unit—Instrument number
connect 0—Disconnect the ammeter
connect 1—Connect the ammeter
RETURN VALUE None
tl_sps_ammeter_disable_alarm
Disable the selected SPS alarm.
SYNOPSIS tl_sps_ammeter_disable_alarm(unit, alarm)
int unit, alarm;
DESCRIPTION Disables the selected Synchronized Power Subsystem alarm.
ARGUMENTS unit—The instrument number
alarm—1 = Over range, 2 = Guard
RETURN VALUE None
IMAGE Solutions V8.3 26-390
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_sps_ammeter_enable_alarm
Enable the selected SPS alarm.
SYNOPSIS tl_sps_ammeter_enable_alarm(unit,alarm)
int unit, alarm;
DESCRIPTION Enables the selected Synchronized Power Subsystem alarm.
ARGUMENTS unit—The instrument number
alarm—1 = Over range, 2 = Guard
RETURN VALUE None
tl_sps_ammeter_reset
Resets the HVA.
SYNOPSIS tl_sps_ammeter_reset(unit)
int unit;
DESCRIPTION Sets the High Voltage Ammeter (HVA) clear bit.
ARGUMENTS unit—The instrument number.
RETURN VALUE None
tl_sps_discon_meter_input
Disconnect SPS from meter input.
SYNOPSIS tl_sps_discon_meter_input()
DESCRIPTION Disconnects the Synchronized Power Subsystem by setting the
gate enable bit off the HPVCC.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_gateoff
Set the SPS gate enable bit off.
SYNOPSIS tl_sps_gateoff()
DESCRIPTION Sets the SPS gate enable bit off Terabus.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_gateon
Set the SPS gate enable bit.
IMAGE Solutions V8.3 26-391
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS tl_sps_gateon()
DESCRIPTION Sets the SPS gate enable bit on Terabus.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_get_amm_cal_stat
Return the HVA calibration status.
SYNOPSIS tl_sps_get_amm_cal_stat(unit)
int unit;
DESCRIPTION Return the High Voltage Ammeter (HVA) calibration status.
ARGUMENTS unit—Instrument number
RETURN VALUE 0—calibration is uncalibrated
1—calibration successful
-1—failed
tl_sps_get_amm_cal_time
Return HVA calibration time.
SYNOPSIS tl_sps_get_amm_cal_time(unit)
int unit;
DESCRIPTION Returns the last HVA calibration time.
ARGUMENTS unit—Instrument number
RETURN VALUE Returns time if calibrated, 0 if not
tl_sps_get_fvs_status
Get FVS alarm status.
SYNOPSIS int tl_sps_get_fvs_status(unit)
int unit;
DESCRIPTION Returns the alarm status of the specified FVS.
ARGUMENTS unit—FVS unit number (0 based). Unit number = instrument
number - 1. So, to get the alarm status of FVS 1, unit should be 0.
RETURN VALUE 0 if FVS is ok. If the FVS is alarming, the return value is bit
encoded as:
1 overvoltage alarm
2 open loop
IMAGE Solutions V8.3 26-392
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_sps_get_hccs_status
Get HCCS alarm status.
SYNOPSIS int tl_sps_get_hccs_status(unit)
int unit;
DESCRIPTION Returns the alarm status of specified HCCS.
ARGUMENTS unit—HCCS unit number (0 based). Unit number = instrument
number - 1. So, to get the alarm status of HCCS 1, unit should
be 0.
RETURN VALUE 0 if HCCS is ok. If the HCCS is alarming, the return value is bit
encoded as:
0x1 open Kelvin
0x2 limit alarm
0x4 dead
0x8 open loop
0x10 sense overload
0x20 heat sync
0x40 relay switch
0x80 junction
0x100 overvoltage
tl_sps_get_hcvs_status
Get HCVS alarm status.
SYNOPSIS int tl_sps_get_hcvs_status(unit)
int unit;
DESCRIPTION Returns the alarm status of the specified HCVS.
ARGUMENTS unit—HCVS unit number (0 based). Unit number = instrument
number - 1. So, to get the alarm status of HCVS 1, unit should
be 0.
RETURN VALUE 0 if HCVS is OK. If the HCVS is alarming, the return value is bit
encoded as:
0x1 open Kelvin
0x2 overload
0x4 dead
0x8 open loop
0x10 sense overload
0x20 heat sync
0x40 relay switch
0x80 junction
0x100 overvoltage
IMAGE Solutions V8.3 26-393
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_sps_get_hpvi_status
Get HPVI alarm status.
SYNOPSIS int tl_sps_get_hpvi_status(unit)
int unit;
DESCRIPTION Returns the alarm status of specified HPVI.
ARGUMENTS unit—HPVI unit number (0 based). Unit number = instrument
number - 1. So, to get the alarm status of HPVI 1, unit should be
0.
RETURN VALUE 0 if HPVI is ok. If the HPVI is alarming, the return value is bit
encoded as:
0x1 open loop 1
0x2 open loop 2
0x4 overload 1
0x8 overload 2
0x10 open Kelvin
0x20 heat sync 1
0x40 relay switch
0x80 junction 1
0x100 junction 2
tl_sps_get_hvs_status
Get HVS alarm status.
SYNOPSIS int tl_sps_get_hvs_status(unit)
int unit;
DESCRIPTION Returns the alarm status of specified HVS.
ARGUMENTS unit—HVS unit number (0 based). Unit number = instrument
number - 1. So, to get the alarm status of HVS 1, unit should be
0.
RETURN VALUE 0 if HVS is OK. If the HVS is alarming, the return value is bit
encoded as:
1 open loop
2 I/V mode
4 heat sync
tl_sps_hccs_comp
Set HCCS compensation.
SYNOPSIS tl_sps_hccs_comp(unit,hilow)
int unit, hilow;
IMAGE Solutions V8.3 26-394
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Sets HCCS compensation to slow or fast.
ARGUMENTS unit—Instrument number
hilow—1 sets to slow comp
0 sets to fast comp
RETURN VALUE None
tl_sps_hccs_connect
Connect the HCCS to the DUT.
SYNOPSIS tl_sps_hccs_connect(unit)
int unit;
DESCRIPTION Connects the High Current Current Source to the DUT.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_hccs_disconnect
Disconnect the HCCS from the DUT.
SYNOPSIS tl_sps_hccs_disconnect(unit)
int unit;
DESCRIPTION Disconnects the High Current Current Source from the DUT.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_hcvs_comp
Set HCVS compensation.
SYNOPSIS tl_sps_hcvs_comp(unit,hilow)
int unit, hilow;
DESCRIPTION Sets HCVS compensation to slow or fast.
ARGUMENTS unit—Instrument number
hilow—1 sets to slow comp
0 sets to fast comp
RETURN VALUE None
tl_sps_hcvs_connect
Connect the HCVS to the DUT.
IMAGE Solutions V8.3 26-395
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS tl_sps_hcvs_connect(unit)
int unit;
DESCRIPTION Connects the High Current Voltage Source to the DUT.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_hcvs_disconnect
Disconnect the HCVS from the DUT.
SYNOPSIS tl_sps_hcvs_disconnect(unit)
int unit;
DESCRIPTION Disconnects the High Current Voltage Source from the DUT.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_hpvcc_alarm_clear
Sets HPVI alarm clear bit.
SYNOPSIS tl_sps_hpvcc_alarm_clear(unit)
int unit;
DESCRIPTION Sets the HPVCC alarm_clear bit.
ARGUMENTS unit—The instrument number
RETURN VALUE None
tl_sps_hpvcc_connect
Connect the HPVCC to the DUT.
SYNOPSIS tl_sps_hpvcc_connect(unit)
int unit;
DESCRIPTION Connects the High Power V/I Source to the DUT.
ARGUMENTS unit—Instrument number.
RETURN VALUE None
tl_sps_hpvcc_connect_bvcs
Optimized connect from the HPVCC to the BVCS.
SYNOPSIS tl_sps_hpvcc_connect_bvcs(unit)
int unit;
IMAGE Solutions V8.3 26-396
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Connects the HPVCC to the Breakdown Voltage Current Source.
ARGUMENTS unit—Instrument number.
RETURN VALUE None
tl_sps_hpvcc_disconnect
Disconnect the HPVCC from the DUT.
SYNOPSIS tl_sps_hpvcc_disconnect(unit)
int unit;
DESCRIPTION Disconnects the High Power V/I Source from the DUT.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_hpvcc_gateoff
Set the HPVCC gate enable bit off.
SYNOPSIS tl_sps_hpvcc_gateoff(unit)
int unit;
DESCRIPTION Sets the High Power V/I Source gate enable bit off.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_hpvcc_gateon
Set the HPVCC gate enable bit on.
SYNOPSIS tl_sps_hpvcc_gateon(unit)
int unit;
DESCRIPTION Sets the High Power V/I Source gate enable bit on.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_hpvcc_reset
Reset the HPVI.
SYNOPSIS tl_sps_hpvcc_reset(unit)
int unit;
DESCRIPTION Sets the HPVCC clear bit.
ARGUMENTS unit—The instrument number
IMAGE Solutions V8.3 26-397
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
tl_sps_hpvi_comp
Set HPVI compensation.
SYNOPSIS tl_sps_hpvi_comp(unit,hilow)
int unit, hilow;
DESCRIPTION Sets HPVI compensation to slow or fast.
ARGUMENTS unit—The instrument number
hilow—1 sets to slow comp
0 to fast comp
RETURN VALUE None
tl_sps_hvs_connect
Connect the HVS to the DUT.
SYNOPSIS tl_sps_hvs_connect(unit)
int unit;
DESCRIPTION Connects the High Voltage Source to the DUT.
ARGUMENTS unit—Instrument number.
RETURN VALUE None
tl_sps_hvs_disconnect
Disconnect the HVS from the DUT.
SYNOPSIS tl_sps_hvs_disconnect(unit)
int unit;
DESCRIPTION Disconnects the High Voltage Source from the DUT.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_reset
Reset all Synchronized Power Subsystem instruments.
SYNOPSIS tl_sps_reset(rtype)
register int rtype;
DESCRIPTION This is a compiler callable function which calls the Synchronized
Power Subsystem reset function.
ARGUMENTS rtype—DRVRST_PREJOB, DRVRST_POSTJOB, DRVRST_POWERUP
IMAGE Solutions V8.3 26-398
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
tl_sps_set_ammeter
Set up the HVA.
SYNOPSIS tl_sps_set_ammeter(unit,himux,lomux, range)
int unit,himux,lomux,range;
DESCRIPTION Sets up the SPS High Voltage Ammeter.
ARGUMENTS unit—Instrument number
himux
lomux
range
RETURN VALUE None
tl_sps_set_hpvcc
Set the HPVCC voltage and current.
SYNOPSIS tl_sps_set_hpvcc(unit,von,voff,ion,ioff,vrng,irng)
int unit;
double von, voff, ion, ioff, vrng, irng;
DESCRIPTION Sets voltage and current on the High Power V/I Source.
ARGUMENTS unit—Instrument number
RETURN VALUE None
tl_sps_testfor_safety
Read the safety bit.
SYNOPSIS int tl_sps_testfor_safety()
DESCRIPTION Reads the safety bit from the Terabus.
ARGUMENTS None
RETURN VALUE 1 if safe
tl_statmon_memo
Write a memo string to the station monitor window.
SYNOPSIS int tl_statmon_memo(s)
char *s;
DESCRIPTION This function writes a string to the memo field of the station
monitor window if the window is up. If the window is not currently
on the screen, the function returns a -1. Note that the memo field
IMAGE Solutions V8.3 26-399
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
in the station monitor window must be enabled for this call to
work. See “The Station Monitor” on page 8-49.
This function causes communications with the system computer.
Do not use it indiscriminately in throughput-sensitive
applications because it introduces delays. Example:
{
set_handler_temp(temp);
handler_at_temp = FALSE;
while (handler_not_at_temp)
{
sleep(10);
tl_statmon_memo("Waiting for handler to reach
Temp.");
if (get_handler_temp() == temp) handler_at_temp=
TRUE;
}
/* Clear the message, and continue */
tl_statmon_memo("");
}
ARGUMENTS s—String to write to station monitor memo field
RETURN VALUE 0—Memo write to station monitor was successful
-1—Write failed or no station monitor running
SIDE EFFECTS Updates the station monitor.
tl_system
Execute system command from inside a test program.
SYNOPSIS tl_system(command)
char * command;
DESCRIPTION The function allows a system command to be called from inside
a test program. It causes execution of the command as if you
typed the command directly at the terminal associated with this
test program. The command line is issued immediately and test
program execution continues. Execution of the system
command times out after 20 seconds. Example:
tl_system("wave");
This brings up a Wave Display from inside the test program. If
the Wave Display does not start up in 20 seconds, an error is
generated and the attempt to start the Wave Display is aborted.
Do not use this function with commands that require user input
from the keyboard. This causes IMAGE to lock up. For example,
do not use the command
tl_system ("rm -i *.tmp")
IMAGE Solutions V8.3 26-400
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS command—String defining system command to be executed.
RETURN VALUE None
SEE ALSO “tl_system_timeout”
tl_system_timeout
Execute system command from inside a test program.
SYNOPSIS tl_system_timeout(command, timeout)
char * command;
int timeout
DESCRIPTION The function allows a system command to be called from inside
a test program. This function causes execution of the command
as if you typed the command directly at the terminal associated
with this test program. The command line is issued immediately
and test program execution continues. For example:
tl_system_timeout("wave", 20);
This will bring up the Wave Display from inside the test program.
ARGUMENTS command—String defining system command to be executed.
timeout—The system command times out at the time specified.
The range is 0 to 2,147,483,647 seconds. If the timeout is set to
0, the system command will not timeout.
RETURN VALUE None
tl_tach_trg_ctrl
Connect the TACH trigger bus to the TSY.
SYNOPSIS tl_tach_trg_ctrl (trg, action)
int trg;
int action;
DESCRIPTION Connect the specified trigger bus in the test head to the trigger
switchyard (TSY) in the mainframe. Trigger buses are numbered
from 0 to (n-1) for internal code and from 1 to n for the TLP
syntax. So you must program trigger bus <n> in the set trigger
syntax and <n-1> in tl_tach_trg_ctrl() function.
ARGUMENTS trg—Trigger to be affected (zero based) [0..7]
action—44 (decimal value indicating TACH TRIGGER TO TSY)
RETURN VALUE None
SEE ALSO “tl_tsy_trg_ctrl”
IMAGE Solutions V8.3 26-401
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_tba_read_timer
Use the Terabus timer to time something.
SYNOPSIS unsigned tl_tba_read_timer(v)
unsigned v;
DESCRIPTION This function reads the timer of the Terabus adapter and returns
the difference between this value and the 32 bit value passed as
a parameter. Only works on a test system; always returns zero
on the simulator.
An example which times execution of some code would be:
unsigned tl;
extern unsigned tl_tba_read_timer();
tl = tl_tba_read_timer(0);
.
. /*code to time goes here*/
.
fprintf(stderr,"Elasped time in microseconds: %u\n",
tl_tba_read_timer(t1));
ARGUMENTS v—Number to subtract from reading to give difference in time.
RETURN VALUE Current timer reading minus v.
tl_tbase_addr
Get pointer to word of Terabus space.
SYNOPSIS tl_tbase_addr(addr)
int addr;
DESCRIPTION This function returns the virtual address of a Terabus location.
Do not reference the return value directly. It can be passed to
tl_ptr_r() or tl_ptr_w().
ARGUMENTS addr—Location in Terabus space to get pointer to. addr of 0
returns old tl_tbase.
RETURN VALUE Virtual address requested.
SEE ALSO “tl_ptr_r”, “tl_ptr_w”
tl_tdef_remaining
Get number of test statements left.
SYNOPSIS int tl_tdef_remaining()
DESCRIPTION Gets number of test statements remaining for the current TESTF
function (for compound seq line). Must be called from within a
test function (TESTF). Causes a run time error otherwise.
IMAGE Solutions V8.3 26-402
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS None
RETURN VALUE Number of test statements remaining, or negative number on
error.
SIDE EFFECTS Calls tl_error() when called from outside a TESTF function
and returns -1.
tl_testfor_safety
Determine if tester safety signal is asserted.
SYNOPSIS tl_testfor_safety();
DESCRIPTION This function checks if the safety signal is asserted in the tester.
Operation without it represents an unsafe condition where an
operator could be exposed to dangerous voltages at the test
head.
ARGUMENTS None
RETURN VALUE 1 safety on
0 safety not asserted
tl_tj306_delta_drives_wave
Set delta bus to drive AABUS II wave bus.
SYNOPSIS tl_tj306_delta_drives_wave(value)
int value;
DESCRIPTION This function is used to program the connection between the
AABUS II wave bus and the delta bus. delta bus drives AABUS
II wave bus.
ARGUMENTS value 0, AABUS II wave bus is disconnected from delta
bus
1, delta bus drives AABUS II wave bus
RETURN VALUE int value
SIDE EFFECTS Possibly changes relay state and programs Terabus settle timer.
tl_tj306_wave_drives_delta
Set AABUS II wave bus to drive the delta bus.
SYNOPSIS tl_tj306_aabus2_delta(value)
int value;
DESCRIPTION This function is used to program the connection between the
AABUS II wave bus and the delta bus. AABUS II wave bus drives
delta bus.
IMAGE Solutions V8.3 26-403
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS value—0 AABUS II wave bus is disconnected from delta bus
1 AABUS II wave bus drives delta bus
RETURN VALUE int value
SIDE EFFECTS Possibly changes relay state and programs Terabus settle timer.
tl_tja_calc_avg_clock
Calculate clock period based on event list.
SYNOPSIS double tl_tja_calc_avg_clock(stamp_array,
stamp_array_size, expected_period)
double stamp_array[];
int stamp_array_size;
double expected_period;
DESCRIPTION Calculate the average clock period based on events in the list. It
is assumed that the captured events are synchronized to an
underlying clock signal. This function returns the period of that
underlying clock signal.
The events in the list may not be periodic. For example, even if
the input signal to the capture instrument is periodic, the period
may be such that the instrument capture teeters between
capturing every second and every third event. Another example
is a data signal which, while synchronized to an underlying clock,
is not periodic itself.
Because the events in the list may not be periodic, Texp (the
expected period of the underlying clock) is used to fill in the
blanks in the event list. It is assumed that captured events are
separated from the underlying clock tick by no more than one
half the expected period of the underlying clock.
ARGUMENTS stamp_array—The list of time stamps for which to calculate the
underlying clock period. [ptr to an array of doubles]
stamp_array_size—The number of elements in the list. [0, 1,
2...]
expected_period—Specifies the expected period of the
underlying clock in seconds. This value is required in order to
analyze 1) events that occur too close together for the TJA to
capture every event, and 2) events that are not periodic. [The
period in seconds.]
RETURN VALUE The calculated period of the underlying clock. [The period in
seconds]
IMAGE Solutions V8.3 26-404
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_tja_calc_deviations
Calculate event deviations from underlying clock.
SYNOPSIS int tl_tja_calc_deviations(deviation_array,
stamp_array, num_events, clock_period)
double deviation_array[];
double stamp_array[];
int num_events;
double clock_period;
DESCRIPTION Calculate the list of deviations between events in a list and the
underlying clock. Events are assumed to occur synchronous to
an underlying clock. This function calculates how much each
event deviates from that underlying clock. A negative deviation
means the event occurred early, and a positive deviation means
the event occurred late.
An event may not be captured for every tick of the clock.
Therefore, it is assumed that captured events are separated
from the underlying clock tick by no more than one half the period
of the underlying clock.
ARGUMENTS deviation_array—The destination to return the deviations. [ptr
to an array of doubles large enough to hold the number of
deviations to be calculated]
stamp_array—The list of time stamps from which to calculate
the deviations. [ptr to an array of doubles]
num_events—The number of deviations to calculate. [0 to the
number of time stamps in the event list]
clock_period—The period of the underlying clock in seconds.
[The period in seconds]
RETURN VALUE The number of calculated deviations.
tl_tja_calc_intervals
Calculate the event intervals between the 2 lists.
SYNOPSIS int tl_tja_calc_intervals(num_intervals,
interval_array, from_array, to_array)
int num_intervals;
double interval_array[];
double from_array[];
double to_array[];
DESCRIPTION Calculate the intervals between events in the from_array and
events in the to_array. The results are returned in the
interval_array. Each interval is the difference defined as
interval[i] = to[i] - from[i].
IMAGE Solutions V8.3 26-405
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS num_intervals—The number of intervals to calculate. [0 to the
number of time stamps in each of the from and to lists]
interval_array—The destination to return the intervals
(pointer to an array of doubles large enough to hold the number
of intervals to be calculated)
from_array—The list of beginning times from which to calculate
the intervals. [ptr to an array of doubles]
to_array—The list of ending times from which to calculate the
intervals (pointer to an array of doubles)
RETURN VALUE The number of intervals calculated. (0 to the number of time
stamps in each of the from and to lists)
tl_tja_calc_max
Calculate the maximum of the list of numbers.
SYNOPSIS double tl_tja_calc_max(list, list_size)
double list[];
int list_size;
DESCRIPTION Calculate the maximum of the list of double precision floating
point numbers.
ARGUMENTS list—The list of double precision floating point numbers for
which to calculate the maximum. (pointer to an array of doubles)
list_size—The number of elements in the list [0, 1, 2...]
RETURN VALUE The maximum of the list of numbers (a double)
tl_tja_calc_mean
Calculate the mean of the list of numbers.
SYNOPSIS double tl_tja_calc_mean(list, list_size)
double list[];
int list_size;
DESCRIPTION Calculate the mean of the list of double precision floating point
numbers.
ARGUMENTS list—The list of double precision floating point numbers for
which to calculate the mean. [ptr to an array of doubles]
list_size—The number of elements in the list [0, 1, 2...]
RETURN VALUE The mean of the list of numbers (a double)
IMAGE Solutions V8.3 26-406
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_tja_calc_min
Calculate the minimum of the list of numbers.
SYNOPSIS double tl_tja_calc_min(list, list_size)
double list[];
int list_size;
DESCRIPTION Calculate the minimum of the list of double precision floating
point numbers.
ARGUMENTS list—The list of double precision floating point numbers for
which to calculate the minimum (pointer to an array of doubles)
list_size—The number of elements in the list [0, 1, 2...]
RETURN VALUE The minimum of the list of numbers (a double)
tl_tja_calc_periods
Calculate the periods between event pairs.
SYNOPSIS int tl_tja_calc_periods (num_periods, period_array,
stamp_array)
int num_periods;
double period_array[];
double stamp_array[];
DESCRIPTION Calculate the period between each pair of time stamps in the
stamp_array. The results are returned in the period_array.
Each period is the difference defined as period[i] = event[i+1] -
event[i]. Note that to calculate N periods, there must be at least
N+1 events in the stamp_array.
ARGUMENTS num_periods—The number of periods to calculate (0 to one less
than the number of time stamps in the event list)
period_array—The destination to return the periods (pointer to
an array of doubles large enough to hold the number of periods
to be calculated)
stamp_array—The list of time stamps from which to calculate
the periods (pointer to an array of doubles)
RETURN VALUE The number of periods calculated (0 to the number of time
stamps in each of the from and to lists)
tl_tja_calc_pkpk
Calculate the peak to peak of the list of numbers.
IMAGE Solutions V8.3 26-407
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS double tl_tja_calc_pkpk(list, list_size)
double list[];
int list_size;
DESCRIPTION Calculate the peak to peak value of the list of double precision
floating point numbers. The peak to peak value is the difference
between the maximum and the minimum values.
ARGUMENTS list—The list of double precision floating point numbers for
which to calculate the peak to peak value (pointer to an array of
doubles)
list_size—The number of elements in the list [0, 1, 2...]
RETURN VALUE The peak to peak value of the list of numbers (a double)
tl_tja_calc_std_dev
Calculate the standard deviation of the numbers.
SYNOPSIS double tl_tja_calc_std_dev(list, list_size)
double list[];
int list_size;
DESCRIPTION Calculate the standard deviation of the list of double precision
floating point numbers. Standard deviation is defined as:
std_dev = (sum((x[i]-m)**2) / (n-1))**(1/2),
where:
n Is the number of elements in the list,
x[i] Is the i’th element in the list,
sum(exp) Calculate the sum of exp for i=0 to n-1,
m Is the arithmetic mean of the list of numbers, and
** Is the operator that means raised to the power of.
ARGUMENTS list—The list of double precision floating point numbers for
which to calculate the standard deviation. [ptr to an array of
doubles]
list_size—The number of elements in the list. [0, 1, 2...]
RETURN VALUE The standard deviation of the list of numbers. [a double]
tl_tja_move_raw_data_to_darray
Moves the uncalibrated data into a DARRAY without the use of compute blocks.
SYNOPSIS void tl_tja_move_raw_data_to_darray(raw_data)
DARRAY raw_data;
DESCRIPTION This routine does the error checking and moving for a TJA
measurement without using compute blocks and the move
IMAGE Solutions V8.3 26-408
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
scheduler. This function is provided to support the TJA in a
multisite environment when only one TJA in the system is
present — the user will put this function inside a serial block and
perform one measurement at a time.
ARGUMENTS raw_data — The darray and the data is to be moved into
RETURN VALUE None
tl_tja_num_stamps_captured
Return number of stamps captured.
SYNOPSIS tl_tja_num_stamps_captured(raw_data, stamper)
DARRAY raw_data;
int stamper;
DESCRIPTION Given a DARRAY and a stamper, this function returns the
number of timestamps that were captured in the specified
stamper.
NOTE
Call this function only from within a compute block.
ARGUMENTS DARRAY raw_data—Darray handle
int stamper—Time stamper to move data from (1 = Stamper 1,
2 = Stamper 2)
RETURN VALUE Returns number of timestamps captured by TJA. Returns 0 if
there is an error or if run on a simulator.
tl_tja_read_duty_cycle
Compute the duty cycle from a DARRAY.
SYNOPSIS double tl_tja_read_duty_cycle(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the average duty cycle
value. Use this function only in duty cycle measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
RETURN VALUE Returns the duty cycle as a ratio.
tl_tja_read_duty_cycle_array
Compute the array of duty cycles from a DARRAY.
IMAGE Solutions V8.3 26-409
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS void tl_tja_read_duty_cycle_array(raw_data, array)
DARRAY raw_data;
double array[];
int array_size;
DESCRIPTION Given a DARRAY, this function calculates the duty cycles from
the data in the DARRAY. This duty cycles are placed in an array.
Use this function only with duty cycle measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
double array[]—Array that contains the values
int array_size—Size of the array
RETURN VALUE None
tl_tja_read_event_count
Read event_count value from DARRAY.
SYNOPSIS tl_tja_read_event_count(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the event count value.
This is equal to the number of timestamps that were captured in
stamper A while a gate_input signal was high or low.
NOTE
Call this function only from within a compute block.
ARGUMENTS DARRAY raw_data—Darray handle
RETURN VALUE Returns number of timestamps captured by TJA. Returns 0 if an
error occurs or if run on a simulator.
tl_tja_read_frequency
Read frequency val from DARRAY.
SYNOPSIS double tl_tja_read_frequency(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the frequency value. This
is calculated from the following formulas:
Note that “# samples” equals the number of timestamps actually
taken, while “# events” is the number of periods used to calculate
the frequency.
holdoff counter automatically set to max value (255 = 0xFF
IMAGE Solutions V8.3 26-410
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
# events = (1 million)/(accuracy)
# samples = [(# events) / (256)] + 1 and rounded up to the next
whole #
frequency = (# events) / (total_test_time)
= [(# samples -1) * 256] / (last timestamp - first
timestamp)
NOTE
Call this function only from within a compute block.
ARGUMENTS DARRAY raw_data—Darray handle
RETURN VALUE Returns the frequency in Hz.
SIDE EFFECT Calls tl_tja_read_timestamps().
tl_tja_read_period
Compute the period value from a DARRAY.
SYNOPSIS double tl_tja_read_period(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the average period value.
Use this function only with period measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
RETURN VALUE Returns the period in seconds.
tl_tja_read_period_array
Compute the array of periods from a DARRAY.
SYNOPSIS void tl_tja_read_period_array(raw_data, array,
array_size)
DARRAY raw_data;
double array[];
int array_size;
DESCRIPTION Given a DARRAY, this function calculates the periods from the
data in the DARRAY. This periods are placed in an array. Use this
function only with period measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
double array []—Array that contains the values
int array_size—Size of the array
RETURN VALUE None.
IMAGE Solutions V8.3 26-411
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_tja_read_pin_to_pin_delay
Compute the pin-to-pin delay from a DARRAY
SYNOPSIS double tl_tja_read_pin_to_pin_delay(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the average pin-to-pin
delay value. Use this function only in pin-to-pin delay
measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
RETURN VALUE Returns the pin-to-pin delay in seconds.
tl_tja_read_pin_to_pin_delay_array
Compute the array of pin-to-pin delays from a DARRAY.
SYNOPSIS void tl_tja_read_pin_to_pin_delay_array(raw_data,
array)
DARRAY raw_data;
double array[];
int array_size;
DESCRIPTION Given a DARRAY, this function calculates the pin-to-pin delay
from the data in the DARRAY. This pin-to-pin delay are placed in
an array. Use this function only with pin-to-pin delay
measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
double array[]—Array that contains the values
int array_size—Size of the array
RETURN VALUE None.
tl_tja_read_pulse_width
Compute the pulse width from a DARRAY.
SYNOPSIS double tl_tja_read_pulse_width(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the average pulse width
value. Use this function only with pulse width measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
RETURN VALUE Returns the pulse width in seconds.
tl_tja_read_pulse_width_array
Compute the array of pulse widths from a DARRAY.
IMAGE Solutions V8.3 26-412
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS void tl_tja_read_pulse_width_array(raw_data, array)
DARRAY raw_data;
double array[];
int array_size;
DESCRIPTION Given a DARRAY, this function calculates the pulse widths from
the data in the DARRAY. This pulse widths are placed in an array.
Use this function only with pulse width measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
double array[]—Array that contains the values
int array_size—Size of the array
RETURN VALUE None
tl_tja_read_ratio_count
Read ratio_count value from DARRAY.
SYNOPSIS tl_tja_read_ratio_count(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the ratio count value. This
is the ratio of the number of timestamps captured by A to the
number of timestamps captured by B. (The B number should
equal the “count value” parameter defined in the software data
structure.)
NOTE
Call this function only from within a compute block.
ARGUMENTS DARRAY raw_data—Darray handle
RETURN VALUE Returns ratio of timestamps captured by TJA (stamper
A/stamper B) if successful. Return 0.0 if there is an error or on a
simulator.
tl_tja_read_rise_or_fall_time
Compute the rise-or-fall time from a DARRAY
SYNOPSIS double tl_tja_read_rise_or_fall_time(raw_data)
DARRAY raw_data;
DESCRIPTION Given a DARRAY, this function returns the average rise or fall
time value. Use this function only in rise or fall time
measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
IMAGE Solutions V8.3 26-413
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Returns the rise-or-fall time in seconds.
tl_tja_read_rise_or_fall_time_array
Compute the array of rise-or-fall times from a DARRAY.
SYNOPSIS void tl_tja_read_rise_or_fall_time_array(raw_data,
array)
DARRAY raw_data;
double array[];
int array_size;
DESCRIPTION Given a DARRAY, this function calculates the rise-or-fall time
from the data in the DARRAY. This duty cycles are placed in an
array. Use this function only with rise or fall time measurements.
ARGUMENTS DARRAY raw_data—DARRAY handle
double array[]—Array that contains the values
int array_size—Size of the array
RETURN VALUE None
tl_tja_read_status
Return the status of last capture.
SYNOPSIS int tl_tja_read_status (meas_index)
char meas_index;
DESCRIPTION Returns the status of the last TJA capture. On a simulated
system always returns that the capture completed.
ARGUMENTS meas_index—Index of measurement.
RETURN VALUE Returns NULL if the function cannot complete. Otherwise, it
returns an error number listed in table 26-10:
Table 26-10. tl_tja_read_status Return Values and Their Meanings
Value Value Meaning
14217 TJA_STATUS_MEAS_COMPLETE capture completed
14218 TJA_STATUS_A_MEAS_NOT_STARTED A did not start
14219 TJA_STATUS_A_MEAS_NOT_COMPLETED A did not finish
14220 TJA_STATUS_B_MEAS_NOT_STARTED B did not start
14221 TJA_STATUS_B_MEAS_NOT_COMPLETED B did not finish
14222 TJA_STATUS_AB_MEAS_NOT_STARTED A and B did not start
IMAGE Solutions V8.3 26-414
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Table 26-10. tl_tja_read_status Return Values and Their Meanings (Continued)
Value Value Meaning
14223 TJA_STATUS_AB_MEAS_NOT_COMPLETED A and B did not finish
14224 TJA_STATUS_MEAS_A_NOT_STARTED_B_NOT_COMPLETED A did not start, B did not finish
14225 TJA_STATUS_MEAS_B_NOT_STARTED_A_NOT_COMPLETED B did not start, A did not finish
14226 TJA_STATUS_NOT_ARMED cannot move data from TJA
until after arming TJA
The return values of the form TJA_STATUS_XXX are equal to TJA
error numbers as listed in the quick help. For example:
TJA_STATUS_MEAS_COMPLETE = 14217 = ERR_TJA_MEAS_COMPLETE
tl_tja_read_timestamps
Get the array of time stamps from a DARRAY.
SYNOPSIS void tl_tja_read_timestamps(darray_name,
stamp_array, offset, size, stamper)
DARRAY darray_name;
double *stamp_array;
int offset;
int size;
int stamper;
DESCRIPTION Given the DARRAY associated with a particular measurement,
calculates the associated time stamps and puts them in an array
pointed to by stamp_array.
Note: This function should only be called from within a compute
block.
ARGUMENTS darray_name—Contains raw data moved from the TJA.
stamp_array—Array of doubles containing time stamps.
offset—The offset of data.
size—The size of the data block to be read.
stamper—Which stamper to read from (1 or 2).
RETURN VALUE None
tl_tjd_calc_avg_clock
Calculate TJD clock period based on event list.
IMAGE Solutions V8.3 26-415
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS double tl_tjd_calc_avg_clock (list, list_size, Texp)
double list [];
int list_size;
double Texp;
DESCRIPTION Calculate the average Time-Jitter Digitizer (TJD) clock period
based on events in the list. It is assumed that the captured
events are synchronized to an underlying clock signal. This
function returns the period of that underlying clock signal.
Events in the list cannot be periodic. For example, even if the
input signal to the capture instrument is periodic, the period can
be such that the instrument capture teeters between capturing
every second and every third event. Another example is a data
signal which, while synchronized to an underlying clock, is not
periodic itself.
Because events in the list cannot be periodic, Texp (the
expected period of the underlying clock) is used to fill in the
blanks in the event list. It is assumed that captured events are
separated from the underlying clock tick by no more than one
half the expected period of the underlying clock.
ARGUMENTS list—The list of time stamps for which to calculate the
underlying clock period (pointer to an array of doubles)
list_size—The number of elements in the list (0, 1, 2...)
Texp—The expected period in seconds of the underlying clock.
This value is required to analyze: 1) events that occur too close
together for the TJD to capture every event, and 2) events that
are not periodic.
RETURN VALUE The calculated period of the underlying clock (the period in
seconds)
tl_tjd_calc_deviations
Calculate event deviations from the underlying TJD clock.
SYNOPSIS int tl_tjd_calc_deviations(deviation_list,
event_list, num_events, clock_period)
double deviation_list [];
double event_list [];
int num_events;
double clock_period;
DESCRIPTION Calculates the list of deviations between Time-Jitter Digitizer
(TJD) events in a list and the underlying clock. Events are
assumed to occur synchronous to an underlying clock. This
function calculates how much each event deviates from that
underlying clock. A negative deviation means the event occurred
early. A positive deviation means the event occurred late.
IMAGE Solutions V8.3 26-416
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
An event cannot be captured for every tick of the clock.
Therefore, it is assumed that captured events are separated
from the underlying clock tick by no more than one half the period
of the underlying clock.
ARGUMENTS deviation_list—The destination to return the deviations
(pointer to an array of doubles large enough to hold the number
of deviations to be calculated)
event_list—The list of time stamps from which to calculate the
deviations (pointer to an array of doubles)
num_events—The number of deviations to calculate. (0 to the
number of time stamps in the event list)
clock_period—The period of the underlying clock in seconds
RETURN VALUE The number of calculated deviations.
tl_tjd_calc_intervals
Calculate the TJD event intervals between the two lists.
SYNOPSIS int tl_tjd_calc_intervals(num_intervals,
interval_list, from_list, to_list)
int num_intervals;
double interval_list [];
double from_list [];
double to_list [];
DESCRIPTION Calculate the intervals between Time-Jitter Digitizer (TJD)
events in from_list and events in to_list. The results are
returned in interval_list. Each interval is the difference
defined as interval[i] = from[i] - to[i].
ARGUMENTS num_intervals—Number of intervals to calculate. (0 to the
number of time stamps in each of the from and to lists)
interval_list—Destination to return the intervals (pointer to
an array of doubles large enough to hold the number of intervals
to be calculated)
from_list—List of beginning times from which to calculate the
intervals (pointer to an array of doubles)
to_list—List of ending times from which to calculate the
intervals (pointer to an array of doubles)
RETURN VALUE The number of intervals calculated (0 to the number of time
stamps in each of the from and to lists)
tl_tjd_calc_max
Calculate the maximum of the list of TJD numbers.
IMAGE Solutions V8.3 26-417
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS double tl_tjd_calc_max(list, list_size)
double list [];
int list_size;
DESCRIPTION Calculate the maximum of the list of Time-Jitter Digitizer (TJD)
double precisions floating point numbers.
ARGUMENTS list—List of double precision floating point numbers for which
to calculate the maximum (pointer to an array of doubles)
list_size—Number of elements in the list (0, 1, 2...)
RETURN VALUE The maximum of the list of numbers
tl_tjd_calc_mean
Calculate the mean of the list of TJD numbers.
SYNOPSIS double tl_tjd_calc_mean(list, list_size)
double list [];
int list_size;
DESCRIPTION Calculate the mean of the list of Time-Jitter Digitizer (TJD)
double precisions floating point numbers.
ARGUMENTS list—List of double precision floating point numbers for which
to calculate the mean (pointer to an array of doubles)
list_size—Number of elements in the list (0, 1, 2...)
RETURN VALUE The mean of the list of numbers, a double.
tl_tjd_calc_min
Calculate the minimum of the list of TJD numbers.
SYNOPSIS double tl_tjd_calc_min(list, list_size)
double list [];
int list_size;
DESCRIPTION Calculate the minimum of the list of Time-Jitter Digitizer (TJD)
double precisions floating point numbers.
ARGUMENTS list—List of double precision floating point numbers for which
to calculate the minimum (pointer to an array of doubles)
list_size—Number of elements in the list (0, 1, 2...)
RETURN VALUE The minimum of the list of numbers (a double)
tl_tjd_calc_periods
Calculate the periods between TJD event pairs.
SYNOPSIS int tl_tjd_calc_periods(num_periods, period_list,
event_list)
IMAGE Solutions V8.3 26-418
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int num_periods;
double period_list [];
double event_list [];
DESCRIPTION Calculate the period between each pair of Time-Jitter Digitizer
(TJD) time stamps in event_list. The results are returned in
period_list. Each period is the difference defined as period[i]
= event[i+1] - event[i]. To calculate N periods, there must be at
least N+1 events in the event list.
ARGUMENTS num_periods—Number of periods to calculate (0 to one less
than the number of time stamps in the event list)
period_list—Destination to return the periods (pointer to an
array of doubles large enough to hold the number of periods to
be calculated)
event_list—List of time stamps from which to calculate the
periods (pointer to an array of doubles)
RETURN VALUE The number of periods calculated (0 to the number of time
stamps in each of the from and to lists)
tl_tjd_calc_pkpk
Calculate the peak-to-peak of the list of TJD numbers.
SYNOPSIS double tl_tjd_calc_pkpk(list, list_size)
double list [];
int list_size;
DESCRIPTION Calculate the peak-to-peak value of the list of Time-Jitter
Digitizer (TJD) double precisions floating point numbers. The
peak-to-peak value is the difference between the maximum and
the minimum values.
ARGUMENTS list—List of double precision floating point numbers for which
to calculate the peak-to-peak value (pointer to an array of
doubles)
list_size—Number of elements in the list (0, 1, 2...)
RETURN VALUE Peak-to-peak value of the list of numbers, a double.
tl_tjd_calc_std_dev
Calculate the standard deviation of the TJD numbers.
SYNOPSIS double tl_tjd_calc_std_dev(list, list_size)
double list [];
int list_size;
DESCRIPTION Calculate the standard deviation of the list of Time-Jitter Digitizer
(TJD) double precisions floating point numbers. Standard
deviation is defined as:
IMAGE Solutions V8.3 26-419
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
std_dev = (sum((x[i]-m)**2) / (n-1))**(1/2),
Where
n—The number of elements in the list,
x[i]—The i’th element in the list,
sum(exp)—Calculate the sum of exp for i=0 to n-1,
m—The arithmetic mean of the list of numbers
**—The operator that means raised to the power of
ARGUMENTS list—List of double precision floating point numbers for which
to calculate the standard deviation (pointer to an array of
doubles)
list_size—Number of elements in the list (0, 1, 2...)
RETURN VALUE Standard deviation of the list of numbers, a double.
tl_tms_cal_has_run
Status indicating whether TMS calibration ran.
SYNOPSIS unsigned tl_tms_cal_has_run()
DESCRIPTION This function returns a status indicating whether TMS calibration
ran since last call. This allows a test program to know that
autocal has been active and calibration has run. This is to allow
the program to reload tset and patterns only as needed.
ARGUMENTS None
RETURN VALUE FALSE = 0 = Calibration has not run since the last time this
function was called.
TRUE = 1 = Calibration has run since the last time this function
was called.
SIDE EFFECTS When called, this function resets its own status. This function
supports the digital tset reload.
This function will not work correctly on a tester using two
stations.
tl_tms_cal_set_interval
Set the Time Measurement Subsystem calibration interval.
SYNOPSIS tl_tms_cal_set_interval(interval)
time_t interval;
DESCRIPTION This function allows you to set the TMS autocalibration time
interval from a test program. The parameter is the time interval.
ARGUMENTS interval—Time interval in seconds
IMAGE Solutions V8.3 26-420
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Affects the time between required calibration. If set longer that
the default, this can allow the test system specifications to drift
outside expected limits.
tl_tsy_cpu_trg_clr
Clears the specified TSY trigger latches.
SYNOPSIS tl_tsy_cpu_trg_clr(mask)
unsigned mask;
DESCRIPTION Clears all TSY trigger latches specified by mask, where any
trigger is connected to the CPU wait function.
ARGUMENTS mask—(unsigned) The bits in mask correspond to trigger latches:
bit 0 (0x01) corresponds to trigger latch 1 for trigger line 1. Bit 7
(0x80) corresponds to trigger latch 8 for trigger line 8. A one in
the mask clears the corresponding trigger latch. A zero leaves
the corresponding trigger latch unchanged.
RETURN VALUE None
tl_tsy_trg_ctrl
Connect the mainframe trigger bus to test head.
SYNOPSIS tl_tsy_trg_ctrl(trg, src, head, tsy_bp, global)
int trg;
int src;
int head;
int tsy_bp;
int global;
DESCRIPTION Connect the specified trigger bus in the mainframe to the to the
test head (TACH). Enable this connection and calm the other two
connections (TSY backplane and TSY Global Bus).
Trigger buses are numbered from 0 to (n-1) for internal code and
from 1 to n for the TLP syntax. So you must program trigger bus
<n> in the set trigger syntax and <n-1> in
tl_tach_trg_ctrl() function.
ARGUMENTS trg—Trigger to be affected (zero based) [0..7]
src—11 [decimal value indicating TSY HEAD]
head—13 [decimal value indicating TSY ENABLE]
tsy_bp—28 [decimal value indicating TSY CALM]
global—28 [decimal value indicating TSY CALM]
RETURN VALUE None
IMAGE Solutions V8.3 26-421
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “tl_tach_trg_ctrl”
tl_turbo_apply_downconverter_compensation
Applies Turbo AC downconverter calibration compensations to signal spectrum
SYNOPSIS void tl_turbo_apply_downconverter_compensation(pin,
h_in, down_conv_freq, down_conv_if_freq,
down_conv_attenuator)
int pin;
DARRAY h_in;
double down_conv_freq;
double down_conv_if_freq;
int down_conv_attenuator;
DESCRIPTION This routine applies the Turbo AC downconverter calibration
compensations to the spectrum of a signal captured using the
Turbo AC capture channel. The compensation is applied in-
place to h_in, which can be either a power-spectrum or a
complex spectrum.
ARGUMENTS pin—A Turbo AC capture pin
h_in—The spectrum of the captured signal
down_conv_freq—The value of the parameter
wfcap: down_conversion_frequency
down_conv_if_freq—The value of the parameter
wfcap: down_conversion_if_frequency
down_conv_attenuator—TRUE if you specified
down_conversion_attenuator: on, FALSE if you specified
down_conversion_attenuator: bypass
RETURN VALUE None
tl_turbo_apply_downconverter_compensation_full
Applies full Turbo AC downconverter calibration compensations to signal spectrum
SYNOPSIS void tl_turbo_apply_downconverter_compensation_full
(pin, h_in, down_conv_freq, down_conv_if_freq,
down_conv_attenuator, fs)
int pin;
DARRAY h_in;
double down_conv_freq;
double down_conv_if_freq;
int down_conv_attenuator;
double fs;
IMAGE Solutions V8.3 26-422
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION This routine applies the Turbo AC downconverter calibration
compensations to the spectrum of a signal captured using the
Turbo AC capture channel. The compensation is applied in-
place to h_in, which can be either a power-spectrum or a
complex spectrum.
ARGUMENTS pin—A Turbo AC capture pin
h_in—The spectrum of the captured signal
down_conv_freq—The value of the parameter
wfcap: down_conversion_frequency
down_conv_if_freq—The value of the parameter
wfcap: down_conversion_if_frequency
down_conv_attenuator—TRUE if you specified
down_conversion_attenuator: on, FALSE if you specified
down_conversion_attenuator: bypass
fs—The value of the wfcap: sample_rate parameter
RETURN VALUE None
tl_turbo_disable_dut_connects
Disable connections to the DUT.
SYNOPSIS void tl_turbo_disable_dut_connects()
DESCRIPTION Disables connections to the DUT on Turbo hardware (Source
and Digitizer). Connect statements will appear to succeed, but
relay connections to the DUT (channel card Pogo pins) will not
be made. Any such relays already connected will remain so, and
disconnect syntax will operate normally. By default, DUT
connects are enabled.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS None
SEE ALSO “tl_lfac_enable_dut_connects”, “tl_lfac_disable_dut_connects”,
“tl_turbo_enable_dut_connects”
tl_turbo_disable_linearity_corrections
Disable linearity corrrection.
SYNOPSIS void tl_turbo_disable_linearity_corrections(pin)
int pin;
DESCRIPTION Disables the Turbo AC linearity corrections for the specified pin.
IMAGE Solutions V8.3 26-423
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS pin—pinmap identifier
RETURN VALUE None
tl_turbo_enable_dut_connects
Enable connections to the DUT.
SYNOPSIS void tl_turbo_enable_dut_connects()
DESCRIPTION Re-enables connections to the DUT on Turbo hardware (Source
and Digitizer). Connect statements will operate normally. This is
the default behavior.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS None
SEE ALSO “tl_lfac_enable_dut_connects”, “tl_lfac_disable_dut_connects”,
“tl_turbo_disable_dut_connects”
tl_turbo_enable_linearity_corrections
Enable linearity corrrections.
SYNOPSIS void tl_turbo_enable_linearity_corrections(pin)int
pin;
DESCRIPTION Enables the Turbo AC linearity corrections for the specified pin.
ARGUMENTS pin—pinmap identifier
RETURN VALUE None
SIDE EFFECTS This function will trigger the re-calibration of both the PACS and
the Turbo AC instrument if the pin specified refers to a Turbo AC
capture channel and the Turbo AC has not been calibrated since
one of the following:
a) the job was loaded
b) the tester was re-initialized
c) mainframe loopback mode was used (checker only)
tl_turbo_get_1knotch_compensation
Report attenuation through 1k notch for a given frequency.
SYNOPSIS double tl_turbo_get_1knotch_compensation(pin,
frequency)
int pin;
double frequency;
IMAGE Solutions V8.3 26-424
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Report the compensation for the attenuation through the 1kHz
notch for a given frequency. The compensation includes the
attenuation due to the notch filter and the roughly 30dB fixed
gain which follows the notch. As a result the compensation will
always be much smaller than 1.0. In order to apply the
compensation, it should be multiplied by the measured voltage
amplitude of a signal component at a particular frequency.
ARGUMENTS pin—Identifies the specific Turbo AC capture channel. A pin of
-1 means to use the global tl_achan.
frequency—The frequency for which to report the
compensation_factor.
RETURN VALUE compensation_factor
tl_turbo_get_downconverter_compensation
Retrieves Turbo AC downconverter calibration compensation for specific frequencies.
SYNOPSIS double tl_turbo_get_downconverter_compensation(pin,
rf_freq, if_freq, down_conv_attenuator)
int pin;
double rf_freq;
double if_freq;
int down_conv_attenuator;
DESCRIPTION Retrieves the Turbo AC downconverter calibration
compensation for a specific combination of RF frequency, IF
frequency, and downconverter attenuator setting. The voltage
amplitude of the captured signal at the specified IF frequency
should be multiplied by the gain compensation that this function
returns.
ARGUMENTS pin—A Turbo AC capture pin
rf_freq—RF frequency
if_freq—IF frequency
down_conv_attenuator—TRUE if you specified
down_conversion_attenuator: on, FALSE if you specified
down_conversion_attenuator: bypass
RETURN VALUE Gain compensation
tl_turbo_measure_src_vrms
Measure Vrms amplitude of source channel.
SYNOPSIS double tl_turbo_measure_src_vrms(pin)
int pin;
IMAGE Solutions V8.3 26-425
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Measures the RMS amplitude at the output of the Turbo AC
source channel. The measurement is made using an RMS-to-
DC converter circuit located right before the DUT relays of the
Turbo AC source channel. The DC output of this circuit is
measured using the Turbo AC capture channel. The DUT will be
temporarily disconnected from both the source and capture
channels (if connected) and the capture channels settings will be
changed to make the measurement. All settings and connections
will be automatically restored after the measurement has been
made.
ARGUMENTS pin—A Turbo AC source pin
RETURN VALUE RMS amplitude in Volts
tl_turbo_set_cw_cal_amp_tolerance
Set amplitude tolerance of CW level calibration.
SYNOPSIS void tl_turbo_set_cw_cal_amp_tolerance(pin,
new_tolerance)
int pin;
double new_tolerance;
DESCRIPTION Changes the amplitude tolerance of the Turbo AC CW level
calibration. The amplitude tolerance determines how large an
amplitude change is necessary to trigger a new level calibration.
ARGUMENTS pin—A Turbo AC Source pin
new_tolerance—The new amplitude tolerance or a negative
value to reset the tolerance to its default value.
RETURN VALUE None
tl_turbo_set_cw_cal_freq_tolerance
Set frequency tolerance of CW level calibration
SYNOPSIS void tl_turbo_set_cw_cal_freq_tolerance(pin,
new_tolerance)
int pin;
double new_tolerance;
DESCRIPTION Changes the frequency tolerance of the Turbo AC CW level
calibration. The frequency tolerance determines how large of a
frequency change is necessary to trigger a new level calibration.
ARGUMENTS pin—A Turbo AC Source pin
new_tolerance—The new frequency tolerance or a negative
value to reset the tolerance to its default value.
IMAGE Solutions V8.3 26-426
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
tl_turbosrc_lp_filter_auto_set
Set Turbo AC Source low-pass filter.
SYNOPSIS double tl_turbosrc_lp_filter_auto_set(pin, freq)
int pin;
double freq;
DESCRIPTION This function will automatically select the most appropriate low-
pass filter on the Turbo AC source channel given the frequency
of the signal being sourced. The filter with the smallest passband
will be selected such that the given frequency will still be within
the passband. If the signal frequency is less than or equal to 0.0
or if it is greater than 150MHz, then the filters will be bypassed.
ARGUMENTS pin—Any Turbo AC Source pin number
freq—Frequency of sourced signal (highest frequency
component for multitones)
RETURN VALUE Cutoff frequency of the filter that was selected or 0.0 if the filters
were bypassed.
tl_turn_multi_threaded
Turns multithreading on or off or reads current mode.
SYNOPSIS int tl_turn_multi_threaded(int mode);
DESCRIPTION Turns multithreading on or off or reads current mode. Any mode
passed in other than ON or OFF equivalents (-1 is recommended)
will not change the current mode. The previous mode is always
returned. The main thread can change the mode at any time.
Side threads that are already started will not be affected. Side
threads only return the current mode. They cannot alter it.
ARGUMENTS mode—Turns multithreading on when set to ON. Turns
multithreading off when set to OFF. Any other value (-1 is
recommended) leaves mode unchanged.
RETURN VALUE The previous mode (ON or OFF)
tl_ubvi100_set_supply_reset_state
Changes reset state of power supply selector
SYNOPSIS int tl_ubvi100_set_supply_reset_state(srcnum, read,
state)
int srcnum;
IMAGE Solutions V8.3 26-427
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int read;
int state;
DESCRIPTION This function reads/writes the reset state of the UBVI100 power
supply selector. This allows you to control whether the UBVI100
resets to normal mode or high voltage mode. Unless the reset
state of the power supply selector is changed with this function,
it defaults to normal mode.
ARGUMENTS srcnum—Source number UBVI100 is installed as or 0 for all
read— 1 = read
0 = write
state— 1 = reset board to 60 V mode
0 = reset board to high voltage mode
RETURN VALUE 0 if error
1 if successful
SIDE EFFECTS Sets tl_ubvi100_regs
tl_uhfmm_read_freq
Return the UFHMM freq parameter setting.
SYNOPSIS double tl_uhfmm_read_freq(pin)
int pin;
DESCRIPTION Returns the UHFMM freq parameter setting.
ARGUMENTS pin—UHFMM pin
RETURN VALUE Frequency UWMM is currently programmed to
tl_uhfmm_read_if_freq
Return the UHFMM if_freq parameter setting.
SYNOPSIS double tl_uhfmm_read_if_freq(pin)
int pin;
DESCRIPTION Returns the UHFMM if_freq parameter setting.
ARGUMENTS slot—UHFMM/UWRECV/UWPORT slot
RETURN VALUE if_freq that UHFMM is programmed to
SIDE EFFECTS Calls tl_achan_setup(); restores tl_achan
tl_uhfsrc_cal_interval
Set the UHFSRC calibration interval.
SYNOPSIS void tl_uhfsrc_cal_interval(amt)
int amt;
IMAGE Solutions V8.3 26-428
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Sets the Microwave Source calibration interval.
ARGUMENTS amt—Time interval
RETURN VALUE None
tl_uhfsrc_get_freq
Return the current frequency of the UHFSRC.
SYNOPSIS double tl_uhfsrc_get_freq()
DESCRIPTION Return the current frequency of the selected Microwave Source.
ARGUMENTS None
RETURN VALUE Frequency in hertz
tl_uhfsrc_is_lin_cal_data_valid
Print out if linearity calibration data are valid.
SYNOPSIS void tl_uhfsrc_is_lin_cal_data_valid()
int on_off;
DESCRIPTION Print out if lin cal data are valid.
ARGUMENTS on_off 1 - use linearity cal data
0 - not use linearity cal data
RETURN VALUE None
tl_uhfsrc_level_table_valid
Returns whether the UHFSRC leveling table is valid.
SYNOPSIS int tl_uhfsrc_level_table_valid(pin_num)
int pin_num;
DESCRIPTION Returns whether the leveling table for the Microwave Source
specified by pin_num is valid.
ARGUMENTS pin_num—UWSRC pin number
RETURN VALUE 1 if valid, 0 otherwise.
tl_uhfsrc_level_table_valid_slot
Returns whether the Microwave Source leveling table is valid.
SYNOPSIS int tl_uhfsrc_level_table_valid_slot(slotnum)
int slotnum;
IMAGE Solutions V8.3 26-429
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Returns whether the leveling table for the Microwave Source
specified by the test head slot number is valid.
ARGUMENTS slotnum—UWSRC test head slot number
RETURN VALUE 1 if valid, 0 otherwise.
SEE ALSO “tl_uhfsrc_level_table_valid”
tl_uhfsrc_max_freq
Return the maximum CW frequency for the selected UHFSRC.
SYNOPSIS double tl_uhfsrc_max_freq()
DESCRIPTION Returns the maximum CW frequency allowed for the selected
Microwave Source.
ARGUMENTS None
RETURN VALUE Maximum CW frequency allowed for the given UWSRC
configuration.
tl_uhfsrc_max_mod_freq
Return the maximum allowable carrier frequency for the selected Microwave Source.
SYNOPSIS double tl_uhfsrc_max_mod_freq()
DESCRIPTION Returns the maximum allowable carrier frequency for the
selected Microwave Source.
ARGUMENTS None
RETURN VALUE Maximum carrier frequency in Hertz
tl_uhfsrc_mod_synth_freq
Inquire UHFSRC for its current synthesizer frequency setting if this UHFSRC is in
modulation mode.
SYNOPSIS double tl_uhfsrc_mod_synth_freq(uhf_unum)
DESCRIPTION Return the current synthesizer frequency setting of the selected
UHFSRC when it is in modulation mode, zero otherwise.
ARGUMENTS UHFSRC instrument number
RETURN VALUE Frequency in Hertz if in modulation mode or zero otherwise.
tl_uhfsrc_set_table_size
Set the maximum size of table for the Microwave Source.
IMAGE Solutions V8.3 26-430
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS void tl_uhfsrc_set_table_size(num)
int num;
DESCRIPTION Sets the maximum size of look-up table (BCD and pre-level data)
for the Microwave Source.
ARGUMENTS num—Number of entries in the table
RETURN VALUE None
tl_uhfsrc_use_lin_cal_data
Set uhfsrc_use_lin_cal_data on or off.
SYNOPSIS void tl_uhfsrc_use_lin_cal_data(on_off)
int on_off;
DESCRIPTION Find the linearity cal correction given freq and amp_dbm
ARGUMENTS on_off—1 - use linearity cal data, 0 - not use linearity cal data
RETURN VALUE None
tl_update_data_collection_state
Update data structures in test program with latest data collection setup information.
SYNOPSIS int tl_update_data_collection_state(void)
DESCRIPTION This function first establishes with the dataserv process for the
given test program and sends it a command requesting the latest
data collection setup information. This information is then
retrieved and stored in local data structures in the test program
and can be accessed by the following functions:
tl_get_data_collection_streams()
tl_get_stream_criteria()
tl_get_stream_sample_rate()
tl_get_stream_sample_limit()
tl_get_stream_filename()
tl_get_stream_datalog_directory()
See the individual functions for more information.
Unless tl_update_data_collection_state() is called, the
stream information is not guaranteed to be up to date. These
functions assume that data collection is set at the beginning of a
lot and remains fairly static from that point on, or changes only
infrequently. If data collection has changed (using datalog,
datastream, or the data collection display) after this function has
been called, the state will be incorrect.
IMAGE Solutions V8.3 26-431
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
After stream information is retrieved, this function sends a
command to dataserv to get the default datalog directory to
which files will written.
Before calling any of the above functions, call
tl_update_data_collection_state to verify that the data
collection state is up to date.
ARGUMENTS None
RETURN VALUE 0—Error updating data collection state, the current state of the
state in the test program is not guaranteed to be correct. It is
possible that when this function has been called another
command process may have been communicating with the
dataserv process and the connection was refused. Wait several
seconds and try again.
1—Data collection state successfully updated.
SIDE EFFECTS Updates the data collection state in the test program.
tl_user_datalog_changed
User function to take action when datalog setup has changed.
SYNOPSIS void tl_user_datalog_changed()
DESCRIPTION If this function is defined by the user in a test program, it is called
after the datalog setup has been changed using datalog
commands or using tl_set_datalog... functions.
ARGUMENTS None
RETURN VALUE None
tl_user_eeprom_present
Determine whether EEPROM is present.
SYNOPSIS int tl_user_eeprom_present(type)
EEPROM_ENUM_TYPE type;
DESCRIPTION Handshakes with EEPROM and returns true if it responds.
ARGUMENTS type—serial EEPROM type
CONFIGA Configuration Board A
CONFIGB Configuration Board B
DIB Device Interface Board (DIB)
TLDUT Device Under Test (DUT)
RETURN VALUE 1 = Successfully found on EEPROM
0 = No acknowledgment from EEPROM
IMAGE Solutions V8.3 26-432
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_user_endlot
User callable function for custom endlot processing.
SYNOPSIS (void) tl_user_endlot(void)
DESCRIPTION This function is provided to allow access to the endlot process
from a test program. This is not an IMAGE-callable function, you
must write the function and included as part of your test program.
If this function exists in the test program, it is called before any
IMAGE endlot processing occurs, before any FIRMS events are
called or any summary records are written. You are free to have
this function perform any endlot tasks desired.
The function is of type void and accepts no arguments.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS This will vary with what users have the function perform.
tl_user_mcfd_handler
User defined function which is called whenever a site experiences maximum consecutive
failing devices (MCFD).
SYNOPSIS void tl_user_mcfd_handler(int site, int mcfd_count)
DESCRIPTION This function is designed to be defined by users and included in
the test program. Whenever the count of maximum consecutive
failing devices reaches a preset value, this function is called,
before any IMAGE processing of the event. Perform any user-
specific processing using this function, such as communication
with a handler or prober.
This function receives two integer arguments: the site number
experiencing MCFD and the count of maximum consecutive
failing devices. Note that this value can be greater than the value
used to trigger the MCFD event. If a particular site has not been
disabled, continues to test, and continues to experience MCFD,
the count will continue to increment and the function will continue
to be called.
In the case of multisite testing, this function is called once per
site.
If this function has not been defined by the user, IMAGE invokes
a dummy function which does nothing. There is no default action
for this function. IMAGE will post a run time error after this
function is called.
IMAGE Solutions V8.3 26-433
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS site—The site experiencing MCFD.
mcfd_count—The current count of MCFD at site.
RETURN VALUE None
SIDE EFFECTS User defined. The dummy has none.
tl_user_postautocal
Called after any instrument calibration from autocal.
SYNOPSIS void tl_user_postautocal()
DESCRIPTION This function is called from the autocal utility after any
instruments are calibrated by autocal if any instruments required
calibration.
ARGUMENTS None
RETURN VALUE None
tl_user_preautocal
Called before any instrument calibration from autocal.
SYNOPSIS void tl_user_preautocal()
DESCRIPTION This function is called from the autocal utility before any
instruments are calibrated by autocal if any instruments require
calibration.
ARGUMENTS None
RETURN VALUE None
tl_user_resetall
Call user function at end of reset all.
SYNOPSIS void tl_user_resetall()
DESCRIPTION If this function exists in a test program, any statements located in
the body of the function are executed at the end of reset all.
This occurs at the beginning of each test program run.
ARGUMENTS None
RETURN VALUE None
tl_user_shutdown
Get user function when site fails.
SYNOPSIS void tl_user_shutdown()
IMAGE Solutions V8.3 26-434
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION If this function exists in a test program, any statements located in
the body of the function are executed at the end of the test
program or when the device fails. (In a multisite test program,
after all devices fail). Use this function in a test program to
specify actions to be performed after all testing is complete.
NOTE
To re-enable the device, use set site_enable_all; as the first line in this function. If this
statement is not used, instrument statements in the function are not executed.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_site_shutdown”
tl_user_startup
Call user function at start of test program.
SYNOPSIS void tl_user_startup(argc, argv)
int argc;
char* argv[];
DESCRIPTION If this function exists in a test program, any statements located in
the body of the function are executed at the start of the test
program before main() is called. Any arguments passed to
main() are passed to tl_user_startup() also.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_user_shutdown”, “Passing Command Line Parameters to
main()” on page 5-23
tl_using_simulator
Flag indicating tester is in simulator mode.
SYNOPSIS extern int tl_using_simulator;
DESCRIPTION If tl_using_simulator is nonzero, Terabus is not present and
IMAGE tester simulator library has been linked.
tl_uwmm_dump
Prints ASCII representation of UHFMM state.
IMAGE Solutions V8.3 26-435
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_uwmm_dump(slot)
int slot;
DESCRIPTION Prints an ASCII representation of the UWMM’s state to the
screen.
ARGUMENTS slot—Slot number of UWMM
RETURN VALUE !0 if error
tl_uwms_present
Return modulation option of the source directly behind the specified UWPORT pin (no add
path).
SYNOPSIS int tl_uwms_present(uwport_pin)
int uwport_pin;
DESCRIPTION Return the modulation option, if any, of the UHFSRC directly
behind the specified UWPORT pin. This function supports both
IFMS and UWMS.
ARGUMENTS uwport_pin—UWPORT pin number
RETURN VALUE enum Mod_option—Enumerated value where enum
Mod_option has the following values:
ERROR_MOD—Illegal UWPORT pin or no UHFSRC behind it
NO_MOD—Sine mode only
IFMS_MOD—IFMS modulation mode (10MHz - 180MHz)
UWMS_MOD—UWMS modulation mode (10MHz - 2.7GHz)
SEE ALSO “tl_uwms_present_slot”
tl_uwms_present_slot
Return modulation option of the source behind a UWPORT pin specified by UWPORT slot
number and schan number.
SYNOPSIS int tl_uwms_present_slot(uwport_slot, uwport_schan)
int uwport_slot;
int uwport_schan;
DESCRIPTION Return the modulation option, if any, of the UHFSRC behind a
UWPORT pin specified by UWPORT slot and schan. This
function supports both IFMS and UWMS.
ARGUMENTS int uwport_slot—UWPORT slot number
int uwport_schan—UWPORT schan number
RETURN VALUE enum Mod_option—Enumerated value where enum
Mod_option has the following values:
IMAGE Solutions V8.3 26-436
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ERROR_MOD Illegal UWPORT pin or no uhfsrc behind it
NO_MOD Sine mode only
IFMS_MOD IFMS modulation mode (10MHz - 180MHz)
UWMS_MOD UWMS modulation mode (10MHz - 2.7GHz)
SEE ALSO “tl_uwms_present”
tl_uwport_caldib_find_interpolated_ENR
Find the interpolated ENR and the source match at the given schan of the UWPORT.
SYNOPSIS UWPORT_CALDIB_ENUM_FIND_RESULT
tl_uwport_caldib_find_interpolated_ENR(slot, schan,
freq, enr, gamma_cold, gamma_hot,
max_interpole_interval)
int slot;
int schan;
double freq;
double *enr;
D_COMPLEX *gamma_cold;
D_COMPLEX *gamma_hot;
double max_interpole_interval;
DESCRIPTION Looks up the ENR/gamma data of the internal noise source for
the given UWPORT slot/schan from the caldib data cache.
If the data point interval meeting the given max interval limit is
found, it returns linearly interpolated ENR and gamma data in the
ptrs provided.
If the suitable data interval is not found, the values in the ptrs are
unmodified.
The result of the data search is indicated by the return value:
UWPORT_CALDIB_FIND_NO_CACHE—Caldib cache does not exist
UWPORT_CALDIB_FIND_FAIL—Could not find the requested data
UWPORT_CALDIB_FIND_SUCCESS—Successfully found the
requested data
ARGUMENTS slot—Slot # of UWPORT
schan—Schan # of UWPORT [1-2 or 5-6]: ENR data are not
applicable to side 2 channels
freq—Requested freq point
enr—Ptr to return ENR value
gamma_cold—Ptr to return gamma cold
gamma_hot—Ptr to return gamma hot
max_interpole_interval—Max allowable interpolation
interval. if <= 0.0, the function applies the system default of
40.0MHz
RETURN VALUE One of UWPORT_CALDIB_ENUM_FIND_RESULT
IMAGE Solutions V8.3 26-437
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “tl_uwport_caldib_find_interpolated_system_NF”
tl_uwport_caldib_find_interpolated_system_NF
Find the interpolated system NF at the given UWPORT slot/schan
SYNOPSIS UWPORT_CALDIB_ENUM_FIND_RESULT
tl_uwport_caldib_find_interpolated_system_NF(slot,
schan,freq, nf_rfl, nf_lna, max_interpole_interval)
int slot;
int schan;
double freq;
double *nf_rfl;
double *nf_lna;
double max_interpole_interval;
DESCRIPTION Looks up the system NF measurements data for the given
UWPORT slot/schan from the caldib data cache.
If the data point interval meeting the given max interval limit is
found, it returns linearly interpolated system NF data in the ptrs
provided.
If the suitable data interval is not found, the values in the ptrs are
unmodified.
The result of the data search is indicated by the return value:
UWPORT_CALDIB_FIND_NO_CACHE—Caldib cache does
not exist
UWPORT_CALDIB_FIND_FAIL—Could not find the requested
data
UWPORT_CALDIB_FIND_SUCCESS—Successfully found the
requested data
ARGUMENTS slot—Slot # of UWPORT
schan—Schan # of UWPORT [3 - 4 or 7-8]: system NF data are
not applicable to side 1 channels
freq—Requested freq point
nf_rfl—Ptr to return the system NF through the reflect path
nf_lna—Ptr to return the system NF through the LNA path
max_interpole_interval—Max allowable interpolation
interval. If <= 0.0, the function applies the system default of
40.0MHz
RETURN VALUE One of UWPORT_CALDIB_ENUM_FIND_RESULT
SEE ALSO “tl_uwport_caldib_find_interpolated_ENR”
IMAGE Solutions V8.3 26-438
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_uwport_cal_s_params
Calibrate s-parameters from autocal
SYNOPSIS int tl_uwport_cal_s_params(slot)
int slot;
DESCRIPTION If you write a function with the name tl_uwport_cal_s_params
it will be called during autocal whenever s-parameter calibration
is needed. This function will be called once for each UWPORT in
the pinmap or test head, depending on whether autocal is used
with -pinmap_only or not.
This function should prompt for the user or handler to insert the
appropriate cal standards or execute the ProGen code that
calibrates with data transferred to the internal cal standards.
ARGUMENTS int slot—UWPORT slot number
RETURN VALUE TL_AUTOCAL_CALIBRATED—Calibration passed
TL_AUTOCAL_UNCALIBRATED—Calibration failed
0—This slot does not need to be calibrated for s-parameters
SEE ALSO “tl_uwport_pin_to_slot_and_schan”,
“read_uwport_one_port_cal_std”,
“read_uwport_two_port_cal_std_forward”
tl_uwport_config
Return a bit vector of UWPORT configuration information.
SYNOPSIS int tl_uwport_config(slot)
int slot;
DESCRIPTION Returns a bit vector indicating which UHFSRCS and UHFMMS
are present (or -1 in case of error).
ARGUMENTS slot—Test head slot number
RETURN VALUE bit vector
bit: Significance:
0 UHFSRC connected to J1 (UHFSRC #1 -- 2 matrix xpts)
1 UHFSRC connected to J2 (lna side)
2 UHFMM connected to J7
0 may also indicate an error. (Used to return -1 if bad slot
number.) Will tl_error(), so only an issue if tmode is continue
on error. The -1 error code was causing code to operate
improperly because it said all instruments were available behind
UWPORT when no UWPORT was present.
SEE ALSO “tl_uwport_receiver_slot”, “tl_uwport_pin_to_slot_and_schan”
IMAGE Solutions V8.3 26-439
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_uwport_current_pin
Pin on which power de-embedding is done.
SYNOPSIS int tl_uwport_current_pin(pin);
int pin;
DESCRIPTION For the purposes of power de-embedding, this function returns
the currently active pin.
The “current pin” is important because IMAGE uses s-parameter
calibration data for that pin when adjusting the source and
receiver amplitude.
Choose the current pin based on the following, in order of
preference:
1) Only pin on this schan. (No DIB switching.)
2) Pin used with de_embed_file.
3) Pin used with gamma.
4) Pin used with connect.
5) Pin used with power_de_embed.
If none of these parameters changed from its default value, 0 is
returned.
Note that power_de_embed must be on and the UWPORT
connected for the current pin to have any effect, so it is unlikely
that this function will return 0. However, it is possible to use a
statement like:
set slot=21 schan=3 uwport: power_de_embed: on;
which will not tell IMAGE which pin to use. (rfdisp does this.
Making a connection with the UWSRC or UWRECV or UWMM
page uses slot programming so no pin number is set by that
statement.)
The pin used with a connect statement is remembered even after
the UWPORT has been disconnected from that pin. Therefore, if
you want to change the pin on which power de-embedding is
done and you are not using de-embed files or setting gamma,
use a connect when you change the switches on the DIB.
de_embed_file has highest precedence because it affects s-
parameters as well as power de-embedding. Also, there may be
one pin name for two different pins and changing the de-embed
files when the DIB switches are changed keeps everything
correct.
ARGUMENTS pin—UWPORT pin
RETURN VALUE Pin number or 0, if none.
SEE ALSO “tl_uwport_current_pin_slot”
IMAGE Solutions V8.3 26-440
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_uwport_current_pin_slot
Pin on which power de-embedding is done.
SYNOPSIS int tl_uwport_current_pin_slot(slot, schan)
int slot, schan;
DESCRIPTION For the purposes of power de-embedding, this function returns
the currently active pin. This function is the same as
tl_uwport_current_pin(), except it takes a slot and schan as
arguments and does not do any pin or site consistency checking.
ARGUMENTS slot—UWPORT slot number
schan—1 to 4, corresponding uwport_A to uwport_D
RETURN VALUE Pin number or 0, if none
SEE ALSO “tl_uwport_current_pin”, “tl_uwport_pin_to_slot_and_schan”
tl_uwport_do_s11
Hook to replace driver s-param code (use DSP).
SYNOPSIS int tl_uwport_do_s11(source_slot, source_schan,
sample_freq, if_freq, uwrecv_sample_size,
ignore, driver_num_samples,
driver_window_samples, incident, reflect,
two_port, measure_slot, measure_schan,
transmit)
int source_slot;
int source_schan;
double sample_freq;
double if_freq;
int uwrecv_sample_size;
int ignore;
int driver_num_samples;
int driver_window_samples;
D_COMPLEX *incident;
D_COMPLEX *reflect;
int two_port;
int measure_slot;
int measure_schan;
D_COMPLEX *transmit;
DESCRIPTION If this function is defined in a test program, it will replace the
UWPORT driver’s s-parameter measurement code.
This function was provided at the request of Applications so they
could use the array processor for faster math and optimize the
number of samples taken in each segment of a waveform to
improve accuracy.
IMAGE Solutions V8.3 26-441
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
When this function is called, the user has connected a source to
the device through source_slot, source_schan.
For a 1-port measurement, two_port is 0 and the UWRECV is
connected through the reflect coupler to source_slot,
source_schan. To preserve incremental programming, it is
necessary to make sure the state of these connections is
restored before this function exits. The easiest way to do this is
to measure the incident portion of the waveform first, then the
reflect, which will leave everything set up correctly.
For a 2-port measurement, two_port is not 0 and the UWRECV
is connected to measure_slot, measure_schan. Again, the
state of the UWPORT must be restored correctly, and, to for the
sake of compatibility with future calibrations involving the lna,
you cannot assume that the lna is off as you can in the 1-port
case. (You cannot measure 1-port s-parameters through the
LNA. (The source signal can’t get through it to the device.)
However, it may be necessary to measure the s-parameters of
the LNA and the signal transmitted into the LNA. You get an error
if you try to leave the LNA on when doing a s-parameter
measurement in IMAGE V6.2 or earlier, but it is possible we will
introduce a calibration which requires the LNA to be on in V6.3.)
Sample code skeleton:
#include <itlh/uwport.h> * macros for tl_uwport_set_slot() *
int tl_uwport_do_s11( ... ) {
* set uwrecv sample size. This may be a function
of if_freq and sample_freq as well as it being a
1 or 2 port capture. *
set slot = source_slot uwrecv:
sample_size = XXX;
* connect incident coupler *
tl_uwport_set_slot(source_slot, source_schan,
UWPORT_INCIDENT);
* if this is a 2-port operation, figure out how
to restore LNA state correctly *
if (two_port)
if (tl_uwport_lna_slot(measure_slot, measure_schan))
two_port_op = UWPORT_LNA_ON;
else
two_port_op = UWPORT_REFLECT;
start uwrecv; * or plfdig... *
tl_delay(xxx); * optional *
IMAGE Solutions V8.3 26-442
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
* connect reflect coupler *
tl_uwport_set_slot(source_slot, source_schan,
UWPORT_REFLECT);
if (two_port) {
tl_delay(xxx); * optional *
tl_uwport_set_slot(measure_slot, measure_schan,
two_port_op);
}
* if you use wavetool to look at c_mem, you should
see 1 or 2 transitions *
* move capture to array processor. One big move
will usually be faster than 3 small ones. *
move c_mem: tl: dsp_data = buff;
* perform FFTs on each segment. You will have to
determine where each segment begins and ends. The
driver values are provided, but your code is not
the same as the driver’s.... *
* first segment is first N samples *
incident->real = real;
incident->imag = imaginary;
* second starts, say, 100 microseconds into capture
and lasts N samples.(Or last N samples if 1-port.) *
reflect->real = real;
reflect->imag = imaginary;
if (two_port) {
* fft of last N samples of capture *
transmit->real = real;
transmit->imag = imaginary;
}
* restore uwrecv sample size *
set slot = source_slot uwrecv:
sample_size = uwrecv_sample_size;
* This function must return a value other than 0
for its results to be used. *
return 1;
}
IMAGE Solutions V8.3 26-443
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
NOTE
This function must be used consistently for all s-parameter measurements. S-parameter
calibration relies on the same phase relationship between the incident, reflect, and
transmitted portions of the waves. Using this function for only some of the captures will not
work.
This function is not intended to be provided by customers; the
description here is to help customers understand what
applications code is doing. (And for reference by the applications
engineers themselves.)
ARGUMENTS source_slot—Source is connected here
source_schan—Source is connected here
sample_freq—UWRECV (HFDIG) sample rate
if_freq—UWRECV if_freq setting
uwrecv_sample_size—Current UWRECV sample_size
ignore—Used to be results, an obsolete UWRECV parameter
driver_num_samples—Sample size the driver would use
driver_window_samples—N in above example that driver
would use
incident—Return complex FFT result for incident capture here
reflect—Return complex FFT result for reflect capture here
two_port—2-port s-parameter capture if true (IMAGE 6.2)
measure_slot—”the other slot” for a 2-port measurement
measure_schan—”the other schan” for a 2-port measurement
transmit—Return complex FFT result for transmit capture here
RETURN VALUE non-zero—This function measured the s-parameters
0—This function did nothing
tl_uwport_do_spar_proc
Perform s-parameter processing.
SYNOPSIS int tl_uwport_do_spar_proc(sample_freq,
if_freq,number_samples, start_reflect,
start_transmit, incident, reflect, transmit,
snr_segment, noise_test_fail,data_error)
double sample_freq;
double if_freq;
int number_samples;
int start_reflect;
int start_transmit;
D_COMPLEX *incident;
D_COMPLEX *reflect;
D_COMPLEX *transmit;
int snr_segment;
IMAGE Solutions V8.3 26-444
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int *noise_test_fail;
int *data_error;
DESCRIPTION If this function is defined in a test program (that is, it returns a 1),
the UWPORT driver’s s-parameter processing is bypassed. This
function is only called when the s-parameter hardware timer is
present and is being used for one or two port s-parameter
measurements. This function is called when the s-parameter
capture has been initiated.
This user supplied function will be provided the following inputs:
the sample frequency of the digitizer, the IF frequency of the
receiver, the number of samples in each data window (incident,
reflect and transmit), the reflect offset in the capture memory, the
transit offset in the capture memory and segment number (1,2,3)
if noise testing is requested or zero otherwise. If this is a one port
capture the transmit offset will be zero. The user supplied
function will be expected to return D_COMPLEX values for
incident, reflect and transmit. If noise testing is requested and
the user supplied noise test fails, the function must return a
TRUE value for noise_test_fail and a FALSE value
otherwise. If noise testing is not requested this value is not
tested. The user function is also expected to return TRUE for
data_error if the capture does not complete or there is a move
data failure and FALSE otherwise.
The purpose of this function is to allow the user the option of
using the DSP processor to compute the incident, reflect and
transmit values for the s-parameter measurement while not
having to be responsible for the mechanics of the capture. The
s-parameter capture will be initiated prior to this function call. It
is the user’s responsibility to move this data and perform the
appropriate processing based on whether this is a one port or
two port capture. Do not re-program or modify, via functions or
set syntax, the microwave port module within this function.
ARGUMENTS sample_freq—Sample frequency of digitizer
if_freq—IF frequency of receiver
number_samples—Number of samples in each data window
start_reflect—Reflect offset in capture memory
start_transmit—Transmit offset in capture memory
incident—Pointer to D_COMPLEX incident value
reflect—Pointer to D_COMPLEX reflect value
transmit—Pointer to D_COMPLEX transmit value
snr_segment—Segment number to perform noise testing
(1-incident, 2-reflect, 3-transmit) 0 if no testing is required.
noise_test_fail—If noise testing, TRUE for fail, FALSE for
pass
data_error—TRUE if capture or move data failure, FALSE
otherwise
IMAGE Solutions V8.3 26-445
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 1—If this function performed the s-parameter processing
0—If this function did nothing
tl_uwport_dump
Dump UWPORT block diagram for debugging.
SYNOPSIS void tl_uwport_dump(slot)
int slot;
DESCRIPTION Displays an ASCII block diagram of the UWPORT.
imm "tl_uwport_dump(21)"
uwport 2: tl_uwport_dump(slot = 21)
Dumping state of Port in slot 21, acard 14:
slot 18 ----- PA ---+-------+-------- mux to SCHAN 1
UHFSRC (4GHz)
+---------------------------- MM (slot 20)
UHFSRC (4GHz) |
slot 19 -/ -- -20 dB ---+--- LNA ------ mux to SCHAN 4
THADS 1_1 = OFF THADS 1_2 = OFF THADS 2_1 = OFF THADS 2_2 = OFF
Matrix 1_1 = 0x000 Matrix 1_2 = 0x000 Matrix 2_1 = 0x000 Matrix 2_2 = 0x000
ALRO = OFF ALRC = OFF BCS = OFF ALRC/ALRO = 0 BCS/ALRO = 0
Measure Bus OFF Heater: OFF
General information:
v--- uwport instrument number. This is the 2nd uwport in testhead.
uwport 2: tl_uwport_dump(slot = 21)
Dumping state of Port in slot 21, acard 14:
^^--- This is the 14th analog channel card in testhead.
(numbered from slot 1)
RF paths:
+--- source slot number (0 = not present)
v v--- add path (on) v--- connection or
slot 18 ----- PA ---+-------+-------- mux to SCHAN 1 cal std
UHFSRC (4GHz) |
source type ^ | +---------------------------- MM (slot 20)
UHFSRC (4GHz) | | receiver slot number ---^
slot 19 -/ -- -64 dB ---+ REFLECT ---- mux to SCHAN 4
gain stage ---^^^^^^ ^ ^-- directional coupler to receiver
(-20 dB) | (can also be INCIDENT coupler or LNA)
( PA ) +-- terminated switch ("ADD" termination)
"SCHAN 1" is the slot programming equivalent of UWPORT_A.
Schans 2, 3, and 4 are UWPORT_B, UWPORT_C, and UWPORT_D respectively.
Other possibilities are TERM (50 ohm),
SHORT, OPEN, and THRU cal standards.
THADS, DC matrix, and calibration circuitry state:
THADS 1_1 = OFF THADS 1_2 = OFF THADS 2_1 = OFF THADS 2_2 = OFF
Matrix 1_1 = 0x000 Matrix 1_2 = 0x000 Matrix 2_1 = 0x000 Matrix 2_2 = 0x000
ALRO = OFF ALRC = OFF BCS = OFF ALRC/ALRO = 0 BCS/ALRO = 0
Measure Bus OFF Heater: OFF
^^^--- heater should generally be ON
IMAGE Solutions V8.3 26-446
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
In general, ignore this section. The THADS connection
information (<side>_<mux position>), for instance, may be
correct. Without the appropriate relays being thrown in the test
head support cards, however, the signal does not go anywhere.
See rfdisp instead. The ALRO, ALRC, and BCS are for
calibrating the source and receiver. The Measure Bus is a
connection to the DC meter used by the calibration circuitry. The
Heater should generally be ON so the UWPORT stays at the
temperature it was calibrated at.
For debugging s-parameter measurements, the state of the add
path and the gain stage (PA, -20 dB, -64 dB) are most interesting
since these affect the termination of s-parameter measurements.
These should remain the same during s-parameter calibration
when measuring all standards and when making the actual
measurements.
The output of this function may disagree with the output of
rfdisp in several areas.
The add path is used to provide a consistent termination for the
UWRECV. If the UWRECV is connected to a pin and no source
is connected to that same pin (not doing an s-parameter
measurement), the add path is switched on for you
automatically.
The internal calibration standards and other calibration circuitry
are included in this function.
The incident and reflect couplers for s-parameter measurements
are shown if they are in use.
lna:on may appear in the rfdisp page. If the UWRECV is not
connected to the device through the lna, however, the lna is not
actually connected because it would prevent you from sourcing
on side 2.
rfdisp lumps together the states of multiple switches for some
things it displays. It should still be possible to trace the signal
from source to DUT or from DUT to UWRECV with both.
The lines of text below the block diagram refer to cal circuitry or
the state of subsystems which is not meaningful by itself and can
be ignored.
The output of this function reflects the actual state of the
hardware as determined by looking at the bits in the registers
rather than the programmed state of the instrument as shown in
rfdisp.
If a message is printed on the screen saying:
uwport 1: check_hardware: hardware/software mismatch in reg X
IMAGE Solutions V8.3 26-447
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
it probably means you are using non-UWPORT functions to write
to UWPORT registers. If you need low-level access to UWPORT
hardware, contact the Teradyne Applications group to find out
how to do this safely without causing this error. (Ask about
tl_uwport_set(), an undocumented function used for
checkers and factory calibration that gives complete, but
uncalibrated, control over the UWPORT hardware state.) This
error message means that the UWPORT driver is operating
assuming the hardware is in one state while it is really in another.
This may result in erratic behavior. If this message is printed, the
state of the driver is updated to reflect the actual state of the
hardware, so everything should work from this point on. This is
an internal diagnostic message, not something you should ever
see.
ARGUMENTS slot—UWPORT slot number (typically 4 or 21)
RETURN VALUE None
SIDE EFFECTS Corrects driver state if error detected.
SEE ALSO “tl_uwport_pin_to_slot_and_schan”
tl_uwport_dump_1port
Debug s-parameter cal.
SYNOPSIS void tl_uwport_dump_1port(slot, schan)
int slot, schan;
DESCRIPTION Prints values of 1-port cal standards (open, short, load) for each
frequency in the station window. There should be multiple entries
for a frequency if there are multiple amplitudes at that frequency
or multiple pins connected to that schan calibrated at that
frequency.
If you see a column of <INVALID>, it means you did not calibrate
with that standard. If you see two columns of valid data followed
by one column of valid data, it means there is a difference
between the ways the cal standards were measured. See
tl_uwport_dump_port() for details of what the difference is.
ARGUMENTS slot, schan—UWPORT slot and schan
RETURN VALUE None
SEE ALSO “tl_uwport_dump_port”
tl_uwport_dump_closest_freq
Print closest calibrated frequency.
IMAGE Solutions V8.3 26-448
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_uwport_dump_closest_freq(pin, freq)
int pin;
double freq;
DESCRIPTION Given a frequency, reports closest calibrated frequencies and
index for 1-port data, which can be used with
tl_uwport_dump_one_port().
ARGUMENTS pin—UWPORT pin
freq—Frequency
RETURN VALUE UWPORT_SUCCESS, UWPORT_FAIL
tl_uwport_dump_closest_freq_slot
Print closest calibrated frequency.
SYNOPSIS int tl_uwport_dump_closest_freq_slot(slot, schan,
freq)
int slot, schan;
double freq;
DESCRIPTION Given a frequency, reports closest calibrated frequencies and
index for 1-port data, which can be used with
tl_uwport_dump_one_port().
ARGUMENTS slot, schan—UWPORT slot and schan
freq—Frequency
RETURN VALUE UWPORT_SUCCESS, UWPORT_FAIL
tl_uwport_dump_de_embed_file
Print de_embed_file.
SYNOPSIS int tl_uwport_dump_de_embed_file(pin)
int pin;
DESCRIPTION Prints the de_embed_file for pin in the station window.
ARGUMENTS pin—UWPORT pin
RETURN VALUE < 0—Error
>= 0—Number of de-embed files
tl_uwport_dump_de_embed_file_slot
Print de_embed_file.
SYNOPSIS int tl_uwport_dump_de_embed_file_slot(slot, schan)
int slot;
int schan
IMAGE Solutions V8.3 26-449
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Prints the de_embed_file for slot and schan in the station
window.
ARGUMENTS slot—UWPORT slot
schan—UWPORT schan
RETURN VALUE < 0—Error
>= 0—Number of de-embed files
tl_uwport_dump_fixture
S-parameter debugging function.
SYNOPSIS void tl_uwport_dump_fixture(pin, index)
int pin, index;
DESCRIPTION Prints the de-embed files and their combined value to the station
window for the fixture with the specified index.
fixture 299 refers to 1-port 899; next fixture is -1
index to 1-port data --^ other pin or de-embed file
de_embed_file (299) = ("")
^--- no de-embed file selected
(default)
valid = 1
fixt (299) = {s11 = ( 0.0000 0.00) s21 = ( 1.0000 0.00)
s12 = ( 1.0000 0.00) s22 = ( 0.0000 0.00)}
^--- cascaded value of all .s2p files
Note that the fixture printed is not necessarily associated with the
passed pin. Fixture information is stored separately for each of
the four UWPORT schans, not by pin. So if multiple pins are
connected to a single UWPORT schan (DIB switching), the
fixture you see will have the index you request, but not
necessarily the correct pin number. To make sure you are
looking at the right pin, use
tl_uwport_dump_one_port(pin, <index_1port>)
ARGUMENTS pin—A UWPORT pin
index—Fixture to look at
RETURN VALUE None
SEE ALSO “tl_uwport_dump_fixture_slot”, “tl_uwport_dump_one_port”,
“tl_uwport_dump_de_embed_file”
tl_uwport_dump_fixture_slot
s-parameter debugging function.
SYNOPSIS void tl_uwport_dump_fixture_slot(slot, schan, index)
int slot, schan, index;
IMAGE Solutions V8.3 26-450
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Prints the de-embed files and their combined value to the station
window for the “fixture” with the specified index.
fixture 299 refers to 1-port 899; next fixture is -1
index to 1-port data --^ other pin or de-embed file
de_embed_file (299) = ("")
^--- no de-embed file selected
(default)
valid = 1
fixt (299) = {s11 = ( 0.0000 0.00) s21 = ( 1.0000 0.00)
s12 = ( 1.0000 0.00) s22 = ( 0.0000 0.00)}
^--- cascaded value of all .s2p files
ARGUMENTS slot—UWPORT slot number (typically 4 or 21)
schan—UWPORT schan number (1-4)
index—Fixture to look at (0 - ???)
RETURN VALUE None
SEE ALSO “tl_uwport_dump_fixture_slot”, “tl_uwport_dump_one_port”,
“tl_uwport_dump_de_embed_file”
tl_uwport_dump_one_port
S-parameter debugging function.
SYNOPSIS void tl_uwport_dump_one_port(pin, index)
int pin, index;
DESCRIPTION The UWPORT software stores an array of 1-port s-parameter
calibration data for each schan. By specifying the index into this
array when calling this function, you can look at any 1-port data
you want, whether internal or external.
Likely values for index can be obtained from
tl_uwport_dump_closest_freq(), tl_uwport_dump_port(),
or a previous call to tl_uwport_dump_one_port(). Also, it is
possible to write all of the 1-port data to a file using:
biggest index ---vvv pin ----vvvvvv
imm "int i;for(i=0; i<300;i++)tl_uwport_dump_one_port(TX_OUT,i);"
>one_port_TX_OUT.log
This function prints all s-parameter data needed for 1-port s-
parameter measurements and source power de-embedding.
This function was written for software development and
debugging purposes. Many fields are terse or do not have
enough information to be generally useful. Other fields are
sometimes not relevant. However, to be sure you have all the
information you need for debugging s-parameter calibration, you
have access to all fields.
IMAGE Solutions V8.3 26-451
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Fields you are most likely to find important are flagged in the left
margin with ***.
Data for the following example was generated using this
statement after calibrating but forgetting to measure the short
standard:
imm "tl_uwport_dump_one_port_slot(21, 1, 899)"
vvv-- vvv--- index and number of calibrated points
1-port 899 of 900 (900 available)
pin = 0 (<NULL>) on site 0
freq = 3000.000000 MHz
*** type = 2 ( EXTERNAL )
^^^^^^^^-- EXTERNAL data is what you measure;
INTERNAL data is measured by the driver
--- you do not need internal data
for s-parameters if you have external
data. You need both for power
de-embedding if you do external cal.
*** internal data index = 598, next pin index = -1
^^^ ^
Internal data is used with external data for power
de-embedding. Use this index to look it up. The
internal data index will also point you to all
of the pins on this schan which have been calibrated
at this frequency; just follow the "next pin" index.
See tl_uwport_dump_one_port(<pin>, <index>)
*** source termination = 0, PA {
^--- cal data below is for this termination
valid = 0xf
OPEN = ( 1.0000 0.00); ( 1.0000 -0.15) actual
^--- measured value ^--- actual value of
of open standard open standard (from file)
file 3 = apc7_10M_open.s1p
^--- file characterizing open standard
SHORT = ( 1.0000 180.00); ( 1.0000 180.00) actual
file 7 = apc7_10M_short.s1p
LOAD = ( 0.0000 0.00); ( 0.0000 0.00) actual (ideal)
no file given; standard is ideal ---^^^^^
file 8 = <default/unset>
^--- No filename ("" or NULL) used
with read_uwport_one_port_cal_std()
RAW MATCH < NOT MEASURED >
^--- Only set for internal cal std data
(used for power de-embedding)
MATCH < NOT COMPUTED >
^--- source match (source power de-embedding)
Need INTERNAL MATCH and delta_EA3 or
RAW MATCH and OPEN, SHORT, LOAD standards
to compute MATCH.
EA3 = {s11 = ( 0.2243 109.35) s21 = ( 1.0000 0.00)
IMAGE Solutions V8.3 26-452
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
s12 = ( 0.2840 -140.95) s22 = ( 0.1433 151.51) }
^--- 3 term error adapter for s-param cal
All 3 fields, OPEN, SHORT, and LOAD,
must be filled in to compute EA3.
cfg bd gain = < NOT COMPUTED >
^--- config board has this much loss. Power
de-embedding only. (0 to -1 dB typical)
Only filled in for power de-embedding.
}
source termination = 1, -20 dB {
^-- below -30 dBm (949-310-12)
valid = 0x3
OPEN = ( 1.0000 0.00); ( 1.8587 -46.75) actual
^--- internal data
may have |gamma| > 1
file 0 = tl_eedata 0 21 43
^^^^^^-- eeprom data (INTERNAL
standards only; never EXTERNAL)
SHORT = ( 1.0000 180.00); ( 1.1196 150.31) actual
file 1 = tl_eedata 0 21 47
LOAD = < NOT MEASURED --> *** BAD *** >
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You need all 3 standards at once to do
s-parameters or power de-embedding.
MATCH = < NOT COMPUTED >
^^^^^^^^^^^^---- can be found from OPEN,
SHORT, and LOAD data when have INTERNAL
OPEN, SHORT, LOAD, and RAW MATCH data also.
EA3 = { < NOT COMPUTED > }
^^^^^^^^^^^^^-- can find this if have
OPEN, SHORT, and LOAD
cfg bd gain = < NOT COMPUTED >
^^^^^^^^^^^^-- Need MATCH to find
this. Used only for power de-embedding.
}
source termination = 2, -64 dB { < NOT CALIBRATED > }
^-- below -73 dBm (949-310-12)
or using add path to cross
source over to other side
load termination = 3, ADD { < NOT CALIBRATED > }
^^^-- used only for power
de-embedding. Need to do
2-port cal to fill this in.
(See "2-port indices" below.)
delta_valid = 0x0
delta_EA3 = < NOT COMPUTED >
^--- when calibrate with external standards and do power
de-embedding, delta_EA3 is computed to model fixture
between uwport and where standards attached
(or transferred to internal) (Need both internal
and external EA3 for any termination; not computed
for INTERNAL data.)
IMAGE Solutions V8.3 26-453
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
2-port indices = { < none > }
^--- There will be one index here
for each pin a 2-port measurement
was done with. See
tl_uwport_dump_two_port(<pin>, <index>).
fixture indices = { 299 }
^--- if you use multiple de_embed_file
settings for this pin, there will be
a number here for each one. See
tl_uwport_dump_fixture(<pin>, <index>).
ARGUMENTS pin—UWPORT pin
index—Number in the range 0 to # of calibrated points - 1
RETURN VALUE None
SEE ALSO “tl_uwport_dump_closest_freq”, “tl_uwport_dump_port”,
“tl_uwport_dump_one_port_slot”, “tl_uwport_dump_two_port”,
“tl_uwport_dump_fixture”, “tl_uwport_dump_de_embed_file”,
“tl_uwport_dump_1port”, “tl_uwport_dump”
tl_uwport_dump_one_port_slot
S-parameter debugging function.
SYNOPSIS void tl_uwport_dump_one_port_slot(slot,schan, index)
int slot, schan, index;
DESCRIPTION Prints out s-parameter debugging information in station window.
See “tl_uwport_dump_one_port” for a description of the output.
ARGUMENTS slot—UWPORT slot number
schan—UWPORT schan number (1-8)
index—Index into 1-port s-param data
RETURN VALUE None
SEE ALSO “tl_uwport_dump_one_port”, “tl_uwport_dump_two_port_slot”,
“tl_uwport_dump_port”
tl_uwport_dump_port
S-parameter debugging function.
SYNOPSIS void tl_uwport_dump_port(slot, schan)
int slot, schan;
DESCRIPTION Prints s-parameter information for last measurement in station
window. It is most likely to be useful when you see the following
error message:
ERROR #13640 - uwport 2: not calibrated for s-parameters on this pin at
current frequency and amplitude.
IMAGE Solutions V8.3 26-454
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
This function does not take pins as arguments. UWPORT 2 is
always in slot 21. UWPORT 1 may be in slot 4 or slot 21,
depending on how many UWPORTs you have in the test head.
Use rfdisp to figure out which schan to use. Schans are
numbered 1-4 from the top down. To determine slot and schan
information from the pinmap, slots are normally 4 and 21,
corresponding to DIB names uwport2_X and uwport1_X. DIB
names uwportX_A, uwportX_B, uwportX_C, and uwportX_D
correspond to schans 1, 2, 3, and 4 respectively. Look at the
second line of the printout to determine whether you asked for
the right data.
This printout corresponds to all information needed for a 1-port
s-parameter measurement or half of the information for a 2-port
s-parameter measurement. For a 2-port measurement, you also
need to look at the other pin of the device to get a complete
picture.
This function was written for software development and
debugging purposes. Many fields are terse or do not have
enough information to be generally useful. However, to be sure
you have all information you need for debugging s-parameter
calibration, all fields are available to you.
Before reading the output of this function, try using
tl_uwport_dump_1port() to see if you are missing an open,
short, or load standard for this frequency.
Fields you are most likely to find important are flagged in the left
margin with ***.
Data for the following example was generated with this
statement after calibrating but forgetting to measure the short
standard:
imm "tl_uwport_dump_port(21, 1)"
Dump of s-param data structures:
*** pin = 0 (using slot programming) on site 0
^--- If you have a pinmap, ^---
you should use pins
consistently to avoid problems like this
slot = 21 schan = 1 inst_num = 2
*** port 1 of a 1-port measurement, index = 899,
pass this number ^^^ to
tl_uwport_dump_one_port(<slot>, <schan>,
<index>);
*** term = 0 (PA)
^----- VERY IMPORTANT --- match this to
"source termination" below
tl_uwport_dump() will give you an ASCII
diagram of the actual hardware state, including
IMAGE Solutions V8.3 26-455
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
the gain stage, add path, and LNA states.
*** de_embed_file (-1) = ("")
^---- This should match what you
expect. See below for values.
valid = 7
raw = (0.44, 64.10) (1-port)
^--- uncalibrated (can't call a cal function until this
has a valid value)
cooked = (1.00, -179.91) (1-port)
^--- calibrated (not filled in until a readback function
called)
1-port 899 of 900 (900 available)
pin = 0 (<NULL>) on site 0
freq = 3000.000000 MHz
type = 2 ( EXTERNAL )
*** internal data index = 598, next pin index = -1
^^^ ^
Internal data is used with external data for power
de-embedding. Use this index to look it up. The
internal data index will also point you to all
of the pins on this schan which have been calibrated
at this frequency; just follow the "next pin" index.
See tl_uwport_dump_one_port(<pin>, <index>)
*** source termination = 0, PA {
^--- cal data below is for this termination
valid = 0xf
OPEN = ( 0.2631 170.95); ( 1.0000 0.00) actual
(ideal)
^--- measured value ^--- actual value of
of open standard standard, from file
file -1 = <default/unset>
^-- file of values for standard
(none supplied here --> ideal)
SHORT = ( 0.4398 64.06); ( 1.0000 180.00) actual
(ideal)
file -1 = <default/unset>
LOAD = ( 0.2243 109.35); ( 0.0000 0.00) actual
(ideal)
file -1 = <default/unset>
RAW MATCH < NOT MEASURED >
^--- Only set for internal cal std data
(used for power de-embedding)
MATCH < NOT COMPUTED >
^--- source match (source power de-embedding)
EA3 = {s11 = ( 0.2243 109.35) s21 = ( 1.0000 0.00)
s12 = ( 0.2840 -140.95) s22 = ( 0.1433 151.51)
}
^--- 3 term error adapter for s-param cal
All 3 fields, OPEN, SHORT, and LOAD,
must be filled in to compute EA3.
cfg bd gain = < NOT COMPUTED >
IMAGE Solutions V8.3 26-456
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
^--- config board has this much loss. Scalar
de-embedding only. (0 to -1 dB typical)
}
source termination = 1, -20 dB { < NOT CALIBRATED > }
^-- below -30 dBm (949-310-12)
source termination = 2, -64 dB { < NOT CALIBRATED > }
^-- below -73 dBm (949-310-12)
load termination = 3, ADD { < NOT CALIBRATED > }
^-- uwrecv power de-embedding
delta_valid = 0x0
delta_EA3 = < NOT COMPUTED >
^--- when calibrate with external standards and do power
de-embedding, delta_EA3 is computed to model fixture
between uwport and where standards attached
(or transferred to internal)
*** 2-port indices = { 0 }
^--- pass these numbers to
tl_uwport_dump_two_port()
*** fixture indices = { 299 }
^--- if you use multiple de_embed_file
settings for this pin, there will be
a number here for each one.
See tl_uwport_dump_fixture()
2-port 0 of 60 (75 available)
^--- should be a number in "2-port indices" list above
and match "index" below
*** pin = 4 (D) on site 0
^--- other pin in a 2-port measurement
(won't see if using slot programming)
*** slot = 21 schan = 4 inst_num = 2
^--- important!
port 2 of a 2-port measurement,
^---- If this isn't a 2, something is seriously wrong.
(driver bug, ^C at bad time)
*** index = 0,
should match 2-port # above ---^
*** term = 3 (ADD)
2-port (load) termination ---^
ADD indicates a terminated switch at the
add path is terminating the receive path.
Should have this for 2-port s-parameters and
uwrecv measurements.
LNA is possible for uwrecv measurements.
(power de-embedding)
PA
-20 dB
-64 dB
These are generally bad news for a load
termination; check your code to make sure you
haven't forgotten to disconnect a source. If
you are deliberately driving the measure pin of
the DUT during 2-port s-parameter measurements
IMAGE Solutions V8.3 26-457
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
(to prevent oscillation?) you should make sure
the driving source is at a frequency not too
close to the frequency of the s-parameter
measurement. For uwrecv measurements, these
terminations will cause the uwrecv cal constant
to be incorrect, regardless of whether you are
using power de-embedding or not.
valid = 8
*** raw = (0.60, -5.56) (2-port)
^--- uncalibrated (can't call a cal or readback function
until this has a valid value)
cooked = < INVALID >
^--- calibrated (not filled in until a readback function
called)
fixture 299 refers to 1-port 899; next fixture is -1
de_embed_file (299) = ("")
valid = 1
fixt (299) = {s11 = ( 0.0000 0.00) s21 = ( 1.0000 0.00)
s12 = ( 1.0000 0.00) s22 = ( 0.0000 0.00)}
One useful debugging technique is to print this structure out and
save it for each cal standard you measure, then compare those
to each other and to the structure in use for the actual
measurement.
Usually, you will be able to see that you are using a termination
which has not been calibrated (wrong amplitude) or that a
standard was missed during cal.
To debug the calibration code, you can insert an explicit function
call to your code in the beginning of main() (perhaps using if
(switchvar_x)) so you can run to trap in the calibration code.
ARGUMENTS slot, schan—UWPORT slot and schan
RETURN VALUE None
SEE ALSO “tl_uwport_dump_one_port”, “tl_uwport_dump_one_port_slot”,
“tl_uwport_dump_two_port”, “tl_uwport_dump_fixture”,
“tl_uwport_dump_de_embed_file”, “tl_uwport_dump_1port”,
“tl_uwport_dump”
tl_uwport_dump_s_param_timing
Debug s-parameter captures.
SYNOPSIS void tl_uwport_dump_s_param_timing(set_samp_size)
int set_samp_size;
DESCRIPTION printf()s information about s-parameter timing to the station
window. Also optionally sets the UWRECV sample size so wave
-c_mem works correctly.
IMAGE Solutions V8.3 26-458
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS set_samp_size—Boolean: set UWRECV sample size or not
RETURN VALUE None
tl_uwport_dump_two_port
2-port s-parameter debug.
SYNOPSIS void tl_uwport_dump_two_port(pin, idx)
int pin, idx;
DESCRIPTION Dumps the appropriate 2-port data struct to the station window.
2-port data describes the results of measuring the thru and
isolate calibration standards. 2-port data is usually only useful
when combined with 1-port data. As with the 1-port data, IMAGE
stores this information in an array, and any entry can be
accessed using the idx parameter.
Usually the idx parameter can be found by looking at the 2-port
indices = { 1 } section of a 1-port dump function output. To
send all of the values to a file, use:
imm "int i;for(i=0; i<300; i++)tl_uwport_dump_two_port(TX_OUT,i);
">two_port_TX_OUT.log
Lining the 2-port files up with the 1-port files can help make
everything make more sense.
2-port 1 of 31:
^---- max idx + 1
pin 0 (<NULL>), slot 21, schan 1: 1-port = 0 (10.000 MHz)
-^-
pass this index to tl_uwport_dump_one_port()
pin 0 (<NULL>), slot 21, schan 4: 1-port = 0 (10.000 MHz)
^ frequencies had better match! ---^
+--- If one of these has a pin number, both should have
pin numbers. No pin number means either slot
programming or internal cal standard data.
Note that this is not necessarily the pin you
asked for!
Cal data associated with slot 21 schan 1:
source termination = PA,
^--- VERY IMPORTANT - 1-port cal data
must exist for this termination
load termination = ADD
VERY IMPORTANT ---^ This must
describe the termination seen by
the pin attached to the pin named above.
See tl_uwport_dump_port(<slot>).
load match = (0.00, 0.00)
^--- ideally this is a small number;
it is gamma of the receive channel.
IMAGE Solutions V8.3 26-459
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
xmit track = (1.00, 0.00)
^--- ideally this is a larger number;
it describes the gain of the fixture when
an ideal thru is connected.
isolation = < NOT MEASURED >
^--- describes isolation between pins.
This parameter does NOT have to be
valid; isolation is an optional
calibration. Smaller values are better.
raw load match = (0.00, 0.00)
^--- must be filled in for 2-port
s-parameter measurements or receive
power de-embedding. (Used to generate
load match.) If this is invalid, the
THRU standard was not measured for
this termination.
raw xmit track = (1.00, 0.00)
^--- must be filled in for 2-port
s-parameter measurements. If this is
invalid, the THRU standard was not
measured for this termination.
thru std 5 = tl_eedata thru
^--- this is an internal standard,
described by eeprom data. You should
see your thru standard file name here
for external standard data.
{ s11 = ( 0.1197 22.40) s21 = ( 2.0440 1.56)
s12 = ( 2.0481 1.61) s22 = ( 0.0744 6.61)}
^-- The internal thru can have values that
are greater than 1. (This is OK!)
thru std is not reversed
^--- If you measured the thru with the above
pin listed first in "ports =" and "s_params:
forward" then this is what you should expect.
The driver expects the s11 end of the thru
standard (as described in the file) to be
attached to this pin.
valid = 0x1e
^--- driver writer's debug info
Cal data associated with slot 21 schan 4:
source termination = PA, load termination = ADD
load match = (0.00, 0.00)
xmit track = (1.00, 0.00)
isolation = (0.00, 0.00)
raw load match = (0.00, 0.00)
raw xmit track = (1.00, 0.00)
thru std 5 = tl_eedata thru
thru std is reversed
valid = 0x1f
source termination = -20 dB, load termination = ADD
^--- It is possible for multiple
source and load terminations to
IMAGE Solutions V8.3 26-460
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
be calibrated.
For the 949-310-12 uwport:
PA --> source amp > -30 dBm
-20 dB --> source amp > -73 dBm
-64 dB --> source amp < -73 dBm
or add path used to
send signal across uwport
ADD --> "normal" termination
(terminated switch of
add path)
LNA --> lna: on
The three GAIN settings are also legal
for s-parameters, but not for power
(uwrecv) de-embedding. They probably
indicate a bug. (source not
disconnected from receive pin)
load match = < NOT COMPUTED >
^--- this is OK because raw load match is OK
xmit track = < NOT COMPUTED >
^--- this is OK because raw xmit track is OK
isolation = < NOT MEASURED (OK) >
^--- isolation cal is optional --> there
does not have to be a number here.
raw load match = < NOT MEASURED --> *** BAD *** >
^--- This is very bad. Without the
load match, cannot do 2-port
s-parameters or power de-embedding.
(Measured with THRU std attached.)
raw xmit track = (0.00, 0.00)
^--- This is bad! it will cause a CPU
floating point operand ALARM (divide by
zero) in the s-param cal math.
(Caused by using a 1-port s-param .wav
file on the simulator when 2-port
capture needed.) (Should be a
relatively large number.)
raw xmit track is needed for 2-port
measurements. (measured with thru)
thru std 14 = /u/checkers/standards/ideal_thru.s2p
^--- sample non-eeprom thru standard data.
(will not co-exist with internal data)
{ s11 = ( 0.0000 0.00) s21 = ( 1.0000 0.00)
s12 = ( 1.0000 0.00) s22 = ( 0.0000 0.00)}
^--- an ideal thru std has
s11 = s22 = (0, 0) and s21 = s12 = (1, 0).
thru std is reversed
valid = 0x6
This function was written for debugging software code. It
contains some useful information and some that is less useful.
This function provides access to all the information.
IMAGE Solutions V8.3 26-461
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS pin—UWPORT pin
idx—Index of 2-port s-parameter structure (0 - ???)
RETURN VALUE None
SEE ALSO “tl_uwport_dump_two_port_slot”, “tl_uwport_dump_one_port”,
“tl_uwport_dump”
tl_uwport_dump_two_port_slot
2-port s-parameter debug.
SYNOPSIS void tl_uwport_dump_two_port_slot(slot_in, schan_in,
idx)
int slot_in, schan_in, idx;
DESCRIPTION Dumps the appropriate 2-port data struct to the station window.
See tl_uwport_dump_two_port for details.
ARGUMENTS slot_in—UWPORT slot number
schan_in—UWPORT schan number (1-8)
idx—Index of 2-port s-parameter structure
RETURN VALUE None
SEE ALSO “tl_uwport_dump_two_port”
tl_uwport_free_data
Free() memory used by s-parameter cal.
SYNOPSIS void tl_uwport_free_data()
DESCRIPTION Releases memory used to keep track of s-parameter calibration
data and de-embed files. This forces s-parameter calibration to
be completely re-done, including re-reading all de-embed files
and files which characterize cal standards. The driver will also
“forget” whether you are using internal or external standard
calibration and allow you to change from external to internal.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Invalidates s-parameter calibration.
SEE ALSO “tl_uwport_invalidate_s_param_cal”,
“tl_uwport_invalidate_s_param_cal_slot”,
“tl_uwport_invalidate_s_param_cal_all”
tl_uwport_get_num_chans_slot
Find number of channels for the given UWPORT.
IMAGE Solutions V8.3 26-462
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_uwport_get_num_chans_slot(port_slot)
int port_slot;
DESCRIPTION Returns the number of DUT accessible channels provided by the
port module at the given slot number
ARGUMENTS port_slot—Test head slot number of UWPORT
RETURN VALUE Number of channels: 4 or 8 or 0 if UWPORT is not in the given
slot.
tl_uwport_hw_version
Return UWPORT hardware version number.
SYNOPSIS int tl_uwport_hw_version(slot)
int slot;
DESCRIPTION Returns UWPORT hardware version number. Current hardware
versions are:
0 949-310-00
1 949-310-01
2 949-310-02
3 803-596-00
4 803-596-0[1-2]
If rev dates become significant, requiring a change in calibration
or software behavior, they will be considered in addition to the
dash number.
ARGUMENTS slot—UWPORT slot number
RETURN VALUE Hardware version number
tl_uwport_inst_slot
Slot number for connected source/measure.
SYNOPSIS int tl_uwport_inst_slot(slot, inst)
int slot, inst;
DESCRIPTION Returns slot numbers for connected source and measure
instruments. “Connected” is defined as a channel card in the test
head of a type the UWPORT software recognizes (such as
UHFCC or UHFMM) with a configuration board cable connecting
it to the UWPORT.
ARGUMENTS slot—UWPORT slot number
inst—Instrument to return number for:
1 = source 1
2 = source 2
3 = measure
IMAGE Solutions V8.3 26-463
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Slot number
SEE ALSO “tl_uwport_receiver_slot”
tl_uwport_invalidate_s_param_cal
Invalidate s-parameter calibration for one UWPORT.
SYNOPSIS void tl_uwport_invalidate_s_param_cal(pin)
int pin;
DESCRIPTION Invalidates s-parameter calibration for specified UWPORT. Does
not force any files to be reread.
If you calibrate before all existing calibration data is invalidated,
the new calibration data will not change the time stamp from the
original calibration because some of the old calibration data may
still be left after the cal. This function removes any data that can
cause this problem. Calling it before you begin s-parameter
calibration is recommended.
Calling this function while current cal data is still valid causes the
next calibration to reset the calibration time.
To change the files used for de-embedding or characterizing
external cal standards, use tl_uwport_free_data. This function
also allows you to change between internal and external
standard calibration.
ARGUMENTS pin—UWPORT pin
RETURN VALUE None
SIDE EFFECTS Invalidates s-parameter calibration.
tl_uwport_invalidate_s_param_cal_all
Invalidate s-parameter calibration on all UWPORTs.
SYNOPSIS void tl_uwport_invalidate_s_param_cal_all()
DESCRIPTION Invalidates s-parameter calibration for all UWPORTs in test
head. Forces recalibration for all points without forcing all files to
be reread.
If you calibrate before all existing calibration data is invalid, the
new calibration data will not change the time stamp from the
original calibration because some of the old calibration data may
still be left after the cal. This function removes any data that can
cause this problem. Calling it before you begin s-parameter
calibration is recommended.
IMAGE Solutions V8.3 26-464
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Calling this function while current cal data is still valid causes the
next calibration to reset the calibration time.
To change the files used for de-embedding or characterizing
external cal standards, use tl_uwport_free_data.
tl_uwport_free_data also allows you to change between internal
and external standard calibration.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS Invalidates s-parameter calibration.
SEE ALSO “tl_uwport_free_data”
tl_uwport_invalidate_s_param_cal_slot
Invalidate s-parameter calibration for one UWPORT.
SYNOPSIS void tl_uwport_invalidate_s_param_cal(slot)
int slot;
DESCRIPTION Invalidates s-parameter calibration for the specified UWPORT.
Does not force any files to be reread. If you calibrate before all of
existing calibration data is invalidated, the new calibration data
will not change the time stamp from the original calibration
because some of the old calibration data may be left after the cal.
This function removes any data that can cause this problem;
calling it before you begin s-parameter calibration is
recommended.
Calling this function while current cal data is still valid causes the
next calibration to reset the calibration time.
To change the files used for de-embedding or characterizing
external cal standards, use tl_uwport_free_data. This function
also allows you to change between internal and external
standard calibration.
ARGUMENTS slot—UWPORT slot (affects all schans)
RETURN VALUE None
SIDE EFFECTS Invalidates s-parameter calibration.
SEE ALSO “tl_uwport_free_data”, “tl_uwport_invalidate_s_param_cal_all”
tl_uwport_lna
Report whether the UWPORT lna is on or not.
SYNOPSIS int tl_uwport_lna(pin)
int pin;
IMAGE Solutions V8.3 26-465
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Returns true or false depending on whether the lna parameter
for the UWPORT is set to on or off for a given pin. For pins on
the side of the UWPORT that does not have an lna, the result is
always false.
ARGUMENTS pin—UWPORT pin name/number from pinmap
RETURN VALUE Boolean (int)—True if lna is on and false otherwise
tl_uwport_noise_source_present
Noise source option present?
SYNOPSIS int tl_uwport_noise_source_present(pin)
int pin
DESCRIPTION Returns an integer indicating the noise is or is not present for the
indicated pin.
ARGUMENTS pin—UWPORT pin
RETURN VALUE 1—Noise source present
0—Noise source not present
SEE ALSO “tl_uwport_noise_source_present_slot”
tl_uwport_noise_source_present_slot
Noise source present?
SYNOPSIS int tl_uwport_noise_source_present_slot(slot, schan)
int slot;
int schan;
DESCRIPTION Returns an int indicating the noise source’s presence or not.
ARGUMENTS slot —Test head slot number
schan—1-4
RETURN VALUE 1: Noise source present
0: Noise source does not present
SEE ALSO “tl_uwport_noise_source_present”, “tl_uwport_config”
tl_uwport_num_user_chans
Return the number of user channels.
SYNOPSIS int tl_uwport_num_user_chans(slot)
int slot;
DESCRIPTION Return the number of user channels for the UWPORT module at
the given slot #: 4 or 8
IMAGE Solutions V8.3 26-466
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS slot—UWPORT slot number
RETURN VALUE User visible channel number
tl_uwport_pin_to_slot_and_schan
Convert UWPORT pin to slot and schan.
SYNOPSIS int tl_uwport_pin_to_slot_and_schan(pin,slot, schan)
int pin, *slot, *schan;
DESCRIPTION Returns the slot and schan for a pin connected to a UWPORT in
the variables slot and schan. slot and schan are set to 0 in the
event of an error. NULL pointers can be passed for slot or
schan.
ARGUMENTS pin—UWPORT pin
slot—Pointer to the variable to write the slot number into
schan—Pointer to the variable to write the schan number into
RETURN VALUE UWPORT instrument number if no error (1 or 2)
0 if error
SEE ALSO “tl_uwport_config”
tl_uwport_read_match_and_measure_gain
Power de-embed data.
SYNOPSIS int tl_uwport_read_match_and_measure_gain(pin, freq,
match, gain)
int pin;
double freq;
D_COMPLEX *match;
double *gain;
DESCRIPTION Returns the test system load match and gain for the current
hardware state.
If power_de_embed:off, the load match is at the configuration
board plane and the gain is zero.
If power_de_embed:on, the load match is looking into the de-
embed files and gain represents the gain from the end of the de-
embed files to the configuration board (signal traveling from DUT
to system).
This function takes a frequency parameter so multi-tone or
modulated signals and harmonics can be calibrated.
The following parameters affect the values returned by this
function:
IMAGE Solutions V8.3 26-467
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
lna: on/off
add: on/off
source amp
de_embed_file
power_de_embed: on/off
gamma
connect
As always, the care with which s-parameter calibration is done
and with which the de-embed files were generated directly
affects the results.
The gain returned by this function is identical to the gain from
tl_uwport_read_match_and_source_gain if the fixture is
reciprocal. Match is always the same.
ARGUMENTS pin—UWPORT pin number
freq—Frequency
match—Gamma of the system (and fixture if
power_de_embed:on)
gain—Gain to config board
RETURN VALUE 0 = Success
-1 = Failure
SEE ALSO “tl_uwport_read_match_and_measure_gain”,
“tl_uwport_read_match_and_source_gain_slot”
tl_uwport_read_match_and_measure_gain_slot
Power de-embed data.
SYNOPSIS int
tl_uwport_read_match_and_measure_gain_slot(slot,
schan, freq, match, gain)
int slot;
int schan;
double freq;
D_COMPLEX *match;
double *gain;
DESCRIPTION Returns the test system load match and gain for the current
hardware state. See tl_uwport_read_match_and_measure_gain
for details. If you used pin programming to calibrate for
s-parameters, use tl_uwport_read_match_and_measure_gain.
ARGUMENTS slot, schan—UWPORT slot and schan
freq—Frequency
match—Gamma of the system
gain—Gain to config board
IMAGE Solutions V8.3 26-468
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 0 = Success
-1 = Failure
SEE ALSO “tl_uwport_read_match_and_measure_gain”,
“tl_uwport_read_match_and_source_gain_slot”
tl_uwport_read_match_and_source_gain
Power de-embed data.
SYNOPSIS int tl_uwport_read_match_and_source_gain(pin, freq,
match, gain)
int pin;
double freq;
D_COMPLEX *match;
double *gain;
DESCRIPTION Returns the test system source match and gain for the current
hardware state. If power_de_embed:off, the source match is at
the config board and the gain is zero. If power_de_embed:on, the
source match is looking into the de-embed files and gain
represents the gain from the end of the de-embed files to the
config board (signal traveling from system to DUT).
This function takes a frequency parameter so multitone or
modulated signals and harmonics can be calibrated.
The following parameters affect the values returned by this
function:
lna: on/off
add: on/off
source amp
de_embed_file
power_de_embed
gamma
connect
As always, the care with which s-parameter calibration is done
and with which the de-embed files were generated directly
affects the results.
The gain returned by this function is the same as the gain from
tl_uwport_read_match_and_measure_gain if the fixture is
reciprocal. Match is always the same.
ARGUMENTS pin—UWPORT pin number
freq—Frequency
match—Gamma of the system
gain—Gain to specified cal_plane
RETURN VALUE 0 = Success
-1 = Failure
IMAGE Solutions V8.3 26-469
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “tl_uwport_read_match_and_measure_gain”,
“tl_uwport_read_match_and_source_gain”
tl_uwport_read_match_and_source_gain_slot
Power de-embed data.
SYNOPSIS int tl_uwport_read_match_and_source_gain_slot(slot,
schan, freq, match, gain)
int slot;
int schan;
double freq;
D_COMPLEX *match;
double *gain;
DESCRIPTION Returns the test system source match and gain for the current
hardware state. See tl_uwport_read_match_and_source_gain
for details. If you used pin programming to calibrate for
s-parameters, use tl_uwport_read_match_and_source_gain.
ARGUMENTS slot, schan—UWPORT slot and schan
freq—Frequency
match—Gamma of the system
gain—Gain to end of de_embed_file if power_de_embed:on
RETURN VALUE 0 = Success
-1 = Failure
SEE ALSO “tl_uwport_read_match_and_measure_gain”,
“tl_uwport_read_match_and_source_gain”
tl_uwport_read_power_de_embed
Read power_de_embed state.
SYNOPSIS int tl_uwport_read_power_de_embed(pin)
int pin;
DESCRIPTION Returns the state of the power_de_embed parameter.
ARGUMENTS pin—UWPORT pin number
RETURN VALUE ON or OFF
SEE ALSO “tl_uwport_read_power_de_embed”
tl_uwport_read_power_de_embed_slot
Read power_de_embed state.
IMAGE Solutions V8.3 26-470
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_uwport_read_power_de_embed_slot(slot, schan)
int slot;
int schan;
DESCRIPTION Returns the state of the power_de_embed parameter.
ARGUMENTS slot—UWPORT slot number
schan—1, 2, 3, or 4, corresponding to UWPORT_A, B, C, or D
RETURN VALUE ON or OFF
SEE ALSO “tl_uwport_read_power_de_embed”
tl_uwport_read_s1p
Read 2-port s-parameter file (.s1p).
SYNOPSIS int tl_uwport_read_s1p(filename, freqs, s_params,
max_num_s_params)
char *filename;
double *freqs;
D_COMPLEX *s_params;
int max_num_s_params;
DESCRIPTION Reads the named .s1p file into the arrays freqs and s_params,
up to the max_num_s_params such that freqs[i] corresponds
to s_params[i]. The actual number of s-parameters read is
returned. Only the first 255 characters on a line are significant.
ARGUMENTS filename—String such as /u/checkers/data/lna_in.s1p
freqs[LENGTH]—Double precision array of frequencies, filled in
by function
s_params[LENGTH]—D_COMPLEX array of s-parameter data in
(real, imaginary) format. Filled in by function.
max_num_s_params—Typically LENGTH of arrays.
RETURN VALUE Number of s-parameters actually read. 0 usually indicates an
error of some kind.
SEE ALSO “tl_uwport_write_s1p”, “tl_uwport_write_s1p_fmt”,
“tl_uwport_read_s2p”, DSP documentation for definition of
D_COMPLEX
tl_uwport_read_s2p
Read 2-port s-parameter file (.s2p).
SYNOPSIS int tl_uwport_read_s2p(filename, freqs, s11, s21,
s12, s22, max_num_s_params)
char *filename;
double freqs[];
D_COMPLEX s11[];
IMAGE Solutions V8.3 26-471
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
D_COMPLEX s12[];
D_COMPLEX s21[];
D_COMPLEX s22[];
int max_num_s_params;
DESCRIPTION Reads the named .s2p file into the arrays freqs, s11, s21, s12,
and s22 up to the max_num_s_params such that freqs[i]
corresponds to s11[i], s21[i], and so on. The actual number
of s-parameters read is returned. Note that the order of the
columns in a .s2p file is:
frequency s11 s21 s12 s22
Each of the four s-parameters takes two columns, corresponding
to “real” and “imaginary” for the RI format, magnitude and angle
(argument) for the MA format, and 20*log10(magnitude) and
angle for the DB format.
Regardless of the format of the data in the file, the values written
into the s11, s12, s21, and s22 arrays will be in (real, imaginary)
format.
Only the first 255 characters on a line are significant.
ARGUMENTS filename—String such as /u/checkers/data/lna.s2p or
hi.s2p
freqs[LENGTH]—Frequencies for each s-parameter
measurement
s11[LENGTH]—(real, imaginary) formatted D_COMPLEX value of
s11
s21[LENGTH]—(real, imaginary) formatted D_COMPLEX value of
s21
s12[LENGTH]—(real, imaginary) formatted D_COMPLEX value of
s12
s22[LENGTH]—(real, imaginary) formatted D_COMPLEX value of
s22
max_num_s_params—Typically LENGTH of arrays
RETURN VALUE Number of s-parameters actually read.
0 usually indicates an error of some kind.
SEE ALSO “tl_uwport_write_s2p”, “tl_uwport_write_s2p_fmt”,
“tl_uwport_read_s2p”, DSP documentation for definition of
D_COMPLEX
tl_uwport_receiver_slot
Find slot of UWMM attached to UWPORT.
SYNOPSIS int tl_uwport_receiver_slot(port_slot)
int port_slot;
IMAGE Solutions V8.3 26-472
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Returns the slot number of the UWMM/UWRECV attached to
UWPORT in slot port_slot or 0 if none is present.
ARGUMENTS port_slot—UWPORT test head slot number
RETURN VALUE Slot number of measure instrument attached to UWPORT (0 if
none)
SEE ALSO “tl_uwport_config”, “tl_uwport_pin_to_slot_and_schan”
tl_uwport_set_gain_error_limits
Power de-embed error check.
SYNOPSIS int tl_uwport_set_gain_error_limits(pin,lower,
upper)
int pin;
double lower;
double upper;
DESCRIPTION Sets the error threshold for the gain power de-embedding will
apply for a given UWPORT channel. Example:
You have a DIB with a 20 dB pad on it. By default, IMAGE will
complain because it assumes there will be less than 10 dB of
loss. Since you know the loss will always be there, you want to
make sure power de-embedding is working correctly, so you set
the new limits accordingly using:
tl_uwport_set_gain_error_limits(<pin>, -15.0, -25.0);
Leaving headroom is a good idea because loss will change from
fixture to fixture and tester to tester.
Note that these limits are on a per-schan basis. If you have two
pins on a single UWPORT channel, they will both have the same
limits.
ARGUMENTS pin—Pin number these limits are to apply to
lower—Lower limit
upper—Upper limit
RETURN VALUE >=0—OK
<0—error
SIDE EFFECTS Changes when error 13677 happens
tl_uwport_set_gain_error_limits_slot
Power de-embed error check
SYNOPSIS int tl_uwport_set_gain_error_limits_slot(slot,
schan,
lower, upper)
IMAGE Solutions V8.3 26-473
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int slot;
int schan;
double lower;
double upper;
DESCRIPTION Sets the error threshold for the gain power de-embedding will
apply for a given UWPORT channel.
Example: you have a DIB with a 20 dB pad on it. By default, the
driver will complain because it assumes there will be less than
10dB of loss. Since you know the loss will always be there, you
want to make sure power de-embedding is working correctly, so
you set the new limits accordingly:
tl_uwport_set_gain_error_limits_slot(21, 1, -15.0, -25.0);
Leaving headroom is a good idea because loss will change from
fixture to fixture and tester to tester.
ARGUMENTS slot—UWPORT slot number
schan—UWPORT schan
lower—Lower limit
upper—Upper limit
RETURN VALUE >= 0—OK
< 0—Error
SIDE EFFECTS Changes when error 13677 is triggered
tl_uwport_set_interpolation_frequency_range
Power de-embedding interpolation.
SYNOPSIS void tl_uwport_set_interpolation_frequency_range
(range)
double range;
DESCRIPTION Power de-embedding does not require s-parameter calibration at
every frequency. By default, if you calibrate for s-parameters
every 10MHz, you can do power de-embedding at any
frequency between those points.
However, if a fixture does not have a flat frequency response,
you may experience large amplitude errors. This typically shows
up as a series of humps in the data as you sweep frequency.
To shut this feature off to make sure you calibrate at every
frequency, call this function with the range 0.0.
If you know a fixture is flat, you may want to increase the
frequency range to 20 or 30MHz. Be aware that the UWPORT
source match and load match are not flat, so you must allow for
that as well.
IMAGE Solutions V8.3 26-474
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Note that range is the maximum distance a point can be from the
two closest s-parameter cal points. If you calibrate every 20MHz,
setting range to 20E6 allows you to program any frequency
between the two.
Extrapolation beyond s-parameter cal points is not allowed as
errors get very large quickly.
ARGUMENTS range—Maximum distance a point can be from the closest s-
parameter cal points for interpolation to be allowed
RETURN VALUE None
tl_uwport_simulate_capture
Set results of s-parameter capture.
SYNOPSIS void tl_uwport_simulate_capture(pin, s11, s21)
int pin;
D_COMPLEX s11;
D_COMPLEX s21;
DESCRIPTION Replaces the results of the most recent start statement with the
passed s-parameter values.
start uwport: s_params: s11—Passed value of s21 is
ignored.
start uwport: s_params: forward—s11 and s21 are filled in
with passed values.
start uwport: s_params: reverse—s22 and s12 are filled in
with passed values.
This allows you to make actual s-parameter measurements on
hardware then use them on the simulator. This can be used for
raw device and cal standard measurements.
Note: This function is not ignored on hardware. If you do not
want this function to be used except on the simulator, use:
if (tl_using_simulator)
tl_uwport_simulate_capture(PIN, s11, s21);
A possible use of this function on hardware is averaging. Make
multiple raw captures, average them, then write the result back
into the driver with this function, then call the normal calibrated
readback function.
ARGUMENTS pin—UWPORT pin number. Must have been used in a start
uwport statement for readbacks to work correctly.
s11—Value of reflect portion of s-param measurement
s21—Value of transmit portion of s-param measurement
RETURN VALUE None
IMAGE Solutions V8.3 26-475
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Clobbers results of most recent s-parameter capture at
UWPORT output specified by pin. (If multiple pins connected to
same UWPORT output, they are all affected.)
tl_uwport_simulate_capture_slot
Set results of s-parameter capture.
SYNOPSIS void tl_uwport_simulate_capture_slot(slot, schan,
s11, s21)
int slot, schan;
D_COMPLEX s11;
D_COMPLEX s21;
DESCRIPTION Replaces the results of the most recent start statement with the
passed s-parameter values.
start uwport: s_params: s11—passed value of s21 is
ignored.
start uwport: s_params: forward—s11 and s21 are filled in
with passed values.
start uwport: s_params: reverse—s22 and s12 are filled in
with passed values.
This allows you to make actual s-parameter measurements on
hardware then use them on the simulator. This can be used for
raw device and cal standard measurements.
Note: This function is not ignored on the hardware. If you do not
want this function to be used except on the simulator, use
if (tl_using_simulator)
tl_uwport_simulate_capture_slot
(slot, schan, s11, s21);
A possible use of this function on hardware is averaging. Make
multiple raw captures, average them, then write the result back
into the driver with this function, then call the normal calibrated
readback function.
ARGUMENTS slot—UWPORT slot number
schan—UWPORT schan number (1-4)
s11—Value of reflect portion of s-param measurement
s21—Value of transmit portion of s-param measurement
RETURN VALUE None
SIDE EFFECTS Clobbers results of most recent s-param capture on schan
tl_uwport_source_freq_range
Maximum and minimum UWPORT source frequencies.
IMAGE Solutions V8.3 26-476
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_uwport_source_freq_range(pin, max, min)
int pin;
double *max;
double *min;
DESCRIPTION Returns the maximum and minimum frequency the UWPORT
can source. This is a function of both UWPORT and source
hardware limitations. Note that the frequency range can change
if the source is being modulated.
If there is a source directly behind this schan, the frequency limits
of that source will be considered.
If there is no source behind this schan and add: on, source 1 will
be considered. (source 1 must always be present for a legal
UWPORT configuration)
ARGUMENTS pin—UWPORT pin
max—Highest frequency UWPORT can be programmed to
source
min—Lowest frequency UWPORT can be programmed to
source
RETURN VALUE 1—OK
0—No source
-1—Bad slot or schan
tl_uwport_source_freq_range_slot
Maximum and minimum UWPORT source frequencies
SYNOPSIS int tl_uwport_source_freq_range_slot(slot, schan,
max, min)
int slot;
int schan;
double *max;
double *min;
DESCRIPTION Returns the maximum and minimum frequency the UWPORT
can source. This is a function of both UWPORT and source
hardware limitations. If there is a source directly behind this
schan, the frequency limits of that source will be considered. If
there is no source behind this schan and add: on, source 1 will
be considered. (source 1 must always be present for a legal
UWPORT configuration)
ARGUMENTS slot—UWPORT slot number
schan—UWPORT schan
max—Highest frequency UWPORT can be programmed for
min—Lowest frequency UWPORT can be programmed for
IMAGE Solutions V8.3 26-477
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE 1—OK
0—No source
-1—Bad slot or schan
SEE ALSO “tl_uwport_pin_to_slot_and_schan”,
“tl_uwport_source_freq_range”
tl_uwport_s_param_sample_size
Read back s-parameter capture size.
SYNOPSIS int tl_uwport_s_param_sample_size()
DESCRIPTION Returns the number of samples in the last s-parameter capture.
To prevent the UWRECV sample size from being clobbered by
s-parameter measurements, IMAGE saves and restores the
sample size during start uwport statements. For example:
int samp_size;
* uwrecv sample_size is some_value *
start pin = A uwport:
s_params: s11;
* uwrecv sample_size is still some_value *
samp_size = tl_uwport_s_param_sample_size();
set pin = A uwrecv:
sample_size = samp_size;
* uwrecv sample size is now the same as it was during
the last s-param capture. Note that 1-port and
2-port s-param captures are of different sizes *
* "wave -c_mem" should now show the s-param capture
correctly. *
* move the first 1k samples of the s-param capture
to the array processor *
move c_mem
to: dsp_data = AP_cmem size = 1024;
ARGUMENTS None
RETURN VALUE UWRECV sample size from last s-parameter capture
SEE ALSO “tl_uwport_dump_s_param_timing”
tl_uwport_s_param_snr_test_enable
S-param capture quality testing.
SYNOPSIS int tl_uwport_s_param_snr_test_enable(enable)
int enable;
DESCRIPTION Enables driver tests which detect bad s-parameter captures.
These tests compute the signal-to-noise ratio for the s-
IMAGE Solutions V8.3 26-478
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
parameter capture and fail if the capture is unlikely to be
repeatable.
Because of known hardware and software limitations which
affect repeatability, Teradyne recommends leaving the SNR test
enabled. If, however, your program is stable and repeatable
without these tests, you may improve test time by disabling
them. (Note that averaging several points is slower than allowing
IMAGE to check that the data is good and using just one or a few
points.)
ARGUMENTS enable—1 = enable, 0 = disable
RETURN VALUE Last setting for enable
SEE ALSO Runtime error list error #13663
tl_uwport_sparam_timer
S-param hardware timer supported?
SYNOPSIS int tl_uwport_sparam_timer(pin)
int pin
DESCRIPTION Determines whether the LA310 controller for the port module has
the s-parameter hardware timer feature as well as detecting
whether the Trigger Switchyard is present.
ARGUMENTS pin—Pin number connected to the port module
RETURN VALUE TRUE—If LA310 controller has s-parameter timer and TSY is
present
FALSE—If either of the above conditions are false
SEE ALSO “tl_uwport_sparam_timer_slot”
tl_uwport_sparam_timer_slot
Hardware s-parameter timing supported?
SYNOPSIS int tl_uwport_sparam_timer_slot(slot)
int slot
DESCRIPTION Determines whether the LA310 controller for the port module has
the s-parameter hardware timer feature as well as detecting
whether the Trigger Switchyard is present.
ARGUMENTS slot—Slot number of the port module
RETURN VALUE TRUE—If LA310 controller has s-parameter timer and TSY is
present
FALSE—If either of the above conditions are false
IMAGE Solutions V8.3 26-479
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “tl_uwport_sparam_timer”
tl_uwport_thinfo
Return UWPORT info structure.
SYNOPSIS THINFO tl_uwport_thinfo(slot)
int slot;
DESCRIPTION This function packets the data that are displayed in setupdisp.
ARGUMENTS slot—UWPORT slot number
RETURN VALUE UWPORT info structure. If there is no UWPORT in slot, returns
a structure of zeros.
tl_uwport_user_cal_std_func
Demand calibration function for user.
SYNOPSIS char *tl_uwport_user_cal_std_func(pin_num, slot_num,
schan_num, cal_std, pin_num2, slot_num2,
schan_num2)
int pin_num, slot_num, schan_num;
enum tl_uwport_cal_std_type cal_std;
int pin_num2, slot_num2, schan_num2;
DESCRIPTION This function supports external s-parameter calibration when
standards can be switched in quickly and automatically
(switches on the DIB) without forcing the user to write a
calibration function that explicitly goes through all frequencies
and amplitudes. This code will be called whenever s-parameter
calibration needs to be done (each time a new frequency or
amplitude comes up) so it is not suitable for use with a
handler/prober or manual operator.
This function can be used selectively for only certain pins, but all
pins on the same schan must use this function and the function
must always do what it is supposed to or runtime errors will be
generated.
Sample code:
char *tl_uwport_user_cal_std_func(pin_num, slot_num, schan_num,
cal_std, pin_num2, slot_num2, schan_num2)
int pin_num, slot_num, schan_num;
enum tl_uwport_cal_std_type cal_std;
int pin_num2, slot_num2, schan_num2;
{
switch (cal_std) {
case TL_UWPORT_CAL_BEGIN: {
* probably don’t need to do anything here *
printf("S-parameter calibration starting...\n");
IMAGE Solutions V8.3 26-480
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
result = TL_UWPORT_CAL_OK;
break;
}
case TL_UWPORT_CAL_END: {
* put dib switches back where they belong *
* be sure to handle both ports if this is a 2-port *
printf("S-parameter calibration done.\n");
result = TL_UWPORT_CAL_OK;
}
case TL_UWPORT_CAL_OPEN: {
* attach open standard *
printf("OPEN standard attached.\n");
result = "open_std_00123.s1p";
* If want to assume standards are ideal,
set results to TL_UWPORT_CAL_OK *
* If something is wrong, return
TL_UWPORT_CAL_ERROR to make calibration fail *
}
.
. * rest of standards are the same *
.
default: {
...
result = TL_UWPORT_CAL_DEFAULT;
}
}
return result;
}
ARGUMENTS pin_num—Pin on a UWPORT which needs to be calibrated or
about which information is being requested If pin_num = 0, use
slot_num instead.
slot_num—UWPORT slot number. Valid whether or not
pin_num is valid. (non-zero)
schan_num—UWPORT schan number (1-4). Like slot_num,
always valid.
cal_std—Which cal standard to attach, or which piece of
information to provide. This is an enumerated type variable. You
must #include <itlh/uwport_std_cal.h> to define it.
These entries are only filled in for 2-port measurements. They
will be valid if cal_std is TL_UWPORT_CAL_ISOLATE or
TL_UWPORT_CAL_THRU.
pin_num2—Pin on a UWPORT which needs to be calibrated or
about which information is being requested If pin_num = 0, use
slot_num instead.
slot_num2—UWPORT slot number. Valid whether or not
pin_num is valid. (non-zero)
IMAGE Solutions V8.3 26-481
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
schan_num2—UWPORT schan number (1-4). Like slot_num,
always valid.
RETURN VALUE Returns a character string which may be any of the following:
TL_UWPORT_CAL_DEFAULT—Almost always legal - do whatever
the driver would do as if this function is not defined.
Responses to cal_std == TL_UWPORT_CAL_BEGIN:
TL_UWPORT_CAL_END:
TL_UWPORT_CAL_OK - no problem
TL_UWPORT_CAL_ERROR - something went wrong
Responses to cal_std == TL_UWPORT_CAL_LOAD:
TL_UWPORT_CAL_OPEN:
TL_UWPORT_CAL_SHORT:
TL_UWPORT_CAL_OK - no problem; assume standard is
ideal
TL_UWPORT_CAL_ERROR - something went wrong
filename.s1p - any valid file in .s1p format that
characterizes the attached cal standard.
Responses to cal_std == TL_UWPORT_CAL_ISOLATE:
TL_UWPORT_CAL_OK - no problem; assume standard is
ideal
TL_UWPORT_CAL_ERROR - something went wrong
This is the first half of a 2-port measurement involving 2 LOAD
standards. The load standard for this prompt must be connected
to pin_num2 instead of pin_num. No measurement will be made
immediately after this standard is connected. The next standard
to be requested will be a LOAD, and that should be connected
as for a normal 1-port measurement, after which a 2-port
measurement will be made to find the isolation. It is OK to
connect both loads at once and just return a file name when this
function is called with LOAD. At this time, IMAGE does not
accept files for this parameter because their contribution to the
overall accuracy of the system is insignificant.
Responses to cal_std = TL_UWPORT_CAL_THRU:
TL_UWPORT_CAL_OK - No problem; assume standard is
ideal
TL_UWPORT_CAL_ERROR - Something went wrong
filename.s2p - Any valid file in .s2p format that
characterizes this cal standard.
SIDE EFFECTS if cal_std == TL_UWPORT_CAL_LOAD, TL_UWPORT_CAL_OPEN,
TL_UWPORT_CAL_SHORT, TL_UWPORT_CAL_ISOLATE, or
TL_UWPORT_CAL_THRU the appropriate standard must be
connected or there will be runtime errors or future
measurements will be improperly calibrated.
IMAGE Solutions V8.3 26-482
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “read_uwport_one_port_cal_std”,
read_uwport_two_port_cal_std()
tl_uwport_write_s1p
Write one-port s-parameter file (.s1p).
SYNOPSIS int tl_uwport_write_s1p(filename, freqs, s_params,
num_spars, pin)
char *filename;
double *freqs;
D_COMPLEX *s_params;
int num_spars;
int pin;
DESCRIPTION Writes num_spars s-parameters to filename from the freqs and
s_params arrays in .s1p format.
ARGUMENTS filename—String such as /u/checkers/data/lna.s1p or
hi.s1p
freqs[LENGTH]—Double precision array of frequencies, filled in
by function
s_params[LENGTH]—D_COMPLEX array of s-parameter data in
(real, imaginary) format, filled in by function.
num_spars—Number of s-parameters to write (≤LENGTH)
pin—Pin number. Puts extra hardware and pin information into
header of .s1p file. Set to 0 if pinmap not defined or extra
information is not desired.
RETURN VALUE 0—no error
!0—error of some kind
SEE ALSO “tl_uwport_read_s2p”, “read_uwport_one_port”, smithdisp
tl_uwport_write_s1p_fmt
Write one-port s-parameter file (.s1p).
SYNOPSIS int tl_uwport_write_s1p_fmt(filename, freqs,
s_params, num_s_params, pin, data_fmt,
freq_unit)
char *filename;
double *freqs;
D_COMPLEX *s_params;
int num_s_params;
int pin;
char *data_fmt;
char *freq_unit;
IMAGE Solutions V8.3 26-483
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Writes num_s_params s-parameters to filename from the freqs
and s_params arrays in .s1p format. Format of data in file is
determined by data_fmt and freq_unit.
data_fmt can be RI for (real, imaginary) (rectangular
coordinates) or MA for (magnitude, angle) (polar coordinates) or
DB for (20*log10(magnitude), angle) (return loss).
The frequency units are determined by the freq_unit
argument, which can be Hz, kHz, MHz, or GHz.
ARGUMENTS filename—String such as /u/checkers/data/lna.s1p or
hi.s1p
freqs[LENGTH]—Double precision array of frequencies—filled
in by function
s_params[LENGTH]—D_COMPLEX array of s-parameter data in
(real, imaginary) format. -- filled in by function.
num_s_params—Number of s-parameters to write (<= LENGTH)
pin—Pin number—puts extra hardware and pin info into header
of .s1p file. Set to 0 if pinmap not defined or extra information is
not desired.
data_fmt—Write data into file in this format
freq_unit—Frequencies scaled to this unit
RETURN VALUE 0—No error
!0—Error of some kind
SEE ALSO “tl_uwport_write_s1p_fmt”, “tl_uwport_read_s2p”,
“read_uwport_one_port”, smithdisp
tl_uwport_write_s2p
Write 2-port s-parameter file (.s2p).
SYNOPSIS int tl_uwport_write_s2p(filename, freqs, s11, s21,
s12, s22, num_s_params, pin1, pin2)
char *filename;
double freqs[];
D_COMPLEX s11[];
D_COMPLEX s21[];
D_COMPLEX s12[];
D_COMPLEX s22[];
int num_s_params;
int pin1;
int pin2;
DESCRIPTION Writes num_s_params sets of s-parameter data to filename from
the freqs, s11, s21, s12, and s22 arrays. Format:
IMAGE Solutions V8.3 26-484
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
freq s11.re s11.im s21.re s21.im s12.re s12.im s22.re s22.im
freq is in Hz.
ARGUMENTS filename—String such as
/u/checkers/data/lna.s2p or hi.s2p
freqs[LENGTH]—Frequencies for each s-parameter
measurement
s11[LENGTH]—spar from read_uwport_two_port_s11()
s21[LENGTH]—spar from read_uwport_two_port_s21()
s12[LENGTH]—spar from read_uwport_two_port_s12()
s22[LENGTH]—spar from read_uwport_two_port_s22()
num_s_params—Number of s-parameters to write (<= LENGTH)
pin1, pin2—pin numbers—Put extra hardware and pin info into
header of .s2p file. Set to 0 if pinmap not defined or extra
information is not desired.
file_fmt—Write data into file in this format
RETURN VALUE 0—No error
!0—Error of some kind
SEE ALSO “tl_uwport_read_s2p”, “tl_uwport_write_s2p_fmt”,
“read_uwport_two_port_s11”,
“read_uwport_raw_two_port_s11”, “tl_uwport_write_s1p”,
smithdisp
tl_uwport_write_s2p_fmt
Write 2-port s-parameter file (.s2p).
SYNOPSIS int tl_uwport_write_s2p_fmt(filename, freqs, s11,
s21, s12, s22, num_s_params, pin1, pin2,
data_fmt, freq_unit)
char *filename;
double freqs[];
D_COMPLEX s11[];
D_COMPLEX s21[];
D_COMPLEX s12[];
D_COMPLEX s22[];
int num_s_params;
int pin1;
int pin2;
char *data_fmt;
char *freq_unit;
DESCRIPTION Writes num_s_params sets of s-parameter data to filename from
the freqs, s11, s21, s12, and s22 arrays.
The format of the data within the file is determined by the
data_fmt argument, which can be RI for (real, imaginary)
IMAGE Solutions V8.3 26-485
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
(rectangular coordinates) or MA for (magnitude, angle) (polar
coordinates) or DB for (20*log10(magnitude), angle) (return loss).
The frequency units are determined by the freq_unit
argument, which can be Hz, kHz, MHz, or GHz.
Note that the order of the columns in a .s2p file is:
frequency s11 s21 s12 s22
where each s-parameter uses two columns described by
data_fmt and the frequency is scaled to freq_unit. (The units
for freqs passed into this function is Hz, same you would use in
set pin = X uwport: freq = freqs[0].)
ARGUMENTS filename—String such as /u/checkers/data/lna.s2p or
hi.s2p
freqs[LENGTH]—Frequencies for each s-parameter
measurement
s11[LENGTH]—spar from read_uwport_two_port_s11()
s21[LENGTH]—spar from read_uwport_two_port_s21()
s12[LENGTH]—spar from read_uwport_two_port_s12()
s22[LENGTH]—spar from read_uwport_two_port_s22()
num_s_params—Number of s-parameters to write (<= LENGTH)
pin1, pin2—pin numbers—Put extra hardware and pin info into
header of .s2p file. Set to 0 if pinmap not defined or extra
information is not desired.
data_fmt—Write data into file in this format
freq_unit—Frequencies are in this format
RETURN VALUE 0—no error
!0—error of some kind
SEE ALSO “tl_uwport_read_s2p”, “tl_uwport_write_s2p”,
“read_uwport_two_port_s11”,
“read_uwport_raw_two_port_s11”, “tl_uwport_write_s1p”,
smithdisp
tl_uwrecv_ap_read_uncal_amp
User’s Array Processor based code for UWRECV reads.
SYNOPSIS int tl_uwrecv_ap_read_uncal_amp(slot, schan,
freq_of_interest, mm_freq, f_if, fs,
sample_size, uncal_amp, rfp, vrng);
int slot;
int schan;
double freq_of_interest;
double mm_freq;
double f_if;
double fs;
IMAGE Solutions V8.3 26-486
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
int sample_size;
double *uncal_amp;
int rfp;
double vrng;
DESCRIPTION This function can optionally be provided by users who wish to
use the array processor for UWRECV calculations instead of
relying on the UWRECV driver’s CPU based computations.
ARGUMENTS slot—Slot of UWRECV or UWPORT upstream of UWRECV
schan—Schan of UWRECV or UWPORT upstream of UWRECV
freq—Freq that we want to know amplitude of
mm_freq—RF freq UWRECV is programmed to
f_if—Intermediate Frequency (what the digitizer sees)
sample_size—Number of samples captured
uncal_amp—Where to fill in the result
rfp—Boolean: if non-0, freq specs RF freq; else specs IF. This
argument added in IMAGE 6.0 (the others introduced in 5.7.uw).
vrng—digitizer vrng
RETURN VALUE 1 If uncal_amp filled in successfully
0 Force the UWRECV to compute the result in the CPU
tl_uwrecv_characterize_phase_noise_PSD
Get the complete characterization of the phase noise power spectral density.
SYNOPSIS int tl_uwrecv_characterize_phase_noise_PSD(pin,
freq_array, psd_array, num_avg)
DESCRIPTION The last UWRECV capture is assumed to be from the phase
noise demodulator, and it produces the complete
characterization of the phase noise power spectral density at the
current capture setting of the digitizer of UWRECV by using the
radix-2 based FFT function on the Array Processor.
The function returns the number of frequency points processed
with the list of frequencies written back to the given double array,
freq_array, followed by the PSD estimate for each frequency
point written to the array, psd_array, at the corresponding array
index.
In applying radix 2 FFT on each data segment, the segment size
is selected as the maximum radix 2 number less than or equal to
total sample size/num_avg. Therefore, the actual frequency
sampling points of the FFT and the number of average
performed may be different from the case of DFT/tester
computer unless the total sample size is initially selected as a
num_avg multiple of a radix 2 number.
IMAGE Solutions V8.3 26-487
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
Due to the above method in segment size selection, the per
segment data size would be at maximum total sample size /
num_avg. Therefore, the recommended size for the two data
arrays is total sample size/num_avg.
ARGUMENTS pin—Pin # of UWPORT connected to UWRECV
freq_array—Array to write the offset frequencies at which the
PSD has been estimated.
psd_array—Array to write the PSD estimate for the
corresponding freq in FREQ_ARRAY
num_avg—Number of averages
RETURN VALUE -1 : for any errors or the number of valid data points in
freq_array[]/psd_array[]
SEE ALSO “read_uwrecv_phase_noise_PSD”,
“read_uwrecv_phase_noise_PSD_array”
tl_uwrecv_czt
Evaluate and return all DFT samples using CZT.
SYNOPSIS int tl_uwrecv_czt(t_samples, f_samples, size,
perm_buffer)
float *t_samples, *f_samples;
int size;
int perm_buffer;
DESCRIPTION Evaluate all DFT samples, i.e., all freq components at
sample_rate / sample_size * n for 0 <= n <= sample_size/2-1,
with the Chirp Z-Xform on the Array Processor.
NOTE
This function does not provide the full capability of Chirp-Z Xform which allows evaluation
of Z-Xform on equally spaced points on a spiral contour starting at an arbitrary point with an
arbitrary sampling interval on the Z-plane.
This function is limited to evaluating DFTs, that is., starting at DC
with the freq interval of sample_rate/sample_size. The results
should be identical to iterating the DFT through all freq sample
points, but its execution time should be considerably faster.
Specifically, in most cases, its execution time should be
comparable to 4 ~ 10 times of the execution time of FFT with a
similar data size.
The results are returned to the array, f_samples, as Discrete
Fourier Series Coefficients, i.e., after applying 1/N scaling factor.
IMAGE Solutions V8.3 26-488
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
For a series of calls to this function with an identical data size,
performance improvement can be achieved by enabling
perm_buffer flag. With this feature enabled, the chirp signal and
filter are stored in the permanent buffer and reused over multiple
invocations of this function until they need to be recomputed due
to a change in the data size. Further note that the size of the
permanent buffer cannot be changed during the job run;
therefore, the initial enabling of this feature sets the maximum
data size.
ARGUMENTS size—Size of time/frequency data array.
t_samples—Array containing time data samples
f_samples—Array to receive frequency domain transforms.
Only positive half of the frequencies are returned.
perm_buffer—Store chirp related signals in permanent buffers.
RETURN VALUE 1 : success, 0 : error
tl_uwrecv_get_PSD_use_AP
Return the current state of “use Array Processor” flag.
SYNOPSIS int tl_uwrecv_get_PSD_use_AP()
DESCRIPTION Returns the current state of “use Array Processor Flag.” The
meaning of the return values are:
0—Disable
1—Use radix 2 FFT
2—Perform DFT
tl_uwrecv_phase_noise_signal_check
Enable or disable checks on the input signal to the phase noise analyzer.
SYNOPSIS int tl_uwrecv_phase_noise_signal_check(flag)
int flag;
DESCRIPTION This function enables or disables the following checks on the
input signal to the phase noise analyzer:
o IF frequency output is 10MHz +/- 2kHz
o IF output power is 0dBm +/- 6dBm
o Quadrature error is < 500.0mV
ARGUMENTS 0 : disable
1 : enabled and quiet if no error. No IF spectrum written out to a
.wave file otherwise: enabled and verbose: prints out the max IF
frequency and power. IF spectrum written out to
phase_noise_IF_spectrum.wav
RETURN VALUE Current value
IMAGE Solutions V8.3 26-489
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_uwrecv_read_ampval
Return amp parameter setting.
SYNOPSIS double tl_uwrecv_read_ampval(pin)
int pin;
DESCRIPTION Return amp parameter setting.
ARGUMENTS pin—Pin of UWRECV
RETURN VALUE amp (in whatever unit is currently being used) to which
UWRECV is programmed
tl_uwrecv_read_ampval_slot
Return amp parameter setting.
SYNOPSIS double tl_uwrecv_read_ampval_slot(slot)
int slot;
DESCRIPTION Return amp parameter setting
ARGUMENTS slot—Slot of UWRECV
RETURN VALUE amp (in whatever unit is currently being used) to which
UWRECV is programmed
tl_uwrecv_read_level
Readback UWRECV “level” parameter.
SYNOPSIS int tl_uwrecv_read_level(pin)
int pin;
DESCRIPTION Readback UWRECV level parameter.
ARGUMENTS pin—UWPORT/UWRECV pin
RETURN VALUE 0 = automatic
1 = immediate
2 = none
-1 = error
SEE ALSO “tl_uwrecv_read_level_slot”
tl_uwrecv_read_level_slot
Readback UWRECV “level” parameter.
SYNOPSIS int tl_uwrecv_read_level(slot, schan)
int slot, schan;
DESCRIPTION Readback UWRECV level parameter.
IMAGE Solutions V8.3 26-490
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS slot—UWPORT/UWRECV slot
schan—UWPORT/UWRECV schan
RETURN VALUE 0 = automatic
1 = immediate
2 = none
-1 = error
SEE ALSO “tl_uwrecv_read_level”
tl_uwrecv_set_PSD_turbo_avg
Enable or disable the Turbo Avg feature in the PSD estimators.
SYNOPSIS int tl_uwrecv_set_PSD_turbo_avg(flag)
int flag;
DESCRIPTION Enables or disables the Turbo Averaging feature for the PSD
estimation functions. This feature enables you to effectively
double the average count specified to any of the power spectral
density estimation functions by forming overlapping segments
from the time domain data in computing the power spectral
density.
Scope of impact: general PSD functions, phase noise PSD
functions
Benefit: the measurement variance or the repeatability in the
multiple measurements is directly related to the number of
averaging performed. Consequently, this function allows you to
approximately double the repeatability performance with a given
number of time domain data.
Note that the advantage of this function is specifically in reducing
the sample size requirement rather than the test time.
Since the effectiveness of this feature somewhat depends on
individual cases, you are advised to measure and evaluate the
repeatability improvement versus the test time increase for each
case.
The default state of this feature is disabled.
ARGUMENTS 0: disable
1: HAMMING WINDOW
2: HANN WINDOW
3: Triangular Window
RETURN VALUE Current value
IMAGE Solutions V8.3 26-491
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_uwrecv_set_PSD_use_AP
Enable or disable usage of the Array Processor/radix2 FFT in the PSD estimator functions.
SYNOPSIS int tl_uwrecv_set_PSD_use_AP(flag)
int flag;
DESCRIPTION Enables or disables usage of the Array Processor and radix 2
FFT in the spectral estimation functions.
Note that with this option enabled, the segment size is selected
as the maximum radix 2 number less than or equal to “total
sample size”/num_avg.
Then, the actual average count is selected as “total sample size”
/ radix 2 segment size.
Consequently, the actual average count performed and the
frequency resolution would be different from the results of the
DFT based function unless the total sample size is set as the
num_avg multiple of a radix 2 number.
Note that the differences in the freq sampling points and the
average count should not be an issue unless particular
frequency points need to be sampled exactly as in measuring the
amplitude of known discrete frequency components (that is,
spurs or harmonics). For these cases, set the total sample size
exactly as the desired radix 2 segment size times the desired
average count.
ARGUMENTS 0—DFT
1—FFT
2—CZT
tl_uwrecv_spectrum_reversed
Returns 1 if IF spectrum reversed.
SYNOPSIS int tl_uwrecv_spectrum_reversed(pin)
int pin;
DESCRIPTION Returns 1 if the UWRECV reverses the IF spectrum. The
spectrum is reversed if increasing RF results in decreasing IF for
a constant UWMM setting.
ARGUMENTS pin—UWRECV pin
RETURN VALUE 0—Spectrum is not reversed
1—Spectrum is reversed
-1—Error (bad pin number, missing hardware)
IMAGE Solutions V8.3 26-492
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_uwrecv_spectrum_reversed_slot
IF spectrum reversed?
SYNOPSIS int tl_uwrecv_spectrum_reversed_slot(slot, schan)
int slot, schan;
DESCRIPTION Returns 1 if the UWRECV reverses the IF spectrum. The
spectrum is reversed if increasing RF results in decreasing IF for
a constant UWMM setting.
ARGUMENTS slot—UWRECV slot
schan—UWRECV schan
RETURN VALUE 0—Spectrum is not reversed
1—Spectrum is reversed
-1—Error (bad pin number, missing hardware)
tl_uwrecv_suggest_digitizer
Find a digitizer for UWRECV.
SYNOPSIS int tl_uwrecv_suggest_digitizer(pin)
int pin;
DESCRIPTION All valid microwave configurations contain at least one HFDIG or
VHFDIG. This function returns the slot number of a digitizer that
should work for your test program.
For µWAVE6000 (949-595-0x UWMM) systems, each UWMM
must have its own VHFDIG (direct co-ax cable connection). The
first UWMM is mapped to the first VHFDIG in order of increasing
slot numbers.
Other test systems (949-310-02 UHFMM) have only one
measure module so if a VHFDIG is present it will be used,
otherwise a HFDIG will be used.
ARGUMENTS pin—UWRECV/UWPORT pin
RETURN VALUE Slot number of digitizer or 0 if error
SEE ALSO “tl_read_uwrecv_digslot”
tl_uwrecv_suggest_digitizer_slot
Find a digitizer for UWRECV.
SYNOPSIS int tl_uwrecv_suggest_digitizer_slot(slot, schan)
int slot;
int schan;
IMAGE Solutions V8.3 26-493
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION All valid microwave configurations contain at least one HFDIG or
VHFDIG. This function returns the slot number of a digitizer that
should work for your test program.
For µWAVE6000 (949-595-0x UWMM) systems, each UWMM
must have its own VHFDIG (direct co-ax cable connection). The
first UWMM is mapped to the first VHFDIG in order of increasing
slot numbers.
Other test systems (949-310-02 UHFMM) have only one
measure module so if a VHFDIG is present it will be used,
otherwise a HFDIG will be used.
ARGUMENTS slot—UWRECV/UWPORT slot number
schan—UWRECV/UWPORT schan number
RETURN VALUE Slot number of digitizer or 0 if error
SEE ALSO “tl_read_uwrecv_digslot_slot”
tl_uwsrc_read_amp_dbm_slot
Read back source amplitude in dBm.
SYNOPSIS int tl_uwsrc_read_freq_slot(slot, schan, amp)
int slot, schan;
double *amp;
DESCRIPTION Writes the current source amplitude, converted to dBm if
necessary, into amp
ARGUMENTS slot—UWSRC or UWPORT slot number
schan—UWSRC or UWPORT schan
amp—Address of a double precision variable
RETURN VALUE 0 if OK
-1 if error
SIDE EFFECTS “Selects” UWSRC
SEE ALSO “tl_uwsrc_read_freq_slot”, “tl_uwsrc_read_connection_slot”
tl_uwsrc_read_connection_slot
Returns UWSRC connection state.
SYNOPSIS int tl_uwsrc_read_connection_slot(slot, schan, conn)
int slot, schan;
int *conn;
DESCRIPTION Reads back whether source is connected or not.
IMAGE Solutions V8.3 26-494
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS slot—UWSRC or UWPORT slot number
schan—UWSRC or UWPORT schan
conn—1 = connected; 0 = disconnected
RETURN VALUE 0 = OK
-1 = error
SEE ALSO “tl_uwsrc_read_freq_slot”, “tl_uwsrc_read_amp_dbm_slot”
tl_uwsrc_read_freq_slot
Read back UWSRC freq parameter.
SYNOPSIS int tl_uwsrc_read_freq_slot(slot, schan, freq)
int slot, schan;
double *freq;
DESCRIPTION Writes the current value of the UWSRC freq parameter into the
variable freq.
ARGUMENTS slot—UWSRC or UWPORT slot number
schan—UWSRC or UWPORT schan
freq—Address double precision variable to write frequency into
RETURN VALUE 0 if OK
-1 if error
SIDE EFFECTS “Selects” UWSRC
SEE ALSO “tl_uwsrc_read_amp_dbm_slot”,
“tl_uwsrc_read_connection_slot”
tl_vhfawg_cal_interval
Set the VHFAWG calibration interval.
SYNOPSIS void tl_vhfawg_cal_interval(amt)
int amt;
DESCRIPTION Sets the Very High Frequency Arbitrary Waveform Generator
calibration interval.
ARGUMENTS amt—Time interval in seconds
RETURN VALUE None
tl_vhfawg_fs_sclk_cond
Prevent VHFAWG fs and SCLK race condition which occurs if fs or fs_div is programmed
on the fly when the VHFAWG is running.
SYNOPSIS void tl_vhfawg_fs_sclk_cond(bugfix_enable)
int bugfix_enable;
IMAGE Solutions V8.3 26-495
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Prevents fs and sclk race condition when fs or fs_div is
programmed when the VHFAWG is sourcing a waveform. This is
done by temporarily stopping the waveform, programming the fs
divider, and restarting the waveform.
ARGUMENTS bugfix_enable—
0—IMAGE behaves as it always did and race condition
can intermittently cause memory corruption
1—race condition is avoided with stop wave_end
2—race condition is avoided with stop immediately
RETURN VALUE None
tl_vhfawg_get_dccal_size
Return dccal table size.
SYNOPSIS int tl_vhfawg_get_dccal_size(pin_num)
int pin_num;
DESCRIPTION Returns the dccal table size for the VHFAWG specified by
pin_num.
ARGUMENTS pin_num—Pin number of the VHFAWG.
RETURN VALUE Size of table.
tl_vhfawg_get_dccal_size_slot
Return dccal table size.
SYNOPSIS int tl_vhfawg_get_dccal_size_slot(slot_num)
int slot_num;
DESCRIPTION Returns the dccal table size for the VHFAWG specified by
pin_num.
ARGUMENTS slot_num—Test head slot number of the VHFAWG.
RETURN VALUE Size of table.
tl_vhfawg_get_level_table_size
Return leveling table size.
SYNOPSIS int tl_vhfawg_get_level_table_size(pin_num)
int pin_num;
DESCRIPTION Returns the leveling table size for the VHFAWG specified by
pin_num. A size of zero indicates an invalid table for the
specified AWG.
ARGUMENTS pin_num—Pin number of the VHFAWG.
IMAGE Solutions V8.3 26-496
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
RETURN VALUE Size of table.
tl_vhfawg_get_level_table_size_slot
Return leveling table size.
SYNOPSIS int tl_vhfawg_get_level_table_size_slot(slot_num)
int slot_num;
DESCRIPTION Returns the leveling table size for the VHFAWG specified by
pin_num. A size of zero indicates an invalid table for the
specified AWG.
ARGUMENTS slot_num—Test head slot number of the VHFAWG.
RETURN VALUE Size of table.
tl_vhfawg_get_pll_value
Read back VHFAWG phase-lock loop value.
SYNOPSIS int tl_vhfawg_get_pll_value()
DESCRIPTION Read back phase-lock loop value of the selected VHFAWG.
Value returned can be used to calculate desired fs_div value.
NOTE
Programming the VHFAWG using the method described below is not recommended. The
fs_div syntax is obsolete. Do not use it in new test programs. Program sample rate using
the fs parameter instead.
Value returned can be used to calculate desired fs_div value as
follows:
int val, pll;
set pin=AC_IN vhfawg: aclock: a3;
pll = tl_vhfawg_get_pll_value();
val = (int) (desired_fs / pll * an_freq + 0.5);
set pin=AC_IN vhfawg:
fs_div = val;
ARGUMENTS None
RETURN VALUE PLL value of hardware selected
4 for AD780 and LA608 (VHFAWG200 and VHFAWG VIDEO)
8 for LA654 (VHFAWG400)
32 for LA736 (VHFAWG1200)
64 for LA819 (VHFAWG2500)
IMAGE Solutions V8.3 26-497
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_vhfawg_get_type
Return VHFAWG option type given pin number.
SYNOPSIS int tl_vhfawg_get_type(pin_num)
int pin_num;
DESCRIPTION Given a pin number, return VHFAWG option type behind that pin.
ARGUMENTS pin_num—Pin number
RETURN VALUE 0—not a VHFAWG
1—VHFAWG200, 256K memory option
2—VHFAWG200, 1M memory option
3—VHFAWG400, 1M memory single-ended CC option
4—VHFAWG400, 1M memory differential CC option
5—VHFAWG1200, 2M memory option
6—VHFAWG2500, 4M memory option
tl_vhfawg_get_type_slot
Return VHFAWG type given slot number.
SYNOPSIS int tl_vhfawg_get_type_slot(th_slot)
int th_slot;
DESCRIPTION Given a test head slot number, return VHFAWG option type.
ARGUMENTS th_slot—Test head slot number
RETURN VALUE 0—not a VHFAWG
1—VHFAWG200, 256K memory option
2—VHFAWG200, 1M memory option
3—VHFAWG400, 1M memory single-ended CC option
4—VHFAWG400, 1M memory differential CC option
5—VHFAWG1200, 2M memory option
6—VHFAWG2500, 4M memory option
tl_vhfawg_level_table_valid
Return whether the VHFAWG leveling table is valid.
SYNOPSIS int tl_vhfawg_level_table_valid(pin_num)
int pin_num;
DESCRIPTION Returns whether the leveling table for the Very High Frequency
Arbitrary Waveform Generator specified by pin_num is valid. The
leveling table is considered valid if ANY information in it is valid.
ARGUMENTS pin_num—VHFAWG pin number
RETURN VALUE 1 if valid, 0 if invalid
IMAGE Solutions V8.3 26-498
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_vhfawg_level_table_valid_slot
Return whether the VHFAWG leveling table is valid.
SYNOPSIS int tl_vhfawg_level_table_valid_slot(slotnum)
int slotnum;
DESCRIPTION Returns whether the leveling table for the Very High Frequency
Arbitrary Waveform Generator specified by the test head slot
number is valid. The leveling table is considered valid if any
information in it is valid.
ARGUMENTS slotnum—VHFAWG test head slot number
RETURN VALUE 1 if valid, 0 if invalid
SEE ALSO “tl_vhfawg_level_table_valid”
tl_vhfawg_move_event
Move event pulses within a VHFAWG segment after the segment is defined.
SYNOPSIS void tl_vhfawg_move_event(seg_var, eventnum,
old_start, old_stop, new_start, new_stop);
SEGMENT seg_var;
int eventnum, old_start, old_stop, new_start,
new_stop;
DESCRIPTION Move an event pulse after a segment define. VHFAWG should
not be running during this call. Minimal error checking is
performed on the old and new start/stop sample.
ARGUMENTS seg_var—Segment variable
eventnum—Event number, 1 to 8
old_start—Original start sample, 1 to N
old_stop—Original stop sample, 4 to N
new_start—New start sample, 1 to N
new_stop—New stop sample, 4 to N
RETURN VALUE None
tl_vhfawg_segment_ltable_valid
Return whether a VHFAWG segment has valid leveling data.
SYNOPSIS int tl_vhfawg_segment_ltable_valid(pin_num, seg_var)
int pin_num;
SEGMENT seg_var;
DESCRIPTION Returns whether VHFAWG segment specified has valid leveling
data.
IMAGE Solutions V8.3 26-499
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS pin_num—Pin number of the VHFAWG used to create the
segment.
seg_var—Variable of the segment created.
RETURN VALUE 1 if valid, 0 if invalid.
tl_vhfawg_segment_ltable_valid_slot
Return whether a VHFAWG segment has valid leveling data.
SYNOPSIS int tl_vhfawg_segment_ltable_valid_slot(slot_num,
seg_var)
int slot_num;
SEGMENT seg_var;
DESCRIPTION Returns whether VHFAWG segment specified has valid leveling
data.
ARGUMENTS slot_num—Test head slot number of the VHFAWG with the
segment.
seg_var—Variable of the segment created
RETURN VALUE 1 if valid, 0 if invalid.
tl_vhfawg_set_dccal_size
Set the maximum number of dccal entries in look-up table.
SYNOPSIS void tl_vhfawg_set_dccal_size(entries)
int entries;
DESCRIPTION Sets tl_vhfawg_max_dccal.
ARGUMENTS entries—Maximum number of entries for dccal data.
RETURN VALUE None
tl_vhfawg_set_level_size
Set maximum number of prelevel entries.
SYNOPSIS void tl_vhfawg_set_level_size(entries)
int entries;
DESCRIPTION Programs the maximum number of preleveled data entries.
ARGUMENTS entries—Maximum entries in prelevel table.
RETURN VALUE None
tl_vhfawg_sine_gen_debug
Set leveling sine generation debug flag.
IMAGE Solutions V8.3 26-500
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS void tl_vhfawg_sine_gen_debug(on)
int on;
DESCRIPTION Turn leveling sine generation debug message on or off.
ARGUMENTS on—Debug message flag
1—Turn on message
0—Turn off message
RETURN VALUE None
tl_vhfawg_wave_freq
Report actual frequency.
SYNOPSIS double tl_vhfawg_wave_freq(wave_name, mclk,
tone_index)
char *wave_name;
double mclk;
int tone_index;
DESCRIPTION Returns the actual frequency generated by wave wave_name
when the master clock is set to mclk. For multitone waves, the
tone of interest is specified by tone_index.
ARGUMENTS wave_name—Specifies the wave
mclk—Frequency of the master clock. If 0, use the master clock
value which was in effect when the wave was created.
tone_index—For multitone waves, specifies tone [1 to 7]. For
other waves, this parameter is ignored.
RETURN VALUE Actual frequency which would be produced for the specified
tone, or 0.0, if any error.
tl_vhfawg_wave_fs
Report actual sample rate.
SYNOPSIS double tl_vhfawg_wave_fs(wave_name)
char *wave_name;
DESCRIPTION Returns the actual sample rate of wave wave_name.
ARGUMENTS wave_name—Specifies the wave
RETURN VALUE Sample rate of the specified wave_name, 0 on error.
tl_vhfawg_wave_size
Report sample size.
IMAGE Solutions V8.3 26-501
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_vhfawg_wave_size(wave_name)
char *wave_name;
DESCRIPTION Returns the sample size of wave wave_name.
ARGUMENTS wave_name—Specifies the wave
RETURN VALUE Sample size of the specified wave_name, 0 on error.
tl_vhfcw_cal_interval
Set the VHFCW calibration interval.
SYNOPSIS void tl_vhfcw_cal_interval(amt)
int amt;
DESCRIPTION Sets the Very High Frequency Continuous Waveform Source
calibration interval.
ARGUMENTS amt—Time interval in seconds
RETURN VALUE None
tl_vhfcw_level_table_valid
Return whether the VHFCW leveling table is valid.
SYNOPSIS int tl_vhfcw_level_table_valid(pin_num)
int pin_num;
DESCRIPTION Returns whether the leveling table for the Very High Frequency
Continuous Waveform Source specified by pin_num is valid.
ARGUMENTS pin_num—VHFCW pin number
RETURN VALUE 1 if valid, 0 otherwise.
tl_vhfcw_level_table_valid_slot
Return whether the VHFCW leveling table is valid.
SYNOPSIS int tl_vhfcw_level_table_valid_slot(slotnum)
int slotnum;
DESCRIPTION Returns whether the leveling table for the Very High Frequency
Continuous Waveform Source specified by the test head slot
number is valid.
ARGUMENTS slotnum—VHFCW test head slot number
RETURN VALUE 1 if valid, 0 otherwise.
SEE ALSO “tl_vhfcw_level_table_valid”
IMAGE Solutions V8.3 26-502
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_vhfcw_set_dccal_size
Set the maximum VHFCW dccal setups.
SYNOPSIS void tl_vhfcw_set_dccal_size(num)
int num;
DESCRIPTION Sets the maximum number of Very High Frequency Continuous
Waveform Source dccal setups per test program.
ARGUMENTS size—Number of VHFCW dccal setups.
RETURN VALUE None
tl_vhfcw_set_level_max
Program the number of maximum allowable VHFCW leveling setups.
SYNOPSIS void tl_vhfcw_set_level_max(num)
int num;
DESCRIPTION Override the internal number of maximum allowable Very High
Frequency Continuous Waveform Source leveling setups with
provided value.
ARGUMENTS num—Maximum number of leveling setups per test program
(>100).
RETURN VALUE None
tl_vmcu_busy_wait
Wait until VMCU is idle.
SYNOPSIS tl_vmcu_busy_wait(vmcu_num)
int vmcu_num;
DESCRIPTION Sends information to the VMCU display.
ARGUMENTS vmcu_num—VMCU number 1 - 8
RETURN VALUE 0 if idle, else runtime error
tl_vreg_dutsrc_to_channel
Which channel am I?
SYNOPSIS int tl_vreg_dutsrc_to_channel(dutsrc_num)
DESCRIPTION Find the channel number for vreg for a given DUTSRC.
ARGUMENTS int dutsrc_num;—DUTSRC number (1-8)
RETURN VALUE Channel number (VREG_CH_A or VREG_CH_B) or 0 (failed)
IMAGE Solutions V8.3 26-503
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SEE ALSO “tl_vreg_dutsrc_to_slot”
tl_vreg_dutsrc_to_slot
Which slot am I in?
SYNOPSIS int tl_vreg_dutsrc_to_slot(dutsrc_num)
DESCRIPTION Find the slot number for vreg cc for a given DUTSRC.
ARGUMENTS int dutsrc_num—DUTSRC number (1-8)
RETURN VALUE Slot number or 0 (failed)
SEE ALSO “tl_vreg_slot_to_dutsrc”
tl_vreg_image_dump
Dump information about the state of the Vreg.
SYNOPSIS void tl_vreg_image_dump(dutsrc_num)
DESCRIPTION Dumps information to the station window about the state of the
Vreg for a given DUT source. This includes the slot, voltage,
mode, stored parameters, and connection state for the Vreg.
ARGUMENTS int dutsrc_num—DUTSRC number (1-8)
RETURN VALUE None
tl_vreg_slot_to_dutsrc
Which DUTSRC am I cabled to?
SYNOPSIS int tl_vreg_slot_to_dutsrc(vreg_slot, schan)
DESCRIPTION Find the DUTSRC number for a given slot and schan of a vreg
cc.
ARGUMENTS int vreg_slot—Slot number of vreg cc
int schan—Schan (1-4) for current channel
RETURN VALUE DUTSRC number (1-8) or 0 (failed)
SEE ALSO “tl_vreg_dutsrc_to_slot”
tl_wait
Execute a delay.
SYNOPSIS void tl_wait(ftime)
double ftime;
IMAGE Solutions V8.3 26-504
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
DESCRIPTION Execute a delay. Minimum delay is about 30 µs. Accurate within
3 µs or 0.1%, whichever is less.
ARGUMENTS Time in seconds
RETURN VALUE None
tl_wait_wait
Start Terabus settling delay timer.
SYNOPSIS void tl_wait_wait();
DESCRIPTION Wait for wait timer done. In case of timer hardware problems
there is a two minute timeout on the wait. If the remaining wait
period will be legitimately longer than two minutes, tl_set_wait
and tl_wait_wait are not recommended.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_set_wait”, “tl_set_wait_timeout”
tl_wf_cal_temp_diff
Set the calibration temperature interval.
SYNOPSIS void tl_wf_cal_temp_diff(amt)
int amt;
DESCRIPTION Sets the wf calibration temperature interval.
ARGUMENTS amt—Temperature drift in degrees Celsius
RETURN VALUE None
tl_wf_cal_time_interval
Set the calibration interval.
SYNOPSIS void tl_wf_cal_time_interval(amt)
int amt;
DESCRIPTION Sets the wf calibration interval.
ARGUMENTS amt—Time interval in seconds.
RETURN VALUE None
tl_wfcap_current_bank
Return the current memory bank number.
IMAGE Solutions V8.3 26-505
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS unsigned int tl_wfcap_current_bank(pin)
DESCRIPTION Returns the memory bank currently being used for capture.
ARGUMENTS int pin—The pin number for the instrument
RETURN VALUE A one-based number for the memory bank currently being used
for capture, or 0 if there was an error.
tl_wfcap_get_actual_sample_rate
Return the actual programmed sample rate for the instrument.
SYNOPSIS double tl_wfcap_get_actual_sample_rate(pin)
DESCRIPTION This function returns the actual sample rate that was
programmed. This rate is calculated by clock manager while
taking into account all frequencies in the clock setup being
loaded.
ARGUMENTS int pin—The pin number for the instrument
RETURN VALUE The sample rate, or 0.0 if it has not yet been programmed.
tl_wfcap_num_samples_captured
Get number of captured samples.
SYNOPSIS unsigned int tl_wfcap_num_samples_captured(pin)
DESCRIPTION Returns the number of samples captured.
ARGUMENTS int pin—Pin number for the instrument
RETURN VALUE The number of samples captured during the last capture. If
capture is in progress but has not completed, returns the number
of samples captured so far. If capture has been enabled but not
started, returns 0.
If the instrument is actively capturing IMAGE issues an error,
because the samples captured are read from two registers, and
it is likely to read back a confusing value while they are
incrementing.
There is a very small but finite chance that a test program could
start capturing from a pattern after IMAGE reads the capture
state but before getting the count from both registers. Be aware
of this potential problem if using the function while a pattern is
running.
tl_wfcap_num_samples_overranged
Get number of overranged samples.
IMAGE Solutions V8.3 26-506
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS unsigned int tl_wfcap_num_samples_overranged(pin)
DESCRIPTION Returns the number of samples overranged during the last
capture.
ARGUMENTS int pin—Pin number for the instrument
RETURN VALUE The number of samples overranged during the last capture. If
capture is in progress but has not completed, returns the number
of samples overranged so far. If capture has been enabled but
not started, returns 0.
tl_wf_disable_80MHz_clock
Disable clocks on all WF instruments.
SYNOPSIS void tl_wf_disable_80MHz_clock
DESCRIPTION Turns off the 80MHz clocks on all WF instruments.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS The affected instruments are not usable while their 80MHz
clocks are off.
tl_wf_enable_80MHz_clock
Enable clocks on all WF instruments.
SYNOPSIS void tl_wf_enable_80MHz_clock
DESCRIPTION Turns on the 80MHz clocks on all WF instruments.
ARGUMENTS None
RETURN VALUE None
SIDE EFFECTS The affected instruments are placed in their reset state.
tl_wfsrc_get_crest_factor
Return crest factor of segment.
SYNOPSIS double tl_wfsrc_get_crest_factor(pin, pName)
int pin;
char *pName;
DESCRIPTION Retrieves crest factor from the segment database.
ARGUMENTS pin—Pinmap identifier
pName—Name of the defined segment
RETURN VALUE Crest Factor of segment
IMAGE Solutions V8.3 26-507
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_wfsrc_get_frequency
Return frequency of segment.
SYNOPSIS double tl_wfsrc_get_frequency(pin, pName)
int pin;
char pName;
DESCRIPTION Retrieves the segment frequency from the segment database.
For multitones it will return the highest frequency tone.
ARGUMENTS pin—Pinmap identifier
pName—Name of the defined segment
RETURN VALUE Frequency of segment
tl_wfsrc_get_last_sample_rate
Return sample rate of last started segment.
SYNOPSIS double tl_wfsrc_get_last_sample_rate(pin)
int pin;
DESCRIPTION Retrieves the sample rate of the segment that was sourced last.
ARGUMENTS pin—Pinmap identifier
RETURN VALUE Sample Rate of segment
tl_wfsrc_get_sample_rate
Return sample rate of segment.
SYNOPSIS double tl_wfsrc_get_sample_rate(pin, pName)
int pin;
char *pName;
DESCRIPTION Retrieves sample rate from the segment database.
ARGUMENTS pin—Pinmap identifier
pName—Name of the defined segment
RETURN VALUE Sample Rate of segment
tl_wfsrc_get_segment_data
Return segment data.
SYNOPSIS int *tl_wfsrc_get_segment_data(pin, pName)
int pin;
char *pName;
DESCRIPTION Retrieves segment data for the named segment. The int pointer
that is returned must be freed by the caller.
IMAGE Solutions V8.3 26-508
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS pin—Pinmap identifier
pName—Name of the defined segment
RETURN VALUE Pointer to segment data
tl_wfsrc_get_segment_memory_size
Return total memory size.
SYNOPSIS int tl_wfsrc_get_segment_memory_size(pin)
int pin;
DESCRIPTION Returns total segment memory size.
ARGUMENTS pin—Pinmap identifier
RETURN VALUE Size of segment memory minus calibration wave storage
tl_wfsrc_get_segment_size
Return segment size.
SYNOPSIS int tl_wfsrc_get_segment_size(pin, pName)
int pin;
char *pName;
DESCRIPTION Retrieves segment size for the named segment.
ARGUMENTS pin—Pinmap identifier
pName—Name of the defined segment
RETURN VALUE Size of segment
tl_wfsrc_show_segment_info
Print segment info.
SYNOPSIS void tl_wfsrc_show_segment_info(pin, pName)
int pin;
char *pName;
DESCRIPTION Retrieves and prints segment information.
ARGUMENTS pin—Pinmap identifier
pName—Name of the defined segment or NULL which will cause
the info of all segments to be printed.
RETURN VALUE None
tl_write_datnum
Change the test datalog number.
IMAGE Solutions V8.3 26-509
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_write_datnum(newnum);
int newnum;
DESCRIPTION Changes the datalog number of a test (the test number). This
function must be called from within a TESTF function. Otherwise,
the function return an error value (-2) and generates a runtime
error.
The new test number is first checked to see if it is within bounds
(greater than 0). If the test number is less than or equal to 0, a
runtime error is generated.
If successful, the function returns the old test number.
Possible error messages:
tl_write_datnum() illegal outside of a TESTF
tl_write_datnum() illegal test number <#>
ARGUMENTS newnum—New test number
RETURN VALUE -2 on error, otherwise the former test number
SIDE EFFECTS Changes the test number and alters the datalog printout
tl_write_format
Change the test result datalog format.
SYNOPSIS int tl_write_format(newfmt)
char *newfmt;
DESCRIPTION Changes the test format string. Previous format string is
overwritten, and data is written according to the specified format.
Format string cannot exceed 15 characters.
ARGUMENTS newfmt—Pointer to character string containing new format.
RETURN VALUE 0 Change was successful
-2 Errors occurred
SIDE EFFECTS Changes format string for ASCII datalog output.
SEE ALSO “tl_write_label”
tl_write_highlim
Change the upper limits for a test.
SYNOPSIS int tl_write_highlim(newlim)
double newlim;
DESCRIPTION Changes the upper limit for a test to the value in newlim. The
original limit is erased and all future test statements will use the
new limit.
IMAGE Solutions V8.3 26-510
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS newlim—Double variable containing the new high limit.
RETURN VALUE 0 Limit set, there was previously no upper limit
1 Limit set, previous limit replaced
-2 Error
SIDE EFFECTS Changes comparison limits for a test.
SEE ALSO “tl_read_lowlim”, “tl_read_highlim”
tl_write_label
Change the test label string.
SYNOPSIS int tl_write_label(s)
char *s;
DESCRIPTION Changes the test’s label string. Should not exceed 18 characters
(not including the null at end). Subsequent output displays the
new label.
This function can be used to change the label if repeat has been
used on the sequencer line, giving each test iteration a unique
label. For example:
SEQUENCER HBINTEST()
{
seq test_val() "Dummy" $9000 repeat = 3 >5.0v <10.0v f(0);
}
TESTF test_val()
{
int i;
char buffer[1024];
for (i = 0; i < 3; i++) {
sprintf(buffer, "New test label %d", i);
tl_write_label(buffer);
test 5.8v;
}
}
The ability to generate a unique test label per test in a repeat is
the new default behavior for this function. You can defeat it by
including the following line in a .load file or a .image_behavior
file:
-behavior variable_labels_in_repeat disable
This causes the function, when used in with repeat, to modify
the label only for the first test.
ARGUMENTS s—Pointer to character string containing new test label.
RETURN VALUE 0 Successful change
-2 Errors
IMAGE Solutions V8.3 26-511
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SIDE EFFECTS Changes test’s label string.
SEE ALSO “tl_read_ids”, “tl_read_lot_id”, “tl_read_sblot_id”, “tl_begin_lot”,
“tl_write_format”, “tl_write_lot_id”, “tl_write_sblot_id” and
“Changing Test Labels When Using Repeat” on page 14-17
tl_write_lowlim
Change the lower test limit.
SYNOPSIS int tl_write_lowlim(newlim)
double newlim;
DESCRIPTION Changes the lower limit for a test to the value in newlim. The
original limit is erased and all future test statements will use the
new limit.
ARGUMENTS newlim—Double variable containing the new low limit.
RETURN VALUE 0 Limit set, there was previously no lower limit
1 Limit set, old limit replaced
-2 Errors
SIDE EFFECTS Changes low limit for a test.
tl_write_user_eeprom_all_data
Write all data to HUC ID PROM.
SYNOPSIS int tl_write_user_eeprom_all_data(which, buf)
EEPROM_ENUM_TYPE which;
unsigned short *buf;
DESCRIPTION Writes all data (16 words x 16 bits/word) to one of four ID
EEPROMs on the HUC. The argument which determines to
which EEPROM is written. The data is obtained from a 16
element array of unsigned short pointed to by the argument buf.
ARGUMENTS which—Determines which ID EEPROM on the HUC is written to:
CONFIGA—Configuration Board A
CONFIGB—Configuration Board B
DIB—Device Interface Board (DIB)
TLDUT—Device Under Test (DUT)
buf—Points a 16 element array of unsigned short from which to
obtain the data
RETURN VALUE 1 operation successful
0 failure
IMAGE Solutions V8.3 26-512
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
tl_write_user_eeprom_id_data
Write coded data to HUC ID PROM.
SYNOPSIS int tl_write_user_eeprom_id_data(which, buf)
EEPROM_ENUM_TYPE which;
TER_EEPROM_ID *buf;
DESCRIPTION Writes Teradyne configuration data to one of four ID EEPROMS
on the HUC. The argument which determines to which
EEPROM is written. The data is obtained from the structure of
type TER_EEPROM_ID pointed to by the argument buf.
ARGUMENTS which—Determines which ID EEPROM on the HUC is written to:
CONFIGA—Configuration board A
CONFIGB—Configuration board B
DIB—Device interface board (DIB)
TLDUT—Device under test (DUT)
buf—Points a structure of type TER_EEPROM_ID from which to
obtain the data
RETURN VALUE 1 operation successful
0 failure
tl_xachan
Read or write a register in the mixed-signal test head (analog).
SYNOPSIS int tl_xachan(achan, echo, reg, write, data)
char *achan;
int echo, reg, write, data;
DESCRIPTION This function is the low-level I/O function used to read or write a
register in the analog part of the mixed-signal (A500/550) test
head, given an analog channel string, such as 4A.
ARGUMENTS achan—Analog Channel string, such as 4A.
echo—Set to 1 if echo RAM, 0 for no echo
reg—Register number, 0 to 63
write—Set to 1 for write, 0 for read
data—Data when transfer is a write
RETURN VALUE If write is 1, return 0, else return the data read.
SEE ALSO “tl_xath”
tl_xath
Read or write a register in the mixed-signal test head (analog).
IMAGE Solutions V8.3 26-513
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_xath(slot, echo, reg, write, data)
int slot, echo, reg, write, data;
DESCRIPTION This function is the low-level I/O function used to read or write a
register in the analog part of the mixed-signal (A500/A550) test
head, given a slot number in the head.
ARGUMENTS slot—Test head slot number
echo—Set to 1 if echo RAM, 0 for no echo
reg—Register number, 0 to 63
write—Set to 1 for write, 0 for read
data—Data when transfer is a write
RETURN VALUE If write is 1, return 0, else return the data read.
SEE ALSO “tl_xachan”
tl_xcc
Read or write a register in a mixed-signal conversion cage.
SYNOPSIS int tl_xcc(mapsel, brdsel, field, reg, write, data)
int mapsel, brdsel, field, reg, write, data;
DESCRIPTION This function is the low-level I/O function used to read or write a
register in a mixed-signal (A500/A550) conversion cage. An
address in the conversion cage is made up of the following
components: a map select, a board select, a field, and a register
number.
ARGUMENTS mapsel—The map select value from 0 to 31.
brdsel—Board select value 0 to 63
field—Field number, 0, 1, 2, or 3
reg—Register number, 0 to 31
write—Set to 1 for write, 0 for a read
data—16 bit data to write when transfer is a write
RETURN VALUE If write is 1, return 0, else return the data read.
tl_xpacs
Read or write a register in a Precision AC cage.
SYNOPSIS int tl_xpacs(brdsel, field, reg, write, data)
int brdsel, field, reg, write, data;
DESCRIPTION This function is the low-level I/O function used to read or write a
register in a Precision AC Subsystem cage. An address in the
Precision AC cage is made up of the following components: a
board select, a field, and a register number.
IMAGE Solutions V8.3 26-514
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
ARGUMENTS brdsel—Board select value 0 to 63
field—Field number, 0, 1, 2, or 3
reg—Register number, 0 to 31
write—Set to 1 for write, 0 for a read
data—16 bit data to write when transfer is a write
RETURN VALUE If “write” is 1, return 0, else return the data read
tl_xvb
Read or write a register in a mixed-signal vector bus cage.
SYNOPSIS int tl_xvb(mapsel, brdsel, field, reg, write, data)
int mapsel, brdsel, field, reg, write, data;
DESCRIPTION This function is the low-level I/O function used to read or write a
register in a mixed-signal (A500/A550) vector bus cage. An
address in the vector bus cage is made up of the following
components: a map select, a board select, a field, and a register
number.
ARGUMENTS mapsel—The map select value from 0 to 31.
brdsel—Board select value 0 to 63
field—Field number, 0, 1, 2, or 3
reg—Register number, 0 to 31
write—Set to 1 for write, 0 for a read
dat—16 bit data to write when transfer is a write
RETURN VALUE If write is 1, return 0, else return the data read.
wait_until_cdig_halt
Check for stopped Serial Bus Channel Card (SBCC) hardware.
SYNOPSIS int wait_until_cdig_halt(pinnum);
int pinnum;
DESCRIPTION This function checks the SBCC board(s) referenced by the pin
number and returns from the call when the board(s) have either:
a) finished executing the current segment, or
b) timed out in either hardware or software
If the pin is multisite, the function waits for the boards from both
sites to halt or timeout. The maximum number of sites is limited
by the maximum number of SBCC boards per test head, which
is 2.
If software timeout is enabled and the segment was started
by_cpu, the timeout period begins when the start <spec>
IMAGE Solutions V8.3 26-515
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
cdig:by_cpu was executed. If the segment was set up to start
by_trigger or by_event, the timeout period begins when
wait_until_cdig_halt is called.
If the segment times out and the segment is still running, the
segment is halted, and the pattern address is set to 1 past the
end of the timed-out segment.
On the simulator, patterns never fail and never time out.
ARGUMENTS pinnum—Pin number that references card(s) to be checked
RETURN VALUE 0 hardware has halted
1 pattern has timed out (software)
2 pattern has timed out (hardware)
-1 error
SEE ALSO “wait_until_cdig_halt_slot”
wait_until_cdig_halt_slot
Check for stopped Serial Bus Channel Card (SBCC) hardware.
SYNOPSIS int wait_until_cdig_halt_slot(slot);
int slot;
DESCRIPTION This function checks the SBCC board(s) referenced by the slot
number and returns from the call when the board has finished
executing the current segment or has timed out while trying to do
so.
If software timeout is enabled and the segment was started
by_cpu, the timeout period begins when the start <spec>
cdig:by_cpu was executed. If the segment was set up to start
by_trigger or by_event, the timeout period begins when
wait_until_cdig_halt is called.
If the segment times out and the segment is still running, the
segment is halted, and the pattern address is set to 1 past the
end of the timed-out segment.
On the simulator, patterns never fail and never time out.
ARGUMENTS slot—Slot number that references card to be checked
RETURN VALUE 0 hardware has halted
1 pattern has timed out (software)
2 pattern has timed out (hardware)
-1 error
SEE ALSO “wait_until_cdig_halt”
IMAGE Solutions V8.3 26-516
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
wait_until_h50_halt
Check if SCM is still running.
SYNOPSIS int wait_until_h50_halt()
DESCRIPTION Waits for either the pattern timeout to expire (if timeout is
enabled) or for the pattern to halt on the first sequencer. If
timeout is enabled and expires the pattern will be halted by this
function before returning.
Note that if timeout is NOT enabled, and the pattern has an
infinite loop, this function may never return.
Under simulation, timeout will never occur. The pattern will run
forever if it has an infinite loop regardless of timeout state.
If all sites have been disabled, then stop the pattern that is
running on this sequencer. Note that a sequencer in keepalive is
not considered running.
ARGUMENTS None
RETURN VALUE TL_H50_TIMEOUT if pattern was still running, timeout was
enabled and timeout expired. else TL_H50_NOREADCODE if
pattern returned no readcode. else the readcode returned by the
pattern (from 0 to 2047).
SEE ALSO wait_until_h50_halt_scm()
wait_until_h50_halt_scm
Check if SCM is still running.
SYNOPSIS int wait_until_h50_halt_scm(scm)
int scm;
DESCRIPTION Waits for either the pattern timeout to expire (if timeout is
enabled) on scm number scm, or for the pattern to halt.
If timeout is enabled and expires the pattern will be halted by this
function before returning.
Note that if timeout is NOT enabled, and the pattern has an
infinite loop, this function may never return. Under simulation,
timeout will never occur. The pattern will run forever if it has an
infinite loop regardless of timeout state.
ARGUMENTS int which_scm—TL_FIRST_SCM for scm 1
TL_SECOND_SCM for scm 2
RETURN VALUE TL_H50_TIMEOUT if pattern was still running, timeout was
enabled and timeout expired. else TL_H50_NOREADCODE if
IMAGE Solutions V8.3 26-517
IMAGE Base Language: Base IMAGE Functions: Base IMAGE Function Reference
Table of Contents Index Home Master Index Search Help
pattern returned no readcode. else the readcode returned by the
pattern (from 0 to 2047).
SEE ALSO wait_until_h50_halt()
IMAGE Solutions V8.3 26-518
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
Obsolete Functions
Obsolete functions remain in IMAGE and continue to work, provided the hardware they
control does not change. Use of obsolete functions is discouraged in new programs. New
functions are provided to replace obsolete functions for functionality that is still needed. Use
the new functions in new programs and to update programs that must work with new
hardware.
The obsolete IMAGE functions in table 26-11 are listed for reference.
Table 26-11. Obsolete Base IMAGE Test Program Functions
Function Action
handlerprober_bin Send bin command to handler
handlerprober_start Wait for handler start
read_apu_pin Read results APU local meter measurement
tl_apu_read_pin Read results of APU local meter measurement
tl_apucal_subr Calibrate all installed APU channels
tl_hand_id Global variable containing the name of a handler or
prober
tl_read_dib_id Read back DIB ID code.
tl_read_hand_id Return the value of the handler ID
tl_read_prb_card Read the ID of the DIB (or probe card)
tl_hsds_dsim_clear Reset simulation parameters
tl_hsds_dsim_clutch1 Simulate clutch1
tl_hsds_dsim_clutch2 Simulate clutch2
tl_hsds_dsim_cond1 Simulate hardware condition 1
tl_hsds_dsim_cond2 Simulate hardware condition 2
tl_hsds_dsim_cond3 Simulate hardware condition 2
tl_hsds_dsim_cycles_per_pass Set cycles per pass
tl_hsds_dsim_fail Simulate failing results
tl_hsds_dsim_io_timing Simulate IO channel operation
tl_hsds_dsim_max_cycles Set maximum HRAM cycle count
tl_hsds_dsim_nopatsim Disable pattern execution simulation
tl_hsds_dsim_pass Simulate passing results
IMAGE Solutions V8.3 26-519
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
Table 26-11. Obsolete Base IMAGE Test Program Functions (Continued)
Function Action
tl_hsds_dsim_patsim Simulate pattern execution
tl_set_hand_id Set handler ID for the current lot
tl_set_trouble_indicator Control station trouble indicator
tl_touch_pages_record_faults Record page faults before run
tl_uwport_std_cal_one_port Calibrate one port s-parameter for all frequencies and
amp
tl_uwport_std_cal_one_port_slot One port s-parameter
tl_write_device Set the device number for the next device to be tested
tl_write_dib_id_to_stdf Write the DIB ID to the datalog stream
tl_write_job_rev Set the test program revision ID
tl_write_lot_id Set the lot or sublot ID.
tl_write_lot_ids Set the lot or sublot ID in a single function call.
tl_write_sblot_id See tl_write_lot_id
tl_write_newtest Create a new test or modify an existing one
tl_write_wafer Write device wafer coordinates
tl_write_wavefile Write wavefile data.
tl_write_wavefile_struct Write wavefile using struct header.
handlerprober_bin
Send bin command to handler (obsolete).
SYNOPSIS handlerprober_bin()
DESCRIPTION This function send a binning command to the handler currently
connected and enabled. It is designed to be used with the
function handlerprober_start. This function was designed for
programs using IMAGE versions before V2.0. It is supported
mainly for backward compatibility. Most programs written for
later versions of IMAGE take advantage of more powerful
handler software, in which the IMAGE executive sends the bin
command to handler automatically after each run.
ARGUMENTS None
RETURN VALUE -1 for error, 1 for success
IMAGE Solutions V8.3 26-520
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
handlerprober_start
Wait for handler start (obsolete).
SYNOPSIS handlerprober_start()
DESCRIPTION This function polls the currently enabled handler or prober,
waiting for a start signal. It will block until a start is received or
until an error occurs. This function was designed for programs
using versions of IMAGE before V2.0. It is supported mainly for
backward compatibility; most programs written for later versions
of IMAGE take advantage of more powerful handler software, in
which the IMAGE executive polls the handler for start signals.
ARGUMENTS None
RETURN VALUE -1 for error, 1 for success
SIDE EFFECTS Blocks (waits) until handler start or error
read_apu_pin
Read results APU local meter measurement. Obsolete; replaced by
“read_apu_pin_multisite”.
SYNOPSIS double read_apu_pin(pin_number_array, result_array)
short *pin_number_array;
double *result_array;
DESCRIPTION Note: This function does not work properly on multisite programs
and exists only for legacy purposes. It is replaced by
read_apu_pin_multisite.
Reads the results of an APU local meter measurement for a
single pin or list of pins and returns the result(s) in
result_array. The first parameter can either be a single pin
number or a pointer to a 0-terminated list of pin numbers. The
second parameter is a two-dimensional array of doubles of the
form result_array[TL_SYS_MAX_SITES] [NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
If the first parameter is a single pin, the measurement result is
also returned as the function return value. If there is not exactly
one active test site, 0 is returned. If the first parameter specifies
a list of pins, the function return value is undefined.
If the test program uses multisite test, result_array must be
large enough to store values from all test sites. The function
does not fill in results for sites that are not active.
double results[TL_SYS_MAX_SITES][NUMBER_OF_PINS];
int i;
IMAGE Solutions V8.3 26-521
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
serial {
read_apu_pin(APU_PINS, results);
for (i = 0; i < NUMBER_OF_PINS; i++)
test results[tl_site][i];
}
For the UB APU, this function reads the results of an APU local
meter measurement which was simulated via the measure driver
and measure bus.
ARGUMENTS short *pin_number_array—Pointer to list of APU pin numbers
double *result_array—Pointer to list of APU results
RETURN VALUE See description.
SIDE EFFECTS Produces a run-time error for error conditions.
SEE ALSO “tl_apu_read_pin”, “read_apu”, “read_apu_pin_multisite”
tl_apu_read_pin
Read results of APU local meter measurement. Obsolete; replaced by
“read_apu_pin_multisite”.
SYNOPSIS double
tl_apu_read_pin(pin_number_array,result_array)
short *pin_number_array;
double *result_array;
DESCRIPTION Reads the results of an APU local meter measurement for a
single pin or a list of pins and returns the value(s) in the
parameter result_array. The first parameter can either be a
single pin number or a pointer to a zero-terminated list of pin
numbers. The second parameter must be a two-dimensional
array of doubles of the form
result_array[TL_SYS_MAX_SITES] [NUMBER_OF_PINS]
where NUMBER_OF_PINS is the number of pins specified in the
first parameter.
If the first parameter is a single pin, the measurement result is
also returned as the function return value. If there is not exactly
one active test site, 0 is returned. If the first parameter specifies
a list of pins, the function return value is undefined.
The function can be used inside or outside a serial loop. It does
not fill in results for test sites that are not active.
double results[TL_SYS_MAX_SITES][NUMBER_OF_PINS];
int i;
tl_apu_read_pin(APU_PINS, results);
serial {
for (i = 0; i < NUMBER_OF_PINS; i++)
IMAGE Solutions V8.3 26-522
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
test results[tl_site][i];
}
serial {
tl_apu_read_pin(APU_PINS, results);
for (i = 0; i < NUMBER_OF_PINS; i++)
test results[tl_site][i];
}
For the UB APU, this function reads the results of an APU local
meter measurement which was simulated via the measure driver
and measure bus.
ARGUMENTS pin_number_array—Pointer to list of APU pin numbers
result_array—Pointer to list of APU results
RETURN VALUE See description.
SIDE EFFECTS Produces a run-time error for error conditions.
SEE ALSO “read_apu_pin”, “read_apu”, “read_apu_pin_multisite”
tl_apucal_subr
Calibrate all installed APU channels.
SYNOPSIS short tl_apucal_subr(output_mode)
int output_mode;
DESCRIPTION This function is supported for compatibility with a user-level
function in the original APU driver. It is also called from
imagemain.o to implement the calibrate -apu command. It
calibrates all installed UB APU channels.
ARGUMENTS int output_mode—Output mode as described in
tl_cal_setup
RETURN VALUE 0—Calibration passed for all channels
!=0—Number of the first channel which failed calibration
SIDE EFFECTS Calibrates all installed APUs. Resets all instruments.
SEE ALSO tl_apu_calibrate_all, tl_apu_cal,
“tl_apu_cal_set_interval”, tl_apu_cal_time_check,
tl_apucal_subr (in original APU driver file spmucal.c)
system/standards/drivers/s.calibrator.rules
system/standards/drivers/s.cal_util.doc
tl_hand_id
This global variable contains either the name of the handler (or prober) selected or a null
(zero-length) string. The variable is set either when the command handlerconf -connect
is executed or when the handlerprober_init function is passed the name of a peripheral (see
IMAGE Solutions V8.3 26-523
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
“Initializing Handler Software Interface” on page 1-27 in the Handler/Prober Manual). To
reference this global variable, you must add a declaration to the header section of your
program:
extern char tl_hand_id[]
NOTE
The handlerconf -connect command must be given before the test program has been
run to ensure that tl_hand_id is set correctly to name given in the handlerconf -connect
command.
tl_hsds_dsim_clear
Reset simulation parameters.
SYNOPSIS void tl_hsds_dsim_clear();
DESCRIPTION Resets digital simulator commands (dsim -clear)
ARGUMENTS None
RETURN VALUE None
tl_hsds_dsim_clutch1
Simulate clutch1.
SYNOPSIS void tl_hsds_dsim_clutch1(patname, vec_first,
vec_last, cycle_first, cycle_last)
char *patname;
int vec_first, vec_last;
int cycle_first, cycle_last;
DESCRIPTION Simulate the clutch1 for the specified range of vectors and/or
cycles.
ARGUMENTS patname—Pattern name
vec_first, vec_last—First and last vector numbers
cycle_first, cycle_last—First and last cycle numbers
RETURN VALUE None
tl_hsds_dsim_clutch2
Simulate clutch2.
SYNOPSIS void tl_hsds_dsim_clutch2(patname, vec_first,
vec_last, cycle_first, cycle_last)
char *patname;
IMAGE Solutions V8.3 26-524
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
int vec_first, vec_last;
int cycle_first, cycle_last;
DESCRIPTION Simulate the clutch2 for the specified range of vectors and/or
cycles.
ARGUMENTS patname—Pattern name
vec_first, vec_last—First and last vector numbers
cycle_first, cycle_last—First and last cycle numbers
RETURN VALUE None
tl_hsds_dsim_cond1
Simulate hardware condition 1.
SYNOPSIS void tl_hsds_dsim_cond1(patname, vec_first,
vec_last, cycle_first, cycle_last)
char *patname;
int vec_first, vec_last;
int cycle_first, cycle_last;
DESCRIPTION Simulate the hardware condition 1 (cond1) for the specified
range of vectors and/or cycles.
ARGUMENTS patname—Pattern name
vec_first, vec_last—First and last vector numbers
cycle_first, cycle_last—First and last cycle numbers
RETURN VALUE None
tl_hsds_dsim_cond2
Simulate hardware condition 2.
SYNOPSIS void tl_hsds_dsim_cond2(patname, vec_first,
vec_last, cycle_first, cycle_last)
char *patname;
int vec_first, vec_last;
int cycle_first, cycle_last;
DESCRIPTION Simulate the hardware condition 2 (cond2) for the specified
range of vectors and/or cycles.
ARGUMENTS patname—Pattern name
vec_first, vec_last—First and last vector numbers
cycle_first, cycle_last—First and last cycle numbers
RETURN VALUE None
IMAGE Solutions V8.3 26-525
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
tl_hsds_dsim_cond3
Simulate hardware condition 3.
SYNOPSIS void tl_hsds_dsim_cond3(patname, vec_first,
vec_last, cycle_first, cycle_last)
char *patname;
int vec_first, vec_last;
int cycle_first, cycle_last;
DESCRIPTION Simulate the hardware condition 3 (cond3) for the specified
range of vectors and/or cycles.
ARGUMENTS patname—Pattern name
vec_first, vec_last—First and last vector numbers
cycle_first, cycle_last—First and last cycle numbers
RETURN VALUE None
tl_hsds_dsim_cycles_per_pass
Set cycles per pass.
SYNOPSIS void tl_hsds_dsim_cycles_per_pass
int ct;
DESCRIPTION Sets the number of cycles executed per pass through the pattern
simulator.
ARGUMENTS ct—Cycles per pass
RETURN VALUE None
tl_hsds_dsim_fail
Simulate failing results.
SYNOPSIS void tl_hsds_dsim_fail(patname, chan_first,
chan_last, vec_first, vec_last)
char *patname;
int chan_first, chan_last;
int vec_first, vec_last;
DESCRIPTION Set up specific channels/vectors to fail.
ARGUMENTS patname—Pattern name
chan_first, chan_last—First and last channel numbers
vec_first, vec_last—First and last vector numbers
RETURN VALUE None
IMAGE Solutions V8.3 26-526
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
tl_hsds_dsim_io_timing
Simulate I/O channel operation.
SYNOPSIS void tl_hsds_dsim_io(patname)
char *patname;
DESCRIPTION Enables I/O channel operation simulation for the specified
pattern (dsim -io_timing).
ARGUMENTS patname—Pattern name
RETURN VALUE None
tl_hsds_dsim_max_cycles
Set maximum HRAM cycle count.
SYNOPSIS void tl_hsds_dsim_max_cycles(max_ct)
int max_ct;
DESCRIPTION Sets the maximum HRAM cycle count (dsim -max_cycles).
ARGUMENTS max_ct—Maximum count in the range 0 to 4K
RETURN VALUE None
tl_hsds_dsim_nopatsim
Disable pattern execution simulation.
SYNOPSIS void tl_hsds_dsim_nopatsim(patname)
char *patname;
DESCRIPTION Disables simulation of pattern execution (dsim -nopatsim).
ARGUMENTS patname—Pattern name
RETURN VALUE None
tl_hsds_dsim_pass
Simulate passing results.
SYNOPSIS void tl_hsds_dsim_pass(patname, chan_first,
chan_last, vec_first, vec_last)
char *patname;
int chan_first, chan_last;
int vec_first, vec_last;
DESCRIPTION Set up specific channels/vectors to pass (dsim -pass).
ARGUMENTS patname—Pattern name
chan_first, chan_last—First and last channel numbers
vec_first, vec_last—First and last vector numbers
IMAGE Solutions V8.3 26-527
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
RETURN VALUE None
tl_hsds_dsim_patsim
Simulate pattern execution.
SYNOPSIS void tl_hsds_dsim_patsim(patname)
char *patname;
DESCRIPTION Enables simulation of pattern execution (dsim -patsim).
ARGUMENTS patname—Pattern name
RETURN VALUE None
tl_read_dib_id
Obsolete function. Read back DIB ID code.
SYNOPSIS int tl_read_dib_id()
DESCRIPTION OBSOLETE—Actually reads the DIB type, not the DIB ID, but is
maintained for backwards compatibility. Use
“tl_read_dib_type_int” instead.
ARGUMENTS None
RETURN VALUE Integer board type value from the board type field as described
in the appendix, “Test Head EEPROMs”. Returns 0 if EEPROM
can’t be read.
tl_read_hand_id
Return the value of the handler or prober ID.
SYNOPSIS char *tl_read_hand_id(s);
DESCRIPTION Receives a pointer to a character string as an argument and
copies the handler or prober ID into it. The handler or prober ID
is set automatically by the handlerconf command when the
handler or prober is connected (by software). Example:
{
char text[S_STDF_STRING+1];
printf("The handler is:
'%s'\n",tl_read_hand_id(text));
}
ARGUMENTS char *s—A pointer to user-allocated memory which will have
the handler or prober ID written to it. It is your responsibility to
allocate sufficient memory.
RETURN VALUE A character string containing the handler or prober ID, through
the argument.
IMAGE Solutions V8.3 26-528
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
tl_read_prb_card
Read the DIB (or probe card) ID.
SYNOPSIS char * tl_read_prb_card(s)
char s[];
DESCRIPTION Use the preferred function “tl_read_and_set_dib_info”
If you use tl_read_prb_card(), its behavior is governed by the
IMAGE Behavior Chooser option accurate_eeprom_strings.
When this option is enabled (the default), tl_read_prb_card()
calls tl_read_and_set_dib_info(EEPROM_LONG_STRING).
When disabled, tl_read_prb_card() retains its behavior
before IMAGE V6.4 and reads the DIB ID from the EEPROM and
stores it in the prb_card field in the Site Description Record,
which gets written to the datalog stream.
ARGUMENTS (The address of) An array in which to place the probe card (or
DIB) ID string.
RETURN VALUE Its argument (the probe card or DIB ID).
SIDE EFFECTS Reads the DIB ID and sets tl_prb_card to this ID.
tl_set_hand_id
Set handler ID for the current lot.
SYNOPSIS int tl_set_hand_id(s)
char *s;
DESCRIPTION This function sets the handler ID for the current lot. The handler
ID is a string sent to the datalogger to record the name of the
handler used to test the lot.
You must call this function before any testing or datalogging is
done for the lot. In other words, to set the handler ID for the
current lot, you must call this function before the execution of the
first sequencer of the first run of the test program.
For details on the information recorded by the IMAGE datalogger
in STDF files, see “Generating STDF Files” on page 24-2 or the
Standard Test Data Format (STDF) Specification, Version 4.
ARGUMENTS s—String containing the handler ID
RETURN VALUE None
SIDE EFFECTS Dumps the datalog buffer when called.
May generate a TL error if called after testing has begun.
IMAGE Solutions V8.3 26-529
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
tl_set_trouble_indicator
Control station trouble indicator.
SYNOPSIS int tl_set_trouble_indicator(flag)
int flag;
DESCRIPTION This function controls the setting of the “trouble” indicator for the
station in which the test program is loaded. When the trouble
indicator is turned on, the “station status” window flashes the
appropriate station number, signalling the operator that an error
condition exists for the test station. This function has no effect if
the station status window is not running.
ARGUMENTS flag—if nonzero, indicator is turned on
if zero, indicator is turned off
RETURN VALUE None
tl_touch_pages_record_faults
Record page faults before run. This function is no longer user-callable. Use the memory
profiling feature introduced in IMAGE V5.6 instead.
SYNOPSIS int tl_touch_pages_record_faults;
int tl_touch_pages_faults;
DESCRIPTION Before each test program run, IMAGE performs an operation
called “touch pages” which brings all virtual memory pages used
by the program into physical memory, provided that the test
program is small enough to fit into the available physical memory
along with IMAGE and UNIX. This technique ensures that the
program avoids page faults during execution, resulting in
repeatable execution.
These global variables control recording of the number of page
faults encountered during the touch pages operation. Setting the
variable tl_touch_pages_record_faults to 1 instructs
IMAGE to record the number of page faults during touch pages
and place this number in the global variable
tl_touch_pages_faults on each run.
Note that page faults recorded in tl_touch_pages_faults are
different from faults reported by the run command. The latter
correspond to page faults generated by user code (usually
indicating that the test program is too big to fit in the available
physical memory of the tester).
Throughput-sensitive test programs should not indiscriminately
set tl_touch_pages_record_faults to 1, since gathering the
page fault data involves an additional UNIX system call per run,
which can add a few milliseconds of test time (or more).
IMAGE Solutions V8.3 26-530
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
ARGUMENTS Not applicable
RETURN VALUE Not applicable
SIDE EFFECTS Setting tl_touch_pages_record_faults results in an
additional UNIX system call per run
tl_uwport_std_cal_one_port
Calibrate one port s-parameter for all frequencies and amplitudes used with a pin.
SYNOPSIS int tl_uwport_std_cal_one_port(pin, freqs, amps,
open_vals, short_vals, load_vals, num_vals,
open_filename, short_filename, load_filename);
int pin;
double freqs[], amps[];
D_COMPLEX open_vals[], short_vals[], load_vals[];
int num_vals;
char open_filename[], short_filename[],
load_filename[];
DESCRIPTION Calibrates s-parameter for a single pin. Builds the one port error
adapter for a single pin on a UWPORT at each
frequency/amplitude pair given. You write a function to gather
raw s-parameter measurements of each calibration standard on
each pin of interest, then call this function for each pin with the
corresponding cal standard data.
ARGUMENTS pin—pin name or pin number (must correspond to a UWPORT)
freqs[LENGTH], amps[LENGTH]—frequency and amplitude
pairs at which to calibrate. Freq in Hz, amp in dBm.
open_vals[LENGTH], short_vals[LENGTH],
load_vals[LENGTH]—measured s-parameter values for the
open, short, and load cal standards
num_vals—number of points to calibrate at (typically, LENGTH)
open_filename, short_filename, load_filename—names of
files of data on the open, short, and, load standards in .s2p
format.
RETURN VALUE 0 if no error
Nonzero if error
SEE ALSO “read_uwport_raw_one_port”
tl_uwport_std_cal_one_port_slot
One port s-parameter calibration for all frequencies and amplitudes used with a pin.
IMAGE Solutions V8.3 26-531
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
SYNOPSIS int tl_uwport_std_cal_one_port_slot(slot, schan,
freqs, amps, open_vals, short_vals, load_vals,
num_vals, open_filename, short_filename,
load_filename);
int slot, schan;
double freqs[], amps[];
D_COMPLEX open_vals[], short_vals[], load_vals[];
int num_vals;
char open_filename[], short_filename[],
load_filename[];
DESCRIPTION This function is obsolete. Use
“read_uwport_one_port_cal_std_slot” instead.
This function description is provided only for reference. It does
not maintain termination information so it is not possible to
distinguish sourcing directly through the UWPORT to the device
from sourcing through the add path to the device.
If your program is running correctly now and you do not use the
add path during s-parameter measurements unless there is only
one UWSRC attached to the UWPORT, the program should
continue to work. However, write new code using the new
functions.
Two port s-parameter support is provided by
read_uwport_two_port_cal_std_forward_slot and
read_uwport_two_port_cal_std_reverse_slot.
Call this function to do s-parameter calibration for a single
slot/schan. It builds the one port error adapter for a single pin on
a UWPORT at each frequency/amplitude pair given. Write a
function to gather raw s-parameter measurements of each cal
standard on each pin of interest then call this function for each
pin with the corresponding cal standard data.
ARGUMENTS slot, schan—UWPORT slot and schan
freqs[LENGTH], amps[LEGTH]—frequency and amplitude pairs
at which to calibrate. Freq in Hz, amp in dBm.
open_vals[LENGTH], short_vals[LENGTH],
load_vals[LENGTH]—measured s-parameter values for the
open, short, and load cal standards
num_vals—number of points to calibrate at (LENGTH, if the
array is full)
*open_filename, *short_filename, *load_filename—
names of files of data on the open, short, and load standards in
.s2p format.
RETURN VALUE 0 if no error
!0 if error
IMAGE Solutions V8.3 26-532
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
SEE ALSO “read_uwport_one_port_cal_std”,
“read_uwport_one_port_cal_std_slot”,
“read_uwport_two_port_cal_std_forward_slot”,
“read_uwport_two_port_cal_std_reverse_slot”
tl_write_device
Set the device number for the next device to be tested.
SYNOPSIS int tl_write_device;
DESCRIPTION Sets the device number for the next device to be tested. The
device number for the current device under test cannot be
changed.
ARGUMENTS None
RETURN VALUE Old number for the next device
SEE ALSO “tl_read_device”, “tl_read_part_id”
tl_write_dib_id_to_stdf
Write the DIB ID to the datalog stream.
SYNOPSIS void tl_write_dib_id_to_stdf();
DESCRIPTION Use the preferred function tl_read_and_set_dib_info().
If you use tl_write_dib_id_to_stdf(), its behavior is
governed by the IMAGE Behavior Chooser option
accurate_eeprom_strings. When this option is enabled (the
default), tl_write_dib_id_to_stdf() calls
tl_read_and_set_dib_info(EEPROM_LONG_STRING). When
disabled, tl_write_dib_id_to_stdf() retains its behavior
before IMAGE V6.4 and reads the DIB ID from the EEPROM and
stores it in the dib_typ field in the Site Description Record,
which gets written to the datalog stream.
You must call this function before any sequencers are executed
during the first run of a test program for any particular lot.
Otherwise, the information may not be correct. Normally, IMAGE
writes the DIB ID to the SDR automatically.
ARGUMENTS None
RETURN VALUE None
SEE ALSO “tl_read_and_set_dib_info”
tl_write_job_rev
Set the test program revision ID.
IMAGE Solutions V8.3 26-533
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
SYNOPSIS tl_write_job_rev(s)
char *s;
DESCRIPTION Sets the revision ID string of the test program. Example:
{
tl_write_job_rev("Development Version #2");
}
You can only set the test program revision string from a test
program using tl_write_job_rev. If you are using SCCS to
control the sources, you might place the following code in your
test program’s tl_init() to set the test program revision:
tl_init()
{
static char *REV= "%W% %G% -
By John Henry";
tl_write_job_rev(REV);
}
ARGUMENTS (The address of) An array from which to set the revision string.
RETURN VALUE None
tl_write_lot_id
Set the lot or sublot ID.
SYNOPSIS tl_write_lot_id(s)
char *s;
tl_write_sblot_id(s)
char *s;
DESCRIPTION Sets the lot or sublot ID for the lot about to be tested. Set the lot
and sublot IDs before calling tl_begin_lot (or issuing the
startlot command) as they set up the data which will be used
for the next device lot. Example:
{
/* IN SETUP MODE: Read the bar code reader to get
the lot ID and open/start testing the new lot */
char lotid_from_reader[S_STDF_STRING+1];
get_barcode_text(lotid_from_reader);
tl_write_lot_id(lotid_from_reader);
tl_begin_lot(TRUE);
exit(); /*The next run will be the first part*/
}
ARGUMENTS The lot ID or sublot ID (text) to be assigned.
RETURN VALUE None
SEE ALSO “tl_read_lot_id”, “tl_read_sblot_id”, “tl_begin_lot”, “tl_read_ids”,
“tl_write_lot_ids”
IMAGE Solutions V8.3 26-534
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
tl_write_lot_ids
Set the lot or sublot ID in a single function call.
SYNOPSIS tl_write_lot_ids(s)
char *s;
DESCRIPTION Sets the lot or sublot ID or both for the lot which is about to be
tested in a single function call. This function scans the lot ID text
string for a “:” and if present sets both the lot and sublot IDs
accordingly. If one of the fields is “unspecified,” (that is, ":12" ==>
missing lot ID) then that field is set to NULL. If the “:” is not
present, the lot ID is set to the specified text, and the sublot ID is
unaffected. Example:
{
char lsid[[S_STDF_STRING+1];
sprintf(lsid,"Wafer:%d",wafer_number);
tl_write_lot_ids(lsid);
tl_begin_lot(TRUE);
exit();
}
ARGUMENTS A text string of the form: <lot ID>:<sublot ID> where either
item may be NULL.
RETURN VALUE None
SEE ALSO “tl_read_ids”, “tl_read_lot_id”, “tl_read_sblot_id”, “tl_begin_lot”,
“tl_write_lot_id”, “tl_write_sblot_id”
tl_write_sblot_id
See “tl_write_lot_id” on page 26-534.
tl_write_newtest
Create a new test and test number at runtime or modify the characteristics on an existing
one.
SYNOPSIS #include <limit_ops.h>
tl_write_newtest (num, label, format, loflag, lolim,
hiflag, hilim)
int num;
char *label, *format
unsigned char loflag, hiflag
double lolim, hilim;
DESCRIPTION This function is called from with a test function to change the
characteristics of that test function. Use this function sparingly.
You can accomplish most tasks requiring this capability using
variable test numbers at the sequencer level.
IMAGE Solutions V8.3 26-535
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
Calling tl_write_newtest() with a “new” test number replaces
the test number of the calling TESTF, effectively creating a new
test and leaving the “old” test number as a dummy. That is,
subsequent calls to the test from the same seq line (usually
subsequent runs of the program), automatically use the new test
number. The old number may appear on the summary report as
never executed. Be careful when using this function to create
new tests or test numbers. Again, consider using variable test
numbers.
ARGUMENTS num—new or existing test number
label—label for this test or 0 to use an existing one
format—format for this test or 0 to use an existing one
loflag—a FLAG (listed below) used to clarify the low limit
hiflag—a FLAG (listed below) used to clarify the high limit
lolim—value of the lower limit (according to loflag)
hilim—value of the upper limit (according to hiflag)
FLAGs (defined in limit_ops.h):
{LIM_SAME, Use the same limit as "calling" test
LIM_NOLIM, No limit to be used
LIM_LT, Specifies lower limit
LIM_GT, Specifies upper limit
LIM_EQ, Compare for equality for this limit
LIM_LE, Literally: (LIM_LT | LIM_EQ)
LIM_GE, Literally: (LIM_GT | LIM_EQ)
}
When setting or changing the limits to test for explicit equality, set
both the upper and lower limit flags to LIM_EQ and specify the
(same) value for each.
RETURN VALUE Nothing (NULL)
A -2 error code usually accompanied by a runtime error
signifying one of the following illegal conditions:
–Function not called from within a TESTF
–Specified format string is illegal (does not begin with %)
–Specified test number is illegal
SIDE EFFECTS Using this function to modify the characteristics of the existing
TESTF (that is, label, format, and limits, but not the test number)
is fairly straightforward. The only side effect is that it increases
the size of the datalog record (and resulting file) for that test
result.
SEE ALSO “tl_read_datnum”, “tl_write_label”, “tl_write_format”,
“tl_write_lowlim”, “tl_write_highlim”
IMAGE Solutions V8.3 26-536
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
tl_write_wafer
Write device wafer coordinates, for wafer mapping (obsolete). You must explicitly write them
for each device if wafer mapping reporting is desired. There are no default coordinates.
(This function is obsolete. Use tl_set_wafer instead.)
SYNOPSIS tl_write_wafer(x, y);
RETURNS 0 Write complete, no previous coordinates
-1 Write complete, old coordinates erased
SEE ALSO “tl_set_wafer”
tl_write_wavefile
Write wavefile data.
SYNOPSIS int tl_write_wavefile(fn, array, samples, rate,
gain, offset, flag)
char *fn; /* filename */
float *array; /* wave float array */
int *samples;
float *rate;
float *gain;
float *offset;
int *flag; /* 0 = fract2, 1 = real */
DESCRIPTION This function writes fract2 and real wavefile data. Any value <
0 returned by this function is an error. The user code calling this
function should check the return value for every call. You must
include the file, libapps.a, in the .load file for the test program.
ARGUMENTS fn—name of file to be read. The name must include a .wav
extension. If you do not add one, one is added automatically
array—floating point array to receive waveform data
samples—Number of samples actually read
rate—sample frequency
gain—gain for fract2 data or the maximum data point for real
data
offset—offset for fract2 data or the minimum data point for
real data
flag—0=fract2 data, 1=real data.
RETURN VALUE None
tl_write_wavefile_struct
Write wavefile using struct header.
SYNOPSIS int tl_write_wavefile_struct(fn, array, head, data,
databytes, param_id)
IMAGE Solutions V8.3 26-537
IMAGE Base Language: Base IMAGE Functions: Obsolete Functions
Table of Contents Index Home Master Index Search Help
char *fn;
float *array;
struct wavefilehead *head;
char *data;
int databytes,param_id;
DESCRIPTION This function writes a wave file. Storing of parameter data is
supported by passing in an array (of any type) and a param_id
number to identify that data. The data is preceded in the file with
an appropriate header containing the param_id number and
number of bytes total. Any entry of head ≥ parambytes passed
in is ignored. You must include the file libapps.a in the .load
file for the test program.
ARGUMENTS fn—name of the file to be written
array—float array containing the waveform data
head—filled struct wavefilehead (see
IMAGEBIN/itlh/wave.h)
data—parameter data array to be included with the file
databytes—number of bytes in data array
param_id—unique ID to identify parameter data format
RETURN VALUE 0 success
Nonzero value is an error
IMAGE Solutions V8.3 26-538
IMAGE Base Language: Base IMAGE Functions: Initializing Memory-Dependent Data
Table of Contents Index Home Master Index Search Help
Initializing Memory-Dependent Data
tl_powerup is an IMAGE variable that is TRUE under the following conditions:
• Before a test program has been run the first time.
• After test system power has been removed.
This is important. The test system has many memory-based instruments. When power is
removed from these instruments, the contents of all “instrument” memories is lost. This
means that all high-speed digital vectors and AC waveform segments are also lost.
Initialization and setup of memory-dependent data should use a format similar to the
following:
if(tl_powerup)
{
setup_ac_sources();
}
If you use the tl_init function, this might be implemented:
if(tl_powerup) tl_init();
IMAGE Solutions V8.3 26-539
IMAGE Base Language: Base IMAGE Functions: IMAGE Conversion Functions
Table of Contents Index Home Master Index Search Help
IMAGE Conversion Functions
You can use the following functions in a test program as function calls. Note that the prefix
convert_ is reserved by IMAGE. Avoid creating your own functions with this prefix.
convert_double_to_frac
convert_double_to_frac(d_source, i_dest, size);
Parameter definitions:
double *d_source
unsigned *i_dest
int size
This function takes a pointer to an array of double precision floating point numbers and
converts each element to a fractional twos complement number. The result is placed in the
unsigned array pointed to by i_dest. You must specify the number of points to convert. Be
sure that the i_dest array is large enough to hold the results.
convert_frac_to_double
convert_frac_to_double(i_source, d_dest, size);
Parameter definitions:
unsigned *i_source
double *d_dest
int size
This function takes a pointer to an array of unsigned integers that represent fractional twos
complement numbers and converts each element to a double precision floating point
number. The result is placed in the double array pointed to by d_dest. You must specify the
number of points to convert. Be sure that the d_dest array is large enough to hold the
results.
convert_frac_to_float
convert_frac_to_float(i_source, f_dest, size);
Parameter definitions:
unsigned *i_source
float *f_dest
int size
This function takes a pointer to an array of unsigned integers that represent fractional twos
complement numbers and converts each element to a floating point number. The result is
placed in the float array pointed to by f_dest. You must specify the number of points to
convert. Be sure that the f_dest array is large enough to hold the results.
IMAGE Solutions V8.3 26-540
IMAGE Base Language: Base IMAGE Functions: IMAGE Conversion Functions
Table of Contents Index Home Master Index Search Help
convert_float_to_frac
convert_float_to_frac(f_source, i_dest, size);
Parameter definitions:
float *f_source
unsigned *i_dest
int size
This function takes a pointer to an array of floats and converts each element to a fractional
twos complement number. The result is placed in the unsigned array pointed to by i_dest.
You must specify the number of points to convert. Be sure that the i_dest array is large
enough to hold the results.
convert_alaw_to_float
convert_alaw_to_float(i_source, f_dest, size);
Parameter definitions:
unsigned *i_source
float *f_dest
int size
This function takes a pointer to an array of unsigned integers whose rightmost eight bits
represent alaw data and converts them to floating point numbers. The result is placed in the
float array pointed to by f_dest. You must specify the number of points to convert. Be sure
that the f_dest array is large enough to hold the results.
NOTE
This function expects the input alaw data to have its even bits inverted.
convert_ulaw_to_float
convert_ulaw_to_float(i_source, f_dest, size);
Parameter definitions:
unsigned *i_source
float *f_dest
int size
This function takes a pointer to an array of unsigned integers whose rightmost bits represent
ulaw data and converts them to floating point numbers. The result is placed in the float array
pointed to by f_dest. You must specify the number of points to convert. Be sure that the
f_dest array is large enough to hold the results.
NOTE
This function expects the input ulaw data to be inverted.
IMAGE Solutions V8.3 26-541
IMAGE Base Language: Base IMAGE Functions: IMAGE Conversion Functions
Table of Contents Index Home Master Index Search Help
convert_analog_to_alaw
convert_analog_to_alaw(f_source, i_dest, size);
Parameter definitions:
float *f_source
unsigned *i_dest
int size
This function takes a pointer to an array of ±1.0 normalized floating point numbers and
converts them to right-justified alaw codes. The result is placed in the unsigned integer array
pointed to by i_dest. You must specify the number of points to convert. Be sure that the
i_dest array is large enough to hold the results.
NOTE
This function produces alaw codes that are even bit inverted.
convert_analog_to_ulaw
convert_analog_to_ulaw(f_source, i_dest, size);
Parameter definitions:
float *f_source
unsigned *i_dest
int size
This function takes a pointer to an array of ±1.0 normalized floating point numbers and
converts them to right-justified ulaw codes. The result is placed in the unsigned integer array
pointed to by i_dest. You must specify the number of points to convert. Be sure that the
i_dest array is large enough to hold the results.
NOTE
This function produces inverted ulaw codes.
IMAGE Solutions V8.3 26-542
IMAGE Base Language: FlexDSP Programmer’s Reference
Table of Contents Index Home Master Index Search Help
27 FLEXDSP PROGRAMMER ’S REFERENCE
This FlexDSP Programmer’s Reference describes all functions available to perform
operations on samples and other data contained in FlexDSP data arrays.
Data array functions, denoted by the prefix da_, can be used only on Tiger, on Catalyst in
native mode, or on A5 test systems equipped to use the FlexDSP feature set.
For information on using FlexDSP, including concepts, programming procedures, and other
reference information, see “Digital Signal Processing” on page 18-1.
Functions are listed in two ways:
• “FlexDSP Function Summary”
Functions are listed by topic. This section allows you to look up what you want to use
the function for and find the name of the function that does it.
• “FlexDSP Function Reference”
Functions are listed alphabetically. This section allows you to look up the description of
a function whose name you know.
IMAGE Solutions V8.3 27-1
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
FlexDSP Function Summary
This section lists data array functions by topic. If you know what you want a function to do,
but do not know which function to use, look it up in the summary tables below. If you know
the name of a function and want complete information about it, look it up in “FlexDSP
Function Reference” on page 27-14.
All uses of functions are grouped under one or more of the following topics:
• Access to and Creation of Data Arrays
• Conversion, Data And Type
• Device Measurements (Sinusoidal Analysis)
• Exponent and Log
• FFTs and Spectra
• Logical Operators
• Manipulate Data: Initialize, Modify, Compare to Limit
• Matrix Operations
• Maximum and Minimum
• Mean and RMS
• Miscellaneous
• Scalar Math
• Square and Square Root
• Sum
• Trigonometric Functions
• Vector Math
• Windows, Data
• Data Fitting
• Sampling Simulation
• A/D, D/A Testing
IMAGE Solutions V8.3 27-2
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Access to and Creation of Data Arrays
Table 27-1. Access to and Creation of Data Arrays
To Use
Define (create) a new data array da_define
Get the data domain of a DARRAY da_get_domain
Get the sample frequency of the sample data da_get_Fs
Get the test (fundamental) frequency of the sample data da_get_Ft
Locate the queue a darray is on da_get_lifetime
Return the number of samples da_get_number_samples
Get the size (length) of the data vector da_get_size
Get the data type of the data vector da_get_type
Get the location of the data vector da_get_vector
Print the contents of a data array da_print_darray
Release the memory associated with a DARRAY da_free
Set the sample frequency of the sample data da_set_Fs
Set the test (fundamental) frequency of the sample data da_set_Ft
Set the lifetime of a data array da_set_lifetime
Set the number of samples in a data array da_set_number_samples
Conversion, Data And Type
Table 27-2. Conversion, Data, and Type
To Use
Convert (truncate) vector elements from real numbers to integers da_aint
Combine two vectors, one with real parts and the other with imaginary da_cvcomb
parts, into one complex vector
Convert complex vector elements to complex conjugate values da_cvconj
Convert vector elements to the reciprocal values da_cvrcip
Convert a fraction to value in dB (10log, power) da_dB
Convert vector elements to values in decibels da_dbcon
IMAGE Solutions V8.3 27-3
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Table 27-2. Conversion, Data, and Type (Continued)
To Use
Convert vector elements from double precision floating point to single da_dpsp
precision floating point
Convert vector elements from double precision floating point to fract2 da_double_to_frac
Convert vector elements from double precision floating point to integer da_fix32d
Convert vector elements from single precision floating point to integer da_flt32d
Convert vector elements from fract2 to double precision floating point da_frac_to_double
Convert vector elements from fract2 to single precision floating point da_frac_to_real
Convert vector elements from offset binary to single precision floating da_offset_binary_to_real
point
Convert vector elements from rectangular coordinate form to polar da_polar
coordinate form
Convert vector elements from single precision floating point to fract2 da_real_to_frac
Convert vector elements from polar coordinate form to rectangular da_rect
coordinate form
Convert vector elements from single precision floating point to double da_spdp
precision floating point
Convert vector elements from single or double precision floating point da_vfix
to integer
Convert vector elements from integer to single precision floating point da_vfloat
Convert vector elements from integer to double precision floating point da_vfloatd
Convert (truncate) vector elements from single precision floating point da_vifix
numbers to integers
Extract the imaginary part from each vector element da_vimag
Extract the real part from each vector element da_vreal
Device Measurements (Sinusoidal Analysis)
Table 27-3. Device Measurements (Sinusoidal Analysis)
To Use
Calculate third order intermodulation distortion of a two-tone sine da_3rd_order_imd
wave
IMAGE Solutions V8.3 27-4
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Table 27-3. Device Measurements (Sinusoidal Analysis) (Continued)
To Use
Calculate third order intermodulation distortion of a two-tone sine da_3rd_order_imd_full
wave with control parameters
Calculate effective number of bits of a sampled signal da_enob_best_fit
Calculate effective number of bits using the signal-to-noise ratio da_enob_snr
Calculate effective number of bits using the signal-to-noise ratio da_enob_snr_full
with control parameters
Calculate harmonic distortion of an input sine wave da_hd
Calculate harmonic distortion of an input sine wave with control da_hd_full
parameters
Calculate intermodulation distortion of a two-tone sine wave da_imd
Calculate intermodulation distortion of a two-tone sine wave with da_imd_full
control parameters
Calculate the difference between maximum and minimum da_peak_to_peak
elements of a vector
Calculate the difference in phase and amplitude in two sine da_phase_gain_change
waves
Calculate the difference in phase and amplitude in two sine wave da_phase_gain_change_full
with control parameters
Calculate noise present in a sinusoid at a given frequency da_phase_noise
Calculate noise present in a sinusoid at a given frequency with da_phase_noise_full
control parameters
Calculate RMS value of the elements of a vector da_rms
Calculate spurious-free dynamic range of a sampled signal da_sfdr
Calculate spurious-free dynamic range of a sampled signal with da_sfdr_full
control parameters
Calculate signal-to-noise ratio of a frequency domain spectrum da_snr
Calculate signal-to-noise ratio of a frequency domain spectrum da_snr_full
with control parameters
Calculate total harmonic distortion of power or voltage frequency da_thd
domain spectrum
Calculate total harmonic distortion of power or voltage frequency da_thd_full
domain spectrum
IMAGE Solutions V8.3 27-5
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Exponent and Log
Table 27-4. Exponent and Log
To Use
Convert a fraction to value in dB (10log, power) da_dB
Calculate complex coordinates on the unit circle from a vector of phase da_cvexp
angles
Calculate natural antilog of vector elements by raising e (base of da_vexp
natural logarithms) to the power of input vector elements
Calculate base 10 antilog of vector elements by raising 10 to the power da_vexp10
of input vector elements
Calculate natural logarithm of vector elements da_vlog
Calculate base 10 logarithm of vector elements da_vlog10
FFTs and Spectra
Table 27-5. FFT and Spectra
To Use
Compute amplitude at a specified frequency da_amplitude
Compute amplitude at a specified frequency and specified sample rate da_amplitude_full
Compute complex FFT, in-place da_cfft
Compute complex FFT, not-in-place da_cfftb
Compute complex inverse FFT, in-place da_cifft
Compute complex inverse FFT, not-in-place da_cifftb
Calculate complex spectrum of time domain samples using the FFT da_complex_spectrum
Calculate square of the magnitude of complex vector elements da_cvmags
Calculate FFT, in-place da_fft
Calculate FFT, not-in-place da_fftb
Calculate inverse FFT, in-place da_ifft
Calculate inverse FFT, not-in-place da_ifftb
Compute phase at the specified frequency da_phase
IMAGE Solutions V8.3 27-6
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Table 27-5. FFT and Spectra (Continued)
To Use
Compute amplitude at a specified frequency and sample rate da_phase_full
Calculate power spectrum of a frequency domain spectrum da_power_spectrum
Scale and format frequency domain spectrum, in-place da_rfftsc
Logical Operators
Table 27-6. Logical Operators
To Use
Compare vector elements for logical equality da_lveq
Compare vector elements for logical greater than or equal to da_lvge
Compare vector elements with logical greater than da_lvgt
Compare vector elements with logical inequality da_lvne
Compare vector elements with logical equal to zero da_lvnot
Compare vector elements with logical AND da_vandi
Compare vector elements with logical equality da_veqvi
Compare vector elements with logical OR da_vori
Manipulate Data: Initialize, Modify, Compare to Limit
Table 27-7. Manipulate Data: Initialize, Modify, Compare to Limit
To Use
Decimate (subsample, stride) vector elements da_decimate
Expand vector and fill with zeros, except for elements of input vector da_expand
Reorder vector elements by elements of another vector. da_lookup
Copy vector and replace each nth element with corresponding element da_merge
of another vector
Clip (limit) vector element values to be within a specified range da_vclip
Set value of each vector element to zero da_vclr
IMAGE Solutions V8.3 27-7
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Table 27-7. Manipulate Data: Initialize, Modify, Compare to Limit (Continued)
To Use
Copy vector elements and optionally decimate (subsample, stride), da_vcopy
beginning at a specified index (offset)
Set value of each vector element to a specified constant value da_vfill
Compare each vector element to a value and replace with a specified da_vlim
value
Set vector element values to points on a ramp (sloped, straight line) da_vramp
with specified intercept and slope
Reverse order of vector elements da_vrvrs
Matrix Operations
Table 27-8. Matrix Operations
To Use
Calculate matrix multiply on a matrix represented by two vectors da_rmmul
Calculate matrix transpose of submatrix of a matrix represented by two da_rmtran
vectors
Maximum and Minimum
Table 27-9. Maximum and Minimum
To Use
Find value of vector element with the maximum magnitude (absolute da_maxmgv
value)
Find value and index of the vector element with the maximum value da_maxv
Find value of vector element with the minimum magnitude (absolute da_minmgv
value)
Find value and index of the vector element with the minimum value da_minv
Calculate vector elements that are the maximum valued element at da_vmax
each index in two input vectors
Calculate vector elements that are the maximum magnitude (absolute da_vmaxmg
value) of the elements at each index in two input vectors
IMAGE Solutions V8.3 27-8
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Table 27-9. Maximum and Minimum (Continued)
To Use
Calculate vector elements that are the minimum valued element at da_vmin
each index in two input vectors
Calculate vector elements that are the minimum magnitude (absolute da_vminmg
value) of the elements at each index in two input vectors
Mean and RMS
Table 27-10. Mean and RMS
To Use
Calculate mean of the absolute values of vector elements da_meamgv
Calculate mean of the values of vector elements da_meanv
Calculate mean of the squares of the values of vector elements da_measqv
Calculate RMS value of the elements of a vector da_rms
Calculate RMS of the values of vector elements da_rmsqv
Miscellaneous
Table 27-11. Miscellaneous
To Use
Convolve two vectors (convolution function) da_conv
Correlate two vectors (correlation function) da_corr
Generate histogram of vector elements da_hist
Evaluate an nth order polynomial at specified points da_vpoly
Scalar Math
Table 27-12. Scalar Math
To Use
Add a specified scalar to each vector element da_vsadd
Divide each vector element by a specified scalar da_vsdiv
IMAGE Solutions V8.3 27-9
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Table 27-12. Scalar Math (Continued)
To Use
Multiply each vector element by a specified scalar da_vsmul
Multiply each vector element by a specified scalar and then (vector) da_vsma
add to another vector
Multiply each vector element by a specified scalar and add a second da_vsmsa
specified scalar to the product
Multiply each vector element by a specified scalar and then (vector) da_vsmsb
subtract from another vector
Square and Square Root
Table 27-13. Square and Square Root
To Use
Calculate square of the magnitude of complex vector elements da_cvmags
Calculate square of vector elements da_vsq
Calculate square root of vector elements da_vsqrt
Calculate signed square (product of element and its absolute value) of da_vssq
vector elements
Sum
Table 27-14. Sum
To Use
Compute sum of vector elements da_sve
Compute sum of the magnitudes (absolute value) of vector elements da_svemg
Compute sum of the squares of vector elements da_svesq
Compute sum of the signed squares (product of element and its da_svessq
absolute value) of vector elements
Compute sum of all vector elements up to and including a specified da_vsum
index
IMAGE Solutions V8.3 27-10
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Trigonometric Functions
Table 27-15. Trigonometric Functions
To Use
Calculate arctangent of vector elements da_vatan
Calculate arctangent of the ratio of corresponding elements of two da_vatan2
vectors
Calculate cosine of vector elements da_vcos
Calculate sine of vector elements da_vsin
Vector Math
Table 27-16. Vector Math
To Use
Compute dot (inner) product of complex vectors da_cdotpr
Compute dot (inner) product of two real vectors da_dotpr
Compute absolute value of vector elements da_vabs
Add two vectors (vector add) da_vadd
Add two vectors (vector add) and multiply by third vector (vector da_vam
multiply)
Divide vector by another vector (vector divide) da_vdiv
Multiply two vectors (vector multiply) and add to third vector (vector da_vma
add)
Multiply two vectors (vector multiply) and add specified scalar “da_vmsa”
Multiply two vectors (vector multiply) and subtract third vector (vector da_vmsb
subtract)
Multiply two vectors (vector multiply) da_vmul
Negate (multiply by -1) vector elements da_vneg
Subtract two vectors (vector subtract) and multiply by third vector da_vsbm
(vector multiply)
Subtract two vectors (vector subtract) da_vsub
IMAGE Solutions V8.3 27-11
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Windows, Data
Table 27-17. Windows, Data
To Use
Window sample data using Blackman window function da_blkman
Window sample data using Hamming window function da_hamm
Window sample data using Hanning window function da_hann
Calculate spectra and measurements without windowing (null window) da_null_window
Data Fitting
Table 27-18. Date Fitting
To Use
Generate new DARRAY that fits a given slope and offset da_best_fit_ramp
Calculate amplitude, phase, and offset of a sine wave to fit da_best_fit_sine
the input
Calculate amplitude, phase, and offset of a sine wave to fit da_best_fit_sine_full
the input with control parameters
Calculate least-squares fit slope and offset to a sampled da_best_fit_slope_and_offset
period of a ramp waveform
Calculate least-squares fit slope and offset to a sampled da_best_fit_slope_and_offset_full
period of a ramp waveform with control parameters
Sampling Simulation
Table 27-19. Sampling Simulation
To Use
Generate new DARRAY that fits a given slope and offset da_best_fit_ramp
Simulate sampling of a continuous-time waveform da_cosine
Simulate sampling of a multitone cosine waveform da_multitone
Simulate sampling of a continuous periodic pulse waveform da_pulse
Simulate sampling of a continuous periodic ramp waveform da_ramp
IMAGE Solutions V8.3 27-12
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Summary
Table of Contents Index Home Master Index Search Help
Table 27-19. Sampling Simulation (Continued)
To Use
Simulate sampling of a periodic triangle waveform da_triangle
A/D, D/A Testing
Table 27-20. A/D, D/A Testing
To Use
Calculate differential nonlinearity of a ramp waveform da_ramp_dnl
Calculate differential and integral nonlinearity of a ramp waveform da_ramp_dnl_and_inl
Calculate integral nonlinearity of a ramp waveform da_ramp_inl
Calculate differential nonlinearity of a sine waveform da_sine_dnl
Calculate differential and integral nonlinearity of a sine waveform da_sine_dnl_and_inl
Calculate integral nonlinearity of a sine waveform da_sine_inl
IMAGE Solutions V8.3 27-13
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
FlexDSP Function Reference
This section lists functions alphabetically. If you know the name of a function that does what
you want to do, look here for a complete description. If you know what you want to do but
do not know the name of the function, see “FlexDSP Function Summary” on page 27-2.
da_3rd_order_imd
Calculate the third order intermodulation distortion of a two-tone sine wave.
This function performs a third order intermodulation calculation. The input waveform is the
sum of two sine waves of equal power and different frequencies. Input parameters include
the two frequencies of the sine waves. The sampling frequency of the waveform is taken
from the input DARRAY.
The result of this algorithm is a ratio of the power in the signal to the power in the third order
intermodulation harmonics. The signal power is the magnitude of the FFT of the input at
either frequency, Ft1 or Ft2 (since they are equal). The harmonic power is the sum of the
magnitude at four specific frequencies. These frequencies are:
2(Ft1) +/- Ft2
Ft1 +/- 2(Ft2)
Note that the power of negative frequencies equals the corresponding power at the positive
frequency for all real signals. The algorithm finds those four powers, sums them, and divides
the signal power by the result to calculate the final result.
Synopsis
double da_3rd_order_imd(DARRAY input, double Ft1, double Ft2)
Arguments
input Input variable containing the input two-tone sine wave. The
signal power of the two tones must be approximately equal.
The input data array must have a length which is a power of 2
and contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
Ft1 Frequency of the first tone. Value must be between 0 and Fs/2.
Ft2 Frequency of the second tone. Value must be between 0 and
Fs/2.
A run-time error results from choosing frequencies such that the
harmonic frequencies are undersampled. The sampling
frequency must be greater than both 2*Ft1 + Ft2 and Ft1 + 2*Ft2.
Returns
The ratio of the signal power to the harmonic power, or TL_DA_ERROR.
IMAGE Solutions V8.3 27-14
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
See Also
“da_3rd_order_imd_full”
da_3rd_order_imd_full
Calculate the third order intermodulation distortion of a two-tone sine wave, with additional
parameter sample frequency.
This function performs a third order intermodulation calculation. The input waveform is the
sum of two sine waves of equal power and different frequencies. Input parameters include
the two frequencies of the sine waves and the sample frequency of the waveform.
The result of this algorithm is a ratio of the power in the signal to the power in the third order
intermodulation harmonics. The signal power is the magnitude of the FFT of the input at
either frequency, Ft1 or Ft2 (since they are equal). The harmonic power is the sum of the
magnitude at four specific frequencies. These frequencies are:
2(Ft1) +/- Ft2
Ft1 +/- 2(Ft2)
Note that the power of negative frequencies equals the corresponding power at the positive
frequency for all real signals. The algorithm finds those four powers, sums them, and divides
the signal power by the result to calculate the final result.
Synopsis
double da_3rd_order_imd_full(DARRAY input, double Ft1, double Ft2,
double Fs)
Arguments
input Input variable containing the input two-tone sine wave. The
signal power of the two tones must be approximately equal.
The input data array must have a length which is a power of 2
and contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
Ft1 Frequency of the first tone. Value must be between 0 and Fs/2.
Ft2 Frequency of the second tone. Value must be between 0 and
Fs/2.
Fs Sample frequency. Value must be greater than both 2*Ft1 + Ft2
and Ft1 + 2*Ft2.
Returns
The ratio of the signal power to the harmonic power, or TL_DA_ERROR.
See Also
“da_3rd_order_imd”
IMAGE Solutions V8.3 27-15
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_aint
Vector real to whole number.
da_aint converts a vector of real numbers to a vector of whole numbers. This function
applies the integer truncation function to each element of the input data array
out [ n ] = truncate ( in [ n ] ) (27–1)
where
truncate(t) = n, if n ≤ t < n+1, and n is an integer.
Synopsis
DARRAY da_aint(DARRAY h_in)
Arguments
h_in The input DARRAY can have any length > 0. Data must be a
floating point type, DA_REAL or DA_DREAL.
Returns
A DARRAY handle to the data array containing the output data.
In normal operation, the output DARRAY is the same length as the input DARRAY. The output
DARRAY type is the same as the input type.
Zero is returned in the case of a run-time error which is ignored or continued.
da_amplitude
Compute the amplitude at a given frequency.
The amplitude is the value of the Fourier component at the input frequency. The input
should be a spectrum. The sample rate must be in the input data array.
The amplitude can be the magnitude in a complex spectrum or the magnitude squared in a
power spectrum, depending on the data array contents.
See “Notes on Using Block Algorithms When Calculating FFTs and Spectra”.
Synopsis
double da_amplitude(DARRAY input, double f_i)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input spectrum data.
f_i The frequency of interest.
IMAGE Solutions V8.3 27-16
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
The amplitude at the given frequency. da_amplitude_full includes only those frequencies
that occur before Fs/2. However, if the sample is not band-limited to Fs/2, images of noise
and harmonics may interfere with the correct calculation of the amplitude.
See Also
“da_amplitude_full”, “da_phase”, “da_phase_full”
da_amplitude_full
Calculate amplitude at a given frequency, with additional parameter sample rate.
The amplitude is the value of the Fourier component at the input frequency. The input
should be a spectrum. The sample rate is specified using parameter f_s.
The amplitude can be the magnitude in a complex spectrum or the magnitude squared in a
power spectrum, depending on the data array contents. The elements of the array can have
any of the legal types.
Synopsis
double da_amplitude_full(DARRAY input,
double f_i,
double f_s)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input spectrum data.
f_i The frequency of interest.
f_s The sample frequency.
Returns
The amplitude at the given frequency. da_amplitude_full includes only those frequencies
that occur before Fs/2. However, if the sample is not band-limited to Fs/2, images of noise
and harmonics may interfere with the correct calculation of the amplitude.
See Also
“da_amplitude”, “da_phase”, “da_phase_full”
da_best_fit_ramp
Return a new DARRAY that fits a given slope and offset.
This function generates a DARRAY containing a ramp waveform that corresponds to the
specified slope (in volts/second) and offset (in volts). A new DARRAY is allocated, its size
specified by num_samples. The type of the new DARRAY is DA_REAL. The sample frequency
IMAGE Solutions V8.3 27-17
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
is set to Fs and the ramp waveform is filled in according to the slope and offset. The resulting
handle is returned.
Synopsis
DARRAY da_best_fit_ramp(da_size_t num_samples, double Fs, double slope,
double offset)
Arguments
num_samples The number of elements in the new DARRAY. Must be 8 or larger.
Fs Sample frequency of the new DARRAY. Value must be 8 or larger.
slope Slope of the waveform in volts/s.
offset Offset of the waveform in volts.
Returns
DARRAY with the new waveform.
Side Effects
Allocates memory.
See Also
“da_best_fit_slope_and_offset”
da_best_fit_sine
Calculate the amplitude, phase, and offset of a sine wave to fit the input.
This function calculates a least-squares fit approximation to a sampled real sine wave. You
provide the sample data in an input DARRAY and pointers to where the function returns the
amplitude, phase, and offset values. The sample and waveform frequencies are taken from
the input DARRAY.
The least-squares fit algorithm for a known frequency sine wave is given in ANSI/IEEE 1057
(Standard for Digitizing Waveform Recorders), Section 4.1.3.1 “An algorithm for Three
Parameter (Known Frequency) Least Squared Fit to Sine Wave Data.” The algorithm
returns values for the amplitude (in volts), phase angle (in radians), and DC offset (in volts)
such that the theoretical waveform described by those values matches the real sample data.
The matching criteria is that the squares of the voltage differences between the real data
and the theoretical data is minimized when summed over all of the available samples. For
a full description of the algorithm used to calculate these values, see ANSI/IEEE 1057.
Synopsis
void da_best_fit_sine(DARRAY input, double *amplitude, double *phase,
double *offset)
IMAGE Solutions V8.3 27-18
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
input Input variable containing the input waveform.
The data array must have a length which is a power of 2 and
contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
*amplitude A pointer which represents where to write the amplitude data.
*phase A pointer which represents where to write the phase data.
*offset A pointer which represents where to write the offset data.
Side Effects
Writes values A, P, and C to amplitude, phase, and offset, such that A*sin(Wx+P)+C is the
least-squares fit to the input waveform of frequency W.
See Also
“da_best_fit_sine_full”
da_best_fit_sine_full
Calculate the amplitude, phase, and offset of a sine wave to fit the input, with additional
parameters, test frequency and sample frequency.
This function calculates a least-squares fit approximation to a sampled real sine wave. You
provide the sample data in an input DARRAY and pointers to where the function returns the
amplitude, phase, and offset values. The sample and waveform frequencies are specified
as parameters.
The least-squares fit algorithm for a known frequency sine wave is given in ANSI/IEEE 1057
(Standard for Digitizing Waveform Recorders), Section 4.1.3.1 “An algorithm for Three
Parameter (Known Frequency) Least Squared Fit to Sine Wave Data.” The algorithm
returns values for the amplitude (in volts), phase angle (in radians), and DC offset (in volts)
such that the theoretical waveform described by those values matches the real sample data.
The matching criteria is that the squares of the voltage differences between the real data
and the theoretical data is minimized, when summed over all of the available samples. For
a full description of the algorithm used to calculate these values, see ANSI/IEEE 1057.
Synopsis
void da_best_fit_sine_full(DARRAY input, double *amplitude, double *phase,
double *offset, double Fs, double Ft)
Arguments
input Input variable containing the input waveform.
IMAGE Solutions V8.3 27-19
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
The data array must have a length which is a power of 2 and
contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
*amplitude A pointer which represents where to write the amplitude data.
*phase A pointer which represents where to write the phase data.
*offset A pointer which represents where to write the offset data.
Fs Sample frequency. Value must be greater than 0.
Ft Test frequency. Value must be between 0 and Fs/2.
Side Effects
Writes values A, P, and C to amplitude, phase, and offset, such that A*sin(Wx+P)+C is the
least-squares fit to the input waveform of frequency W.
See Also
“da_best_fit_sine”
da_best_fit_slope_and_offset
Calculate the least-squares fit slope and offset to a sampled period of a ramp waveform.
This function calculates a least-squares fit approximation on a real sampled ramp waveform
to find the best theoretical slope and DC offset for the equation describing that ramp. The
slope is in volts per second and the offset in volts. You provide the sample data in an input
DARRAY and pointers to where the function returns the slope and offset values. The sample
frequency is taken from the input DARRAY.
The least-squares fit algorithm finds the equation of a line that approximates the real
waveform. This line has the property that the squares of the voltage differences between
the actual data and the theoretical data summed over every data point, is minimized. In
other words, on one sample, subtract the real data from the theoretical data, and square the
result. Do that to every sample and add up the results. The slope and offset computed by
this function describe the line that minimizes that result.
Synopsis
void da_best_fit_slope_and_offset(DARRAY input, double *slope, double *offset)
Arguments
input Input variable containing the input waveform.
The data array must have a length which is a power of 2 and
contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
*slope A pointer which represents where to write the slope data. Value
must not be zero.
IMAGE Solutions V8.3 27-20
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
*offset A pointer which represents where to write the offset data. Value
must not be zero.
Side Effects
Writes values to the pointers, slope and offset.
See Also
“da_best_fit_slope_and_offset_full”
da_best_fit_slope_and_offset_full
Calculate the least-squares fit slope and offset to a sampled period of a ramp waveform with
additional parameter sample frequency.
This function calculates a least-squares fit approximation on a real sampled ramp waveform
to find the best theoretical slope and DC offset for the equation describing that ramp. The
slope is in volts per second and the offset in volts. You provide the sample data in an input
DARRAY and pointers to where the function returns the slope and offset values. Also, you
specify the sample frequency as a parameter.
The least-squares fit algorithm finds the equation of a line that approximates the real
waveform. This line has the property that the squares of the voltage differences between
the actual data and the theoretical data, summed over every data point, is minimized. In
other words, on one sample, subtract the real data from the theoretical data and square the
result. Do that to every sample and add up the results. The slope and offset computed by
this function describe the line that minimizes that result.
Synopsis
void da_best_fit_slope_and_offset_full(DARRAY input, double *slope,
double *offset, double Fs)
Arguments
input Input variable containing the input waveform.
The data array must have a length which is a power of 2 and
contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
*slope A pointer which represents where to write the slope data. Value
must not be zero.
*offset A pointer which represents where to write the offset data. Value
must not be zero.
Fs Sample frequency. Value must be greater than 0.
Side Effects
Writes values to the pointers, slope and offset.
IMAGE Solutions V8.3 27-21
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
See Also
“da_best_fit_slope_and_offset”
da_blkman
Blackman window.
da_blkman applies the Blackman window to a vector of input data.
This function applies the Blackman windowing function to each element of the input vector
π π
out [ n ] = in [ n ] × 0.42 – 0.5 × cos n × 2.0 × ---- + 0.08 × cos n × 4.0 × ---- (27–2)
N N
for each index n, where N is the length of the input vector.
The input vector is not modified.
Synopsis
DARRAY da_blkman(DARRAY h_in)
Arguments
h_in The input DARRAY must have input data size of a power of 2. Data
can be any noncomplex type.
Returns
A DARRAY handle to the data array containing the windowed data.
The output data is the smallest type compatible with the input type and DA_REAL. Data will
have type DA_DREAL if the input type is DA_DREAL and DA_REAL in all other cases. Output
vector length is the same as the input vector.
Zero is returned in the case of a run-time error which is ignored or continued.
da_cdotpr
Complex dot product.
da_cdotpr performs the complex dot product operation on two complex input vectors
output = in1 [ 0 ] × in2 [ 0 ] + ... + in1 [ N – 1 ] × in2 [ N – 1 ] (27–3)
for each index n, where N is the length of the input vector.
Note that this is not the inner product since the computation does not use the complex
conjugate of in2.
IMAGE Solutions V8.3 27-22
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
D_COMPLEX da_cdotpr(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data arrays can contain data of either single or double
precision complex type. h_in1 must have the same length as
h_in2.
h_in2 The input data arrays may contain data of either single or double
precision complex type. h_in2 must have the same length as
h_in1.
Returns
A double precision complex number.
Zero is returned in the case of a run-time error which is ignored or continued.
da_cfft
In-place complex FFT.
This function does not return any value. It changes the program state by replacing the input
DARRAY data with its discrete Fourier transform
N–1 2π
-j ------- nk
N
out [ n ] = ∑ in [ k ]e (27–4)
n=0
where N is the size of the input sequence, and j is the square root of -1. The function uses
a standard radix 8 FFT algorithm.
da_cfft computes the full spectrum for the complex waveform input. Both the positive and
negative frequencies are represented in the output spectrum. This algorithm is scaled so
that the transform of a pure real cosine wave, 1024 samples, peaking at -1 and 1, will appear
as two spikes of amplitude 512 at the appropriate frequencies.
Synopsis
da_cfft(DARRAY h_in)
Arguments
h_in The input DARRAY can have any complex input type. That is, the
input DARRAY can have type DA_CMPLX or DA_DCMPLX. Since the
input is complex, the full spectrum is represented. In normal
operation, after the function’s execution, the length of the input
DARRAY will be the same as the original length. The input
DARRAY’s type will be unaltered.
IMAGE Solutions V8.3 27-23
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
On errors, the data is not altered at all.
Side Effects
The input data is overwritten by the result.
da_cfftb
Not-in-place complex FFT.
Performs a not-in-place complex FFT on the input vector (output not the same as input).
Synopsis
DARRAY da_cfftb(DARRAY h_in)
Arguments
h_in Data array handle for input vector. Type must be complex.
Returns
Data array handle (float/double complex)
See Also
“da_cfft”
da_cifft
In-place complex inverse FFT.
This function does not return any value. It replaces the input data with the inverse discrete
Fourier transform
N–1 2π
j ------- nk
N
out [ n ] = ∑ in [ k ]e (27–5)
n=0
where N is the size of the input sequence, and j is the square root of -1.
The function uses a standard radix 8 FFT algorithm.
Note that, unlike the real FFT algorithm, the results are scaled. If the input is the zero vector
except for bin k, at which the input is
A
out [ k ] = ---- e jφ (27–6)
2
then the output will be k cycles of a real cosine function with zero imaginary component, with
amplitude 2 × A and initial phase φ.
IMAGE Solutions V8.3 27-24
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Since the input is complex, the full spectrum is represented in the input, and the full time
domain signal is computed. In normal operation, after the function’s execution, the input
DARRAY’s type and length will be unaltered.
On errors, the data is not altered.
Synopsis
da_cifft(DARRAY h_in)
Arguments
h_in The input data array must have data which is a complex input
type: DA_CMPLX or DA_DCMPLX.
Side Effects
The input DARRAY’s data is overwritten by the result.
da_cifftb
Not-in-place complex inverse FFT.
The result of this function is a DARRAY handle whose data is the discrete inverse Fourier
transform of the input data
N–1 2π
j ------- nk
N
out [ n ] = ∑ in [ k ]e (27–7)
n=0
where N is the size of the input DARRAY, and j is the square root of -1.
The function uses a standard radix 8 FFT algorithm.
Note that, unlike the real FFT algorithm, the results are scaled. If the input is k cycles of a
real cosine function with zero imaginary component, with amplitude A and initial phase φ,
then the output is the zero vector except for bin k:
A
out [ k ] = ---- e jφ (27–8)
2
Synopsis
DARRAY da_cifftb(DARRAY h_in)
Arguments
h_in The input data must be a complex type: DA_CMPLX or DA_DCMPLX.
IMAGE Solutions V8.3 27-25
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
In normal operation, the output is a DARRAY handle whose length and type are the same as
the length and type of the input DARRAY.
Zero is returned in the case of a run-time error which is ignored or continued.
da_complex_spectrum
Calculate a complex spectrum using time domain sample data.
This function returns a handle to a data array which contains the complex spectrum
calculated from the input sample data. The input vector must be in the time domain but can
be real or complex, single or double precision, or fixed point. The output vector is in the
frequency domain. The type of the output vector is given in table 27-21, where the requested
type is the value of the parameter type.
Based on the input type and requested type, da_complex_spectrum uses the appropriate
FFT algorithm to compute the complex spectrum.
Table 27-21. Output vector type vs. input type and requested type
Requested Input data type
type
DA_INT DA_FRACT2 DA_REAL DA_DREAL DA_CMPLX DA_DCMPLX
DA_INT ERROR ERROR ERROR ERROR ERROR ERROR
DA_FRACT2 ERROR ERROR ERROR ERROR ERROR ERROR
DA_REAL ERROR ERROR ERROR ERROR ERROR ERROR
DA_DREAL ERROR ERROR ERROR ERROR ERROR ERROR
DA_CMPLX DA_CMPLX DA_CMPLX DA_CMPLX ERROR DA_CMPLX ERROR
DA_DCMPLX DA_DCMPLX DA_DCMPLX DA_DCMPLX DA_DCMPLX DA_DCMPLX DA_DCMPLX
Summary:
• If the requested type is (double precision) DA_DCMPLX, the output data is DA_DCMPLX for
any input data type. The data is converted to DA_DCMPLX during the computation.
• If the requested type is (single precision) DA_CMPLX, the output vector is DA_CMPLX if the
input is DA_INT, DA_FRACT2, DA_REAL, DA_DREAL, DA_CMPLX, or DA_DCMPLX. If the input
data is (double precision) DA_DREAL or DA_DCMPLX and the requested type is (single
precision) DA_DREAL, it is an error.
• Any other combination of requested type and input type is an error.
Synopsis
DARRAY da_complex_spectrum (DARRAY input, da_numeric_data_type type,
da_window_function window_function)
IMAGE Solutions V8.3 27-26
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input sample data.
type Requested output vector type. See table 27-21 for valid
combinations with input data types.
window_function Windowing function applied to sample data. If no windowing is
needed, use da_null_window.
Returns
A handle to a data array which contains the complex spectrum.
See Also
“da_phase_full”
da_conv
Convolution.
This function computes the convolution of two vectors. If the length of the vectors are |h_in1|
and |h_in2|, then the convolution is defined to be
h_in2 – 1
conv [ k ] = ∑ h_in1 [ k + n ] × h_in2 [ h_in2 – n + 1 ] (27–9)
n=0
for k = 0..|h_in1|-|h_in2|.
Note that the indices to h_in2 are processed in inverse numeric order, and the indices to
h_in1 are processed in forward numeric order. This means that there are |h_in1|-|h_in2|+1
output elements.
Synopsis
DARRAY da_conv(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 DARRAY handle for first input data array. Must contain data of a
noncomplex type. The length of h_in1 must be greater than or
equal to the length of h_in2 so that the output length is positive.
h_in2 DARRAY handle for second input data array. Must contain data of
a noncomplex type. The length of h_in2 must less than or equal
to than the length of h_in1 so that the output length is positive.
IMAGE Solutions V8.3 27-27
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
In normal operation, the return value is a DARRAY handle for a data array containing data
that is of the smallest type compatible with the types of the two input DARRAYs and also with
DA_REAL. The length of the output vector is as given above.
Zero is returned in the case of a run-time error which is ignored or continued.
da_corr
Correlation.
Computes the correlation of two vectors. If the length of the vectors are |h_in1| and |h_in2|,
the correlation is defined to be
h_in2 – 1
corr [ k ] = ∑ h_in1 [ k + n ] × h_in2 [ n ] (27–10)
n=0
for k = 0..|h_in1|-|h_in2|.
Note that the indices for both h_in1 and h_in2 are processed in numeric order. This means
that there are |h_in1|-|h_in2|+1 output elements.
Synopsis
DARRAY da_corr(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input DARRAY handles must have a noncomplex type. The
length of h_in1 must be greater than or equal to the length of
h_in2 so that length of the output is positive.
h_in2 The input DARRAY handles must have a noncomplex type. The
length of h_in2 must be less than or equal to the length of h_in1
so that length of the output is positive.
Returns
In normal operation, the output is a DARRAY handle for a data array whose length is given as
above. The data type is the smallest type compatible with the types of the two input data
arrays and also with DA_REAL. That is, the output type is DA_DREAL if the one of the input
types is DA_DREAL and is DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_cosine
Simulate the sampling of a continuous-time cosine waveform.
IMAGE Solutions V8.3 27-28
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
This function simulates the sampling of a continuous-time cosine waveform. You specify the
parameters of the sampling, including the sample frequency and the number of samples,
and the parameters of the continuous-time waveform, including frequency, amplitude, DC
offset, and phase angle in radians.
This function allocates a new DARRAY with a vector of data large enough to accommodate
the number of samples and the vector for the current site filled in with data representing
the specified sampling. The sample and waveform frequencies of the DARRAY’s current data
are filled in. The handle of the new DARRAY is returned.
Synopsis
DARRAY da_cosine(double Fs, da_size_t num_samples, double Ft,
double amplitude, double offset, double phase)
Arguments
Fs Sample frequency of the output waveform.
num_samples The number of samples in the output waveform.
Ft Frequency of the cosine.
amplitude Amplitude of the cosine.
offset Offset of the cosine.
phase Phase angle (in radians) of the cosine.
Returns
DARRAY with a cosine waveform. In the case of a run-time error, DA_NULL is returned without
allocating a new DARRAY.
Side Effects
Allocates a new DARRAY.
See Also
“da_multitone”
da_cvcomb
Complex vector combine.
This function returns a DARRAY handle whose data are the complex numbers whose real
parts are given by the first input DARRAY’s data, and whose imaginary parts are given by the
second input DARRAY’s data
out [ n ].real = in1 [ n ]
(27–11)
out [ n ].imag = in2 [ n ]
IMAGE Solutions V8.3 27-29
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_cvcomb(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The first input data array must have a length greater than zero,
equal to length of h_in2. Data can be any noncomplex type.
h_in2 The second input data array must have a length greater than
zero, equal to length of h_in1. Data can be any noncomplex
type.
Returns
The return value has the same length as the input data arrays. Data has the smallest type
compatible with the input data array types and also with DA_CMPLX.
da_cvconj
Complex conjugate.
The result of this function is a DARRAY handle whose data is the result of applying the
complex conjugate function element-wise to the input vector
out [ n ] = complex_conjugate ( in [ n ] ) (27–12)
where complex_conjugate(a+bj) denotes a-bj, which is the complex conjugate of the
parameter a+bj.
Synopsis
DARRAY da_cvconj(DARRAY h_in)
Arguments
h_in The input data array must have a complex type. Length must be
greater than zero.
Returns
In normal operation, the return value is a DARRAY handle for a data array whose type and
length are the same as those of the input.
Zero is returned in the case of a run-time error which is ignored or continued.
da_cvexp
Complex vector natural exponent.
IMAGE Solutions V8.3 27-30
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
The input to this function is a DARRAY handle whose data are a vector of angles, measured
in radians. The output is a complex DARRAY whose data are the complex numbers on the
unit circle which have the given phase angles
out [ k ] = e j × in [ k ] = cos ( in [ k ] ) + j × sin ( in [ k ] ) (27–13)
Synopsis
DARRAY da_cvexp(DARRAY h_in)
Arguments
h_in The input data array must have a noncomplex type. Length must
be greater than zero.
Returns
In normal operation, the output data array will have a complex type. It will be double
precision complex if the input is DA_DREAL and single precision complex in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_cvmags
Complex vector magnitude squared.
This function returns a DARRAY whose data is the element-wise application of the absolute
value or magnitude squared function to the input DARRAY’s data
0 ≤ out [ n ]
(27–14)
out [ n ] = ( in [ n ].real ) 2 + ( in [ n ].imag ) 2
for each index, n.
This function is similar to da_vabs, but it operates on complex data as well as noncomplex
data. Noncomplex data is converted to complex data by setting the imaginary part to 0.0.
Synopsis
DARRAY da_cvmags(DARRAY h_in)
Arguments
h_in The input data array must have a length greater than zero. Data
can be any type.
Returns
In normal operation, the output DARRAY will have the same length as the input. It will have
type DA_DREAL if the input type is DA_DREAL or DA_DCMPLX. It will have type DA_REAL in all
other cases.
IMAGE Solutions V8.3 27-31
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Zero is returned in the case of a run-time error which is ignored or continued.
da_cvrcip
Complex vector reciprocal.
Calculates elementwise reciprocal of a complex vector.
Synopsis
DARRAY da_cvrcip(DARRAY h_in)
Arguments
h_in Data array handle for input vector. Data can be any type.
Returns
Data array handle (complex or double complex)
da_dB
Convert a fraction to decibels.
Given a fraction, compute the fraction’s value in dB using 10*log(fraction).
Synopsis
double da_dB(double fraction)
Arguments
fraction Fraction (ratio) to be converted to dB.
Returns
Value in dB.
da_dbcon
Vector convert to decibels.
The result of this function is a DARRAY handle whose data is the element-wise application of
the decibel function to the input DARRAY’s data
out [ n ] = conv × log ( in [ n ] ⁄ ( scalar ) ) (27–15)
where:
conv is 20 if flag == 0, and 10 if flag == 1
IMAGE Solutions V8.3 27-32
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_dbcon(DARRAY h_in, double scalar, int flag)
Arguments
h_in The input data array can have any length. Data must be a
noncomplex type.
scalar A double precision floating point number.
flag An integer.
Returns
In normal operation, the return value’s data has the same length as the length of the DARRAY
input parameter h_in. The type of the return value’s data is the smallest type compatible
with the type of the DARRAY input’s data and also with DA_REAL. That is, the output type is
DA_DREAL if the input type is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_decimate
Decimate.
The result of this function is a DARRAY handle whose data is the nth element of the input
DARRAY’s data
out [ k ] = in [ k × n ] (27–16)
for every index k.
Synopsis
DARRAY da_decimate(DARRAY h_in, int n)
Arguments
h_in The data array can have any length. Data can be any type.
n The decimation factor is an integer.
Returns
The return value has length
n × ceil ( N ⁄ n ) (27–17)
where N is the length of the input vector, and ceil(t) is the smallest integer which is greater
than or equal to t.
IMAGE Solutions V8.3 27-33
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_define
Allocates a new data array.
Creates a new data array, with the specified type (such as DA_REAL or DA_CMPLX) and size.
If the handle argument is a valid DARRAY handle, that handle is re-used, and the old
DARRAY represented by that handle is re-allocated. In normal cases, however, it is
customary to pass DA_NULL as the first argument, in which case da_define will use the next
available handle.
Examples:
To define a new DARRAY:
DARRAY foo = DA_NULL;
foo = da_define(DA_NULL, DA_REAL, 64);
To redefine a pre-existing DARRAY:
da_define(foo, DA_REAL, 128);
Synopsis
DARRAY da_define(DARRAY handle, unsigned int type, unsigned int size)
Arguments
handle Data array handle. If this is DA_NULL (or any invalid handle),
da_define will allocate a new handle and DARRAY from scratch.
If it is a valid handle, the DARRAY and handle are re-allocated.
type A data type for the sample data in the data array. An unsigned
integer. Valid types are DA_REAL, DA_DREAL, DA_CMPLX,
DA_DCMPLX, DA_INT, DA_FRACT2.
size The number of elements allocated for the data array. An
unsigned integer.
Returns
Handle number which references the data array.
Side Effects
May allocate memory and a handle for the new DARRAY. May re-allocate the memory of
the handle argument.
da_dotpr
Dot product.
This function computes the inner, or dot, product of two real vectors
out = in1 [ 0 ] × in2 [ 0 ] + ... + in1 [ N – 1 ] × in2 [ N – 1 ] (27–18)
IMAGE Solutions V8.3 27-34
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
double da_dotpr(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data array must contain data of a non-complex type.
h_in1 must be the same length as h_in2.
h_in2 The input data array must contain data of a non-complex type.
h_in2 must be the same length as h_in1.
Returns
The output value is a double precision floating point number.
Zero is returned in the case of a run-time error which is ignored or continued.
da_double_to_frac
Vector double to frac2.
The result of this function is a DARRAY handle whose data is the element-wise application to
the input DARRAY’s data of the function which converts double precision floating point
numbers to DA_FRACT2 numbers.
If double_to_fract2(t) is the result of converting the double precision floating point
number t to DA_FRACT2, then
out [ n ] = double_to_fract2 ( in [ n ] ) (27–19)
for all indices n.
Synopsis
DARRAY da_double_to_frac(DARRAY h_in)
Arguments
h_in The input data array length must be greater than zero. Data must
have type DA_DREAL.
Returns
In normal operation, the output DARRAY will have the same length as the input DARRAY. It will
always have type DA_FRACT2.
Zero is returned in the case of a run-time error which is ignored or continued.
da_dpsp
Vector double to float.
IMAGE Solutions V8.3 27-35
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
The result of this function is a DARRAY handle whose data is the element-wise application to
the input data of the function which converts double precision floating point numbers to
single precision floating point numbers:
out [ n ] = ( float )in [ n ] (27–20)
for each index n.
Synopsis
DARRAY da_dpsp(DARRAY h_in)
Arguments
h_in The input data array length must be greater than zero. Data must
be type DA_DREAL.
Returns
In normal operation, the output DARRAY has the same length as the input DARRAY. Its type is
always DA_REAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_enob_best_fit
Calculate effective number of bits in sample data by best fit.
This function calculates the effective number of bits in sample data. The input is a sinusoidal
output from the device, at a given frequency (in Hz) and a nominal number of bits. The
output is the effective number of bits, given by
Effective number of bits = nominal_number_of_bits – lg( 12 ⋅ rms_error) (27–21)
where:
2 lg(x) = x (27–22)
rms_error The RMS error between the best-fit approximation to the input
and the input. The best-fit sinusoidal function is computed using
an algorithm from ANSI/IEEE Std 1057 - An Algorithm for Three
Parameter (Known Frequency) Least Squared Fit to Sine Wave
Data.
Synopsis
double da_enob_best_fit(DARRAY input, da_size_t nominal_number_of_bits)
IMAGE Solutions V8.3 27-36
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input sample data.
nominal_number_of_bits
The nominal number of bits represented by the input, calculated
using equation 27–21 above.
Returns
The effective number of bits.
If an error in the parameters is detected, 0.0 is returned.
da_enob_snr
Calculate the effective number of bits using the signal-to-noise ratio.
This function calculates of the effective number of bits using the signal-to-noise ratio of the
input waveform. The input waveform must be in the time domain, and the nominal number
of bits is specified as a parameter. The sample and waveform frequencies are taken from
the input DARRAY.
The result returned by this function is
( SNR ( input ) – 20 log ( 6 ) ⁄ 2 )
Result = ------------------------------------------------------------------------------- (27–23)
20 log ( 2 )
where SNR is the signal-to-noise ratio of the input waveform.
Synopsis
double da_enob_snr(DARRAY input, da_size_t number_of_bits)
Arguments
input Input variable containing the input sine waveform.
The data array must have a length which is a power of 2 and
contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
number_of_bits The nominal number of bits. Value must be greater than 0.
Returns
The effective number of bits.
See Also
“da_enob_snr_full”, “da_enob_best_fit”
IMAGE Solutions V8.3 27-37
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_enob_snr_full
Calculate the effective number of bits using the signal-to-noise ratio, with input parameters:
number of harmonics, test frequency, and sample frequency.
This function calculates the effective number of bits, using the signal-to-noise ratio of the
input waveform. The input waveform must be in the time domain, and the nominal number
of bits is specified as a parameter. The sample and test frequency of the input waveform
and the number of harmonics to consider in the SNR calculation must be specified as
parameters.
The result returned by this function is
Result = (------------------------------------------------------------------------------
SNR ( input ) – 20 log ( 6 ) ⁄ 2 )
- (27–24)
20 log ( 2 )
where SNR is the signal-to-noise ratio of the input waveform.
Synopsis
double da_enob_snr_full(DARRAY input, da_size_t number_of_bits,
da_size_t number_of_harmonics, double Fs, double Ft)
Arguments
input Input variable containing the input sine waveform.
The data array must have a length which is a power of 2 and
contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
number_of_bits The nominal number of bits. Value must be greater than 0.
number_of_harmonics
Number of harmonics to exclude from noise power.
Fs Sample frequency of the input waveform. Value must be
positive.
Ft Frequency of the waveform. Value must be between 0 and Fs/2.
Returns
The effective number of bits.
See Also
“da_enob_snr”, “da_enob_best_fit”
da_expand
Expand.
IMAGE Solutions V8.3 27-38
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
The result of this function is a DARRAY whose data is zero everywhere except at indices
which are multiples of n. At index k*n the output is the kth element of the input DARRAY’s
data.
Synopsis
DARRAY da_expand(DARRAY h_in, int n)
Arguments
h_in The input data array can have any size and any data type.
n The expansion increment. Must be positive.
Returns
Data array handle.
da_fft
In-place FFT.
This function does not return a value. It changes the program state by replacing the input
DARRAY’s data with its discrete Fourier transform
N–1
out [ n ] = ∑ in [ k ]e ( -j2π × n × k ⁄ N ) (27–25)
k=0
where N is the size of the input sequence, and j is the square root of -1.
The function uses a standard radix 8 FFT algorithm.
Note that, as is usual with the DFT, the output is N times the values the Fourier series might
supply. For example, the cosine function can be written as
A
A × cos ( ωt ) ≡ ---- ( e jωt + e –jωt ) (27–26)
2
The Fourier series coefficients are A/2 at ω and -ω. If ω = 2 × π × n/N, then out[n] is N × A/2.
Synopsis
da_fft(DARRAY h_in)
Arguments
h_in The input data array must have a length which is a power of 2.
The input data must have a floating point type: DA_REAL or
DA_DREAL. Since the input is real, the full spectrum is conjugate
IMAGE Solutions V8.3 27-39
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
symmetric and, therefore, only half the output spectrum must be
represented.
In normal operation, after the function completes, the length of the input DARRAY will be half
the original length. The input data will be set to type DA_DCMPLX if it is initially DA_DREAL and
DA_CMPLX if the initial type is DA_REAL.
On errors, data is not altered.
Side Effects
Input data is overwritten by the result.
See Also
“da_set_number_samples”
da_fftb
Not-in-place FFT.
The result of this function is the discrete Fourier transform of the input data
N–1
out [ n ] = ∑ in [ k ]e ( -j2π × n × k ⁄ N ) (27–27)
k=0
where N is the size of the input sequence, and j is the square root of -1.
Note that, as is usual with the DFT, the output is N times the values the Fourier series might
supply. For example, the cosine function may be written as
A
A × cos ( ωt ) ≡ ---- ( e jωt + e –jωt ) (27–28)
2
The Fourier series coefficients are A/2 at ω and -ω. If ω = 2 × π × n/N, then out[n] is N × A/2.
Synopsis
DARRAY da_fftb(DARRAY h_in)
Arguments
h_in The input data array must have a length which is either a power
of two or 400, or 800. Data must be a floating-point type:
DA_REAL or DA_DREAL.
Returns
Since the input is not complex, the full spectrum is conjugate symmetric and, therefore, only
half the output spectrum needs to be represented. In normal operation, the length of the
IMAGE Solutions V8.3 27-40
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
output DARRAY will be half of the input DARRAY’s length. The type will be the smallest type
compatible with the input type and also with DA_CMPLX. That is, the output type will be
DA_DCMPLX if the input type is DA_DREAL and DA_CMPLX if the input type is DA_REAL.
See Also
“da_set_number_samples”
da_fix32d
Vector double to integer.
The result of this function is a data array whose data is the element-wise application to the
data of the input data array of the function which converts double precision floating point
integers to DA_INT.
Synopsis
DARRAY da_fix32d(DARRAY h_in)
Arguments
h_in The input data array must have type DA_DREAL. It can have any
nonpositive length.
Returns
In normal operation, the output DARRAY has the length of the input DARRAY and has type
DA_DREAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_flt32d
Vector float to integer.
The result of this function is a DARRAY handle whose data is the element-wise application to
the input DARRAY’s data of the function which converts single precision floating point
numbers to DA_INT.
Synopsis
DARRAY da_flt32d(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data type
must be DA_REAL.
IMAGE Solutions V8.3 27-41
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
In normal operation, the output DARRAY will have type DA_INT and will have the same length
as the input DARRAY.
Zero is returned in the case of a run-time error which is ignored or continued.
da_frac_to_double
Vector frac2 to double.
The result of the function is a data array whose data is the element-wise application to the
input data of the function which converts DA_FRACT2 data to double precision floating point
data.
If fract2_to_double(t) is the result of converting the DA_FRACT2 number t to double precision
floating point
out [ n ] = fract2_to_double ( in [ n ] ) (27–29)
for all indices n.
Synopsis
DARRAY da_frac_to_double(DARRAY h_in)
Arguments
h_in The input data array length must be greater than zero. Data must
be type DA_FRACT2.
Returns
In normal operation, the output DARRAY will have the same length as the input DARRAY and
will have type DA_DREAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_frac_to_real
Vector frac2 to float.
The result of this function is a DARRAY whose data is the element-wise application to the
input DARRAY’s data of the function which converts DA_FRACT2 data to single precision
floating point.
If fract2_to_real(t) is the result of converting the DA_FRACT2 number t to single precision
floating point
out [ n ] = fract2_to_real ( in [ n ] ) (27–30)
IMAGE Solutions V8.3 27-42
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_frac_to_real(DARRAY h_in)
Arguments
h_in The input data array length must be greater than zero. Data must
have type DA_FRACT2.
Returns
In normal operation, the output DARRAY has the same length as the input DARRAY. Its type is
always DA_REAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_free
Frees a DARRAY associated with a handle. Deallocates a DARRAY by freeing the
associated data memory. It sets the content of passed DARRAY handle pointer to DA_NULL.
Synopsis
int da_free(DARRAY *handle)
RESTRICTIONS
1. Side threads that are called from a TESTF that has been called from a SEQUENCER
can only free DARRAYs with lifetime of DA_TESTF. Otherwise,
the return value will be TL_DA_CANT_FREE but no runtime
error is thrown.
2. Side threads that are not called from a TESTF that has been
called from a SEQUENCER can only free DARRAYs with
lifetime of DA_TESTF or DA_RUN. Otherwise, the return value
will be TL_DA_CANT_FREE but no run-time error is thrown.
3. If da_free() is called in the main thread, it calls
tl_compute_sync(). That is, it waits for all side threads to finish
before freeing a Data array.
4. The DARRAYs with a lifetime of DA_JOB can only be freed
(by calling da_free()) by the main thread. Side threads are not
allowed to free DARRAYs with a lifetime of DA_JOB.
These restrictions are forced to ensure that you do not
accidentally free a DARRAY that is intended to be used or is
being used by other threads.
Note, however, that it is still logically possible to free a DARRAY
which may be intended to be used later. So, it is your
responsibility to free only those DARRAYs that will not be used
later.
IMAGE Solutions V8.3 27-43
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
*handle - address of Data array handle
Returns
TL_DA_SUCCESS The memory associated with the DARRAY has been freed.
TL_DA_NOT_FOUND The attempt to free memory failed because the DARRAY does
not exist, or there was an error getting to the DARRAY.
TL_DA_CANT_FREE The attempt to free memory failed because you are not allowed
to free this DARRAY.
da_get_domain
Get the data domain of a DARRAY. Locates the data darray referenced by handle and
returns the data domain.
Synopsis
DA_DataDomain da_get_domain(DARRAY handle)
Arguments
DARRAY handle The data array handle
Returns
The data domain of the DARRAY or TL_DA_ERROR.
da_get_Fs
Locates the data array referenced by the parameter handle and returns the value of the
sampling frequency field.
Synopsis
double da_get_Fs(DARRAY handle)
Arguments
handle A handle for a data array or the data array name (type DARRAY).
An unsigned integer.
Returns
The value of the sample frequency field of the data array or TL_DA_ERROR.
IMAGE Solutions V8.3 27-44
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_get_Ft
Locates the data array referenced by the parameter handle and gets the value of the
fundamental or “test” frequency.
Synopsis
double da_get_Ft(DARRAY handle)
Arguments
handle A handle for a data array or the data array name (type DARRAY).
An unsigned integer.
Returns
The value of the test frequency field of the data array or TL_DA_ERROR.
da_get_lifetime
Locates the queue a darray is on and sets the lifetime parameter to that queue value.
Returns a 1 if the darray was found, 0 if not found.
Synopsis
int da_get_lifetime(DARRAY handle, DA_DATA_LIFETIME lifetime)
Arguments
handle the handle of the darray you wish to locate lifetime - a pointer to
the lifetime value
Returns
1 for successfully found darray 0 if not found
da_get_number_samples
Returns the number of samples. For time domain signals this is exactly equal to
da_get_size. for frequency domain signals or power spectra this operation tells how many
samples the original signal had. If the original signal was purely real, this will be twice the
value of da_get_size().
Synopsis
int da_get_number_samples(DARRAY handle)
Arguments
handle Data array handle
IMAGE Solutions V8.3 27-45
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
The number of samples.
da_get_size
Locates the data array referenced by the parameter handle and returns the value of the size
field.
Synopsis
int da_get_size(DARRAY handle)
Arguments
handle A handle for a data array or the data array name (type DARRAY).
An unsigned integer.
Returns
The value of the size field of the data array or TL_DA_ERROR.
da_get_type
Locates the data array referenced by parameter handle and returns the value of the
datatype field.
Synopsis
int da_get_type(DARRAY handle)
Arguments
handle A handle for a data array or the data array name (type DARRAY).
An unsigned integer.
Returns
The value of the datatype field of the data array or TL_DA_ERROR. Possible types and return
values are DA_REAL (1), DA_DREAL (6), DA_CMPLX (2), DA_DCMPLX (7), DA_INT (3), and
DA_FRACT2 (5).
da_get_vector
Locates the data array referenced by the parameter handle and returns a pointer to the data
vector.
Synopsis
void *da_get_vector(DARRAY handle)
IMAGE Solutions V8.3 27-46
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
handle A handle for a data array or the data array name (type DARRAY).
An unsigned integer.
Returns
A pointer to the data vector or nil.
da_hamm
Hamming window.
This function returns the handle of a DARRAY whose data is the result of applying the
Hamming window to the input vector
out [ n ] = in [ n ] × ( 0.54 × 0.46 × cos ( n × 2.0 × π ⁄ N ) ) (27–31)
for each index n, where N is the length of the input vector.
The input vector is not modified.
Synopsis
DARRAY da_hamm(DARRAY h_in)
Arguments
h_in The input data array size must be a power of 2. Data must be a
noncomplex type.
Returns
In normal operation, the function returns the handle of a DARRAY which contains the
windowed signal. The type of the output DARRAY is the smallest type compatible with the
input type and DA_REAL. That is, it is DA_DREAL if the input is DA_DREAL and DA_REAL in all
other cases. Its length is the length of the input vector.
Zero is returned in the case of a run-time error which is ignored or continued.
da_hamming_window
Hamming window function.
This name denotes the Hamming window function. It is not a callable function. It is only used
as a parameter to da_complex_spectrum. The hamming window is defined by
data[i] = 0.08 + 0.46 × ( 1 – cos ( 2.0 × π × i ⁄ N ) ) (27–32)
where N is the size of the data vector.
IMAGE Solutions V8.3 27-47
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
da_window_function da_hamming_window
See Also
“da_3rd_order_imd”
da_hann
Hanning window.
The function returns the result of applying the Hanning window to the input vector
out [ n ] = in [ n ] × 0.5 × cos ( 1.0 – cos ( n × 2.0 × π ⁄ N ) ) (27–33)
for each index n, where N is the length of the input vector.
The input vector is not modified.
Synopsis
DARRAY da_hann(DARRAY h_in)
Arguments
h_in The input data array length must be a power of 2. Data type must
be a noncomplex type.
Returns
In normal operation, the return value is the handle to a DARRAY which contains the
conditioned signal. The type of the output DARRAY is DA_DREAL if the input is DA_DREAL and
DA_REAL in all other cases. Its length is the length of the input vector.
Zero is returned in the case of a run-time error which is ignored or continued.
da_hanning_window
Hanning window function.
This name denotes the Hanning window function. It is not a callable function. It is only used
as a parameter to da_complex_spectrum. The Hanning window is defined by
data[i] = 0.5 × ( 1 – cos ( 2.0 × π × i ⁄ N ) ) (27–34)
where N is the size of the data vector.
Synopsis
da_window_function da_hanning_window
IMAGE Solutions V8.3 27-48
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
See Also
“da_3rd_order_imd”
da_hd
Calculate the harmonic distortion of an input sine wave.
This function calculates harmonic distortion. Harmonic distortion is a measure of the power
of a sine wave signal at the fundamental frequency as compared to the power in the first
few harmonic frequencies. The input DARRAY contains the sine wave to be analyzed and its
sample and test frequency. (These can be set using da_set_Fs and da_set_Ft.)
The result is the ratio of the fundamental power to the maximum power in any of the first few
harmonics. (The fundamental power is the magnitude of the FFT of the input waveform at
frequency Fs, and the harmonic power is at 2*Fs, 3*Fs, and so on.) The number of
harmonics considered is the IMAGE default value (5). An FFT is used to find the power of
the signal at given frequencies.
Synopsis
double da_hd(DARRAY input)
Arguments
input Input variable containing the input sine waveform.
The data array must have a length which is a power of 2 and
contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
Returns
The harmonic distortion, expressed as a ratio, or TL_DA_ERROR, in the case of a run-time
error.
See Also
“da_hd_full”
da_hd_full
Calculate the harmonic distortion of an input sine wave, with input parameters: sample
frequency, test frequency, and the number of harmonics.
This function calculates harmonic distortion. Harmonic distortion is a measure of the power
of a sine wave signal at the fundamental frequency as compared to the power in the first
few harmonic frequencies. The test and sampling frequencies are specified as input
parameters as are the number of harmonics.
The result is the ratio of the fundamental power to the maximum power in any of the first few
harmonics. (The fundamental power is the magnitude of the FFT of the input waveform at
IMAGE Solutions V8.3 27-49
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
frequency Fs, and the harmonic power is at 2*Fs, 3*Fs, and so on.) The number of
harmonics considered is determined by the input parameter num_harmonics. An FFT is
used to find the power of the signal at given frequencies.
Synopsis
double da_hd_full(DARRAY input, double Fs, double Ft, da_size_t num_harmonics)
Arguments
input Input variable containing the input sine waveform.
The data array must have a length which is a power of 2 and
contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
Fs Sample frequency of the input waveform. Value must be
positive.
Ft Frequency of the waveform. Value must be positive. Value must
be no greater than 1/2*num_harmonics times the size of the Fs.
num_harmonics The number of harmonics to consider. Value must be at least
one.
Returns
The harmonic distortion, expressed as a ratio, or TL_DA_ERROR, in the case of a run-time
error.
See Also
“da_hd”
da_hist
Histogram.
This function returns no results. It changes the program state by side-effects on its
parameters. It calculates a histogram for h_in1 and stores the results in h_in2. The
histogram is defined as follows:
If |h_in2| is the length of the vector h_in2:
• h_in1 is never changed
• h_in2[0] is increased by the number of elements of h_in1 which are less than min
• h_in2[|h_in2|-1] is increased by the number of elements of h_in1 which are greater
than or equal to max
• in2[k] is incremented by the number of elements of h_in1 which are in the range [min +
(k-1) * (max - min)/|h_in2|, min + k * (max - min)/|h_in2|) for integer k in the range
[1,|h_in2|-1]
IMAGE Solutions V8.3 27-50
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
This latter calculation divides range [min, max] into |h_in2| bins. Then the kth element
of in2 is increased by the number of elements which fall in the kth bin.
NOTE
The parameter h_in2 may already contain a histogram, in which case the result of calling
this function will be to add values to each existing value in h_in2. h_in2 is not cleared
before use.
Synopsis
da_hist(DARRAY h_in1, DARRAY h_in2, double max, double min)
Arguments
h_in1 The first input data array can have any length. Data must be a
noncomplex type.
h_in2 The second input data array, also an output parameter, can have
any length. Data must be a floating point type: DA_REAL or
DA_DREAL. The second input data array type is not automatically
promoted to DA_DREAL. If the first input data array type is
DA_DREAL, and the second data array type is DA_REAL, an error
results.
max The maximum value for the range of the histogram. This value is
a double precision floating point number.
min The minimum value for the range of the histogram. This value is
a double precision floating point number.
Side Effects
The elements of the input parameter h_in2 are increased by the histogram counts.
da_ifft
In-place inverse FFT.
This function does not return a value. It changes the program state by replacing the input
DARRAY data with its inverse discrete Fourier transform
N–1 k
-j2π × n × ------- 2N – 2 k
-j2π × n × -------
- -
2N 2N
out [ n ] = ∑ in [ k ]e + ∑ conj ( in [ 2N – k – 1 ] )e (27–35)
k=0 k=N
where N is the size of the input sequence, conj(c) is the complex conjugate of the complex
number c, and j is the square root of -1.
IMAGE Solutions V8.3 27-51
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
The function uses a standard radix 8 FFT algorithm. The input vector of length N represents
a length 2N spectrum, whose negative frequency bins are the complex conjugates of the
positive bins.
Note that the amplitude of the input data is assumed to be scaled as with da_rfftsc. For
example, if the spectrum is zero at all points except for bin k, and the value of k is 1.0 + 0.0j,
the result of the ifft is k cycles of the cosine whose amplitude is 2.0.
Synopsis
da_ifft(DARRAY h_in)
Arguments
h_in The data must be a complex type: DA_CMPLX or DA_DCMPLX.
In normal operation, after the function’s execution the length of the input DARRAY will be half
the original length. The input DARRAY’s type will be set to DA_REAL if it is initially DA_CMPLX
and DA_DREAL if the initial type is DA_DCMPLX.
On errors, data is not altered.
Side Effects
The data in the input data array is overwritten by the result.
da_ifftb
Not-in-place inverse FFT.
The result of this function is a DARRAY handle whose data is the inverse discrete Fourier
transform of the input DARRAY’s data
N–1 k
-j2π × n × ------- 2N – 2 k
-j2π × n × -------
- -
2N 2N
out [ n ] = ∑ in [ k ]e + ∑ conj ( in [ 2N – k – 1 ] )e (27–36)
k=0 k=N
where N is the size of the input sequence, conj(c) is the complex conjugate of the complex
number c, and j is the square root of -1.
The function uses a standard radix 8 FFT algorithm. The input vector of length N represents
a length 2N spectrum whose negative frequency bins are the complex conjugates of the
positive bins.
Note that the amplitude of the input data is assumed to be scaled as with da_rfftsc. For
example, if the spectrum is zero at all points except for bin k, and the value of k is 1.0 + 0.0j,
the result of the ifft is k cycles of the cosine whose amplitude is 2.0.
Synopsis
DARRAY da_ifftb(DARRAY h_in)
IMAGE Solutions V8.3 27-52
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
h_in The input data must be a complex type.
Returns
In normal operation, the return DARRAY will have twice the length of the input DARRAY. The
output type will be DA_DREAL if the input type is DA_DCMPLX. The output type will be DA_REAL
if the input type is DA_CMPLX.
da_imd
Calculate the intermodulation distortion.
This function calculates the intermodulation distortion of a two-tone sine wave. The time
domain waveform and its two fundamental frequencies are specified as parameters, f1, and
f2, respectively. Also specified is an output buffer containing allocated memory for six
double-precision results.
The function takes the FFT of the input waveform and records the magnitude of that
spectrum at six key frequencies. Those six values are written in sequence to six locations
in the output buffer. The frequencies of interest are
f1 + f2
f1 - f2
f1 + 2*f2
f1 - 2*f2
2*f1 + f2
2*f1 - f2
Negative frequencies are acceptable (and, in fact, unavoidable), since by definition, the
value of the spectrum of a real signal at frequency -f is the same as it is at frequency f. Note
that the value computed is I[f1+f2] and not I[f1] + I[f2] (assuming I[f] is the value of the input
spectrum at frequency f.)
Synopsis
void da_imd(DARRAY input, double f1, double f2, double *output)
Arguments
input Input variable containing the input two-tone sine wave.
The input data array must have a length which is a power of 2
and contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
f1 Frequency of the first tone. Value must be between 0 and Fs/2.
f2 Frequency of the second tone. Value must be between 0 and
Fs/2.
IMAGE Solutions V8.3 27-53
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
*output A pointer which represents where to write the results. In the case
of an error, the function writes six TL_DA_ERRORs here.
Side Effects
Writes six double-precision numbers.
See Also
“da_imd_full”
da_imd_full
Calculate the intermodulation distortion with additional parameter sample frequency.
This function calculates the intermodulation distortion of a two-tone sine wave. The sample
frequency of the waveform and its two fundamental frequencies are specified as
parameters, f1, and f2, respectively. Also specified is an output buffer containing allocated
memory for six double-precision results.
The function takes the FFT of the input waveform and records the magnitude of that
spectrum at six key frequencies. Those six values are written in sequence to six locations
in the output buffer. The frequencies of interest are
f1 + f2
f1 - f2
f1 + 2*f2
f1 - 2*f2
2*f1 + f2
2*f1 - f2
Negative frequencies are acceptable (and, in fact, unavoidable), since by definition, the
value of the spectrum of a real signal at frequency -f is the same as it is at frequency f. Note
that the value computed is I[f1+f2] and not I[f1] + I[f2] (assuming I[f] is the value of the input
spectrum at frequency f.)
Synopsis
void da_imd_full(DARRAY input, double f1, double f2, double *output,
double Fs)
Arguments
input Input variable containing the input two-tone sine wave.
The input data array must have a length which is a power of 2
and contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
f1 Frequency of the first tone. Value must be between 0 and Fs/2.
f2 Frequency of the second tone. Value must be between 0 and
Fs/2.
IMAGE Solutions V8.3 27-54
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
*output A pointer which represents where to write the results. In the case
of an error, the function writes six TL_DA_ERRORs here.
Fs Sample frequency. Value must be positive.
Side Effects
Writes six double-precision numbers.
See Also
“da_imd”
da_lookup
Lookup.
The result of this function is a DARRAY handle whose elements are a rearranging of the
elements of h_in1, using the elements of h_in2 to determine the rearrangement
out [ n ] = in2 [ in1 [ n ] ] (27–37)
for each index n.
The elements of h_in1 can be duplicated. Elements of h_in2 may be lost in the
rearrangement.
Synopsis
DARRAY da_lookup(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The first input data array must have type DA_INT. It can have any
length greater than zero.
h_in2 The second input data array must have a noncomplex type. It
can have any length greater than zero.
Returns
In normal operation, the return value has the same type as the smallest type compatible with
the type of the second input data array (h_in2) and also DA_REAL. That is, the output
DARRAY type is DA_DREAL if the second parameter (h_in2) has type DA_DREAL and is
DA_REAL in all other cases. The return value has the same length as the first input
parameter, h_in1.
da_lveq
Logical vector equal.
IMAGE Solutions V8.3 27-55
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
This function returns the handle of a data array whose value represents the element-wise
logical equality of the two input vectors:
out [ n ] = 1.0 if in1 [ n ] = in2 [ n ]
(27–38)
out [ n ] = 0.0 if in1 [ n ] ≠ in2 [ n ]
for each index n.
Synopsis
DARRAY da_lveq(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data array h_in1 must have the same length as h_in2.
Data must be a noncomplex type.
h_in2 The input data array h_in2 must have the same length as h_in1.
Data must be a noncomplex type.
Returns
In normal operation, the output DARRAY type is the smallest type compatible with the input
types and DA_REAL. That is, it is DA_DREAL if either of the input vectors have type DA_DREAL
and DA_REAL otherwise. Its length is the common length of the input vectors.
Zero is returned in the case of a run-time error which is ignored or continued.
da_lvge
Logical vector greater than or equal.
This function returns the handle of a data array whose elements represent the element-wise
comparison of the two input vectors for greater than or equality
out [ n ] = 1.0 if in1 [ n ] ≥ in2 [ n ]
(27–39)
out [ n ] = 0.0 if in1 [ n ] < in2 [ n ]
for each index n.
Synopsis
DARRAY da_lvge(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data array h_in1 must have the same length as h_in2.
Data must be a noncomplex type.
h_in2 The input data array h_in2 must have the same length as h_in1.
Data must be a noncomplex type.
IMAGE Solutions V8.3 27-56
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
In normal operation, the output data array type is the smallest type compatible with the types
of the inputs and DA_REAL. That is, its type is DA_DREAL if either of the input vectors have
type DA_DREAL and DA_REAL otherwise. Its length is the common length of the input vectors.
Zero is returned in the case of a run-time error which is ignored or continued.
da_lvgt
Logical vector greater than.
This function returns the handle of a DARRAY whose elements represent the element-wise
comparison of the two input vectors
out [ n ] = 1.0 if in1 [ n ] > in2 [ n ]
(27–40)
out [ n ] = 0.0 if in1 [ n ] ≤ in2 [ n ]
for each index n.
Synopsis
DARRAY da_lvgt(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data array h_in1 must have the same length as h_in2.
Data must be a noncomplex type.
h_in2 The input data array h_in2 must have the same length as h_in1.
Data must be a noncomplex type.
Returns
In normal operation, the output DARRAY type is the smallest type compatible with the types
of the input vectors. This is DA_DREAL if either of the input vectors have type DA_DREAL and
DA_REAL otherwise. Its length is the common length of the input vectors.
Zero is returned in the case of a run-time error which is ignored or continued.
da_lvne
Logical vector not equal.
This function returns the handle of a DARRAY whose elements represent the element-wise
comparison of the two input vectors for inequality
out [ n ] = 1.0 if in1 [ n ] ≠ in2 [ n ]
(27–41)
out [ n ] = 0.0 if in1 [ n ] = in2 [ n ]
for each index n.
IMAGE Solutions V8.3 27-57
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_lvne(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data array h_in1 must have the same length as h_in2.
Data must be a noncomplex type.
h_in2 The input data array h_in2 must have the same length as h_in1.
Data must be a noncomplex type.
Returns
In normal operation, the output DARRAY type is the smallest type compatible with the two
input vectors. That is, this type is DA_DREAL if either of the input vectors have type DA_DREAL
and DA_REAL otherwise. Its length is the common length of the input vectors. On errors, zero
is returned.
Zero is returned in the case of a run-time error which is ignored or continued.
da_lvnot
Logical vector not.
This function returns the handle of a DARRAY whose elements are the element-wise
application of the real complement function to the elements of the input vector
out [ n ] = 1.0 if in1 [ n ] = 0.0
(27–42)
out [ n ] = 0.0 if in1 [ n ] ≠ 0.0
for each index n.
Synopsis
DARRAY da_lvnot(DARRAY h_in)
Arguments
h_in The input data array length must be greater than zero. Data must
be a noncomplex type.
Returns
In normal operation, the output DARRAY type is the smallest type compatible with DA_REAL.
That is, its type is DA_DREAL if the input vector has type DA_DREAL and DA_REAL in all other
cases. Its length is the length of the input vector.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-58
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_maxmgv
Maximum magnitude.
This function returns a double precision floating point number whose value is the maximum
of the absolute values (magnitudes) of the elements of the input vector.
For the returned maximum value r
in [ n ] ≤ r (27–43)
for each index n.
Synopsis
double da_maxmgv(DARRAY h_in)
Arguments
h_in The input data array length must be greater than zero. Data must
be a noncomplex type.
Returns
In normal operation, the return value is a scalar whose type is double precision floating point
number.
Zero is returned in the case of a run-time error which is ignored or continued.
da_maxv
Maximum value.
This function returns the maximum of all the elements of the input vector and its index.
If r is the result of this function, then for all indices n
in [ n ] ≤ r (27–44)
and, if *outIndex is not null
in [ *outIndex ] = r (27–45)
Synopsis
double da_maxv(DARRAY h_in, int *outIndex)
Arguments
h_in The input data array can be any length. The data must be a
noncomplex type.
IMAGE Solutions V8.3 27-59
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
outIndex If this parameter is non-null, it is a pointer to an integer. The
maximum value will be deposited in this integer.
Returns
In normal operation, the result is a scalar whose type is double precision floating point.
Zero is returned in the case of a run-time error which is ignored or continued.
Side Effects
The address at which outIndex points is set to the index of the element at which the
maximum element occurs.
da_meamgv
Mean of element absolute values.
The value of this function is the mean of the absolute value of the elements in the input
vector
out = ( in [ 0 ] + ... + in [ N – 1 ] ) ⁄ N (27–46)
Synopsis
double da_meamgv(DARRAY h_in)
Arguments
h_in The input data array can be any length. The data must be a
noncomplex type.
Returns
In normal operation, the output is a double precision floating point number.
Zero is returned in the case of a run-time error which is ignored or continued.
da_meanv
Mean of elements.
The value of this function is the mean of the values of the elements in the input vector
out = ( in [ 0 ] + ... + in [ N – 1 ] ) ⁄ N (27–47)
where N is the size of the input vector.
Synopsis
double da_meanv(DARRAY h_in)
IMAGE Solutions V8.3 27-60
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
h_in The input data array can be any length. The data must be a
noncomplex type.
Returns
In normal operation, the output is a double precision floating point number, even if the input
is DA_INT, DA_FRACT2, or DA_REAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_measqv
Mean of element squares.
The value of this function is the mean of the squares of the values of the elements in the
input vector
out = ( in [ 0 ] 2 + ... + in [ N – 1 ] 2 ) ⁄ N (27–48)
where N is the size of the input vector.
Synopsis
double da_measqv(DARRAY h_in)
Arguments
h_in The input data array can be any length. The data must be a
noncomplex type.
Returns
In normal operation, the output is a double precision floating point number, even if the input
is DA_INT, DA_FRACT2, or DA_REAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_merge
Merge.
The result of this function is a data array whose data is a copy of the data of the input data
array with handle h_in1, with the following changes. Starting at offset, each nth element
of h_in1 in the copy is replaced by the corresponding element of h_in2 data.
Output data will have the same type as the input array which has the highest type.
For each index k,
out [ k ] = in2 [ p ] (27–49)
IMAGE Solutions V8.3 27-61
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
if k has the form offset + p × n.
Otherwise
out [ k ] = in1 [ k ] (27–50)
Synopsis
DARRAY da_merge(DARRAY h_in1, DARRAY h_in2, int offset, int n)
Arguments
h_in1 The first input data array length |h_in1| must be greater than or
equal to (offset + n * (|h_in2|-1)) + 1. The input data arrays can
have any data type.
h_in2 The second input data array length must obey the inequality
listed for h_in1. The input data arrays can have any data types.
offset The element of h_in1 to begin replacing with elements of h_in2.
offset must be an integer, with value greater than zero.
n The “stride” n determines the replacement internal. Every nth
element will be replaced by an element of h_in2. n must be an
integer, with value greater than zero.
Returns
Data array handle of the data array with the merged data.
da_minmgv
Minimum magnitude.
This function returns a double precision floating point number whose value is the minimum
of the absolute values (magnitudes) of the elements of the input vector.
If the result is denoted r, then for each index n
r ≤ in [ n ] (27–51)
where |in[n]| denotes the absolute value, or magnitude, of the number in[n].
Synopsis
double da_minmgv(DARRAY h_in)
Arguments
h_in The input data array must have a noncomplex type.
IMAGE Solutions V8.3 27-62
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
In normal operation, the return value is a scalar whose type is double precision floating
point.
Zero is returned in the case of a run-time error which is ignored or continued.
da_minv
Minimum value.
This function returns the minimum of all the elements of the input vector and its index.
If r is the result of this function, then for all indices n
r ≤ in [ n ] (27–52)
and, if *outIndex is not null
in [ *outIndex ] = r (27–53)
Synopsis
double da_minv(DARRAY h_in, int *outIndex)
Arguments
h_in The input data must be a noncomplex type.
*outIndex This is the output data. If it is not null, it is a pointer to the element
index.
Returns
In normal operation, the result is a scalar whose type is double precision floating point.
Zero is returned in the case of a run-time error which is ignored or continued.
da_multitone
Simulate the sampling of a multitone cosine waveform.
This function generates a DARRAY containing a multitone cosine wave. You specify the size
of the waveform and the sample frequency. Additionally, you pass to it an array of
structures, one for every tone in the waveform. Each structure contains the frequency,
amplitude, offset, and phase of one tone. The number of tones to be added in the waveform
is the final parameter.
This function allocates a new DARRAY of size num_samples and fills the vector in the current
site with a waveform representing the sum of all the cosine waves described in the tones
array. The sample frequency of the DARRAY will also be filled in, and the handle of this new
DARRAY is returned.
IMAGE Solutions V8.3 27-63
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_multitone(double Fs, da_size_t num_samples, DA_TONE *tones,
da_size_t num_tones)
typedef struct da_tone {
double frequency;
double amplitude;
double offset;
double phase;
} DA_TONE;
Arguments
Fs Sample frequency of the DARRAY.
num_samples Size of the DARRAY.
*tones An array of structures, one for each tone, containing the
amplitude, frequency, offset, and phase of each.
num_tones The number of tones and the number of structures in array
tones.
Returns
A newly allocated DARRAY containing a multitone cosine waveform (the sum of several
cosine waves at the specified parameters). If an error in the parameters is detected,
DA_NULL is returned without allocating a new array.
Side Effects
Allocates a new DARRAY.
See Also
“da_cosine”
da_null_window
Identity window function.
This name denotes the identity window function. It is not a callable function. It is only used
as a parameter to da_complex_spectrum. The identity window function does not scale or
alter the data at all.
Synopsis
da_window_function da_null_window
See Also
“da_3rd_order_imd”
IMAGE Solutions V8.3 27-64
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_offset_binary_to_real
Vector offset binary to real.
This function returns a DARRAY whose data is the result of converting every element of the
input data array from a binary value type to DA_REAL type. Input values are assumed to be
no more than res bits wide but this constraint is not enforced.
The function subtracts a given power of two from the input and then scales it by multiplying
by the scale parameter. The power of two value which is subtracted is (1 << (res - 1)).
An element of the output DARRAY has the value
out [ n ] = scale × ( in [ n ] – ( 1 « ( res – 1 ) ) ) (27–54)
As a result of this operation
scale × ( -2 res – 1 ) ≤ out [ n ] ≤ scale × ( -2 res – 1 ) (27–55)
Synopsis
DARRAY da_offset_binary_to_real(DARRAY h_in, double scale, int res)
Arguments
h_in The input data array length must be greater than 0. Data must be
type DA_INT or DA_FRACT2.
scale The scale factor applied to every element of the h_in after the
element is converted to D_REAL.
res The bit width range of the data before the scale is applied. The
value of res must fall in the range 2 <= res <= 32.
Returns
In normal operation, the output DARRAY has the type DA_REAL. Its length is the length of the
input DARRAY.
Zero is returned in the case of a run-time error which is ignored or continued.
da_peak_to_peak
Calculate the peak to peak voltage of the sample data.
This function calculates the difference between the maximum and minimum elements of a
vector.
Synopsis
double da_peak_to_peak(DARRAY input)
IMAGE Solutions V8.3 27-65
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input sample data.
Returns
The difference between the maximum and minimum elements.
da_phase
Compute the phase at a given frequency.
The phase is the angle of the complex Fourier coefficient of the given frequency. It is in the
range [-π, π]. Both extremes are possible, since the real part of the Fourier coefficient can
be ±0.0. The input should be a spectrum. Sample frequency must be in the input data array.
Synopsis
double da_phase(DARRAY input, double f_i)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input spectrum data.
f_i Frequency of interest.
Returns
The phase.
See Also
“da_amplitude”, “da_amplitude_full”, “da_phase_full”
da_phase_full
Compute the phase at a given frequency, with additional parameter sample frequency.
The sample rate is specified using parameter f_s.
The phase is the angle of the complex Fourier coefficient of the given frequency. It is in the
range [-π, π]. Both extremes are possible, since the real part of the Fourier coefficient can
be ±0.0. The input should be a spectrum.
Synopsis
double da_phase_full(DARRAY input, double f_i, double f_s)
IMAGE Solutions V8.3 27-66
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input spectrum data.
f_i Frequency of interest.
f_s Sample frequency.
Returns
The phase.
See Also
“da_amplitude”, “da_amplitude_full”, “da_phase”
da_phase_gain_change
Calculate the difference in phase and amplitude in two sine waves.
This function compares the phase and amplitude of two waveform segments. The input
DARRAY contains both waveform segments. The first segment begins at start1 and is
length1 elements long, and the second begins at start2 and is length2 elements long.
The two results, phase difference and amplitude difference, are written to pointers that you
provide. The sample and test frequencies of the segments are taken from the input DARRAY.
The result of this function is the difference (in radians) in phase between the two segments
and the difference (in volts) in amplitude. Simply expressed, it is phase(2) - phase(1) written
to the pointer phase, and amplitude(2) - amplitude(1), written to the pointer gain.
Synopsis
void da_phase_gain_change(DARRAY input, da_size_t start1, da_size_t length1,
da_size_t start2, da_size_t length2, double *phase, double *gain)
Arguments
input Input variable containing the input vector. Data type must be
DA_REAL or DA_DREAL.
start1 The beginning index of the first segment. Value must be
nonnegative.
length1 The number of elements in the first segment. Value must be a
power of 2 and equal to or greater than 8.
start2 The beginning index of the second segment. Value must be
nonnegative.
length2 The number of elements in the second segment. Value must be
a power of 2 and equal to or greater than 8.
Note that the following relationships must be true:
IMAGE Solutions V8.3 27-67
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
start2 >= start1 + length1
size >= start2 + length2
where size is the length of the input DARRAY.
*phase A pointer which represents where to write the phase difference.
This difference will be between 0 and 2*π.
*gain A pointer which represents where to write the difference in
amplitude.
Side Effects
Writes to pointers phase and gain.
See Also
“da_phase_gain_change_full”
da_phase_gain_change_full
Calculate the difference in phase and amplitude in two sine waves with additional
parameters, test frequency and sample frequency.
This function compares the phase and amplitude of two waveform segments. The input
DARRAY contains both waveform segments. The first segment begins at start1 and is
length1 elements long, and the second begins at start2 and is length2 elements long.
The two results, phase difference and amplitude difference, are written to pointers that you
provide. Additionally, the sample and test frequency of the segments are specified as
parameters.
The result of this function is the difference (in radians) in phase between the two segments
and the difference (in volts) in amplitude. Simply expressed, it is phase(2) - phase(1) written
to the pointer phase, and amplitude(2) - amplitude(1), written to the pointer gain.
Synopsis
void da_phase_gain_change_full(DARRAY input, da_size_t start1,
da_size_t length1, da_size_t start2, da_size_t length2,
double *phase, double *gain, double Fs, double Ft)
Arguments
input Input variable containing the input vector. Data type must be
DA_REAL or DA_DREAL.
start1 The beginning index of the first segment. Value must be
nonnegative.
length1 The number of elements in the first segment. Value must be a
power of 2 and equal to or greater than 8.
IMAGE Solutions V8.3 27-68
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
start2 The beginning index of the second segment. Value must be
nonnegative.
length2 The number of elements in the second segment. Value must be
a power of 2 and equal to or greater than 8.
Note that the following relationships must be true:
start2 >= start1 + length1
size >= start2 + length2
where size is the length of the input DARRAY.
*phase A pointer which represents where to write the phase difference.
This difference will be between 0 and 2*π.
*gain A pointer which represents where to write the difference in
amplitude.
Fs Sample frequency of the DARRAY. Value must be positive.
Ft Frequency of the sine waves. Value must be between 0 and
Fs/2.
Side Effects
Writes to pointers phase and gain.
See Also
“da_phase_gain_change”
da_phase_noise
Calculate the noise present in a sinusoid at a given frequency.
This function calculates the relative amount of noise present at a given frequency of a
sampled sinusoid. The input DARRAY contains a sine wave. Two important waveform
frequencies are the reference frequency Fc and the phase noise frequency, Fc + offset. You
specify the values for Fc and offset as parameters. The sample frequency is taken from the
input DARRAY.
The calculation is a ratio of power in the input signal at frequency Fc to power at Fc + offset.
An FFT of the input waveform finds the power at those two frequencies.
Synopsis
double da_phase_noise(DARRAY input, double Fc, double offset)
Arguments
input Input variable containing the input waveform.
IMAGE Solutions V8.3 27-69
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
The input data array must have a length which is a power of 2
and contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
Fc The frequency of interest. Value must be between 0 and Fs/2.
offset The frequency offset where the phase noise would occur. Fc +
offset value must be between 0 and Fs/2.
Returns
Returns the ratio of the spectrum magnitudes at frequency Fc and Fc + offset.
See Also
“da_phase_noise_full”
da_phase_noise_full
Calculate the noise present in a sinusoid at a given frequency with additional parameter
sample frequency.
This function calculates the relative amount of noise present at a given frequency of a
sampled sinusoid. The input DARRAY contains a sine wave. Two important waveform
frequencies are the reference frequency Fc, and the phase noise frequency, Fc + offset.
You specify the values for Fc, offset, and sample frequency as parameters.
The calculation is a ratio of power in the input signal at frequency Fc to power at Fc + offset.
An FFT of the input waveform finds the power at those two frequencies.
Synopsis
double da_phase_noise_full(DARRAY input, double Fc, double offset, double Fs)
Arguments
input Input variable containing the input waveform.
The input data array must have a length which is a power of 2
and contain at least 8 elements. Data type must be DA_REAL or
DA_DREAL.
Fc The frequency of interest. Value must be between 0 and Fs/2.
offset The frequency offset where the phase noise would occur. Fc +
offset value must be between 0 and Fs/2.
double Fs Sample frequency. Value must be positive.
Returns
Returns the ratio of the spectrum magnitudes at frequency Fc and Fc + offset.
IMAGE Solutions V8.3 27-70
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
See Also
“da_phase_noise”
da_polar
Vector rectangular to polar.
This function returns a DARRAY handle to a data array whose elements are the polar
coordinate forms of the elements of the input DARRAY. The magnitude of the polar
coordinates are stored in the real part, and the angle of the polar coordinates are stored in
the imaginary part
out [ n ].real = hypot (in [ n ].real,in [ n ].imag)
(27–56)
out [ n ].imag = atan2 (in [ n ].imag,in [ n ].real)
where atan2 and hypot are the standard UNIX math library functions to compute arctangent
and hypotenuse.
The magnitude is always nonnegative, and the angle is in the range π to -π.
Synopsis
DARRAY da_polar(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data can
have any type. If the type is noncomplex, however, the
magnitude part of the output, stored in the real part, is set to the
input value, and the angle part, stored in the imaginary part, is
set to zero.
Returns
In normal operation, the output has the same length as the input and has the smallest type
compatible with the input type and with DA_CMPLX. That is, the output type is DA_DCMPLX if
the input type is DA_DREAL and is DA_CMPLX in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
NOTE
The input array must be of type COMPLEX.
NOTE
The input and output buffers must be different for this algorithm.
IMAGE Solutions V8.3 27-71
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_power_spectrum
Calculate a power spectrum using frequency domain sample data.
This function returns a handle to a data array which contains the power spectrum calculated
from the input sample data. The input data must be in the frequency domain. The output
data is a vector of real numbers.
The input must be complex data of type DA_CMPLX (single precision) or DA_DCMPLX (double
precision). The output data is DA_REAL or DA_DREAL depending on the value of type. Table
27-22 lists valid combinations with input data types.
See “Notes on Using Block Algorithms When Calculating FFTs and Spectra”.
Table 27-22. Output vector type vs. input type and requested type
Input data type
Requested
type
DA_INT DA_FRACT2 DA_REAL DA_DREAL DA_CMPLX DA_DCMPLX
DA_INT ERROR ERROR ERROR ERROR ERROR ERROR
DA_FRACT2 ERROR ERROR ERROR ERROR ERROR ERROR
DA_REAL ERROR ERROR ERROR ERROR DA_REAL ERROR
DA_DREAL ERROR ERROR ERROR ERROR DA_DREAL DA_DREAL
DA_CMPLX ERROR ERROR ERROR ERROR ERROR ERROR
DA_DCMPLX ERROR ERROR ERROR ERROR ERROR ERROR
Synopsis
DARRAY da_power_spectrum(DARRAY input, da_numeric_data_type type)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input sample data.
type Requested output vector type. See table 27-22 for valid
combinations with input data types.
Returns
A handle to a data array which contains the power spectrum.
See Also
“da_3rd_order_imd”, “da_set_number_samples”
IMAGE Solutions V8.3 27-72
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_print_darray
Prints the contents of a data array. Used mainly for debugging the DARRAY system. Prints
the contents of a DARRAY.
Synopsis
da_print_darray(FILE *outfile, char *label, DARRAY d, int detail)
Arguments
*outfile A file pointer which represents where to write the data. A NULL
pointer is replaced with stdout.
*label A label to identify the DARRAY.
d The DARRAY to print.
detail Higher numbers provide more data. detail == 3 gives
essentially everything including the data.
Returns
The input parameter d.
Side Effects
None
da_pulse
Simulate the sampling of a continuous periodic pulse waveform.
This function creates a new DARRAY with a pulse train corresponding to the parameters you
specify. The DARRAY is allocated as it is in other signal generating functions (such as
da_cosine). The waveform consists of a periodic pulse train of frequency Ft with amplitude,
DC offset, and phase that you specify. The duty cycle parameter is the duration of time into
each period when the pulse transitions from low to high (low being at voltage offset, high
being at amplitude + offset). The wave transitions from high to low at the end of each period.
The phase is specified in radians. The sampling and test frequencies of the new DARRAY are
set by this algorithm.
Synopsis
DARRAY da_pulse(double Fs, da_size_t num_samples, double Ft, double amplitude,
double offset, double duty_cycle, double phase)
Arguments
Fs Sample frequency in the new DARRAY.
num_samples Number of samples in the new DARRAY.
Ft Frequency of the pulse waveform.
IMAGE Solutions V8.3 27-73
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
amplitude The peak-to-peak amplitude of the pulse.
offset The at-rest voltage of the pulse.
duty_cycle The fraction of time of the period that elapses before the high-low
transition happens at the end of each period. This value is
between 0.0 and 1.0, exclusive.
phase The phase angle of the pulse.
Returns
A newly allocated DARRAY containing the pulse waveform. In the case of a run-time error,
DA_NULL is returned without allocating a new DARRAY.
Side Effects
Allocates a new DARRAY.
da_ramp
Simulate the sampling of a continuous periodic ramp waveform.
This function generates and returns a ramp waveform with the parameters you specify. A
new DARRAY is allocated, with num_samples elements. The sampling and test frequencies
of the DARRAY are set. The periodic waveform begins each period at a voltage equal to the
offset parameter, and climbs (or falls) at the rate specified by the slope for the duration of
the period. After each period, there is a discontinuity from the peak of the ramp back to the
original offset. The frequency of the waveform is specified by Ft, and the sampling
frequency by Fs.
Synopsis
double da_ramp(double Fs, da_size_t num_samples, double Ft, double slope,
double offset, double phase)
Arguments
Fs Sample frequency of the array.
num_samples The size of the ramp waveform to generate.
Ft Frequency of the ramp waveform.
slope The slope of the ramp in volts/s.
offset The DC offset of the waveform.
phase The phase angle, in radians.
Returns
A newly allocated DARRAY containing the ramp waveform. In the case of a run-time error,
DA_NULL is returned without allocating a new DARRAY.
IMAGE Solutions V8.3 27-74
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Side Effects
Allocates a new DARRAY.
da_ramp_dnl
Calculate the differential nonlinearity of a ramp waveform.
This function calculates differential nonlinearity of converter devices. The input used to drive
the device is a ramp waveform. The reference histogram is a flat line, with value N/M, for N
output samples and M codes.
Synopsis
double da_ramp_dnl(DARRAY input, double full_scale, int num_bits)
Arguments
input Input variable containing the input waveform.
The input data array must contain at least 8 elements. Data type
must be DA_REAL or DA_DREAL.
full_scale The full-scale voltage of the converter device. The range must to
be from 0V to full-scaleV. Value must be a positive voltage.
num_bits The number of bits of the converter device. Value must be a
positive integer.
Returns
The differential nonlinearity of the input waveform in least significant bits. Returns
TL_DA_ERROR in the case of a run-time error.
See Also
“da_ramp_dnl_and_inl”
da_ramp_dnl_and_inl
Calculate the differential and integral nonlinearity of a ramp waveform.
This function calculates differential and integral nonlinearity of converter devices. The input
used to drive the device is a ramp waveform. The reference histogram is a flat line, with
value N/M, for N output samples and M codes. Calling the compound function is more
efficient than calling the two simple functions in sequence.
Synopsis
void da_ramp_dnl_and_inl(DARRAY input, double full_scale, int num_bits,
double *dnl, double *inl)
IMAGE Solutions V8.3 27-75
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
input Input variable containing the input waveform.
The input data array must contain at least 8 elements. Data type
must be DA_REAL or DA_DREAL.
full_scale The full-scale voltage of the converter device. The range must be
from 0V to full-scaleV. Value must be a positive voltage.
num_bits The number of bits of the converter device. Value must be a
positive integer.
*dnl A pointer which represents where to write the dnl. Value must
not be zero.
*inl A pointer which represents where to write the inl. Value must
not be zero.
Side Effects
Writes to the pointers dnl and inl.
See Also
“da_ramp_dnl”, “da_ramp_inl”
da_ramp_inl
Calculate the integral nonlinearity of a ramp waveform.
This function calculates integral nonlinearity of converter devices. The input used to drive
the device is a ramp waveform. The reference histogram is a flat line, with value N/M, for N
output samples and M codes.
Synopsis
double da_ramp_inl(DARRAY input, double full_scale, int num_bits)
Arguments
input Input variable containing the input waveform.
The input data array must contain at least 8 elements. Data type
must be DA_REAL or DA_DREAL.
full_scale The full-scale voltage of the converter device. The range must to
be from 0V to full-scaleV. Value must be a positive voltage.
num_bits The number of bits of the converter device. Value must be a
positive integer.
IMAGE Solutions V8.3 27-76
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
The integral nonlinearity of the input waveform in least significant bits. Returns
TL_DA_ERROR in the case of a run-time error.
See Also
“da_ramp_dnl_and_inl”
da_real_to_frac
Vector real to frac2.
The result of this function is a DARRAY handle whose data is the element-wise application to
the input data of the function which converts single precision floating point data to
DA_FRACT2 data. If real_to_fract2(t) is the result of converting the single precision number t
to type DA_FRACT2, then
out [ n ] = real_to_fract2 ( in [ n ] ) (27–57)
for each index n.
Synopsis
DARRAY da_real_to_frac(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must
have type DA_REAL.
Returns
In normal operation, the output DARRAY will have the same length as the input DARRAY. It will
have type DA_FRACT2.
Zero is returned in the case of a run-time error which is ignored or continued.
da_rect
Vector polar to rectangular.
The result of this function is a DARRAY whose elements are the rectangular coordinate form
of the input data, interpreting the input data as complex numbers in polar coordinates as for
da_polar:
out [ n ].real = in [ n ].real × cos ( in [ n ].imag )
(27–58)
out [ n ].imag = in [ n ].real × sin ( in [ n ].imag )
IMAGE Solutions V8.3 27-77
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_rect(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data can be
any type. If data is a noncomplex type, the magnitude is the input
value and the angle is 0.0.
Returns
In normal operation the output DARRAY has the same length as the input DARRAY. It has the
smallest type compatible with the type of the input DARRAY and also with DA_CMPLX. If the
input data array has type DA_DREAL or DA_DCMPLX the output DARRAY will have type
DA_DCMPLX. The output DARRAY will have type DA_CMPLX in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
NOTE
The input array must be of type COMPLEX.
NOTE
The input and output buffers must be different for this algorithm.
da_rfftsc
In-place FFT scale and format.
This function does not return a value. Instead, it replaces the input data array data by a
scaled and formatted version. This function can perform two different, independent data
manipulations:
• The raw FFT algorithm leaves the frequency domain data larger than it would normally
be by a factor of the length of the (real) time domain data. For example, if 1024 points
of the function cos(2*π*t) are sampled, the expected coefficient in bins 1 and -1 would
be 1/2. However, the FFT function returns 512 in bin 1 and does not return bin -1. The
scaling function corrects this by dividing the size of the time-domain data by half. Also,
when performing a time-domain convolution by a frequency-domain multiplication, a
scale factor of twice the input length is used. The scaling function can provide this as
well.
• When the FFT function operates on a length N real vector, the result is nominally a
length N/2+1 vector of complex numbers. For real input, the output is (almost) half the
length, since the Fourier transform is conjugate symmetric, and the coefficients for the
negative frequencies can be determined from those of the positive frequencies. These
are in the N/2 frequency bins 0 through N/2-1. The extra Fourier coefficient is the
IMAGE Solutions V8.3 27-78
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
coefficient at the Nyquist frequency. This is always purely real. The formatting
parameter chooses one of three operations:
– Reduce the N/2+1 length vector to one of length N/2 by packing the real part of the
spectrum at Nyquist into the imaginary part of bin 0. This is guaranteed to be zero.
– Unpack the output by putting the imaginary value of bin 0 into a new element at bin
N/2, whose real value is the originally imaginary value at 0 and whose imaginary
value is 0.0. This requires adding to the existing storage, so some data may be
allocated for this operation.
– Reduce the spectrum vector to size N/2 by ignoring the value at Nyquist. In most
normal operation, this is what is wanted, since the input signal will be band-limited,
and there will be little or no signal energy at the Nyquist frequency.
The description of the effect of the scale and format parameters below depends on the
following definitions: in[-] is the data array element value before the execution of the
function, out[-] is the data array element value after the execution of the function, and N is
the length of the input data array after the execution of the function.
• scale parameter
This is the scale flag. It determines a scaling factor sf used by the format flag. Possible
values are -1 to +1. The meanings of these values are
1: sf == 1/(2*N)
0: sf == 1.0 - No scaling is done.
-1: sf == 1/(4*e) - This value is used in the correlation function.
• format parameter
This is the formatting flag. Possible values are -3 to +3. The value of the scaling flag is
set to the scaling factor sf (see above). The basic scheme is:
– A format parameter value of -1, 0, or 1 does no special formatting at all.
– A format parameter value of 2 or -2 unpacks from or packs into N/2 elements.
– A format parameter value of 3 or -3 unpacks from or packs into N/2+1 elements.
– Positive format parameters unpack.
– Negative format parameters pack.
For each value of sf, the output data array is defined as follows:
• 1,0,-1:
out [ 0 ] = sf × in [ 0 ]
(27–59)
out [ N ] = sf × in [ N ]
• 2: This is case b, above.
out [ 0 ].real = sf × in [ 0 ] .real
out [ 0 ].image = 0.0 (27–60)
out [ N ] is undefined
IMAGE Solutions V8.3 27-79
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
• 3: This is case a, above.
out [ 0 ].real = sf × in [ 0 ].real
out [ 0 ].imag = 0.0
(27–61)
out [ N ].real = sf × in [ 0 ] .imag
out [ N ].imag = 0.0
• -2: This is also case b, above.
out [ 0 ].real = sf × in [ 0 ] .real
out [ 0 ].imag = 0.0 (27–62)
out [ N ] is undefined
• -3: This is case c, above.
out [ 0 ].real = sf × in [ 0 ] .real
out [ 0 ].imag = sf × in [ N ].real (27–63)
out [ N ] is undefined
Synopsis
da_rfftsc(DARRAY h_in, int format, int scale)
Arguments
h_in The input data array may have any length. Data must be a
complex type.
format See description above. This parameter can have any integer
between -3 and 3 inclusive. The symbolic names for the values
of this parameter are:
3: DA_RFFTSC_UNPACKED_LARGE
2: DA_RFFTSC_UNPACKED_SMALL
1,0,-1: DA_RFFTSC_NOCHANGE
-2: DA_RFFTSC_PACKED_SMALL
-3: DA_RFFTSC_PACKED_LARGE
scale See description above. This parameter can have any integer
value between -1 and 2 inclusive. The named constants for
these values are:
2: DA_RFFTSC_SCALE_BY_N
1: DA_RFFTSC_SCALE_BY_2XN
0: DA_RFFTSC_NOSCALE
-1: DA_RFFTSC_SCALE_BY_4XN
IMAGE Solutions V8.3 27-80
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Side Effects
The input data array is overwritten. Data type and size can also be changed, depending on
the format flag used.
da_rmmul
Vector matrix multiply.
The DARRAY handle input parameters to this function are vectors which represent a matrix.
The result is a DARRAY handle whose data represent the product of the two input
parameters. For the single-index output vector and the input vectors as matrices, with two
indices
out [r ,c ] = out [ r × cols1rows2 + c ]
in1 [r ,c ] = in1 [ r × cols1row2 + c ] (27–64)
in2 [r ,c ] = in2 [ r + c × cols1rows2 ]
then
out [r ,c ] = in1 [r ,0 ] × in2 [0 ,c ] + ... + in1 [r ,( cols1rows2-1 ) ] × in2 [( cols1rows2-1 ) ,c ] (27–65)
for r = 0, ..., (rows1-1) and c = 0, ..., (cols2-1).
Synopsis
DARRAY da_rmmul(DARRAY h_in1, DARRAY h_in2, int rows13, int cols23,
int cols1rows2)
Arguments
h_in1 DARRAY parameters can have any type. The size of input
parameter h_in1 must be no less than rows13*cols1rows2.
h_in2 DARRAY parameters can have any type. The size of input
parameter h_in2 must be no less than cols23*cols1rows2.
rows13 Number of rows in h_in1.
cols23 Number of columns in h_in2.
cols1rows2 Number of columns in h_in1 and rows in h_in2.
Returns
In normal operation, the return value is a DARRAY handle. Its type is the smallest type
compatible with the types of the input vectors. Its length is rows13*cols23 exactly.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-81
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_rms
Calculate rms voltage of the sample data.
Compute the square root of the average value (mean) of the squares of the elements of a
data array. For a data array with n elements
n
2
∑ xi
rms = i=1 -
--------------- (27–66)
n
Synopsis
double da_rms(DARRAY input)
Arguments
input The input value. The name of variable of type DARRAY which is
the name of the data array containing the input sample data.
Returns
The rms value of the elements of the data array.
da_rmsqv
RMS computation.
The result of this function is the square root of the mean of the squares of the elements in
the input vector
N–1
( in [ n ] ) 2
output = n ∑ --------------------
N
(27–67)
n=0
where in[n] in the nth element, and N is the size of the vector.
Synopsis
double da_rmsqv(DARRAY h_in)
Arguments
h_in The input vector can have any length. Data must be a
noncomplex type.
Returns
A floating point number whose type is double precision.
IMAGE Solutions V8.3 27-82
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Zero is returned in the case of a run-time error which is ignored or continued.
da_rmtran
Vector matrix transpose.
The DARRAY handle input parameter to this function is a vector which represents a matrix.
The result is a DARRAY handle whose data represent the matrix transpose of a submatrix of
the input matrix. The submatrix is anchored in the upper left corner of the source matrix
(element 0,0).
For the single-index output vector and the input vectors as two-dimensional matrices, with
two indices
in [r ,c ] = in [ r × full_input_columns + c ]
(27–68)
out [r ,c ] = out [ r × full_output_columns + c ]
then
out [r ,c ] = in [c ,r ] (27–69)
for values of r between 0 and submatrix_input_rows and values of c between 0 and
submatrix_input_columns.
Synopsis
DARRAY da_rmtran(DARRAY h_in, int full_input_rows, int full_input_columns,
int submatrix_input_rows, int submatrix_input_columns)
Arguments
h_in The DARRAY parameter can have any type. The DARRAY
parameter must have size greater than
full_input_columns*submatrix_input_rows.
full_input_rows Number of rows in h_in
full_input_columns Number of columns in h_in
submatrix_input_rows
Number of rows in the submatrix you want to transform.
submatrix_input_columns
Number of columns in the submatrix you want to transform.
Returns
In normal operation, the return value is a DARRAY handle. Its type is the smallest type
compatible with the types of the input vectors. Its length is exactly full_input_columns ×
submatrix_input_rows.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-83
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_set_Fs
Locates the data array referenced by the parameter handle and sets the value of the
sampling frequency.
Synopsis
void da_set_Fs(DARRAY handle, double new_Fs)
Arguments
handle A handle for a data array or the data array name (type DARRAY).
An unsigned integer.
new_Fs Value of new sampling frequency.
da_set_Ft
Locates the data array referenced by handle and sets the value of the fundamental or “test”
frequency.
Synopsis
void da_set_Ft(DARRAY handle, double new_Ft)
Arguments
handle A handle for a data array or the data array name (type DARRAY).
An unsigned integer.
new_Ft Value of new test frequency.
da_set_lifetime
Locates the data array referenced by handle and changes its lifetime by removing it from
one queue and inserting it in another. The data array memory manager structure lock is
used to protect the queues.
Synopsis
void da_set_lifetime(DARRAY *handle,DA_DATA_LIFETIME lifetime)
Arguments
handle Address of the data array handle number.
lifetime How long the data array will persist, one of:
DA_TESTF - Until the end of the TESTF with the compute block
containing the computations using the data array
DA_RUN - Until the test program run is completed
DA_JOB - Until the test program is unloaded
IMAGE Solutions V8.3 27-84
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_set_number_samples
Changes the logical number of samples of the data array. It is used primarily to compensate
for the fact that da_FFT followed by da_power_spectrum reduces the number of real
samples by half (from real plus imaginary samples into complex samples). When the data
array containing the transformed data is copied, the number of samples in the data array is
cut in half. You can use da_set_number_samples to set the correct number of samples.
Synopsis
void da_set_number_samples(DARRAY handle, int number_samples)
Arguments
handle Data array handle
number_samples New number of samples for handle
Side Effects
Modifies handle to reflect the new number of samples.
See Also
“da_fft”, “da_fftb”, “da_power_spectrum”
da_sfdr
Calculate the spurious free dynamic range of the sample data.
This function calculates the spurious free dynamic range of a sampled signal. This is the
ratio of the signal power to the power of the largest harmonic. The fundamental frequency
and sampling frequency are taken from the input data array. The number of harmonics to
consider is the default value (5). The input can be either a spectrum or a power spectrum.
Synopsis
double da_sfdr(DARRAY input)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input sample data.
Returns
The value of the ratio of the signal power to the maximum distortion power.
In the case of errors, or if the maximum noise power is numerically less than the machine
epsilon, the largest double precision floating point value DBL_MAX is returned.
If there are fewer than the specified number of harmonics before the Fs/2 frequency,
da_sfdr considers only those harmonics that occur before Fs/2. However, if the sample is
IMAGE Solutions V8.3 27-85
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
not band-limited to Fs/2, images of noise and harmonics may interfere with the correct
calculation of the range.
See Also
“da_sfdr_full”
da_sfdr_full
Calculate the spurious free dynamic range of the sample data, with input parameters:
number of harmonics, fundamental frequency, and sample frequency.
This function calculates the spurious free dynamic range of a sampled signal. This is the
ratio of the signal power to the power of the largest harmonic. The fundamental frequency
and sampling frequency are taken from the input DARRAY. The input can be either a
spectrum or a power spectrum.
Synopsis
double da_sfdr_full(DARRAY input, da_size_t number_harmonics, double f_i,
double f_s)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input sample data.
number_harmonics Number of harmonics to consider when looking for the largest
amplitude or power.
f_i Frequency of interest. The fundamental frequency of the input
signal.
f_s Sample rate of the sample data.
Returns
The value of the ratio of the signal power to the maximum distortion power.
In the case of errors, or if the maximum noise power is numerically less than the machine
epsilon, the largest double precision floating point value DBL_MAX is returned.
If there are fewer than the specified number of harmonics before the Fs/2 frequency,
da_sfdr_full considers only those harmonics that occur before Fs/2. However, if the
sample is not band-limited to Fs/2, images of noise and harmonics may interfere with the
correct calculation of the range.
See Also
“da_sfdr”
IMAGE Solutions V8.3 27-86
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_sine_dnl
Calculate the differential nonlinearity of a sine waveform.
This function calculates the differential nonlinearity of a converter device using a sine
waveform input. The device is driven by a sine wave, and the resulting output sine wave is
captured and passed into the function as the input DARRAY. The full-scale voltage of the
device and its number of bits are also specified as parameters.
To calculate differential nonlinearity, a histogram of the input waveform is plotted to count
the number of times each code of the device appears in the output. From this histogram, a
reference histogram is subtracted, one which a theoretical device of zero nonlinearity would
produce. (This reference histogram is deduced by looking at the number of zeros and the
number of maximal codes in the input waveform.) The resulting difference represents a
graph with output codes on the x-axis and difference in occurrence frequency on the y-axis.
The y-axis is scaled and normalized to be in units of least significant bits (1 LSB = voltage
width of one output code of the device). The entry in the scaled graph that has the maximum
magnitude is the differential nonlinearity of the device. Entries with positive sign mean the
code occurred more frequently than expected, negative signs mean less frequently.
Regardless of the sign of the nonlinearity, it is reported as a positive number of least
significant bits.
Synopsis
double da_sine_dnl(DARRAY input, double full_scale, int num_bits)
Arguments
input Input variable containing the input sine wave.
The input data array must contain at least 8 elements. Data type
must be DA_REAL or DA_DREAL.
full_scale The full-scale voltage of the converter device. The range must to
be from 0V to full-scaleV. Value must be a positive voltage.
num_bits The number of bits of the converter device. Value must be a
positive integer.
Returns
The differential nonlinearity of the input waveform in least significant bits. Returns zero in
the case of a run-time error.
See Also
“da_sine_dnl_and_inl”
da_sine_dnl_and_inl
Calculate the differential and integral nonlinearity of a sine waveform.
IMAGE Solutions V8.3 27-87
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
This function calculates the differential and integral nonlinearity of a converter device using
a sine waveform input. The device is driven by a sine wave, and the resulting output sine
wave is captured and passed into the function as the input DARRAY. The full-scale voltage of
the device and its number of bits are also specified as parameters.
Calling the compound function is more efficient than calling the two simple functions in
sequence.
To calculate differential nonlinearity, a histogram of the input waveform is plotted to count
the number of times each code of the device appears in the output. From this histogram, a
reference histogram is subtracted, one which a theoretical device of zero nonlinearity would
produce. (This reference histogram is deduced by looking at the number of zeros and the
number of maximal codes in the input waveform.) The resulting difference represents a
graph with output codes on the x-axis and difference in occurrence frequency on the y-axis.
The y-axis is scaled and normalized to be in units of least significant bits (1 LSB = voltage
width of one output code of the device). The entry in the scaled graph that has the maximum
magnitude is the differential nonlinearity of the device. Entries with positive sign mean the
code occurred more frequently than expected, negative signs mean less frequently.
Regardless of the sign of the nonlinearity, it is reported as a positive number of least
significant bits.
Integral nonlinearity is related to differential nonlinearity. To calculate integral nonlinearity,
you start with the differential nonlinearity graph and construct a second graph by keeping a
running-sum total of the entries in the first. In effect, the second is the integral of the first.
The maximum magnitude of the integral graph is the integral nonlinearity. It is returned in
positive least significant bits.
Synopsis
void da_sine_dnl_and_inl(DARRAY input, double full_scale, int num_bits,
double *dnl, double *inl)
Arguments
input Input variable containing the input waveform.
The input data array must contain at least 8 elements. Data type
must be DA_REAL or DA_DREAL.
full_scale The full-scale voltage of the converter device. The range must be
from 0V to full-scaleV. Value must be a positive voltage.
num_bits The number of bits of the converter device. Value must be a
positive integer.
*dnl A pointer which represents where to write the dnl. Value must
not be zero.
*inl A pointer which represents where to write the inl. Value must
not be zero.
IMAGE Solutions V8.3 27-88
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Side Effects
Writes to the pointers dnl and inl.
See Also
“da_sine_dnl”, “da_sine_inl”
da_sine_inl
Calculate the integral nonlinearity of a sine waveform.
This function calculates the integral nonlinearity of a converter device using a sine
waveform input. The device is driven by a sine wave, and the resulting output sine wave is
captured and passed into the function as the input DARRAY. The full-scale voltage of the
device and its number of bits are also specified as parameters.
Integral nonlinearity is related to differential nonlinearity. To calculate integral nonlinearity,
you start with the differential nonlinearity graph and construct a second graph by keeping a
running-sum total of the entries in the first. In effect, the second is the integral of the first.
The maximum magnitude of this integral graph is the integral nonlinearity. It is returned in
positive least significant bits.
Synopsis
double da_sine_inl(DARRAY input, double full_scale, int num_bits)
Arguments
input Input variable containing the input waveform.
The input data array must contain at least 8 elements. Data type
must be DA_REAL or DA_DREAL.
full_scale The full-scale voltage of the converter device. The range must be
from 0V to full-scaleV. Value must be a positive voltage.
num_bits The number of bits of the converter device. Value must be a
positive integer.
Returns
The integral nonlinearity of the waveform in least significant bits. Returns zero in the case
of a run-time error.
See Also
“da_sine_dnl_and_inl”
da_snr
Calculate the signal-to-noise ratio of the spectrum.
IMAGE Solutions V8.3 27-89
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
The input must be in the frequency domain. The test and sampling frequencies must be
known in the input data array. The noise is computed by summing the power of all
nonharmonic bins of the spectrum. The number of harmonics to consider is the default value
(5). The signal is the power in the test frequency bin. The output is a double precision
number (DA_DREAL).
Synopsis
double da_snr(DARRAY input)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input spectrum data.
Returns
The signal-to-noise ratio.
In the case of error, the largest double precision value DBL_MAX is returned.
If there are fewer than the specified number of harmonics before the Fs/2 frequency,
da_snr_full includes only those harmonics that occur before Fs/2. However, if the sample
is not band-limited to Fs/2, images of noise and harmonics may interfere with the correct
calculation of the ratio.
See Also
“da_snr_full”
da_snr_full
Calculate the signal-to-noise ratio of the spectrum, with input parameters: test frequency,
sample frequency, and number of harmonics.
The input must be in the frequency domain. The test and sampling frequencies must be
specified as input parameters. The noise is computed by summing the power of all
nonharmonic bins of the spectrum. The number of harmonics to consider is specified by the
parameter number_harmonics. The signal is the power in the test frequency bin. The output
is a double precision number (DA_DREAL).
Synopsis
double da_snr_full(DARRAY input, da_size_t number_harmonics, double Ft,
double Fs)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input spectrum data.
number_harmonics Number of harmonics to exclude from noise power.
IMAGE Solutions V8.3 27-90
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Ft Test frequency. The fundamental frequency of the captured
signal.
Fs Sample frequency of the captured signal.
Returns
The signal-to-noise ratio.
In the case of error, the largest double precision value DBL_MAX is returned.
If there are fewer than the specified number of harmonics before the Fs/2 frequency,
da_snr_full includes only those harmonics that occur before Fs/2. However, if the sample is
not band-limited to Fs/2, images of noise and harmonics may interfere with the correct
calculation of the ratio.
See Also
“da_snr”
da_spdp
Vector float to double.
The result of this function is a data array whose data is the element-wise application to the
input data of the function which converts single precision floating point numbers to double
precision floating point numbers
out [ n ] = double ( in [ n ] ) (27–70)
for each index n.
Synopsis
DARRAY da_spdp(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
type DA_REAL.
Returns
In normal operation, the output DARRAY has the same length as the input DARRAY. Data type
is always DA_DREAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_sve
Sum of vector elements.
IMAGE Solutions V8.3 27-91
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
This function computes the sum of the elements of the input vector:
output = in1 [ 0 ] + in [ 1 ] + ... + in [ N – 1 ] (27–71)
where N is the length of the input vector.
Synopsis
double da_sve(DARRAY h_in)
Arguments
h_in The input data must be a noncomplex type.
Returns
The return value is always a double precision floating point number.
Zero is returned in the case of a run-time error which is ignored or continued.
da_svemg
Sum of element magnitudes.
This function computes the sum of the magnitudes of the elements of the input vector
output = in [ 0 ] + in [ 1 ] + ... + in [ N – 1 ] (27–72)
where N is the length of the input vector.
Synopsis
double da_svemg(DARRAY h_in)
Arguments
h_in The input data array can have any length. Data must be a
noncomplex type.
Returns
A double precision floating point number.
Zero is returned in the case of a run-time error which is ignored or continued.
da_svesq
Sum of element squares.
This function computes the sum of the squares of the elements of the input vector
IMAGE Solutions V8.3 27-92
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
output = ( in [ 0 ] ) 2 + ( in [ 1 ] ) 2 + ... + ( in [ N – 1 ] ) 2 (27–73)
where N is the length of the input vector.
Synopsis
double da_svesq(DARRAY h_in)
Arguments
h_in The input data array can have any length. Data must be a
noncomplex type.
Returns
A double precision floating point number.
Zero is returned in the case of a run-time error which is ignored or continued.
da_svessq
Sum of element signed squares.
This function computes the sum of the signed square function of element. The signed
squared function is the product of the element’s sign and its square. It can also be
expressed as the product of the element and its absolute value
output = in [ 0 ] × in [ 0 ] + in [ 1 ] × in [ 1 ] + ... + in [ N – 1 ] × in [ N – 1 ] (27–74)
where N is the length of the input vector.
Synopsis
double da_svessq(DARRAY h_in)
Arguments
h_in The input data must be a noncomplex type.
Returns
A double precision floating point number.
Zero is returned in the case of a run-time error which is ignored or continued.
da_thd
Calculate total harmonic distortion.
The total harmonic distortion is the ratio of the signal power to the sum of the power in the
first five harmonics. The test frequency and sampling frequencies are obtained from the
input data array. The input data array can be either a spectrum or a power spectrum.
IMAGE Solutions V8.3 27-93
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
double da_thd(DARRAY input)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input spectrum data.
Returns
The total harmonic distortion, expressed as a ratio.
In the case of errors, or if the distortion is less than the machine epsilon, the largest double
precision floating point value DBL_MAX is returned. If there are fewer than five harmonics
before the Fs/2 frequency, da_thd includes only those harmonics that occur before Fs/2.
However, if the sample is not band-limited to Fs/2, images of noise and harmonics may
interfere with the correct calculation of the distortion.
See Also
“da_thd_full”, “da_phase_full”
da_thd_full
Calculate total harmonic distortion, with input parameters: test frequency, sample
frequency, and number of harmonics.
The total harmonic distortion is the ratio of the signal power to the sum of the power in the
harmonics specified by the parameter number_harmonics. The test frequency and
sampling frequencies are specified as input parameters. The input DARRAY can be either a
spectrum or a power spectrum.
Synopsis
double da_thd_full(DARRAY input, da_size_t number_harmonics, double Ft,
double Fs)
Arguments
input Input variable. The name of the variable of type DARRAY which
contains the input spectrum data.
number_harmonics Number of harmonics to include in distortion power.
Ft The fundamental frequency of the signal spectrum.
Fs The sample frequency of the sample data.
Returns
The total harmonic distortion, expressed as a ratio.
IMAGE Solutions V8.3 27-94
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
In the case of errors, or if the distortion is less than the machine epsilon, the largest double
precision floating point value DBL_MAX is returned. If there are fewer than the specified
number of harmonics before the Fs/2 frequency, da_thd_full includes only those
harmonics that occur before Fs/2. However, if the sample is not band-limited to Fs/2,
images of noise and harmonics may interfere with the correct calculation of the distortion.
See Also
“da_thd”
da_triangle
Simulate the sampling of a periodic triangle waveform.
This function creates a new DARRAY with a triangle waveform corresponding to the given
parameters. This function is similar to da_cosine. Specifically, a triangle waveform of
period 2*π would have value 1 at t = 0, value 0 at t = π / 2, value -1 at t = π, value 0 at t =
3*π / 2, and value 1 at t = 2*π, exactly like a cosine wave. However, these points would be
connected with straight lines, rather than the curve of the cosine.
The algorithm generates the triangle waveform information and fills a newly allocated
DARRAY with the data for the current site. It also sets the sample and test frequency in the
internal structure of the DARRAY.
Synopsis
DARRAY da_triangle(double Fs, da_size_t num_samples, double Ft,
double amplitude, double offset, double phase)
Arguments
Fs Sample frequency in the new DARRAY.
num_samples The number of samples in the new DARRAY.
Ft Frequency of the triangle waveform.
amplitude The peak-to-peak amplitude of the triangle waveform.
offset Offset of the triangle waveform.
phase Phase angle (in radians) of the triangle waveform.
Returns
A newly allocated DARRAY containing the output waveform. In the case of a run-time error,
DA_NULL is returned without allocating a new DARRAY.
Side Effects
Allocates a new DARRAY.
IMAGE Solutions V8.3 27-95
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_triangular_window
Triangular window function.
This name denotes the triangular window function. It is not a callable function. It is only used
as a parameter to da_complex_spectrum. The triangular window is defined by
if (i < N/2) then
data[i] *= 2*(i/N)
else
data[i] *= 2*((N-i)/N
where N is the size of the data vector.
Synopsis
da_window_function da_triangular_window
See Also
“da_3rd_order_imd”
da_vabs
Vector absolute value.
This function returns the handle of a DARRAY whose elements are the element-wise
application of the absolute value function to the input vector
out [ n ] = in [ n ] (27–75)
for each index n, where |x| is the real absolute value of x.
This function is similar to da_cvmags, but it operates on noncomplex data only.
Synopsis
DARRAY da_vabs(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
Returns
In normal operation, the output is a DARRAY handle whose type is the smallest type
compatible with the input DARRAY type and DA_REAL. That is, the output type is DA_DREAL if
one the input parameter is DA_DREAL and DA_REAL otherwise. Its length is the length of the
input vector.
IMAGE Solutions V8.3 27-96
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Zero is returned in the case of a run-time error which is ignored or continued.
da_vadd
Vector add.
This function returns the handle of a data array whose elements are the element-wise
application of the arithmetic addition function to the input vector
out [ n ] = in1 [ n ] + in2 [ n ] (27–76)
for each index n.
Synopsis
DARRAY da_vadd(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The first input data array length equal the second data array
length. Data in each data array can be any type.
h_in2 The second input data array length equal the first data array
length. Data in each data array can be any type.
Returns
In normal operation, the output data type is the smallest type compatible with the two input
types and also with DA_REAL:
• DA_DCMPLX if one or more parameters are complex, and one or more parameters are
double precision
• DA_CMPLX if one or more parameters are complex, and no parameters are double
precision
• DA_DREAL if neither parameter is complex, and one or both parameters are double
precision
• DA_REAL if neither parameter is complex, and neither parameter is double precision.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vam
Vector add and multiply.
The result of this function is a data array containing elements defined by
out [ n ] = ( in1 [ n ] + in2 [ n ] ) × in3 [ n ] (27–77)
for each index n.
IMAGE Solutions V8.3 27-97
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_vam(DARRAY h_in1, DARRAY h_in2, DARRAY h_in3)
Arguments
h_in1 The first input data array must have a noncomplex type. All input
data arrays must all have the same length.
h_in2 The second input data array must have a noncomplex type. All
input data arrays must all have the same length.
h_in3 The third input data array must have a noncomplex type. All input
data arrays must all have the same length.
Returns
In normal operation, the output is a DARRAY handle which has the same length as the input
DARRAYs. The output type is the smallest type compatible with the types of both the input
DARRAYs and also with DA_REAL. The output type is DA_DREAL if either of the types of the
input DARRAYs are DA_DREAL and DA_REAL otherwise.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vandi
Bitwise logical AND.
This function returns the handle of a data array whose elements are the element-wise
application of the conjunction function to the input vector
out [ n ] = in_1 [ n ] & in_2 [ n ] (27–78)
for each index n.
The & operator computes the bitwise conjunction of its operands, as in C. For each bit
position p from 0 to 31, the value of out[n] at bit p is 1 exactly when the values of in_1[n] and
in_2[n] at bit p is 1, and 0 in all other cases.
Synopsis
DARRAY da_vandi(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The two input vectors h_in1 and h_in2 must have equal
lengths. Data must be type DA_INT.
h_in2 The two input vectors h_in1 and h_in2 must have equal
lengths. Data must be type DA_INT.
IMAGE Solutions V8.3 27-98
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
In normal operation, the output DARRAY type is DA_INT. Output data array length is equal to
the length of either input vector, both of which must be equal.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vatan
Vector arctangent.
This function returns a DARRAY whose data are the element-wise application of the
arctangent function to the input DARRAY’s data.
If atan(t) is the arctangent of t, then
out [ n ] = atan ( in [ n ] ) (27–79)
for each index n.
The da_vatan function returns values in the range -π/2 and π/2.
Synopsis
DARRAY da_vatan(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
Returns
In normal operation, the output data array will have the same length as the input. It will have
the smallest type compatible with the input data type and also DA_REAL. The output type is
DA_DREAL if the input is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
See Also
“da_vatan2”
da_vatan2
Vector arctangent of ratio.
This function returns a DARRAY handle whose data is the element-wise application of the
atan2 function to the two input vectors. The atan2 function takes two parameters, y and x in
this order, and computes the arctangent of y/x
IMAGE Solutions V8.3 27-99
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
out [ n ] = atan 2 (in1 [ n ],in2 [ n ])
(27–80)
= atan ( in1 [ n ] ) ⁄ ( in2 [ n ] )
If, for example, V is a vector of points in the plane, whose y coordinates are h_in1 and
whose x coordinates are h_in2, then da_vatan2(h_in1, h_in2) would be the angles
made between the x axis and the lines from the origin to the points.
The atan2 function returns the standard math library results, with values between -π and +π.
Synopsis
DARRAY da_vatan2(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The first input data array length must be greater than 0. The
length of h_in1 must equal the length of h_in2. Data must be a
noncomplex type.
h_in2 The second input data array length must be greater than 0. The
length of h_in1 must equal the length of h_in2. Data must be a
noncomplex type.
Returns
In normal operation, the output DARRAY length is that of the two input DARRAYs. The output
type is the smallest type compatible with the types of the two input DARRAYs and also with
DA_REAL. The output type is DA_DREAL if either of the two input DARRAYs have type DA_DREAL
and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vclip
Vector clip.
The result of this function is a data array handle whose data is the element-wise application
of the clipping function
out [ n ] = clip ( in [ n ] ) (27–81)
for each index n.
The clipping function is defined by
clip [ t ] = min if t < min
clip [ t ] = t if min ≤ t ≤ max (27–82)
clip [ t ] = max if t > max
IMAGE Solutions V8.3 27-100
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_vclip(DARRAY h_in, double min, double max)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
min The lower clip limit. Data point must be double precision floating
point.
max The upper clip limit. Data point must be double precision floating
point.
Returns
The output DARRAY has the same length as the input DARRAY. The output DARRAY type is the
smallest type compatible with both the input DARRAY type and also with DA_REAL.
da_vclr
Vector clear.
This function returns no value. It sets each element of the input data array to zero
in [ n ] = 0 (27–83)
for each index n.
Synopsis
da_vclr(DARRAY h_in)
Arguments
h_in The input data array can have any length. Data must be a
floating point type: DA_REAL or DA_DREAL.
Side Effects
The data in the input data array is modified.
da_vcopy
Copy and subsample.
The output data array is whose type is the same as the input vector, whose size is the
parameter output_size and whose elements are given by
output [ k ] = h_in [ offset + k × stride ] (27–84)
IMAGE Solutions V8.3 27-101
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
where k is the “stride factor” and output is the output vector.
Synopsis
DARRAY da_vcopy(DARRAY h_in, int offset, int stride, int output_size)
Arguments
The values of the offset, stride, and output_size parameters must satisfy the following
inequality:
offset + stride × ( output_size – 1 ) + 1 ≤ h_in (27–85)
where |h_in| is the length of h_in.
h_in The input data array length must be greater than 0. Data can be
any type.
offset See inequality above. offset is the index of the first element of
the input data array to be copied to the output data array. All
input elements before in[offset] are not copied. offset must
be an integer greater than 0.
stride See inequality above. stride is the sampling interval for
elements copied to the output data array. stride must be an
integer greater than 0.
output_size See inequality above. output_size is the length of the output
data array. output_size must be an integer greater than 0.
Returns
The return value has the given output size. It has the same type as the DARRAY input
parameter h_in.
da_vcos
Vector cosine.
This function returns a DARRAY handle whose data is the element-wise application of the
cosine function to the input data
out [ n ] = cos ( in [ n ] ) (27–86)
for all indices n.
The input values are in radians, so the cosine function is periodic with period 2.0 * π.
Synopsis
DARRAY da_vcos(DARRAY h_in)
IMAGE Solutions V8.3 27-102
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
Returns
In normal operation, the output DARRAY will have the same length as the input. It will have
the smallest type compatible with the input data type and also DA_REAL. The output type is
DA_DREAL if the input is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vdiv
Vector divide.
This function returns the handle of a DARRAY whose elements are the element-wise
application of the arithmetic division function to the input vectors
out [ n ] = in1 [ n ] ⁄ in2 [ n ] (27–87)
for each index n.
Synopsis
DARRAY da_vdiv(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The first input data array length must equal the length of the
second. Data must be a noncomplex type.
h_in2 The second input data array length must equal the length of the
first. Data must be a noncomplex type.
Returns
In normal operation, the output is a DARRAY handle whose type is the smallest type
compatible with both types of the input DARRAYs and with DA_REAL. The output type is
DA_DREAL if either of the input vectors have type DA_DREAL and DA_REAL in all other cases.
Its length is the length of the two input vectors.
Zero is returned in the case of a run-time error which is ignored or continued.
da_veqvi
Bitwise logical equality.
The operator equiv computes the bitwise equality of its operands. For each bit position p
from 0 to 31, the value of out[n] at bit p is 1 exactly when the values of in_1[n] and in_2[n]
at bit p are the same, and 0 if they are different
IMAGE Solutions V8.3 27-103
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
out [ n ] = ( in_1 [ n ] equiv in_2 [ n ] ) (27–88)
for each index n.
Synopsis
DARRAY da_veqvi(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The first input data array length must equal the length of the
second. Data must be type DA_INT.
h_in2 The second input data array length must equal the length of the
first. Data must be type DA_INT.
Returns
In normal operation, the output data type is always DA_INT. Its length is the length of the
input vector.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vexp
Vector natural exponent.
This function returns the handle of a data array whose elements are the element-wise
application of the real exponential function to the real input vector
out [ n ] = e in [ n ] (27–89)
for all indices n, where e is the base of the natural logarithms.
Synopsis
DARRAY da_vexp(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type. Each input element must have a value at
which the exponential is defined for the given type.
Returns
In normal operation, the output is a DARRAY handle which has the same length as the input
vector. Its type is the smallest type compatible with the type input of the input DARRAY, and
with DA_REAL. The output type is DA_DREAL if the type of the input DARRAY vector is
DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-104
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_vexp10
Vector base-10 exponent.
This function returns a DARRAY handle whose data is the application of the common antilog
function to each input element
out [ n ] = 10 in [ n ] (27–90)
for each index n.
Synopsis
DARRAY da_vexp10(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type. Each input element must have a value at
which the base 10 antilog is representable with the appropriate
numeric precision.
Returns
In normal operation, the return DARRAY will have the same length as the input DARRAY. The
type of the output will be the smallest type compatible with the input an with DA_REAL. The
output will be DA_DREAL if the input is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vfill
Vector fill.
This function does not return a value. It fills the input data array with the constant value given
by the parameter fill:
in [ n ] = fill (27–91)
for each index value n.
Synopsis
da_vfill(DARRAY h_in, double fill)
Arguments
h_in The input data array length must be greater than 0. Data must be
a floating point type: DA_REAL or DA_DREAL.
fill The constant value to be stored in each element of the data
array. Must be a double precision floating point number.
IMAGE Solutions V8.3 27-105
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_vfix
Vector real to integer.
The result of this function is a data array whose data is the element-wise application to the
input DARRAY data, of the function which converts single or double precision floating point
data to DA_INT.
Synopsis
DARRAY da_vfix(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex floating-point type: DA_REAL or DA_DREAL.
Returns
In normal operation, the output data array has the length of the input data array. Data will
be type DA_INT.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vfloat
Vector integer to float.
The result of this function is a DARRAY handle whose data is the element-wise application to
the input DARRAY data of the function which converts from integer to single precision floating
point
out [ n ] = float ( in [ n ] ) (27–92)
for all indices n.
Synopsis
DARRAY da_vfloat(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data type
must be DA_INT.
Returns
In normal operation, the output data type is always DA_REAL. Output data array length is the
length of the input data array.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-106
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_vfloatd
Vector integer to double.
The result of this function is a data array containing double precision floating point data
which was converted from integer input data
out [ n ] = double ( in [ n ] ) (27–93)
for all indices n.
Synopsis
DARRAY da_vfloatd(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must
have type DA_INT.
Returns
In normal operation, the output data type is DA_DREAL. Output data array length is the length
of the input data array.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vifix
Vector fix to integer.
The result of this function is a data array containing integer data which was converted from
single precision floating point input data
out [ n ] = int ( in [ n ] ) (27–94)
for all indices n. The data is truncated, not rounded.
Synopsis
DARRAY da_vifix(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
type DA_REAL.
Returns
In normal operation, the output data array has the same length as the input DARRAY. Output
data type is DA_INT.
IMAGE Solutions V8.3 27-107
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Zero is returned in the case of a run-time error which is ignored or continued.
da_vimag
Extract imaginary components.
The result of this function is a data array whose data is the element-wise application of the
imaginary part projection function to the input data
out [ n ] = in [ n ].imag (27–95)
for all indices n.
Synopsis
DARRAY da_vimag(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a complex type.
Returns
In normal operation, the output has the same length as the input DARRAY. The output type
is DA_DREAL if the input type is DA_DCMPLX and is DA_REAL if the input type is DA_CMPLX.
da_vlim
Vector limit.
The result of this function is a DARRAY handle whose data is the element wise application to
the input DARRAY’s data, of the limit function:
out [ n ] = limit ( in [ n ] ) (27–96)
for each index n, where
limit t = replacement if t ≥ threshold
(27–97)
= - replacement if t < threshold
Synopsis
DARRAY da_vlim(DARRAY h_in, double threshold, double replacement)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
IMAGE Solutions V8.3 27-108
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
threshold The value against which input data is compared. The value must
be a double precision floating point number.
replacement The value used to replace elements of the input data array based
on comparison to threshold. The value must be a double
precision floating point value.
Returns
In normal operation, the length of the output data array is the length of the input data array.
The type of the output data is the smallest type compatible with the type of the DARRAY input,
h_in, and also with DA_REAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vlog
Vector natural log.
This function results in a data array whose data is the application of the natural logarithm
function to each of the input vector’s elements
out [ n ] = ln ( in [ n ] ) (27–98)
for each index n.
Synopsis
DARRAY da_vlog(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
Returns
In normal operation, the output data array has the same length as the input data array. The
output type is the smallest type compatible with the input type and also with DA_REAL. The
output type is DA_DREAL if the input type is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vlog10
Vector base-10 log.
This function returns a DARRAY handle whose data is the element-wise application of the
common, or base-10 logarithm to the input vector. That is, if log(t) is the common logarithm
of t, then out[n] = log(in[n]) for each index n.
IMAGE Solutions V8.3 27-109
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_vlog10(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must
have a noncomplex type.
Returns
In normal operation, the output data array will have the same length as the input data array.
It will have the smallest type compatible with the input data type and also DA_REAL. The
output type is DA_DREAL if the input is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vma
Vector multiply and add.
The output is a DARRAY handle whose elements are defined by the rule
out [ n ] = ( in1 [ n ] × in2 [ n ] ) + in3 [ n ] (27–99)
for each index n.
Synopsis
DARRAY da_vma(DARRAY h_in1, DARRAY h_in2, DARRAY h_in3)
Arguments
h_in1 The input data arrays must all be the same length. Data must be
a noncomplex type.
h_in2 The input data arrays must all be the same length. Data must be
a noncomplex type.
h_in3 The input data arrays must all be the same length. Data must be
a noncomplex type.
Returns
In normal operation, the output is a handle for a data array which has the same length as
the input data arrays. The output type is the smallest type compatible with the types of all
three input data arrays and also with DA_REAL. The output type is DA_DREAL if any of the
input data array data is type DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-110
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_vmax
Vector maximum.
This function returns the handle of a data array whose elements are the element-wise
application of the maximum function to the input vectors
out [ n ] = max (in_1 [ n ],in_2 [ n ]) (27–100)
for each index n, where max(x,y) is the maximum function
max (x,y) = x if x > y
(27–101)
= y if x < y
Synopsis
DARRAY da_vmax(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data arrays must have the same length. Data must be
a noncomplex type.
h_in2 The input data arrays must have the same length. Data must be
a noncomplex type.
Returns
In normal operation, the output data type is the smallest type compatible with the input types
and DA_REAL. It is DA_DREAL if one of the input parameters is DA_DREAL and DA_REAL
otherwise. The output data array length is the length of the input data array.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vmaxmg
Vector maximum magnitude.
This function returns the handle of a data array whose elements are the element-wise
application of the maximum magnitude function to the input vector
out [ n ] = max ( in_1 [ n ] , in_2 [ n ] ) (27–102)
for each index n, where |x| is the absolute value of x, and max(x,y) is the maximum function
max (x,y) = x if x > y
(27–103)
= y if x < y
IMAGE Solutions V8.3 27-111
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_vmaxmg(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data arrays must have the same length. Data must be
a noncomplex type.
h_in2 The input data arrays must have the same length. Data must be
a noncomplex type.
Returns
In normal operation, the output data type is the smallest type compatible with the two input
types, and DA_REAL. It is DA_DREAL if one of the input parameters is DA_DREAL and DA_REAL
otherwise. Output data array length is the length of the input vector.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vmin
Vector minimum.
This function returns the handle of a data array whose elements are the element-wise
application of the minimum function to the input vector
out [ n ] = min (in_1 [ n ],in_2 [ n ]) (27–104)
for each index n, where min(x,y) is the minimum function
min (x,y) = y if x > y
(27–105)
= x if x < y
Synopsis
DARRAY da_vmin(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data arrays must have the same length. Data must be
a noncomplex type.
h_in2 The input data arrays must have the same length. Data must be
a noncomplex type.
Returns
In normal operation, the output data type is the smallest type compatible with the types of
the input data and with DA_REAL. It is DA_DREAL if one of the input parameters has type
DA_DREAL and DA_REAL otherwise. Output data array length is the length of the input data
array.
IMAGE Solutions V8.3 27-112
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Zero is returned in the case of a run-time error which is ignored or continued.
da_vminmg
Vector maximum magnitude.
This function returns the handle of a data array whose elements are the element-wise
application of the minimum magnitude function to the input vector
out [ n ] = min ( in_1 [ n ] , in_2 [ n ] ) (27–106)
for each index n, where |x| is the absolute value of x, or magnitude function and min(x,y) is
the minimum function
min (x,y) = y if x > y
(27–107)
= x if x < y
Synopsis
DARRAY da_vminmg(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data arrays must have the same length. Data must be
a noncomplex type.
h_in2 The input data arrays must have the same length. Data must be
a noncomplex type.
Returns
In normal operation, the output data type is the smallest type compatible with the input data
type and also with DA_REAL. The output type is DA_DREAL if one of the input parameters is
DA_DREAL and DA_REAL otherwise. Output data array length is the length of the input data
array.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vmsa
Vector multiply scalar add.
The result of this function is a data array whose elements are defined by
out [ n ] = ( in1 [ n ] × in2 [ n ] ) + scalar (27–108)
Synopsis
DARRAY da_vmsa(DARRAY h_in1, DARRAY h_in2, double scalar)
IMAGE Solutions V8.3 27-113
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
h_in1 The input data arrays must have the same length. Data must be
a noncomplex type.
h_in2 The input data arrays must have the same length. Data must be
a noncomplex type.
scalar A scalar value added to a vector product. The scalar input value
must be a double precision floating point number.
Returns
In normal operation, the output data array length is the same length as the input data arrays.
Output data type is the smallest type compatible with the types of the two data array inputs
and also with DA_REAL. The output type is DA_DREAL if either of the types of the input data
are DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vmsb
Vector multiply and subtract.
The output is a data array whose elements are defined by
out [ n ] = ( in1 [ n ] × in2 [ n ] ) – in3 [ n ] (27–109)
Synopsis
DARRAY da_vmsb(DARRAY h_in1, DARRAY h_in2, DARRAY h_in3)
Arguments
h_in1 The input data arrays must all have the same length. Data must
be a noncomplex type.
h_in2 The input data arrays must all have the same length. Data must
be a noncomplex type.
h_in3 The input data arrays must all have the same length. Data must
be a noncomplex type.
Returns
In normal operation, the output is a data array which has the same length as the input data
arrays. The output type is the smallest type compatible with all three input types and also
with DA_REAL. The output type is DA_DREAL if any of the data of the input data arrays is
DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-114
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_vmul
Vector multiply.
This function returns the handle of a DARRAY whose elements are the element-wise
application of the arithmetic multiplication function to the input vector
out [ n ] = in1 [ n ] × in2 [ n ] if option_flag = 1
(27–110)
out [ n ] = in1 [ n ] × complex_conjugate ( in2 [ n ] ) if option_flag ≠ 1
for each index n, where complex_conjugate(a+jb) denotes the complex conjugate, a-jb.
Synopsis
DARRAY da_vmul(DARRAY h_in1, DARRAY h_in2, int option_flag)
Arguments
h_in1 The input data arrays must have the same length. Data can be
any type.
h_in2 The input data arrays must have the same length. Data can be
any type.
option_flag Controls whether the computation uses the complex conjugate
of the elements of the second input data array. Value must be an
integer.
option_flag = 1 causes multiplication by in2[n].
option_flag = -1 causes multiplication by the complex
conjugate of in2[n].
Returns
In normal operation, the output value is a data array whose length is the length of the input
data arrays. Its type is the smallest type compatible with the types of the input parameters
and also with DA_REAL.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vneg
Vector negate.
This function returns the handle of a DARRAY whose elements are the element-wise
application of the arithmetic negation function to the input vector
out [ n ] = - in [ n ] (27–111)
for each index n.
IMAGE Solutions V8.3 27-115
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_vneg(DARRAY h_in)
Arguments
h_in The input vector can have any length. Data must be a
noncomplex type.
Returns
In normal operation, the output data type is the smallest type compatible with both the type
of the input data and DA_REAL. The output type is DA_DREAL if one of the input parameters
is DA_DREAL and DA_REAL otherwise. Output data array length is the length of the input data
array.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vori
Bitwise logical OR.
This function returns the handle of a data array whose elements are the element-wise
application of the disjunction function to the input vector
out [ n ] = in_1 [ n ] | in_2 [ n ] (27–112)
for each index n.
The operator “|” computes the bitwise disjunction of its operands, as in C. For each bit
position p from 0 to 31, the value of out[n] at bit p is 0 exactly when the values of in_1[n] and
in_2[n] at bit p is 0, and 1 in all other cases.
Synopsis
DARRAY da_vori(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data arrays must have the same lengths. Data must be
type DA_INT.
h_in2 The input data arrays must have the same lengths. Data must be
type DA_INT.
Returns
In normal operation, the output data type is DA_INT. Output data array length is the length
of the input data array.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-116
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_vpoly
Vector polynomial.
The result of this function is a data array whose data is the result of evaluating a polynomial
whose coefficients are given by the first data array, at the points given by the second data
array
out [ n ] = in1 [ 0 ]
+ in1 [ 1 ] × in2 [ n ]
+ in1 [ 2 ] × in2 [ n ] 2
(27–113)
+ ...
+ in1 [ order – 1 ] × in2 [ n ] ( order – 1 )
+ in1 [ 1 ] × in2 [ n ]
Synopsis
DARRAY da_vpoly(DARRAY h_in1, DARRAY h_in2, int order)
Arguments
h_in1 Coefficients of the polynomial. The input data array length must
be greater than 0. Data must be a noncomplex type.
h_in2 Points at which the polynomial is evaluated. The input data array
length must be greater than 0. Data must be a noncomplex type.
order Order of the polynomial being evaluated. Value must be an
integer.
Returns
In normal operation, the length of the output data array is the length of the second input data
array. The type of the output data is the smallest type compatible with the types of the two
input data arrays and also with DA_REAL. The output type is DA_DREAL if either of input data
array has data of type DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vramp
Vector ramp.
The result of this function is a data array containing elements with values that increase (or
decrease) linearly from the initial value to the final value determined by parameters
initial, increment, and size:
out [ n ] = initial + n × increment (27–114)
for indices between 0 and size -1.
IMAGE Solutions V8.3 27-117
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Synopsis
DARRAY da_vramp(double initial, double increment, int size)
Arguments
initial The initial value of the ramp. Value must be a double precision
floating point number.
increment The increment between values of the ramp. Value must be a
double precision floating point number.
size The number of elements or length of the data array containing
the ramp. Value must be an integer.
Returns
The return value’s length is the given size. Output data type is DA_DREAL.
da_vreal
Extract real components.
This function returns a data array containing data generated by the element-wise
application of the real part projection function to the input data
out [ n ] = in [ n ].real (27–115)
for each index n.
Synopsis
DARRAY da_vreal(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a complex type.
Returns
In normal operation, the output data array has the same length as the input data array. The
output data is type is DA_DREAL if the input type is DA_DCMPLX and is DA_REAL if the input
type is DA_CMPLX.
da_vrvrs
In-place reverse order.
This function does not return a value. It reverses the order of the data elements in the input
data array
IMAGE Solutions V8.3 27-118
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
out [ n ] = in [ h_in – 1 – n ] (27–116)
for each index n, where |h_in| is the length of the input data array.
Synopsis
da_vrvrs(DARRAY h_in)
Arguments
h_in The input data array can have any length. Data must be a
floating point type: DA_REAL or DA_DREAL. This type and length
are not changed.
Side Effects
The input vector is modified.
da_vsadd
Scalar add.
The result of this function is a data array whose data elements are the result of adding the
specified scalar to each of the elements of the input vector
out [ n ] = scalar + in [ n ] (27–117)
for each index n.
Synopsis
DARRAY da_vsadd(DARRAY h_in, double scalar)
Arguments
h_in The input data array can have any length. Data must be a
noncomplex type.
scalar The scalar value added to each element of the array. The scalar
value must be a double precision floating point number.
Returns
In normal operation, the return value is a data array whose length is the length of the input
data array. Output data type is the smallest type compatible with the types of the input
parameters and with DA_REAL. It is DA_DREAL if the input data is type DA_DREAL and DA_REAL
in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-119
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_vsbm
Vector subtract and multiply.
The result of this function is a data array whose elements are defined by the rule
out [ n ] = ( in1 [ n ] – in2 [ n ] ) × in3 [ n ] (27–118)
for each index n.
Synopsis
DARRAY da_vsbm(DARRAY h_in1, DARRAY h_in2, DARRAY h_in3)
Arguments
h_in1 The input data arrays must all have the same length. Data must
be a noncomplex type.
h_in2 The input data arrays must all have the same length. Data must
be a noncomplex type.
h_in3 The input data arrays must all have the same length. Data must
be a noncomplex type.
Returns
In normal operation, the output is a data array which has the same length as the input data
arrays. The data type is the smallest type compatible with the types of the three input data
arrays and also with DA_REAL. The output type is DA_DREAL if any of the types of the input
data are DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vsdiv
Scalar divide.
The result of this function is a data array whose data elements are the result of dividing each
of the elements of the input vector by the specified scalar
out [ n ] = in [ n ] ⁄ scalar (27–119)
for each index n.
Synopsis
DARRAY da_vsdiv(DARRAY h_in, double scalar)
IMAGE Solutions V8.3 27-120
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
h_in The input data array can have any length. Data must be a
noncomplex type.
scalar The specified divisor of each element of the data array. The
value must be a double precision floating point number.
Returns
In normal operation, the return value is a handle for a data array whose length is the length
of the input data array. Output data type is the smallest type compatible with the input data
array and DA_REAL. The output type is DA_DREAL if the input data has type DA_DREAL and
DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vsin
Vector sine.
This function returns a data array whose data is the element-wise application of the sine
function to the input data
out [ n ] = sin ( in [ n ] ) (27–120)
for each index n.
The input values are in radians. The sine function is periodic with period 2.0 × π.
Synopsis
DARRAY da_vsin(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
Returns
In normal operation, the output data array will have the same length as the input data array.
Output data will have the smallest type compatible with the input data type and DA_REAL.
The output type is DA_DREAL if the input is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vsma
Vector scalar multiply and vector add.
The result of this function is a data array whose elements are defined by the rule
IMAGE Solutions V8.3 27-121
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
out [ n ] = ( in1 [ n ] × scalar ) + in2 [ n ] (27–121)
for each index n.
Synopsis
DARRAY da_vsma(DARRAY h_in1, double scalar, DARRAY h_in2)
Arguments
h_in1 The input data arrays must have the same lengths. Data must be
a noncomplex type.
scalar The specified multiplier for each element of the input data array.
The value must be a double precision floating point number.
h_in2 The input data arrays must have the same lengths. Data must be
a noncomplex type.
Returns
In normal operation, the output is a data array which has the same length as the input data
arrays. Output data type is the smallest type compatible with the two inputs and DA_REAL.
The output type is DA_DREAL if either of the types of the input data arrays are DA_DREAL and
is DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vsmsa
Scalar multiply scalar add.
The result of this function is a data array whose elements are defined by
out [ n ] = ( in1 [ n ] × scalar1 ) + scalar2 (27–122)
for each index n.
Synopsis
DARRAY da_vsmsa(DARRAY h_in, double scalar1, double scalar2)
Arguments
h_in The input data array can have any length. Data must be a
noncomplex type.
scalar1 The specified multiplier for each element of the input data array.
The value must be a double precision floating point number.
IMAGE Solutions V8.3 27-122
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
scalar2 The specified number to be added to each product of an element
of the input data array and scalar1. The value must be a double
precision floating point number.
Returns
In normal operation, the output is a data array which has the same length as the input data
array. The type of the output data is the smallest type compatible with the input data type
and DA_REAL. The input type is DA_DREAL if either of the types of the input data array are
DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vsmsb
Vector scalar multiply and vector subtract.
The result of this function is a DARRAY handle whose elements are defined by
out [ n ] = ( in1 [ n ] × scalar ) – in2 [ n ] (27–123)
for each index n.
Synopsis
DARRAY da_vsmsb(DARRAY h_in1, double scalar, DARRAY h_in2)
Arguments
h_in1 The input data arrays must have the same lengths. Data must be
a noncomplex type.
scalar The specified multiplier for each element of the input data array.
The value must be a double precision floating point number.
h_in2 The input data arrays must have the same lengths. Data must be
a noncomplex type.
Returns
In normal operation, the output is a data array which has the same length as the input data
arrays. The output data is the smallest type compatible with the two inputs and DA_REAL.
The output type is DA_DREAL if either of the input data types are DA_DREAL and DA_REAL in
all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vsmul
Scalar multiply.
IMAGE Solutions V8.3 27-123
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
The result of this function is a data array whose data elements are the result of multiplying
to each of the elements of the input vector by the specified scalar
out [ n ] = scalar × in [ n ] (27–124)
for each index n.
Synopsis
DARRAY da_vsmul(DARRAY h_in, double scalar)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
scalar The specified multiplier for each element of the input data array.
The value must be a double precision floating point number.
Returns
In normal operation, the return value is a data array whose length is the length of the input
data array. The output data is the smallest type compatible with the type of the input data
and DA_REAL. It is DA_DREAL if the type of the input data is DA_DREAL and DA_REAL in all
other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vsq
Vector square.
This function returns a DARRAY handle whose data is the element-wise application of the
squaring function to the input data
out [ n ] = in [ n ] × in [ n ] (27–125)
for each index n.
Synopsis
DARRAY da_vsq(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
IMAGE Solutions V8.3 27-124
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Returns
In normal operation, the output data array will have the same length as the input data array.
The output data will have the smallest type compatible with the input data type and DA_REAL.
The output type is DA_DREAL if the input is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vsqrt
Vector square root.
This function returns a data array whose data is the element-wise application of the square
root function to each element of the input data
out [ n ] = in [ n ]
(27–126)
out [ n ] ≥ 0
for each index n.
Synopsis
DARRAY da_vsqrt(DARRAY h_in)
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
Returns
In normal operation, the output data array will have the same length as the input data array.
The output data will have the smallest type compatible with the input data type and DA_REAL.
The output type is DA_DREAL if the input is DA_DREAL and DA_REAL in all other cases.
Zero is returned in the case of a run-time error which is ignored or continued.
da_vssq
Vector signed square.
This function returns a data array whose data is the element-wise application of the signed
square function to each element of the input data
out [ n ] = in [ n ] × in [ n ] (27–127)
for each index n, where |x| is the absolute value of x.
Synopsis
DARRAY da_vssq(DARRAY h_in)
IMAGE Solutions V8.3 27-125
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Arguments
h_in The input data array length must be greater than 0. Data must be
a noncomplex type.
Returns
In normal operation, the output data array will have the same length as the input data array.
The output data will have the smallest type compatible with the input data type and DA_REAL.
The output type is DA_DREAL if the input is DA_DREAL and DA_REAL in all other cases.
da_vsub
Vector subtract.
This function returns the handle of a data array whose elements are the element-wise
application of the arithmetic subtraction function to the input vector
out [ n ] = in1 [ n ] – in2 [ n ] (27–128)
for each index n, between 0 and the smaller of the lengths of in1 and in2.
Synopsis
DARRAY da_vsub(DARRAY h_in1, DARRAY h_in2)
Arguments
h_in1 The input data arrays can have any length. Data can be any
type.
h_in2 The input data arrays can have any length. Data can be any
type.
Returns
In normal operation, the output is a data array whose length is the lesser of the lengths of
the two input vectors. The output data is the smallest type compatible with the types of the
two input parameters and DA_REAL. The output type is one of the following:
• DA_DCMPLX if one or both parameters are complex and one or both parameters are
double precision
• DA_CMPLX if one or both parameters are complex and no parameters are double
precision
• DA_DREAL if neither parameter is complex and one or both parameters are double
precision
• DA_REAL if neither parameter is complex and neither parameter is double precision.
Zero is returned in the case of a run-time error which is ignored or continued.
IMAGE Solutions V8.3 27-126
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
da_vsum
Running sum.
The output of this function is a data array whose nth value is the sum of all the input values
of index less than or equal to n:
out [ n ] = in [ n ] + in [ n – 1 ] + ... + in [ 0 ] (27–129)
for each index n.
Synopsis
DARRAY da_vsum(DARRAY h_in)
Arguments
h_in The input data array must have a length greater than 0. Data
must be a noncomplex type.
Returns
In normal operation, the output is a data array whose data is the smallest type compatible
with both the type of the input data array and DA_REAL. It is DA_DREAL if the input parameter
is DA_DREAL and DA_REAL in all other cases. The output data array length is the length of
the input data array.
Zero is returned in the case of a run-time error which is ignored or continued.
Notes on Using Block Algorithms When Calculating FFTs and Spectra
This section explains how the results are calculated when using Teradyne block algorithms
to compute FFTs of time-domain signals and other spectral transforms.
Representing a Waveform
All signals are comprised of sinusoids. Any sinusoid can be represented as the sum of real
(Re) and imaginary (Im) components as seen in the following equation:
A cos ( f i × t + θ ) (27–130)
The following is a vector representation of the sinusoid with magnitude A and phase θ. (A
is amplitude in volts peak and θ is phase in radians.)
IMAGE Solutions V8.3 27-127
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
A Imaginary
A sinθ
Real
A cosθ
Figure 27-1. Vector Representation of a Sinusoid
Using da_fft
This waveform was sampled in the time domain and the sample contains N points (where
N is a power of 2). You can convert from the time domain to the frequency domain using
“da_fft”.
real component
N x A cosq
imaginary
N x A sinq component
array index 0 1 2 3 k k+1 (N-1)
bin number 0 1 M N/2 -1
frequency dc fres fi fs/2 - fres
Figure 27-2. Frequency Domain Waveform Resulting From da_fft
Frequency Domain Waveform Calculations and Rules
fi ⁄ fs = M ⁄ N (27–131)
f res = f s ⁄ N (27–132)
therefore,
M = f i × N ⁄ f s = f i ⁄ f res (27–133)
where:
fi test tone
IMAGE Solutions V8.3 27-128
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
fs sampling rate
fres bin width
M bin number corresponding to fi. Also, the number of tone cycles
over fres period.
N number of samples over fres period.
Each bin in the complex spectrum contains a pair of array elements. The even element is
real. The odd element is imaginary.
Rule: To locate the real component of the tone fi, look at the complex array index 2 x M. In
this case, the array index (k) = 2 x M.
To locate the imaginary component of the tone fi, look at the complex array index 2 x M + 1.
Using Power Spectrum
Perform “da_power_spectrum” or “da_cvmags” on the complex spectrum. This converts the
complex spectrum to a power spectrum which is real data.
N2 A 2
array index 0 1 2 3 k N/2 -1
bin number 0 1 2 3 f bin N/2 -1
frequency dc fres fi fs/2 - fres
Figure 27-3. Power Spectrum
Each frequency component of the power spectrum is the magnitude squared of the
corresponding complex frequency pair in the complex spectrum.
2 2
power_spec m = ( RE m ) + ( Im m ) (27–134)
2 2
power_spec m = ( complex_spec k ) + ( complex_spec k + 1 )
= ( N × A cos θ ) 2 + ( N × A sin θ ) 2
= ( N 2 ⋅ A 2 ⋅ cos2 θ + N 2 ⋅ A 2 ⋅ cos2 θ ) (27–135)
= ( N 2 ⋅ A 2 ⋅ ( cos2 θ + sin2 θ ) )
= ( N2 ⋅ A2 )
IMAGE Solutions V8.3 27-129
IMAGE Base Language: FlexDSP Programmer’s Reference: FlexDSP Function Reference
Table of Contents Index Home Master Index Search Help
Using da_amplitude
Use “da_amplitude” to get the amplitude of a spectral component at a certain fi.
da_amplitude() can operate on either a complex spectrum or a power spectrum.
If it operates on a complex spectrum:
result = magnitude of a complex pair at a given fi (27–136)
result magnitude = ( Re ) 2 + ( Im ) 2
= ( N ⋅ A ⋅ cos θ ) 2 + ( N ⋅ A ⋅ sin θ ) 2
= N 2 ⋅ A 2 ⋅ ( cos2 θ + sin2 θ ) (27–137)
= N2 ⋅ A2
= N×A
NOTE
Identity:
( cos2 θ + sin2 θ ) = 1
If it operates on a power spectrum:
result power = component of power spectrum at a given f i
(27–138)
= ( N2 ⋅ A2 )
IMAGE Solutions V8.3 27-130
IMAGE Base Language: Tester API
Table of Contents Index Home Master Index Search Help
28 TESTER API
The Tester Applications Programming Interface (TAPI) provides a mechanism by which an
application program can control an IMAGE based tester. TAPI allows an application more
control over IMAGE by using a library called libtapi.a linked to the libapps.a library and
a header file called tester_api.h.
TAPI also provides two types of handler/prober control, functions that set up or change the
handler/prober configuration and user-driven handler/prober control functions.
IMAGE Solutions V8.3 28-1
IMAGE Base Language: Tester API: TAPI Functions Summary
Table of Contents Index Home Master Index Search Help
TAPI Functions Summary
libtapi.a and libapps.a provide the functions described in the following sections. Table
28-1 lists TAPI functions for controlling IMAGE, table 28-2 lists functions for controlling
handler/prober configuration, and table 28-3 lists user-driven handler/prober control
functions.
Table 28-1. TAPI Functions for Controlling IMAGE
Function Description
tl_run_test_program Run test program
tl_run_test_program_cached Run test program using cached probe card
location and site mask
tl_define_bins Define device bins for test program using
default output handler
tl_define_sites Define device sites for test program using
default output function
tl_locate_site Define location of site on wafer
tl_get_image_version Retrieve version number of IMAGE
tl_get_last_image_error_ofunc Retrieve information about last IMAGE
error
tl_switchvar Manipulate IMAGE switchvars using
default output function
Table 28-2. TAPI Functions for Controlling Handler/Prober Configuration
Function Description
tl_tapi_hp_connect Connect handler or prober (same as
handlerconf -connect)
tl_tapi_hp_disconnect Disconnect handler or prober (same as
handlerconf -disconnect)
tl_tapi_hp_enable Enable handler or prober for polling (same
as
handlerconf -enable)
tl_tapi_hp_disable Disable handler or prober for polling (same
as
handlerconf -disable)
IMAGE Solutions V8.3 28-2
IMAGE Base Language: Tester API: TAPI Functions Summary
Table of Contents Index Home Master Index Search Help
Table 28-2. TAPI Functions for Controlling Handler/Prober Configuration (Continued)
Function Description
tl_tapi_hp_disconnect_all Disable and disconnect all handler or
prober devices from specified station
Table 28-3. TAPI Functions for User-Driven Handler/Prober Control
Function Description
tl_tapi_hp_get_start Poll handler or prober for specified time
and return start site mask and notable
events
tl_tapi_hp_exec_callback Execute test program callbacks
tl_tapi_hp_send_binning Send binning information to handler or
prober
IMAGE Solutions V8.3 28-3
IMAGE Base Language: Tester API: TAPI Functions for Controlling IMAGE
Table of Contents Index Home Master Index Search Help
TAPI Functions for Controlling IMAGE
tl_run_test_program
Run the test program.
SYNOPSIS Tl_run_status tl_run_test_program(stn, cmd, string,
results, output_func)
int stn;
char *cmd;
char *string;
int results[];
Tapi_OFunc output_func;
DESCRIPTION This function executes the test program loaded on station stn.
ARGUMENTS stn—station on which to execute a test program.
cmd—one of run, runtotrap, or cont.
string—string of arguments to pass to the test program.
results—array in which to return binning information.
output_func—function to use to write output produced by call.
The function should be declared as:
int output_funct(int fd, char *data, int len)
where:
fd—file descriptor that can be either 1 (stdout) or 2 (stderr).
data—text to be output.
len—length of text.
The string pointed to by data cannot be null terminated.
The function should return a nonzero value.
RETURN VALUE One of the tl_run_status values, defined in itlh/
run_command.h.
tl_run_test_program_cached
Run the test program using cached probe card location and site mask.
SYNOPSIS Tl_run_status tl_run_test_program_cached(stn, cmd,
string, results, output_func)
int stn;
char *cmd;
char *string;
int results[];
Tapi_OFunc output_func;
IMAGE Solutions V8.3 28-4
IMAGE Base Language: Tester API: TAPI Functions for Controlling IMAGE
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function executes the test program using cached
information on the location of the probe card and the site mask
(cf tl_locate_site and tl_set_active_sites).
ARGUMENTS stn—station for which a site is being located.
cmd—one of run, runtotrap, or cont.
string—string of arguments to pass to the test program.
results—array in which to return binning information.
output_func—function to use to write output produced by call.
The function should be declared as:
int output_funct(int fd, char *data, int len)
where:
fd—file descriptor that can be either 1 (stdout) or 2 (stderr).
data—text to be output.
len—length of text.
The string pointed to by data cannot be null terminated.
The function should return a nonzero value.
RETURN VALUE One of the Tl_run_status values, defined in itlh/
run_command.h.
tl_define_bins
Define device bins for test program using default output handler.
SYNOPSIS int tl_define_bins(stn, num_pass_bins, pass_bins,
num_fail_bins, fail_bins)
int stn;
int num_pass_bins, pass_bins[];
int num_fail_bins, fail_bins[];
DESCRIPTION This function is functionally identical to tl_define_bins_ofunc,
except that it does not allow passing an output_func
parameter. Instead, the output function defined by
tl_tapi_set_output_function is used.
ARGUMENTS stn—station for which binning is being defined.
num_pass_bins—the number of bins specified in the
pass_bins[] array.
pass_bins—an array of bin numbers to be considered pass
bins.
num_fail_bins—the number of bins specified in the fail_bins[]
array.
fail_bins—an array of bin numbers to be considered fail bins.
RETURN VALUE -1 for failure, 1 for success.
IMAGE Solutions V8.3 28-5
IMAGE Base Language: Tester API: TAPI Functions for Controlling IMAGE
Table of Contents Index Home Master Index Search Help
tl_define_sites
Define device sites for test program using default output function.
SYNOPSIS int tl_define_sites(stn, num_sites, sites)
int stn;
int num_sites;
struct image_site_info sites[];
DESCRIPTION This function is functionally identical to
tl_define_sites_ofunc, except that it does not allow passing
an output_func parameter. Instead, the output function defined
by tl_tapi_set_output_function is used.
ARGUMENTS stn—station for which the probe card is being defined.
num_sites—the number of sites specified in the sites[] array.
sites—an array of site definitions.
RETURN VALUE -1 for failure, 1 for success.
tl_locate_site
Define location of a site on a wafer.
SYNOPSIS int tl_locate_site(stn, site, waf_x, waf_y)
int stn;
int site;
int waf_x, waf_y;
DESCRIPTION This function defines the location on the wafer of the sites on the
probe card. It must be called every time the probe card is moved.
However, it is unnecessary to call tl_locate_site for each
active site. Once is enough. Additionally, the site for which a
location is specified need not be an active site. If multiple calls
are made to tl_locate_site with inconsistent information, the
last call is implemented.
ARGUMENTS stn—station for which a site is being located.
site—site number for which a location is being defined.
waf_x, waf_y—coordinates on the wafer of the die under the
specified site.
RETURN VALUE -1 for failure, 1 for success.
tl_get_image_version
Retrieve the version number of IMAGE.
SYNOPSIS char *tl_get_image_version()
DESCRIPTION This function retrieves the version number and date of IMAGE.
For example: V5.4 031694 or V5.3 D2 022594.
IMAGE Solutions V8.3 28-6
IMAGE Base Language: Tester API: TAPI Functions for Controlling IMAGE
Table of Contents Index Home Master Index Search Help
ARGUMENTS None
RETURN VALUE NULL for failure or a pointer to a STATIC null-terminated string
for success.
NOTE
Callers wishing to cache this value must make a copy of it.
tl_get_last_image_error_ofunc
Retrieve information about the last IMAGE error.
SYNOPSIS struct image_error
*tl_get_last_image_error_ofunc(stn, output_func)
int stn;
Tapi_OFunc output_func;
DESCRIPTION This function retrieves information about the last error that
occurred within IMAGE.
ARGUMENTS stn—station for which error information should be retrieved.
output_func—function to use to write output produced by call.
The function should be declared as:
int output_funct(int fd, char *data, int len)
where:
fd—file descriptor that can be either 1 (stdout) or 2 (stderr).
data—text to be output.
len—length of text.
The string pointed to by data cannot be null terminated.
The function should return a nonzero value.
RETURN VALUE NULL for failure or a pointer to a STATIC struct image_error
for success.
NOTE
Callers wishing to cache this value must make a copy of it.
tl_switchvar
Manipulate IMAGE switchvar using default output function.
SYNOPSIS int tl_switchvar(stn, numops, ops);
int stn;
IMAGE Solutions V8.3 28-7
IMAGE Base Language: Tester API: TAPI Functions for Controlling IMAGE
Table of Contents Index Home Master Index Search Help
int numops;
Tapi_Switchvar ops[];
DESCRIPTION This function is identical to tl_switchvar_ofunc, except that it
does not allow passing an output_func parameter. Instead, the
output function defined by tl_tapi_set_output_function is
used.
ARGUMENTS stn—station for which to manipulate switchvars.
numops—number of operations in the ops[] array. This value
must be between 0 and TL_NUM_SWITCHVARS, inclusive.
ops[]—an array of switchvar operations to perform. Each
operation is a structure with the following members:
.svop—either TL_SWITCHVAR_SET or TL_SWITCHVAR_GET, to set
the value of the switchvar, or get the value, respectively.
.svnum—the number of the switchvar to manipulate.
.svval—a pointer to the value to assign (for
TL_SWITCHVAR_SET) or to the variable in which to place the value
(for TL_SWITCHVAR_GET).
RETURN VALUE -1 for failure, 1 for success.
IMAGE Solutions V8.3 28-8
IMAGE Base Language: Tester API: TAPI Functions for Controlling Handler/Prober Configuration
Table of Contents Index Home Master Index Search Help
TAPI Functions for Controlling Handler/Prober
Configuration
tl_tapi_hp_connect
Connect a handler or prober to IMAGE.
SYNOPSIS int tl_tapi_hp_connect(station, name, port)
int station;
char *name;
int port;
DESCRIPTION This function connects the handler or prober to the specified
station and port. The device will not be enabled for polling.
ARGUMENTS name—name of the handler or prober as it appears in the
handcap file.
station—station to which to connect the handler or prober.
port—handler or prober port on which to connect the handler/
prober.
RETURN VALUE -1 for failure, 0 for success.
tl_tapi_hp_disconnect
Disconnect a handler or prober from IMAGE.
SYNOPSIS int tl_tapi_hp_disconnect(station, name)
int station;
char *name;
DESCRIPTION This function disconnects the handler or prober from the
specified station.
ARGUMENTS name—name of the handler or prober as it appears in the
handcap file.
station—station from which to disconnect the handler or
prober.
RETURN VALUE -1 for failure, 0 for success.
tl_tapi_hp_enable
Add a handler or prober to the IMAGE handler or prober polling queue.
SYNOPSIS int tl_tapi_hp_enable(station, name)
int station;
char *name;
IMAGE Solutions V8.3 28-9
IMAGE Base Language: Tester API: TAPI Functions for Controlling Handler/Prober Configuration
Table of Contents Index Home Master Index Search Help
DESCRIPTION This function enables the handler or prober on the specified
station for polling. Any starts that occur during polling result in
running the test program and binning the devices.
ARGUMENTS name—name of the handler or prober as it appears in the
handcap file.
station—station on which to enable the handler or prober.
RETURN VALUE -1 for failure, 0 for success.
tl_tapi_hp_disable
Remove a handler or prober from the IMAGE handler or prober polling queue.
SYNOPSIS int tl_tapi_hp_disable(station, name)
int station;
char *name;
DESCRIPTION This function disables the handler or prober on the specified
station for polling. The device is removed from the polling queue.
ARGUMENTS name—name of the handler or prober as it appears in the
handcap file.
station—station on which to disable the handler or prober.
RETURN VALUE -1 for failure, 0 for success.
tl_tapi_hp_disconnect_all
Disconnect all handler or prober devices from one IMAGE station.
SYNOPSIS int tl_tapi_hp_disconnect_all(station)
int station;
DESCRIPTION Disconnects all handler or prober devices from the specified
station.
ARGUMENTS station—station from which to disconnect the handler or prober
devices.
RETURN VALUE -1 for failure, 0 for success.
IMAGE Solutions V8.3 28-10
IMAGE Base Language: Tester API: TAPI Functions for User-Driven Handler/Prober Control
Table of Contents Index Home Master Index Search Help
TAPI Functions for User-Driven Handler/Prober Control
tl_tapi_hp_get_start
Asynchronously get polling conditions from a handler or prober.
SYNOPSIS int tl_tapi_hp_get_start(station, name, return_cond,
return_sites, return_x_coord, return_y_coord,
timeout_milliseconds)
int station;
char *name;
int *return_cond;
int *return_sites;
int *return_x_coord;
int *return_y_coord;
int timeout_milliseconds;
DESCRIPTION This function polls the specified handler or prober device for
starts until the device asserts a start or a notable event. The
function will also cease polling after a user-specified timeout.
This function does not interrupt the operation of the handler/
prober software. Other handler or prober devices will continue to
operate. You cannot call this function on a handler or prober
device that is enabled for polling.
ARGUMENTS name—name of the handler/prober as it appears in the handcap
file.
station—station to which the device is connected.
return_cond—a user-allocated return storage space
parameter. The function returns a bit field vector that describes
which event caused the termination of polling the device. The
macros for the bits are as follows:
HP_START_COND
HP_TIMEOUT_COND
HP_EOW_COND
HP_EOC_COND
HP_EOL_COND
HP_SOW_COND
HP_SOC_COND
return_sites—a user-allocated return storage space
parameter. The function returns a bit field vector representing on
which sites a start has been detected.
return_x_coord, return_y_coord—user-allocated return
storage space parameters. These functions return the
coordinates of the site 0 die.
timeout_milliseconds—shortest time to poll the device before
returning the HP_TIMEOUT_COND event. The function will
IMAGE Solutions V8.3 28-11
IMAGE Base Language: Tester API: TAPI Functions for User-Driven Handler/Prober Control
Table of Contents Index Home Master Index Search Help
minimally wait as long as the value given here but may actually
wait longer.
RETURN VALUE -1 for failure, 0 for success.
tl_tapi_hp_exec_callback
Execute test program callbacks based on a condition vector.
SYNOPSIS int tl_tapi_hp_exec_callback(station, conditions,
arg)
int station;
int conditions;
void *arg;
DESCRIPTION This function causes the handler/prober software to execute the
appropriate handler/prober callback in the test program. The set
of callbacks executed is specified by the conditions bit vector
argument. You cannot call this function on a handler or prober
device that is enabled for polling.
ARGUMENTS station—station on which to execute the specified handler/
prober callback.
conditions—a bit field vector that denotes which handler/
prober callback to execute. Note that you can only set one bit.
The macros for the bits are as follows:
HP_EOW_COND
HP_EOC_COND
HP_EOL_COND
HP_EOT_COND
HP_SOW_COND
HP_SOC_COND
HP_SOT_COND
HP_USER_COND
arg—holds data for passing to the callback functions in the test
program. You must cast the argument to be of the correct type.
Currently, only HP_SOT_COND, HP_EOT_COND, and HP_USER_COND
require that this field be filled (non-NULL). The function also
returns information in this argument. The SOT callback requires
a pointer to an integer site mask, which may have been modified
by the callback function. The EOT callback requires a pointer to
a structure of type tapi_binning_info which is defined as:
struct tapi_binning_info {
int sitemask;
int bins[MAX_TAPI_BIN_SITES];
int inkers[MAX_TAPI_BIN_SITES];
int passfail[MAX_TAPI_BIN_SITES];
};
IMAGE Solutions V8.3 28-12
IMAGE Base Language: Tester API: TAPI Functions for User-Driven Handler/Prober Control
Table of Contents Index Home Master Index Search Help
The contents of this structure are passed to the test program
callback and may be modified by the call back function. The user
callback requires a pointer to an integer which can be passed to
the test program callback. This integer is not modified.
RETURN VALUE -1 for failure, 0 for success.
tl_tapi_hp_send_binning
Send binning to a handler or prober device.
SYNOPSIS int tl_tapi_hp_send_binning(station, name,
bin_sites, bin_vector[], inker_vector[],
passfail_vector[])
int station;
char *name;
int bin_sites;
int bin_vector[];
int inker_vector[];
int passfail_vector[];
DESCRIPTION This function tries to send binning information to the named
handler or prober device on the specified station. Executing the
function interrupts the operation of the handler/prober software.
The function only returns after the operation has succeeded or
failed. You cannot call this function on a device that is enabled
for polling.
ARGUMENTS station—station to which the device is connected.
name—name of the handler or prober as it appears in the
handcap file.
bin_sites—site mask of valid sites to bin.
bin_vector—array of bin numbers to deliver to the handler or
prober device. Array index 0 corresponds to site 0, index 1 to site
1, and so forth.
inker_vector—array of inker numbers to deliver to the handler
or prober device. It is indexed like the bin_vector argument.
passfail_vector—array of pass/fail status indicators to deliver
to the handler or prober device. A zero indicates failing, a
nonzero indicates passing. It is indexed like the bin_vector
argument.
RETURN VALUE -1 for failure, 0 for success.
IMAGE Solutions V8.3 28-13
IMAGE Base Language: Custom Directory
Table of Contents Index Home Master Index Search Help
29 CUSTOM DIRECTORY
The custom directory (/custom) is shipped with IMAGE software. This directory is located
in $IMAGEBIN/custom. It contains subdirectories and files which enable you to install
software, set up menu displays, modify defaults, and perform other functions in IMAGE.
Table 29-1 lists the contents of the $IMAGEBIN/custom directory. Files are described as
fixed, dynamic, or change. Fixed files are read only. Dynamic files change due to some
action in IMAGE. Files you can change are used to customize IMAGE.
Table 29-1. $IMAGEBIN/custom Directory
Name Description Properties
.Xdefaults X11 defaults file Dynamic
.catdmenu Program menu
.displaymenu_a500 Mixed-Signal station display menu Fixed
.displaymenu_a510 Linear station display menu Fixed
.displaymenu_al Advanced Linear station display Fixed
menu
.displaymenu_h50 Advanced Mixed-Signal station Fixed
display menu
.image-init Start-up tools Dynamic
.image-menu -> .image-menu.no_m218 Change
.image-menu.no_m218 Root menu Change
.image-menu.prod -> .image-menu.prod.no_m218 Change
.image-menu.prod.no_m218 Production mode root menu Change
.image-tools Start-up tool for remote IMAGE Change
.image-xinitrc IMAGE version of .xinitrc Change
.imagepaint.ps Start-up screen Fixed
IMAGE Solutions V8.3 29-1
IMAGE Base Language: Custom Directory:
Table of Contents Index Home Master Index Search Help
Table 29-1. $IMAGEBIN/custom Directory (Continued)
Name Description Properties
.pmctool_defaults PMC defaults
.production_window_info Production mode windows/positions
.production_window_info.disabled
.production_window_info_3
.startup.ps Fixed
.stlogout IMAGE equivalent of .logout
.ttyswrc Empty file Change
.usermenu Station user button menu Change
ImageLoadJobScript PMC job load script
MAKEDEV.image.4.1.1 /dev/MAKEDEV for tester Fixed
MADEDEV.image.4.1.1.3ce /dev/MAKEDEV for tester Fixed
README.extract Document for extract_license Fixed
S95rc.Teradyne Boot start-up script for Solaris 2 Fixed
TeradyneLoadJobScript STG production user interface
a500.im1
a500.im8
backup Example of an old backup script Change
cccp
ce/ Directory containing classing engine
files
cfg_bds/ Directory containing configuration
and confsim files
cgb458_package.mdl
cgb458_package.script
cgb458_probe.mdl
cgb458_probe.script
cgb459.mdl
IMAGE Solutions V8.3 29-2
IMAGE Base Language: Custom Directory:
Table of Contents Index Home Master Index Search Help
Table 29-1. $IMAGEBIN/custom Directory (Continued)
Name Description Properties
confsim Hybrid (linear and mixed-signal) Fixed
configuration file with Synchronized
Power Subsystem
confsim.TRAINING Training configuration file Fixed
(advanced mixed-signal)
confsim.a530 Linear configuration file with Fixed
Synchronized Power Subsystem
confsim.a530al Advanced linear configuration file Fixed
with Synchronized Power
Subsystem
confsim.a540 Hybrid (linear and mixed-signal) Fixed
configuration file with Synchronized
Power Subsystem
confsim.a540al Hybrid (linear and mixed-signal) Fixed
advanced linear configuration file
with Synchronized Power
Subsystem
confsim.a550 Mixed-signal configuration file Fixed
confsim.a560 Linear configuration file Fixed
confsim.a561 Linear configuration file Fixed
confsim.a563 Linear configuration file Fixed
confsim.a565 Advanced analog VLSI Fixed
configuration file
confsim.a569 Linear configuration with Image Fixed
Sensor options file
confsim.a570 Advanced mixed-signal Fixed
configuration file
confsim.a580 Advanced mixed-signal Fixed
configuration file
default.login .login for Teradyne installed Fixed
accounts
diskmon_config Configuration file for diskmon Change
display_items.h
IMAGE Solutions V8.3 29-3
IMAGE Base Language: Custom Directory:
Table of Contents Index Home Master Index Search Help
Table 29-1. $IMAGEBIN/custom Directory (Continued)
Name Description Properties
dl_filters/ Directory containing custom datalog
filter files
engineering_station_buttons Engineering mode station window Change
buttons
extract_license Script to get licenses from floppy Fixed
gpicap gpib bus: master_clock, Change
aux_clock, pmm
handcap Handler prober characteristics Change
database
im_datacollection.mdl
im_utilities.mdl
image_disk_warning Test file for diskmon Fixed
image_setup Old IMAGE installation script Fixed
image_svcompat_menu Menu items for Sunview
compatibility mode
install Directory of IMAGE setup files Fixed
install_rc.csh Obsolete
introscreen.sun Obsolete
kill_remote.script PMC
lib.list.exp
manager.startup Copied to ~manager Fixed
mdl_sample_job.bin Change
mdl_sample_job.tl Change
menufile Operator interface menu description
file
menufile.mdl
menuprogram.svr4
newfileinit.tl Headers for load -new
newhdrinit.h Comment only
operator2.xdefaults Operator account file Fixed
IMAGE Solutions V8.3 29-4
IMAGE Base Language: Custom Directory:
Table of Contents Index Home Master Index Search Help
Table 29-1. $IMAGEBIN/custom Directory (Continued)
Name Description Properties
operator2.image-init Operator account file Fixed
operator2.login Operator account file Fixed
operator2.production_window Operator account file Fixed
_
info
operator2.ttyswrc Operator account file Fixed
operator2production_station Operator account file Fixed
_
buttons
operators List of names Change
option_setup Obsolete
printcap.loc Example of local printcap entry Fixed
printcap.rem Example of a remote printcap Fixed
entry
product_db PMC
production_station_buttons Production mode station window Change
buttons
rc.Teradyne Solaris 1 tester start-up file Fixed
rc.local.TST Obsolete Fixed
remote /etc/remote file for tip hardwire Fixed
remote_image Remote start-up script Change
tester_setup Solaris 2 tester setup Fixed
sample_setup_script Production setup
sed.rc.Ter IMAGE setup file Fixed
start_remote.script PMC
startlot_script Example script for startlot
statmon.data Layout file for Test Station Monitor
sum_filters/ Directory containing summary filter
files
tablegen.tl PMC data
IMAGE Solutions V8.3 29-5
IMAGE Base Language: Custom Directory:
Table of Contents Index Home Master Index Search Help
Table 29-1. $IMAGEBIN/custom Directory (Continued)
Name Description Properties
tester.login ~tester/.login (image_setup) Fixed
tester_setup IMAGE setup file Fixed
yield_monitor.yield Layout file for Yield Monitor Change
IMAGE Solutions V8.3 29-6
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
INDEX
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Numerics Alarm Manager, 22-5
1GVHFD (1 GHz Very High Frequency Digitizer) Alarms
alarms, 22-9 1GVHFD, 22-9
AAPU, 22-10
A AWGLAN, 22-8
.a files, see Library files breaktraps, 7-11
A565 test system capture memory, 22-4, 22-13
selecting head type, 5-3 checking, 22-4, 26-99, 26-146
A5XX Family test systems clearing, 26-239
getting started, 1-5 conditions, 22-7
hardware, 1-2 DC subsystem, 22-10
software, 1-3 debugging, 22-21
AAPU (Advanced Analog Pin Unit) Digital Signal Source, 22-14
alarms, 22-10 disabling, 22-2
calibration, 21-7, 21-30, 21-36 enabling, 22-2
Abbreviations, for directories, 2-27 GigaDig, 22-9
Abort Auto icon, 19-31 HCPS, 22-11
abort button, 3-13 HCU, 22-11
abort button and command, 5-28, 8-7, 8-12 High Voltage V/I Source, 26-396
abort command, 3-14 Large Vector Memory, 22-14
ABORT control button (Production Menu Control), LCA, 22-14
9-10 LFACDIG, 22-9
ABORT keyword, 8-27, 8-32 LFACSRC, 22-9
ABORT keyword (Production Menu Control), logging messages, 3-37
9-11, 9-30, 9-50 masking, 22-17
ac clock function, 26-44 Master Alarm Enable, 22-3
AC Waveform Capture Memory message log files, 8-45
alarms, 22-10 messages, 8-43, 8-44
simulation, 12-10 OVI, 22-12
AC Waveform Source Memory PLFDIG, 22-9
alarm, 22-14 PLFSRC, 22-9
Accelerator keys, 8-42 PMM, 22-15
Accessing bin numbers, 15-11, 17-27 programming examples using, 22-20
accsum command, 6-100 QVS, 22-12
Accumulated summary reports, 6-89, 6-93, 6-100 reporting, 22-5
acmapchanges file, 4-19 SBCC, 22-16
ACTIVE keyword (Production Menu Control), 9-50 set message destinations, 26-346, 26-370
Active variables, 7-62 Source Memory, 22-14
Adding files to test programs, 7-8 stored databits, 22-16
adjust_func function, 15-20 TJA, 22-15
Advanced mixed-signal TJD, 22-15
checkers, 19-10 UBVI source, 22-13
selecting head type, 5-3 VHFDIG, 22-9
test time example, 5-33 yield monitor, 8-62
IMAGE Solutions V8.3 Index-1
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
alias command, 2-28 calibration, 21-6, 21-8, 21-31, 21-47, 26-335
Allocation of tester memory, 5-37 simulator database, 12-3
Analog clocks, reading, 26-43 ATTACH keyword (Production Menu Control),
Analog Pin Unit, see APU 9-51
Analog Sampling Unit, see ASU Attaching station windows to test head, 3-17
ANSI C, 13-30 Auto checker run, 19-22
ANSWER_REMOTE_CALL keyword (Production Checker Setup display, 19-23
Menu Control), 9-51 checker versions, 19-25
AnswerBook, 2-6, 3-25 datalogging, 19-25
Answers, see IMAGE Solutions enabling auto start, 19-31
Appending files, 2-22 installation, 19-22
APU (Analog Pin Unit) on shell station, 19-32
calibration, 26-147, 26-523 Reboot always, 3-38, 19-30
read channel number, 26-48 saving changes, 19-29
read meter measurement, selecting days, 19-25
26-45, 26-521, 26-522 setting checker attributes, 19-26
read pin number, 26-48 Solaris 2, 19-23
read pin status, 26-148 specifying tester, 19-24
simulator database, 12-3 start time, 19-25
Arithmetic operators, 13-13 Autocalibration,
Array processor, calculations in multisite test, 5-6, 5-11, 19-20, 21-3, 21-18, 26-196, 26-34
17-29 7
Array Test Head, see ATH change criteria, 26-166
Arrays, 13-6, 13-24 change mode, 26-166
ANSI C, 13-31 determine state, 21-27
pin, 26-284 enable and disable, 21-17, 21-22, 21-25
printing, 7-63 enabling and disabling, 19-20
variables, 13-24 examples, 21-51
variables display, 7-58 Load test program window, 5-3, 21-17
Assigning bin numbers, 15-8, 17-27 read criteria, 26-160
Assignment operators, 13-16, 13-19 read mode, 26-158, 26-160
Assignment statements, 13-19 read state, 26-159, 26-162
Associativity between operators, 13-16 report, 21-20
ASU (Analog Sampling Unit) set calibration intervals, 21-30
reading, 26-149 set calibration times, 21-29
ATE breaktraps, 7-11 set criteria, 21-29
ATH (Array Test Head) set modes, 21-22, 21-25, 26-164
measure DATA pin frequency, 26-150 syntax summary, 21-60
measure GATE pin frequency, 26-151 Auto-compile, 7-24
read capacitance, 26-152 Automatic login, 3-34
read counter, 26-152 Automatic summary reports, 6-94, 6-96, 26-185
read frequency, 26-152 retrieve setup, 26-196
ATMS (Advanced Time Measurement setup, 6-98, 26-347
Subsystem) Auto-Summary Setup window, 6-94
IMAGE Solutions V8.3 Index-2
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Auxiliary files (Production Menu Control), 9-41 closed bins, 14-16, 15-8
Auxiliary stations, 3-17 determine if bin open or closed, 26-49, 26-69
icon, 3-13 determine pass or fail, 24-26, 26-49
loading, 5-6, 5-10 direct, 15-6
use with checkers, 19-1 disqualify binning, 14-16, 15-8
AWGLAN (Arbitrary Waveform Generator Local error bins, 15-31
Area Network) fail actions, 14-12, 14-15, 14-22, 15-7
alarms, 22-8 get hardware bin number, 26-220
get last bin number, 26-213, 26-218
B get software bin number, 26-219
BACK control button (Production Menu Control), multisite test, 17-6
9-10 open bins, 15-8, 15-12
BACK keyword (Production Menu Control), 9-51 pass actions, 15-6
BAD_UNITS keyword (Production Menu Control), read hardware bin count, 26-211
9-52 read open bin, 26-70
Bank relays, function, 26-289 read software bin count, 26-217
Base language, help, 3-26 send command to handler or prober, 26-238
BBAC set fail bin, 26-157
waveform clock, 26-507 set pass bin, 26-157
BBACCAP (Broadband AC Capture) BINNING_ITEM keyword (Production Menu
calibration, 21-7, 21-32, 21-36 Control), 9-52
manual, 21-36 binstatus command, 15-12
BBACSRC (Broadband AC Source) Bitwise logical operators; see Logical operators
calibration, 21-7, 21-32, 21-36 Body of a function, 13-7
Begin datalog of new device, 26-177 BPS (Begin Program Section Record),
Begin Program Section Record, see BPS 24-6, 24-12
Behavior Chooser, 5-12 Braces, in IMAGE, 8-21, 8-31, 13-6, 13-9
.bin files, see Binary files Brackets, in IMAGE, 13-6
Bin numbers, see Binning Branching, 2-3, 13-19, 13-22
Bin totals in summary report, 6-89 break statement, 13-19, 13-22
Binary files, 5-2, 5-5, 5-11 Breakdown Voltage Current Source, connections,
changing for conditional compiling, 5-18, 5-19 26-396
determining type, 7-43 Breaktraps, 7-11
saving, 7-32 arrow, 7-12, 7-15, 7-18
Solaris 2, 7-27, 7-28, 7-40, 7-43 ATE, 7-11
SUN3 and SUN4, 5-10, 7-27, 7-28, 7-40 deleting, 7-14
binfile command, 7-43 during editing, 7-22, 7-24
Binning, 5-24, 13-4, 14-9, 14-12 in alarms, 7-11
and alarms, 22-3 in for statements, 7-21
assigning bin numbers, 15-6, 15-8 in functions, 7-11
bin numbers, 15-11, 17-27 in patterns, 7-11
hardware, 6-89, 6-134, 10-3, 15-12, 15-18 in test numbers, 7-11
software, in tests, 7-11
5-22, 6-89, 6-135, 10-3, 15-12, 15-18 line number, 7-11
IMAGE Solutions V8.3 Index-3
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
listing, 7-11, 7-13 HVA, 26-392
looping, 7-15, 7-16 instruments, 26-163
placement, 7-13, 7-21 LCA, 21-7, 21-41
runtime error, 7-11, 7-12, 7-13 load parameters, 5-11
setting, 7-11 overriding errors, 21-57
setting trap arrow, 7-10 OVI, 21-7
stopsign icon, 7-12 pinmap_only mode, 5-3, 5-7, 21-29
using, 7-15 PLFDIG, 21-7, 21-16, 21-31, 21-43
variable declarations, 7-21 PLFSRC, 21-8, 21-16, 21-31, 21-43
Brief format, datalog reports, 6-41 PMM, 21-8, 21-44
BUTTON keyword, 8-11 print report, 26-163
Buttons Pulse Driver, 21-8, 21-45
customizing station window, 3-47, 8-10 QVS, 21-8, 21-45
menu defaults for, 3-45 read remaining time, 26-163
standard IMAGE, 8-12 SBCC, 21-8, 21-30, 21-46, 26-168
syntax summary, 21-60
C TJA, 21-8, 21-46
C compiler, 7-39 TJD, 21-8, 21-46
C language Trigger Walking Delay Generator, 21-8, 21-48
ANSI C, 13-8, 13-30 uncalibration instrument, 26-167
differences from IMAGE, 13-9 UWPORT,
C shell, 2-27 21-7, 21-41, 26-100, 26-464, 26-531
calibrate command, 19-20, 21-17, 21-33 UWRECV, 21-7, 21-31, 21-42, 26-128, 26-129
Calibration UWSRC, 21-7, 21-31, 21-42, 26-429
AAPU, 21-7, 21-30, 21-36 VHFAWG, 21-8, 21-31, 21-48, 26-495
APU, 26-147 VHFCW, 21-8, 21-31, 21-49
ATMS, 21-6, 21-8, 21-31, 21-47 VHFDIG, 21-8
automatic, VREG, 21-50
5-6, 5-11, 19-20, 21-3, 21-18, 26-196, 26- Vreg, 21-8
347 CALL_FUNCTION keyword (Production Menu
BBACCAP, 21-7, 21-32, 21-36 Control), 9-52
BBACSRC, 21-7, 21-32, 21-36 CALLHELP keyword (Production Menu Control),
DC subsystem, 21-6, 21-7, 21-30, 21-38 9-53
DC voltmeter, 26-177, 26-178 Calling sequence to functions, 7-18
determining when performed, 21-6 Capture memory
Digital Subsystem, 21-6, 21-7, 21-31, 21-37 alarms, 22-4, 22-13
files Carriage returns in IMAGE, 13-6
forcing use, 5-7, 5-8 case statement, 13-22
loading without, 5-3, 5-7, 5-8 cat command, 2-22, 2-23
Floating Voltage Source, 26-196 Catalyst
GigaDig, 21-7, 21-39 checkers, 19-10
HCPS, 21-7, 21-40 icon, 3-12
HCU, 21-38, 26-235 selecting head type, 5-3, 5-6, 5-10
HSS, 21-7, 21-40 station window type, 3-15, 3-17
IMAGE Solutions V8.3 Index-4
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Catalyst Tiger initialization, 19-2, 19-17
checkers, 19-10 loading, 19-6
icon, 3-13 loading individual, 19-11
selecting head type, 5-6, 5-10 location, 19-4
station window type, 3-15, 3-17 looping, 19-18
CATD (Computer-aided test development), 1-4 running, 19-12
CATD (Computer-aided test development) button, storing failures, 19-19
3-13, 8-12 structure, 19-2
cd command, 2-17 summary, 19-18
Change station number menu item, 8-18, 8-19 system, 19-7
CHANGE_MENU keyword (Production Menu types, 19-3
Control), 9-53 working with multiple versions, 19-4
Changing test program files, 7-8 checkers button, 3-14, 5-29, 8-7, 8-13
Changing test program functions, 7-7 setting submenus, 3-34
Channels, digital Checkpoint frequency, 7-36
get channel number for pin, 26-231 datalog, 6-37
look up pin numbers, 26-230 summary reports, 6-92, 6-104
pin assignments for multisite testing, 17-5 chfile command, 7-8, 7-23
char data type, 13-11 chfunc command, 7-7
Character constants, 13-11 ck_log file, 19-7
Characters, getting, 16-16 CKRBIN environment variable, 8-26, 19-4
CHECK_STATUS keyword, 8-27, 8-33 clear command, 2-15
CHECK_STATUS keyword (Production Menu CLEAR keyword, 8-34
Control), 9-29, 9-54 CLEAR keyword (Production Menu Control), 9-56
CHECK_VARIABLE keyword, 8-28, 8-33 Clearing the screen, 2-15
CHECK_VARIABLE keyword (Production Menu Clobbering files, 2-22
Control), 9-30, 9-55 Closed bins, 14-16, 15-8
Checker Groups menu item, 19-10 Closing a device lot, 6-11
Checker Setup display, 19-23 CMU (Color Monitoring Unit)
Checker summaries, 19-18 read ROI height, 26-171
checkerdisp command, 19-24, 19-32 read ROI position, 26-171, 26-172
Checkers, 19-1 read ROI width, 26-171
automatic running, 19-22 COL keyword (Production Menu Control), 9-56
brief check, 19-2 Collecting histogram data, 6-120
change execution setup, 19-14 Collection files (Production Menu Control), 9-37
change output setup, 19-15 counting total records, 9-40
change resource list, 19-38 creating collections, 9-39
create static configuration, 19-43 creating menu items, 9-40
custom runs, 19-34 deleting collections, 9-40
fast load, 19-11 renaming collections, 9-39
full check, 19-2 selecting field values, 9-40
global commands, 19-41 COLLECTION_MENU keyword (Production
groups, 19-3 Menu Control), 9-41, 9-57
help, 3-26 COLLECTIONS keyword (Production Menu
IMAGE Solutions V8.3 Index-5
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Control), 9-56 Conditional compiling, 5-5, 5-18, 13-9, 14-6
Color compiler flags, 5-18
debug displays, 7-53 directives for, 13-9
in Real Time Wafermap, 10-4 SUN3 and SUN4, 5-19
printing, 3-20 confchanges files, 4-1, 4-18
Color Manager, 3-41 viewing, 4-14
Color Monitoring Unit, see CMU Configuration board description files, 4-5, 4-11
Color printing of windows, 3-40 viewing, 4-12
Color properties, 3-40 Configuration check, reading, 26-55
COMMAND keyword, 8-22, 8-34 Configuration of hardware, checking, 4-18
COMMAND keyword (Production Menu Control), Configuring IMAGE, 3-8, 4-1
9-23, 9-27, 9-57 confsim files, 3-17, 4-1, 12-1
Command lines, 3-14 default, 4-4
passing parameters, 5-23 directory, 3-36
test programs, 26-400 editing, 4-7
Command mode code, 26-351 initializing, 4-15
Command switches, 2-19 licenses, 3-61
Comments location, 4-3
in test programs, 13-6 reading, 3-9, 4-5
COMMON_DIR environment variable, 8-26 selecting, 4-4
communications button and command, 8-13 viewing contents, 4-8
Comparing files, 2-26 writing, 4-6
Compile button, 7-24 Console window, 3-4, 8-6, 8-16
compile command, 7-23, 7-26 tester output action, 3-36
compilemenu command, 8-20, 8-42 Constants, 13-11
Compiler directives, cont button and command, 7-18, 8-13
5-18, 7-8, 7-26, 7-27, 13-4, 13-9, 14-4 Continue on error program termination mode,
Compiler flags, 5-5, 5-19 5-24, 5-25, 15-35
global, 5-18 Continue on fail program termination mode,
listing, 5-19 5-24, 5-25
local, 5-18 continue statement, 13-19, 13-23
Compiler, standalone, 7-38 Control keys, 2-2
Compiling, 7-23 Control panels, 3-12, 3-13, 8-6
auto-compile, 7-24 customizing, 3-47, 8-10
conditional, 5-5, 5-18 Control-C command, 5-27, 7-11, 7-17, 7-65
control, 7-24 controlling datalog sampling, 6-75
diagnostic messages, 7-39 Conversion characters
duplicate, 7-26, 7-27 datalog, 6-75
errors, 7-25 scanf function, 16-8
in debug, 7-24 Conversion functions, IMAGE, 26-540
in edit, 7-25 degrees to radians, 26-217
into object files, 7-42 double to int, 26-39
recompilation, 7-26 radians to degrees, 26-207, 26-208
Computer-aided test development, see CATD Conversion specification, printf, 6-76, 16-5
IMAGE Solutions V8.3 Index-6
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
convert_alaw_to_float function, 26-541 Customizing IMAGE
convert_analog_to_alaw conversion function, /custom directory, 29-1
26-542 control panel, 8-10
convert_analog_to_ulaw conversion function, datalog filters, 6-82
26-542 Help window, 3-27
convert_double_to_frac conversion function, IMAGE Control window, 3-33
26-540 IMAGE Workspace menu, 3-44
convert_float_to_frac conversion function, 26-541 menus, 8-10, 8-20
convert_frac_to_double conversion function, production mode, 8-8
26-540 station monitor window, 8-50
convert_frac_to_float conversion function, 26-540 station window buttons, 3-47, 8-10
convert_ulaw_to_float conversion function, station window control panel, 3-47
26-541 summary filters, 6-103
Copying files, 2-23
Copyright information, 3-10 D
cp command, 2-23 da_3rd_order_imd function, 27-14
Cp index, in summary statistics, 6-7, 6-9, 6-105 da_3rd_order_imd_full function, 27-15
Cpk index, in summary statistics, 6-7, 6-9, 6-105 da_aint function, 27-16
CPU speed, and test program timing, 15-2 da_amplitude function, 27-16, 27-130
CPU type, reading, 24-15 da_amplitude_full function, 27-17
CREATE_COLLECTION keyword (Production da_best_fit_ramp function, 27-17
Menu Control), 9-39, 9-58 da_best_fit_sine function, 27-18
Creating directories, 2-20, 2-21 da_best_fit_sine_full function, 27-19
Creating files, 2-22 da_best_fit_slope_and_offset function, 27-20
Creating generic datastreams, 6-48 da_best_fit_slope_and_offset_full function, 27-21
Creating new test programs, 5-3, 5-5 da_blkman function, 27-22
versions, 7-33 da_cdotpr function, 27-22
.cshrc file, 2-29 da_cfft function, 27-23
CUM_HYIELD_ALARM keyword, 8-62 da_cfftb function, 27-24
CUM_LLIM keyword, 8-60 da_cifft function, 27-24
CUM_LYIELD_ALARM keyword, 8-62 da_cifftb function, 27-25
CUM_ULIM keyword, 8-60 da_complex_spectrum function, 27-26
Cumulative yield, 8-7, 8-17, 8-55 da_conv function, 27-27
Cumulative yield by site, 8-55 da_corr function, 27-28
CUR_HYIELD_ALARM keyword, 8-62 da_cosine function, 27-28
CUR_LLIM keyword, 8-60 da_cvcomb function, 27-29
CUR_ULIM keyword, 8-60 da_cvconj function, 27-30
Current data collection directory, displaying, 6-46 da_cvexp function, 27-30
Current working directory, 2-6, 2-17 da_cvmags function, 27-31, 27-129
Current yield, 8-7, 8-17, 8-55 da_cvrcip function, 27-32
by site, 8-55 da_dB function, 27-32
custom directory, 29-1 da_dbcon function, 27-32
Custom Profiler, 5-39, 5-41, 5-45 da_decimate function, 27-33
custom.menu file, 3-27 da_define function, 27-34
IMAGE Solutions V8.3 Index-7
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
da_dotpr function, 27-34 da_merge function, 27-61
da_double_to_frac function, 27-35 da_minmgv function, 27-62
da_dpsp function, 27-35 da_minv function, 27-63
da_enob_best_fit function, 27-36 da_multitone function, 27-63
da_enob_snr function, 27-37 da_null_window function, 27-64
da_enob_snr_full function, 27-38 da_offset_binary_to_real function, 27-65
da_expand function, 27-38 da_peak_to_peak function, 27-65
da_fft function, 27-39, 27-128 da_phase function, 27-66
da_fftb function, 27-40 da_phase_full function, 27-66
da_fix32d function, 27-41 da_phase_gain_change function, 27-67
da_flt32d function, 27-41 da_phase_gain_change_full function, 27-68
da_frac_to_double function, 27-42 da_phase_noise function, 27-69
da_frac_to_real function, 27-42 da_phase_noise_full function, 27-70
da_free function, 27-43 da_polar function, 27-71
da_get_domain function, 27-44 da_power_spectrum, 27-129
da_get_Fs function, 27-44 da_power_spectrum function, 27-72
da_get_Ft function, 27-45 da_print_darray function, 27-73
da_get_lifetime function, 27-45 da_pulse function, 27-73
da_get_number_samples function, 27-45 da_ramp function, 27-74
da_get_size function, 27-46 da_ramp_dnl function, 27-75
da_get_type function, 27-46 da_ramp_dnl_and_inl function, 27-75
da_get_vector function, 27-46 da_ramp_inl function, 27-76
da_hamm function, 27-47 da_real_to_frac function, 27-77
da_hamming_window function, 27-47 da_rect function, 27-77
da_hann function, 27-48 da_rfftsc function, 27-78
da_hanning_window function, 27-48 da_rmmul function, 27-81
da_hd function, 27-49 da_rms function, 27-82
da_hd_full function, 27-49 da_rmsqv function, 27-82
da_hist function, 27-50 da_rmtran function, 27-83
da_ifft function, 27-51 da_set_Fs function, 27-84
da_ifftb function, 27-52 da_set_Ft function, 27-84
da_imd function, 27-53 da_set_lifetime function, 27-84
da_imd_full function, 27-54 da_set_number_samples function, 27-85
da_lookup function, 27-55 da_sfdr function, 27-85
da_lveq function, 27-55 da_sfdr_full function, 27-86
da_lvge function, 27-56 da_sine_dnl function, 27-87
da_lvgt function, 27-57 da_sine_dnl_and_inl function, 27-87
da_lvne function, 27-57 da_sine_inl function, 27-89
da_lvnot function, 27-58 da_snr function, 27-89
da_maxmgv function, 27-59 da_snr_full function, 27-90
da_maxv function, 27-59 da_spdp function, 27-91
da_meamgv function, 27-60 da_sve function, 27-91
da_meanv function, 27-60 da_svemg function, 27-92
da_measqv function, 27-61 da_svesq function, 27-92
IMAGE Solutions V8.3 Index-8
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
da_svessq function, 27-93 da_vsdiv function, 27-120
da_thd function, 27-93 da_vsin function, 27-121
da_thd_full function, 27-94 da_vsma function, 27-121
da_triangle function, 27-95 da_vsmsa function, 27-122
da_triangular_window function, 27-96 da_vsmsb function, 27-123
da_vabs function, 27-96 da_vsmul function, 27-123
da_vadd function, 27-97 da_vsq function, 27-124
da_vam function, 27-97 da_vsqrt function, 27-125
da_vandi function, 27-98 da_vssq function, 27-125
da_vatan function, 27-99 da_vsub function, 27-126
da_vatan2 function, 27-99 da_vsum function, 27-127
da_vclip function, 27-100 dacldir command, 6-46
da_vclr function, 27-101 Data Collection Setup display, 6-14, 6-17
da_vcopy function, 27-101 control panel, 6-15
da_vcos function, 27-102 datalog criteria, 6-15, 6-20
da_vdiv function, 27-103 datalog format, 6-15, 6-22
da_veqvi function, 27-103 datalog options, 6-15, 6-24
da_vexp function, 27-104 datalog output, 6-15, 6-18
da_vexp10 function, 27-105 histogram items, 6-15, 6-120, 6-121
da_vfill function, 27-105 message area, 6-15
da_vfix function, 27-106 saving and loading, 6-17
da_vfloat function, 27-106 Data collection streams, 6-77
da_vfloatd function, 27-107 Data collection streams, see Datastreams
da_vifix function, 27-107 Data directory, setting, 3-37, 6-46, 6-102, 8-47
da_vimag function, 27-108 Data initialization, 26-539
da_vlim function, 27-108 Data organization, 6-3
da_vlog function, 27-109 Data protection code, reading, 26-330
da_vlog10 function, 27-109 data setup button, 3-13, 6-13, 6-91, 8-12
da_vma function, 27-110 Data space in test programs, 5-22, 5-37
da_vmax function, 27-111 Data types in IMAGE, 13-11
da_vmaxmg function, 27-111 Databits
da_vmin function, 27-112 read, 26-56, 26-57
da_vminmg function, 27-113 unlock, 26-174
da_vmsa function, 27-113 Datalog
da_vmsb function, 27-114 alarms, 22-3
da_vmul function, 27-115 analog tests, 6-38
da_vneg function, 27-115 auto checker run, 19-25
da_vori function, 27-116 begin new device, 26-177
da_vpoly function, 27-117 change format, 26-510
da_vramp function, 27-117 change test number, 26-509
da_vreal function, 27-118 changing in production mode, 8-31
da_vrvrs function, 27-118 checkpoint frequency, 6-37
da_vsadd function, 27-119 criteria, 6-20
da_vsbm function, 27-120 default printer, 3-39
IMAGE Solutions V8.3 Index-9
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
digital tests, 6-38 datalog command, 6-13, 6-31, 24-2
directory, specifying, 3-37, 6-46 Datalog Output window, 6-24, 6-25
disk usage setup, 26-355 Datalog reports, 6-13
disqualify binning, 15-10 brief format, 6-13, 6-41
dump output, 6-46, 26-190 command line options, 6-83
enable and disable, 26-357 fields, 6-46
Enhanced Functional, 6-26 full format, 6-41, 6-42
failing tests, 3-38, 6-92, 6-97 graphical user interface options, 6-22
filters, 6-82 one line format, 6-41
format, 6-23, 14-14, 14-16, 14-24, 24-25 pin spacing, 6-23, 6-83
in test statements, 14-18, 14-21 pins per line, 6-32
intermediate values, 26-175 test program control, 6-75
labels, 14-12, 14-16, 14-24 width, 6-23
leakage, 6-24 writing, 14-24
list files, 6-40 Datalog result format, 14-12
list parameters, 6-21, 6-33 Datalog screen (Production Menu Control), 9-31
monitoring disk space, 6-84 datalog statement, 14-24
output, 3-14, 6-37, 6-41 Datalog test list file, 6-40
histogram files, 6-123 DATASERV_HOST environment variable, 8-26
selection, 6-37 datastream command, 6-48, 24-2
output window, 6-24 Datastream Setup window, 6-17, 6-48
overflow output of integers, 6-77 Datastreams, 6-48, 6-77
pausing, 6-34, 26-303, 26-358 add, 26-143
properties, 3-38 change setup, 26-170
read directory, 26-203 directory, specifying, 6-56
read format, 26-320 get directory, 26-204
read state, 26-199 get filename, 26-223
read test numbers, 26-318 get names, 26-200
reading file names, 8-48 get sampling rate, 26-223
reports writing, 26-41, 26-42 get test criteria, 26-221
resuming, 6-34, 26-341 leakage, 6-52, 6-55
sampled, 6-22, 6-33, 6-47, 6-51 output, 6-49, 6-54, 6-56
setup, 6-14, 6-31 remove, 26-340
showing setup, 6-36, 6-77 sampled, 6-54
test program control, 6-57, 26-352 sending files to FIRMS, 3-38
test program variables, 6-76, 14-24 sending to STDF file, 6-49, 6-54
test selection, 6-20 setup, 6-48, 6-53
text strings, 6-76 setup window, 6-48
to PMC, 6-38 test program control, 26-143, 26-170, 26-340
to STDF, 6-37 test selection, 6-49, 6-54
turning off, 6-34 wafer information, 6-55
update collection states, 26-431 date command, 2-16
wafer information, 6-22, 6-37 DC subsystem
wafer mapping, 10-34 alarms, 22-10
IMAGE Solutions V8.3 Index-10
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
calibration, 21-6, 21-7, 21-30, 21-38, 26-178 Decrement operators, 13-16
digitizing, 26-180 #define compiler directive, 7-26, 14-5
read calibration status, 26-179, 26-180 Delays
simulator database, 12-3 executing, 26-182, 26-504
DC voltmeter delete button and command, 5-30
calibration, 26-177, 26-178 Delete current setup menu item, 8-18
read measurements, 26-72 DELETE_COLLECTION keyword (Production
reading, 26-73, 26-296 Menu Control), 9-40, 9-59
return calibration status, 26-181 Deleting breaktraps, 7-14
return status, 26-296 Deleting directories, 2-20
set delays, 26-327 Deleting files, 2-23
simulation, 12-2 from printer queue, 2-24
Debug, 3-14, 7-1 Deleting test programs, 5-30
alarms, 22-21 Desktop Intro menu item, 3-6, 3-25
change auto mode, 26-168 DETACH keyword (Production Menu Control),
displays, 7-47 9-59
entering, 5-2, 5-3, 5-5, 7-2, 21-17 Determining if bin open or closed, 26-49, 26-69
.load files, 5-9 device command, 8-7
running test program, 5-25 Device Focussed Checkers, 20-1
source files, 7-3 DC module, 20-12
station window, 7-3 DFC compiler, 20-6
debug button, 3-13 HSD50 module, 20-10
debug button and command, 7-2, 8-12 PLFDIG module, 20-9
Debug displays, 7-47 PLFSRC module, 20-8
bring up automatically, 7-48 user callable functions and definitions, 20-4
change default site number, 26-170 Device ID, 5-22, 26-251, 26-329, 26-355, 26-370
color, 7-53 Device interface board IDs, see DIB ID
controls, 7-49 Device lots, 6-3
difference from stored state, 7-53 closing, 6-11, 8-20, 26-193
error conditions, 3-36, 7-54 displaying information, 6-8, 6-11
get site number, 26-181 incrementing, 6-4
help, 3-26 lot ID, 6-3, 6-5, 6-7, 6-8, 26-326, 26-535
IMAGE ExPress, 7-49 mode code, 26-318, 26-369
Immediate window, 7-64 operator name, 6-6, 6-8
interactive, 7-48 part type, 6-6, 6-8, 26-373
Simdbase window, 12-4 process ID, 6-6, 6-8, 26-375
size, 3-36 read lot ID, 26-323
variables display, 7-56 read number of parts tested, 26-329
debugplaces utility, 7-48 read start time, 26-333
Decimal integers, 13-11 read sublot ID, 26-323, 26-331
Declarations, in a function, 13-7 retest code, 6-8, 26-331, 26-378
DECLARE_VARIABLE keyword, 8-25, 8-34 set disposition code, 26-357
DECLARE_VARIABLE keyword (Production set information string, 26-384
Menu Control), 9-22, 9-58 set lot ID, 26-368, 26-534
IMAGE Solutions V8.3 Index-11
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
set operator name, 26-372 specifying load, 3-37, 8-46
set probe card ID, 26-356, 26-374 Disabling device testing, 14-22
set program name, 26-376 Disk Monitor window, 6-85
set protection code, 26-377 Disk Monitor, set datalog disk usage, 26-355
set sublot ID, 26-378, 26-534 Disk space, monitoring during datalog, 6-84
set test code, 26-381 diskmon command, 6-85
starting, 6-7, 8-19, 26-193 diskmon_config file, 6-86
starting new, 6-4, 26-155, 26-156 display button, 3-14, 7-1, 7-56, 7-64, 8-12
STDF files, 24-18 setting submenus, 3-34
sublot ID, 6-3, 6-5, 6-8, 6-9, 26-193, 26-535 Display current setup menu item, 8-18
supervisor name, 6-6, 6-8, 26-333, 26-381 DISPLAY environment variable, 8-26
test conditions, 6-6, 6-8, 26-382 DISPLAY keyword (Production Menu Control),
Device numbers, 6-10, 8-7, 8-16, 26-319, 26-329 9-60
Device sites, 17-3, 17-19, 17-21 Disposition code, 26-320, 26-357
device_bins declaration, 15-13 Disqualify binning, 14-16, 15-8
DIB ID, 26-529, 26-533 datalogging, 15-10
diff command, 2-26, 7-34 syntax, 15-8
Digital patterns test limits, 15-9, 15-10
breaktraps, 7-11 dlgfmt datalog filter, 6-41, 6-82
files, 5-11 double data type, 13-11
multisite test, 17-10, 17-29 Double quotes, in IMAGE, 13-6
Digital Signal Capture Memory do-while statement, 13-19, 13-21
alarms, 22-10 down command, 7-19
multisite testing, 17-14 DSim (Digital Simulator)
simulation of, 12-10 functions,
Digital Signal Processing, see DSP 26-230, 26-524, 26-525, 26-526, 26-527,
Digital Signal Source 26-528
alarm, 22-14 dsim command,
multisite testing, 17-14 26-230, 26-524, 26-525, 26-526, 26-527, 26
Digital Simulator, see DSim -528
Digital Subsystem DSP (Digital Signal Processing)
calibration, 21-6, 21-7, 21-31, 21-37 printing memory and buffer information, 26-187
get master clock frequency, 26-231 dsp buffer data type, 13-11
look up channel name, 26-231 DSSM (Digital Signal Source Memory)
look up pin name, 26-230 alarm, 22-14
read divider value, 26-232 DTR (Datalog Text Record), 24-13
set parametric testing, 26-229 dump_pinmap command, 4-11
Directories, 2-3, 2-20 Dumping datalog information, 6-46, 26-190
abbreviations, 2-27 Duplicate compiling, 7-26
branching structure, 2-3 DUT ID, request from handler/prober, 26-251
commands, 2-17
production mode, 8-46 E
read data, 26-203 edit command, 7-24
setting data, 3-37, 6-46, 6-102, 8-47 Edit history, 7-23, 7-33
IMAGE Solutions V8.3 Index-12
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Editing 3-2, 3-56, 3-73, 6-46, 6-102, 8-24, 8-26, 8-4
exiting, 7-29 7, 19-4
insertion point, 7-24 EPS (End Program Section Record),
test program, 7-23 6-77, 24-6, 24-13, 26-175
with breaktraps, 7-22 Error bins, specifying, 15-31
EDITOR environment variable, 8-26, 19-40 Error codes, handler/prober,
EFD (Enhanced Functional Datalog), 6-26 15-32, 15-34, 26-251, 26-252
adding setups, 6-34 Error message log files, 8-45
determining if enabled, 26-193 ERROR_FORCE_BIN error action code,
display, 6-17, 6-27, 6-30 15-32, 15-34
output format ERROR_FORCE_FAIL error action code,
default, 6-44 15-32, 15-34
one line, 6-44 ERROR_FORCE_HALT error action code, 15-31
two line, 6-45 ERROR_IGNORE error action code, 15-32, 15-34
removing setups, 6-36 ERROR_PRESET error action code, 15-32
restrictions, 6-30 Errors, ANSI C, 13-30
efddlgfmt datalog filter, 6-82 Errors, logging messages, 3-37
#else compiler directive, 13-9, 14-6 Errors, runtime, 15-31
Emergency halt, 2-35 debug displays, 3-36, 7-54
Enabling device testing, 14-22 debugging program, 15-35
END keyword, 8-12 defining, 15-34, 26-193
End Program Section Record, see EPS intercepting, 15-32
#endif compiler directive, 13-9 logging messages, 8-43
endlot button, 6-11, 8-6 messages, 8-43
Endlot signal, 6-11, 6-89, 6-93, 26-193 set message destinations, 26-370
and lots, 6-4 suppressing messages, 8-29
and sublots, 6-4 Event messages
STDF files, 24-2, 24-17, 24-23, 24-31, 24-32 sending to FIRMS, 26-181
eng button, 3-48, 8-5, 8-7, 8-12 .exec files, 7-28
engineering command, 3-48, 8-5 Execution times, test program, 5-31, 5-33
Engineering mode, 3-2, 3-14, 8-1 exit debug button, 7-37, 8-12
namestripe indicator, 3-12 EXIT keyword (Production Menu Control), 9-60
reading, 26-327 Exit menu item, 3-54
setting, 26-369 Exit, from IMAGE, 2-8, 3-11, 3-54, 3-55
engineering_station_buttons file, 3-47, 8-10, 8-13 exitdebug command, 7-37
Enhanced Functional Datalog exitedit command, 7-29
adding setups, 6-62 EXTENSION keyword (Production Menu Control),
controlling within a test program, 6-62 9-61
Enhanced Functional Datalog, see EFD External declarations, 7-27
.enterdebug file, 7-48 External variables, 13-4, 13-13, 14-4
Enumerations, 7-27, 7-59, 13-10
Environment modes, 3-2, 3-12 F
see also Engineering mode, Production mode Factory Integration and Resource Management
Environment variables, System, see FIRMS
IMAGE Solutions V8.3 Index-13
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Fail actions, 14-12, 14-15, 14-22, 15-7 pattern, 5-5, 5-9, 5-11
Fail bin setting, 26-157 renaming, 2-23
Failing tests source, 5-2, 5-11
breaktraps, 7-11 viewing, 2-23
datalog and summary, 3-38 waveform, 5-9
datalogging, 6-92, 6-97 Final summary reports, 6-89, 6-90, 6-93, 6-104
monitoring maximum consecutive, 15-16 find command, 2-25
showing first in production, 8-54 FIRMS (Factory Integration and Resource
sleep state, 17-23 Management System), 1-4
writing EPS record, 6-77 send datastream files, 3-38
Failing vectors, 6-27 send event messages, 26-181
FAR (File Attributes Record), 24-6, 24-14 send files, 3-38
Fast load, 5-6 send tester utilization events, 3-38
Fast load checkers, 19-11 store data, 6-38
fclose function, 16-2, 16-10 support for wafer mapping, 10-19
fflush function, 16-4, 16-15 use with IMAGE, 3-76
fgetc function, 16-13 FLEX License Manager, 3-56
field data type, 13-11 .flexlmrc file, 3-57
FIELD keyword (Production Menu Control), 9-61 float data type, 13-11
Field width specifier Floating point constants, 13-11, 13-17, 13-18
in datalog, 6-75 Floating Voltage Source, calibration, 26-196
in printf, 16-6 Flow control statements, 13-19
Fields Flushing the standard I/O buffer, 16-15
limitations in datalog reports, 6-46 FONT keyword, 8-11, 8-53, 8-59
specification in datalog, 6-75 Font, controlling in production mode, 3-34, 8-10
File Attributes Record, see FAR FONTSIZE keyword (Production Menu Control),
FILENAME keyword (Production Menu Control), 9-61
9-61 fopen function, 16-2, 16-10
Files, 2-22 for statement, 13-19, 13-20
adding to test program, 7-8 breaktraps, 7-21
appending, 2-22 Force next device to be a retest, 26-42
binary, 5-2, 5-5, 5-11 Forcing tests to pass or fail, 5-27
changing test program, 7-8 Formatting text files, 2-25
commands, 2-20 fprintf function, 16-2, 16-11
copying, 2-23 fputc function, 16-12
deleting, 2-23 Frames in functions, 7-19
.ibclog files, 5-16 free function, use in Solaris 2, 13-38
.image_behavior files, 5-13, 5-14 fscanf function, 16-2, 16-11
input and output, 16-10 ftoi function, 26-39
library, 5-5, 5-9, 5-11 FTR (Functional Test Result Record),
.load, 5-2 6-105, 24-6, 24-15
.make, 5-11, 5-12 Full format datalog reports, 6-41, 6-42
manipulating test program, 7-31 fulldlgfmt datalog filter, 6-41, 6-82
object, 5-5, 5-9 Function keys
IMAGE Solutions V8.3 Index-14
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
in debug, 3-34, 7-20 calibration, 21-7, 21-39
remapping, 3-47 Global variables, 13-4, 13-9, 13-11, 13-13, 14-4
Function Keys window, 7-21 cross-referencing, 7-9
FUNCTION keyword (Production Menu Control), handler/prober, 26-523
9-62 load command, 5-9
Functional Test Result Record, see FTR multisite test, 17-17
Functions, 13-7, 14-1 variables display, 7-61
ANSI C, 13-8, 13-36 GOOD_UNITS keyword (Production Menu
breaktraps, 7-11 Control), 9-62
calling, 13-8 goto statement, 13-19, 13-23, 17-7
calling sequence, 7-18 GPIB (General Purpose Interface Bus), 11-1
changing test program, 7-7 addresses, 11-3
cross-referencing, 7-9 cable issues, 11-18
FlexDSP, 27-1 commands, 11-2, 11-3
frames, 7-19 configuration issues, 11-18
header file, 14-4 control lines, 11-5
IMAGE base, 26-1 cut an action, 26-233
input and output, 16-1 dump information, 26-227
library, 13-38 error #41, 11-18
listing test program, 7-9 gpibcap file, 11-7, 26-227
main, 14-9 low-level programming, 11-15
multisite test, 17-6, 17-8 overview, 11-2
names, 13-7 programming, 11-10
obsolete, 26-519 programming examples, 11-13
passing parameters, 13-25 resetting, 3-36, 11-13
Production Menu Control, 9-43 send command to handler/prober, 26-240
prototyping, 13-33, 13-36 timeout, 11-18
sequencer, 14-2, 14-10 gpibcap file, 11-7, 26-227
test, 14-2, 14-11, 14-18 Grayscale, printing, 3-20
without pinmap, 14-26 grep command, 2-26
G H
GAP keyword, 8-11 halt button and command, 8-13
GEMsl halt command, 7-19
send string message, 26-346 halt_sys command, 2-34
General Purpose Interface Bus, see GPIB halt_tst command, 2-34
Generating histogram reports, 6-124 Halting
Generating summary reports, 6-89 test programs, 5-28, 7-19, 7-24
getc function, 16-2, 16-12 tester computer, 2-34
getchar function, 16-2, 16-4, 16-7 user computer, 2-34
Getting a character, 16-16 handcap database, 8-30
GFXPRINTER environment variable, 3-21, 3-39 show enabled options, 26-242
GigaDig Handler bins, see Hardware bins
alarms, 22-9 handler button, 8-7
IMAGE Solutions V8.3 Index-15
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Handler/prober set name, 26-363
abort probing, 26-236 set type, 26-364
adding production menu items, 8-30 setup, 5-6, 10-32
assign good die bins, 26-236 show connection status, 26-242, 26-243
autodisable, 26-184 show handcap options, 26-242
check input tubes, 26-243 unload wafers, 26-255
check output tubes, 26-247 wait for start, 26-521
clear alarms, 26-239 write to RS232 device, 26-345
close jaws, 26-245 Handler/Prober Monitor
close RS232 device, 26-343 printing, 26-255
detect connection, 26-243 handlerconf command, 8-7, 26-528
detect if enabled, 26-243 use in checking coordinates, 10-35
detect if handler, 26-244 use in setting up a wafer prober, 10-32, 10-35
detect if prober, 26-244 handlerprober_bin function, 26-39, 26-520
disabling handlerprober_init function, 26-39
on runtime error, 21-30 handlerprober_reset function, 26-40
effect on test time, 5-31 handlerprober_start function, 26-40, 26-521
execute an action, 26-233 Hardware Bin Record, see HBR
get error code, 26-251, 26-252 Hardware bins, 6-89, 15-6, 15-12
get error message, 26-252 get number, 26-220
get name, 26-211 monitoring consecutive failures, 15-18
get status information, 26-239 on histogram, 6-134
get type, 26-212 read device count, 26-211
global variables, 26-523 STDF files, 24-17
initialize interface, 26-39 wafer mapping, 10-3
load setup parameters, 26-244 Hardware configuration, checking, 4-18
load wafers, 26-245 HBR (Hardware Bin Record),
move absolute die, 26-245 24-7, 24-17, 24-31, 24-33
move relative die, 26-246 HCCS (High Current Current Source)
move relative machine, 26-246 connect to DUT, 26-395
move Z stage, 26-247 disconnect from DUT, 26-395
open jaws, 26-238 set compensation, 26-394
open RS232 device, 26-343 HCPS (High Current Power Source)
poll for start signal, 26-252 alarms, 22-11
probe card ID, 26-356, 26-374 HCPS (High Current Power Supply)
read from RS232 device, 26-345 calibration, 21-7, 21-40
read ID, 26-528 HCU (High Current Unit)
read PIB ID, 26-529 alarms, 22-11
request DUT ID, 26-251 calibration, 21-38, 26-235
reset interface, 26-40 HCVS (High Current Voltage Source)
send commands, 26-238, 26-253, 26-520 connect to DUT, 26-396
send GPIB commands, 26-240 disconnect from DUT, 26-396
send requests, 26-254 set compensation, 26-395
set ID, 26-529 Header files, 16-2
IMAGE Solutions V8.3 Index-16
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
adding, 7-8 data files, 6-78, 6-123
ANSI C, 13-38 directory, specifying, 6-123
during compiling, 7-26 files, merging, 6-139
limits, 14-4 generating, 6-124, 6-127
saving, 7-32 Histogram Tool window, 6-124
Header section, 13-3, 13-4, 14-3, 14-4 plot boundaries, 6-130
Help, 1-8 population limits, 6-130
customizing, 3-27 sample limits, 6-122, 6-123
IMAGE Help window, 2-6, 3-25, 3-26 setting parameters, 6-120, 6-122
IMAGE Solutions, 3-25, 3-26, 3-30 STDF files, 24-2
Quick Help, 3-25 zoom feature, 6-131, 6-132
Spot Help, 3-25 Histogram Save window, 6-128
UNIX and Sun, 2-6 Histogram Tool, 6-124
help button and command, 3-13, 8-12 changing data setup, 6-128
HELP control button (Production Menu Control), changing display characteristics, 6-129
9-10 control panel, 6-125, 6-126
HELP keyword, 8-22, 8-24, 8-34 display region, 6-125
HELP keyword (Production Menu Control), help, 3-26
9-26, 9-62 invoking, 6-126
HELPITEM_NAME keyword, 8-35 loading files, 6-127
HELPPATH environment variable, 8-26 statistical region, 6-125
Hexadecimal constants, 13-11 storing files from, 6-127
HFDIG (High Frequency Digitizer) histoplot command, 6-124, 6-135
read hpfilt, 26-322 History variable, 2-28
read voltage range, 26-66 histoset command, 6-120, 6-122, 24-2
simulator database, 12-3 STDF files, 24-2
High Current Current Source, see HCCS HOME control button (Production Menu Control),
High Current Unit, see HCU 9-10
High Current Voltage Source, see HCVS Home directory, 2-3, 2-6, 2-17
High Frequency Digitizer, see HFDIG HOME environment variable, 8-26
High Power Matrix, resetting, 26-256 HOME keyword (Production Menu Control), 9-63
High Power V/I Source, see HPVI Home menu (Production Menu Control), 9-24
High priority mode, 5-22 Hprintf function, 26-41
High Speed Digital Subsystem, see Digital HPVI (High Power V/I Source)
Subsystem clearing alarm, 26-396
High Voltage Ammeter, see HVA connect to DUT, 26-396
High Voltage Source, see HVS disconnect from DUT, 26-397
histodisp command, 6-134 resetting, 26-397
Histogram Data Setup window, 6-128 set gate enable bit, 26-397
Histogram Display Settings window, 6-130 setting, 26-398, 26-399
Histogram Load window, 6-128 HSS (High Speed Sampler)
Histogram plots, 6-120 calibration, 21-7, 21-40
ASCII, 6-135, 6-136 HUC ID PROM, 26-336, 26-512, 26-513
collecting data, 6-120 HVA (High Voltage Ammeter)
IMAGE Solutions V8.3 Index-17
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
read calibration status, 26-392 basics, 13-6
read calibration time, 26-392 configuring, 4-1
resetting, 26-391 Control window, 3-8
set connect bit, 26-390 controlling tester from remote sites, 3-70
setup, 26-399 customizing, 3-33
HVS (High Voltage Source) environment, 3-1, 3-4
connecting, 26-398 exit from, 2-8, 3-11, 3-54, 3-55
disconnecting, 26-398 Help window, 2-6, 3-26
invoking, 1-5, 2-7, 3-3
I licenses, 3-56
I_CURMENU environment variable, 8-26 passwords, 3-56
I_DONEFLAG environment variable, 8-26 running multiple copies, 3-74
I_MENUSTACK environment variable, 8-26 shell station feature, 3-73
I_RESPONSE environment variable, 8-26 Solaris 2, 13-29
I_STATION environment variable, 8-26 Spot Help, 3-25
I_STATUS environment variable, 8-26 standard buttons, 8-12
I_TMP1 environment variable, 8-26 station window, 2-8
I_TMP2 environment variable, 8-26 tester memory, 5-37
.ibclog files, 5-16 use on remote server, 3-67
icdterd license daemon, 3-56 use on Sun3, 3-68
Icons, 3-4 use on X platforms, 3-70
Abort Auto, 19-31 use with remote terminals, 3-67
station window, 3-12, 4-9 IMAGE Answers, see IMAGE Solutions
#if compiler directive, 13-9, 5-18 IMAGE Behavior Chooser, 5-12
IF_FAIL keyword, 8-35 IMAGE binary file type, determining, 7-43
IF_FAIL keyword (Production Menu Control), image command, 1-5, 3-2, 3-3, 8-5, 8-15
9-30, 9-63 IMAGE Control menu items, 3-6, 3-8
IF_FALSE keyword, 8-35 IMAGE Control window, 3-8, 4-2
IF_FALSE keyword (Production Menu Control), IMAGE environment, 3-33
9-30, 9-64 invoking, 3-8, 4-2
IF_PASS keyword, 8-36 menu items, 3-8
IF_PASS keyword (Production Menu Control), opening new station, 3-10, 3-16
9-29, 9-64 properties, 3-36
IF_TRUE keyword, 8-36 reading and writing files, 3-8, 4-3
IF_TRUE keyword (Production Menu Control), viewing configuration files, 3-9, 4-8
9-30, 9-65 viewing skeleton pinmaps, 3-9, 4-10
IFC signal, 3-36, 11-13 IMAGE ExPress, 7-49
#ifdef compiler directive, 13-9, 14-6, 5-18 debug controls, 7-49
#endif compiler directive, 14-6 error conditions, 7-54
if-else statement, 13-19, 13-20 help, 3-26
#ifndef compiler directive, 13-9 setup changes, 7-50
im_behavior command, 5-15 IMAGE Help window, 3-25, 3-26
IMAGE, 1-3 customizing, 3-27
base functions, 26-1 IMAGE Properties, 3-6, 3-9
IMAGE Solutions V8.3 Index-18
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
assert IFC, 3-36 .image-init file, 3-42, 3-2, 7-48, 8-4
automatic login, 3-34 .image-menu file, 3-42
changing load menu, 3-35 imagesolutions command, 3-26, 3-30
color, 3-40 .image-tools file, 3-68
configuration options, 3-36 .image-xinitrc file, 3-43
console options, 3-36 imm command, 7-66
data directory, 3-37, 6-46, 6-102 Immediate commands, 7-64
debug window size, 3-36 station window, 7-66
displaying tests in datalog summaries, 3-38 using with custom buttons, 7-66
error and alarm messages, 8-43 Immediate window, 7-64
function keys, 3-34 changing prompt, 7-66
Immediate window feedback, 3-36 control panel, 7-64
insertion point during editing, 3-35 errors, 7-65
menu item, 3-9 feedback, 3-36
printing, 3-39 immedwin command, 7-64
production font, 3-34, 8-10 #include compiler directive,
production load directory, 3-37 7-8, 7-27, 13-4, 14-4, 16-2
Production Menu Control, 3-34 INCLUDE keyword, 8-11
production mode, 8-2, 8-46 Increment operators, 13-16
Reboot always item, 19-30 Incremental recompile, 7-26
rebooting for auto checker, 3-38 Incrementing lots and sublots, 6-4
scrollable station window, 3-18, 3-35 initialize command, 4-15
sending files to FIRMS, 3-38 Initialize menu item, 3-6, 3-9, 4-16
setting menu options, 5-12 Initializing
source window, 7-5 data, 26-539
source window iconify behavior, 3-35 handler interface, 26-39
STDF, 3-39 sites, 15-17, 26-291
tester utilization events, 3-38 test programs, 26-283
window, 3-33, 3-34, 8-47 test system, 4-4, 4-15
IMAGE Solutions, 3-25, 3-26, 3-30 variables, 13-12
IMAGE Test Language modules, 5-5, 5-9 Ink bins, 26-237, 26-339, 26-364, 26-386
Image Window Printing display, 3-19 Inkers
IMAGE Workspace menu, 3-5, 3-44 retrieve number, 26-212
.image_behavior files, 5-13, 5-14 Inking, wafer mapping, 10-23
image_disk_warning file, 6-88 Input adjust function, 15-20, 26-283
IMAGE_GRAPHICS environment variable, Input and output
3-73, 8-26 file, 16-10
image_props command, 3-33 functions, 16-1
image_sun3 script, 3-69 special functions, 16-15
IMAGEBIN environment variable, 3-2, 8-26, 29-1 standard library functions, 16-2
imagecontrol command, 3-8 string, 16-14
imageexit command, 3-54, 3-55 terminal, 16-4
listing copies of IMAGE, 3-74 Insertion point during editing, 3-35, 7-24
IMAGEHOST environment variable, 8-26 Instruments, help, 3-26
IMAGE Solutions V8.3 Index-19
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
int data type, 13-11 Production Menu Control, 9-43
Integer overflow, setting output, 6-77 Solaris 2, 7-28, 13-38
Interactive debug displays, 7-48 SUN3 and SUN4 files, 7-28
Inter-IC Control bus, 26-258–26-282 library command, 7-23, 7-45
Intertest time, 5-31 Library functions, 13-38
Invoking IMAGE, 1-5, 2-7, 3-3 Licenses, IMAGE, 3-56
itlc command, 5-18, 7-38 administering, 3-57
for options, 3-62
J license file, 3-63
Job I/O screen (Production Menu Control), 9-31 logging activity, 3-65
job_station_mode event, 26-327 node locking, 3-65
path ($LM_LICENSE FILE environment
K variable), 3-56
Keyboard polling, 16-16 path (.flexlmrc file), 3-57
Korn shell, 2-30 removing, 3-59
rereading the license file, 3-61
reserving, 3-65
L
shutting down, 3-59
l_get_eng_id function, 26-209
simulator, 3-61
LABEL keyword, 8-59
tester, 3-63
LABEL keyword (Production Menu Control), 9-65
viewing status of, 3-57
Labels
Licensing
datalog statement, 14-24
Performance-on-Demand, 3-57
Landscape images, printing, 3-22
Limits, see Test limits
Languages, using in production mode, 8-31
Line number traps, 7-11
Large Vector Memory, alarm, 22-14
Line numbers, selecting, 7-10
LAST_BIN keyword (Production Menu Control),
Line wrap, changing, 7-10
9-66
Linear test time example, 5-32
LAST_SORT keyword (Production Menu Control),
lint, 7-38
9-66
list command, 7-9
LCA (Low Current Ammeter)
List file in datalog, 6-40
alarms, 22-14
List traps menu item, 7-13
calibration, 21-7, 21-41, 26-294
Listing
LD_LIBRARY_PATH environment variable, 8-26
breaktraps, 7-13
Leakage datalog, 6-24, 6-43
compiler flags, 5-19
LFAC Dual Channel Card
directories, 2-19
suppressing functionality, 4-19
test program functions, 7-9
LFACDIG (Low Frequency AC Digitizer)
versions of a test program, 7-33
alarms, 22-9
listtrap command, 7-13
read voltage range, 26-69
LM_LICENSE_FILE environment variable,
simulator database, 12-3
3-56, 8-26
LFACSRC (Low Frequency AC Source)
lmdown command, 3-59
get crest factor, 26-288
lmgrd license daemon, 3-56
Libraries, 7-45
lmremove command, 3-59
files, 5-5, 5-9, 5-11
IMAGE Solutions V8.3 Index-20
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
lmreread command, 3-61 using Load window, 5-2
lmstat command, 3-57 using menus, 8-19
load button, 3-13, 5-2 Local variables, 13-11, 13-13
changing menu, 3-35 stack space, 5-38
setting submenus, 3-34 variables display, 7-61
load button and command, 5-2, 7-2, 8-12 Locating files, 2-25
conditional compiling options, 5-18 Locking a workstation, 3-7
load command, 5-4, 7-2, 26-324 Lockout mechanism in production mode,
Behavior Chooser, 5-13 8-5, 8-16
multisite test, 17-20 Logical operators, 13-15
production mode, 8-47 .login file, 2-29, 8-4, 8-16, 2-29
setting up handlers and probers, 5-6 Login procedure, 2-6, 3-12, 3-23
setting up wafer prober, 10-33 Login prompt, 1-5, 3-12, 3-23
with autocalibration, 5-11, 21-18 Login screen, 2-7
with checkers, 19-6, 19-10 LOGNAME environment variable, 8-26
Load directory, for production mode, 3-37, 8-46 logout command, 2-9, 3-23
Load file menu item, 7-35 Logout procedure, 2-8
.load files, 5-2, 5-9, 5-11 loop command, 5-23, 5-26
and pattern files, 5-9 Looping, 5-26, 5-28, 13-19, 13-20
Behavior Chooser, 5-13 control, 16-16
binary files, 5-9 in ANSI C, 13-31
debug, 5-9 to breaktraps, 7-15, 7-16
IMAGE Test Language modules, 5-9 lot command, 6-9, 8-7, 26-326, 26-331
library modules, 5-9 STDF files, 24-4
object modules, 5-9 Lot ID, 6-3, 6-5, 6-7, 6-8, 26-326
source files, 5-9 incrementing, 6-4
standalone compiler, 7-39 reading, 26-323
wafer mapping, 10-33 setting, 26-368, 26-534, 26-535
wave files, 5-9 station monitor window, 8-7, 8-16
Load test program window, 5-3, 7-2 Lot retest code, reading, 26-331
Load time, reading, 26-332 Lot Setup Manager, 6-5, 6-15, 15-27
load_file command, 7-23, 7-35 Lot start time, reading, 26-333
LOAD_MDL_FILE keyword (Production Menu Lots, see Device lots
Control), 9-66 Low Current Ammeter, see LCA
Loading files in debug, 7-34 Low Frequency AC Digitizer, see LFACDIG
Loading test programs, 1-6, 5-2 Low Frequency AC Source, see LFACSRC
changing menu, 3-35 lpq command, 2-24
entering debug, 7-2 lpr command, 2-24
fast load, 5-6 lprintf function, 6-76, 14-24, 26-41, 26-42
multisite test, 17-10, 17-20 and STDF files, 24-13
setting properties, 5-12 lprm command, 2-24
tester utilization events, 5-35 ls command, 2-19
using drag and drop, 5-4 lsflags command, 5-19
using load command, 5-4 Lvalues, 13-30
IMAGE Solutions V8.3 Index-21
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
M MDL_BTN_NEXT variable (Production Menu
Macro definitions, 13-4, 13-9, 14-4 Control), 9-10
for Solaris 2, 13-29 MDL_BTN_PREV variable (Production Menu
main function, 13-3, 13-4, 14-3, 14-9 Control), 9-10
multisite test, 17-6 MDL_BTN_RUN variable (Production Menu
without pinmap, 14-26 Control), 9-10
.make files, 5-11, 5-12 MDL_EXEC_TYPE variable (Production Menu
malloc data space in test programs, 5-38 Control), 9-12
malloc function, 13-38 MDL_JOBNAME variable (Production Menu
man command, 2-6, 3-25 Control), 9-12, 9-14
MANPATH environment variable, 8-26 MDL_JOBNUM variable (Production Menu
Manuals, online, 3-30 Control), 9-12
Master Alarm Enable, 22-3 MDL_JOBPATH variable (Production Menu
Master Clock, GPIB address, 11-4 Control), 9-12, 9-14
Master Information Record, see MIR MDL_JOBREV variable (Production Menu
Master Results Record, see MRR Control), 9-12
Matching characters, 2-20 MDL_JOBSTATE variable (Production Menu
max_consec_fail_dev command, 15-18 Control), 9-13
Maximum Consecutive Failing Device monitor, MDL_LOT_ID variable (Production Menu
15-16 Control), 9-13
choosing software or hardware bins, 15-18 MDL_OPER_NAME variable (Production Menu
disable sites, 26-290 Control), 9-13
disabling sites for, 15-18 MDL_PERIPHERAL_ID variable (Production
initialize sites, 26-291 Menu Control), 9-13
initializing sites, 15-17 mdl_startup function, 9-24
monitor hardware bins, 26-292 MDL_SUBLOT_ID variable (Production Menu
monitor software bins, 26-293 Control), 9-13
resetting, 15-18, 26-290 MDL_SUPV_NAME variable (Production Menu
return state, 26-292 Control), 9-13
turn on and off, 15-17, 26-293 MDL_SVC_JOBIO variable (Production Menu
user function, 26-433 Control), 9-34
MDF (Menu Description File), 9-3, 9-46 MDL_TEST_CODE variable (Production Menu
sample file, 9-15 Control), 9-13
MDL (Menu Description Language), 9-1, 9-46 MDL_TESTER_TYPE variable (Production Menu
MDL_BTN_ABORT variable (Production Menu Control), 9-13
Control), 9-10 MDL_USR_HOMESCR variable (Production
MDL_BTN_BACK variable (Production Menu Menu Control), 9-13, 9-24
Control), 9-10 MDL_USR_INITSCR variable (Production Menu
MDL_BTN_HELP variable (Production Menu Control), 9-14, 9-24
Control), 9-10 MDL_WAFER_ID variable (Production Menu
MDL_BTN_HOME variable (Production Menu Control), 9-13
Control), 9-10 Measurements
MDL_BTN_MSG variable (Production Menu reading, 26-70, 26-71, 26-72, 26-73
Control), 9-10 Measurements, reading, 26-71
IMAGE Solutions V8.3 Index-22
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Memory Profiler, 5-39, 5-40, 5-42, 5-46 Mode code, 26-318, 26-369
Memory recompaction control, 26-295 more command, 2-23
Memory usage, 5-37, 5-40 Mouse, operating without, 8-15
Menu Description File, see MDF MOVABLE_WINDOWS keyword, 8-9
Menu Description Language, see MDL Mprintf function, 26-42
MENU keyword, 8-12, 8-21, 8-36 MRR (Master Results Record),
MENU keyword (Production Menu Control), 24-7, 24-23, 24-33, 26-384
9-25, 9-67 MSG control button (Production Menu Control),
Menu screens (Production Menu Control) 9-10
Datalog, 9-9, 9-31 Multiplexer, opening, 26-297
Job I/O, 9-9, 9-31 Multiplexing, and test time, 5-32
Runtime/Binning, 9-9, 9-34 Multisite testing, 17-1
MENU_DEFAULTS keyword, 8-36 advanced mixed-signal, 17-10
MENU_ITEM keyword, 8-22, 8-24, 8-36 disqualify binning, 15-11
MENU_ITEM keyword (Production Menu get bin number, 26-213, 26-218
Control), 9-27, 9-68 get site number, 26-181
menufile menu description file, 8-20, 8-30 loading test programs, 5-5
adding handler/prober items, 8-30 retrieve site value, 26-342
changing datalog, 8-31 serial blocks, 17-8, 17-24
compiler, 8-42 Simulator DataBase files, 12-2, 12-8
keywords for, 8-32 sites,
using different languages, 8-31 17-19, 17-21, 26-342, 26-388, 26-389, 26
menuprogram file, 8-42 -434
Menus sleep state, 17-21
customizing, 8-10, 8-20 wafer mapping, 10-3
setting submenus, 3-34 waking sites, 17-22
source window, 7-6 with digital signal source and capture, 17-14
temporary, 8-32 with match mode, 17-12
MERGE_COLLECTIONS keyword (Production without match mode, 17-11
Menu Control), 9-69 mv command, 2-23
merge_histo program, 6-139
Merging histogram files, 6-139 N
Messages to station monitor, 8-54 Names
MIR (Master Information Record), test program, 3-12, 3-13, 8-7, 8-16
6-105, 24-6, 24-18, 26-156, 26-186 Namestripe, 3-12
Mixed-signal Help window, 3-27
read and write conversion cage registers, source window, 7-5
26-514 station window, 3-12
read and write vector bus cage registers, Network node name, reading, 26-328
26-515 Network/user computer, 1-2
selecting head type, 5-3 New Station menu item, 3-6, 3-15, 3-23
test head registers, 26-513, 26-514 New Station windows, 3-15
mkdir command, 2-20 NEWROW keyword, 8-11
Mod-8 rule, 17-5, 17-10 newversion command, 7-23, 7-33
IMAGE Solutions V8.3 Index-23
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
next button and command, 7-18, 8-13 functions, 26-74
next_device_is_retest function, 26-43
NO_CHANGE_SCROLL keyword, 8-9 P
NO_QUIT keyword, 8-9 PACS (Precision AC Subsystem)
NOHELP_ERROR keyword, 8-37 amplitude calculation, 26-302, 26-388
Nongraphic characters, 13-12 multisite testing, 17-15
Nongraphics station window, see Shell station read clock frequency, 26-44, 26-93
NUM_COLS keyword (Production Menu Control), registers, 26-514
9-70 Page faults, recording,
5-40, 5-46, 26-520, 26-530
O Paging, 5-37
Object files, 5-5, 5-9 Parallel testing
see also Binary files see also Multisite testing
Solaris 2, 7-28 Parametric Test Result Record, see PTR
standalone compiler, 7-38, 7-42 Parentheses, in IMAGE, 13-6
standard SunOS, 7-42 Part Count Record, see PCR
SUN3 and SUN4, 7-28 Part count, reading, 26-329
Obsolete functions, 26-519 Part fix string, setting, 26-373
Octal constants, 13-11 Part Information Record, see PIR
One line format datalog reports, 6-41 Part Results Record, see PRR
Online documentation in IMAGE Solutions, 3-30 Part type, 6-6, 6-8, 26-330, 26-373
Open bins, 15-8, 15-12 Partial summary reports, 6-89, 6-93, 8-20
Opening station windows, 3-15 using menus, 8-20
OpenWindows properties, 3-6, 3-43 Parts tested, read number, 26-329
OpenWindows window system, 1-3, 3-2 Pass actions, 14-12, 14-15, 15-6
OPENWINHOME environment variable, 8-26 Pass bin, setting, 26-157
.openwin-init file, 3-2 Passing parameters, 5-21, 5-23, 13-25
oper2 login, 8-4, 8-15 passwd command, 2-15
Operational mode, reading, 26-327 Password file, IMAGE, 8-4, 8-16
operator account, 8-4 Passwords, 2-15, 3-56, 8-5, 8-16
operator command, 6-9, 8-8, 26-328 .pat files, 5-9, 5-11
STDF files, 24-4 PATH environment variable, 8-26
Operator name, 6-6, 6-8, 6-9, 26-328, 26-372 PATH II Test Head
operator2 account, 8-4, 8-16 selecting head type, 5-3
Operators, in IMAGE, 13-13 Path name, returning, 26-214, 26-217
OPTIONS keyword, 8-37 Paths, 2-4
OPTIONS keyword (Production Menu Control), relative, 2-5
9-26, 9-70 rooted, 2-5
Output, datalog, 6-37, 6-41 Pattern Editor
override_config command, 4-20 help, 3-26
Overwriting files, 2-22 Pattern files, 5-5, 5-9, 5-11
OVI (Octal V/I Source) in multisite test, 17-10
alarms, 22-12 multisite test, 17-29
calibration, 21-7 Pattern Generator Unit, see PGU
IMAGE Solutions V8.3 Index-24
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
PCR (Part Count Record), 24-7, 24-26, 24-33 functions, 9-43
PERCENT_BAD keyword (Production Menu libraries, 9-43
Control), 9-71 MDL keywords, 9-46
PERCENT_GOOD keyword (Production Menu menu screens, 9-9
Control), 9-71 modifying the product database, 9-4
Performance-on-Demand Licensing, 3-57 quitting, 9-6
PG UP/PG DN control button (Production Menu sample MDF, 9-15
Control), 9-10 starting, 9-4
PGDN keyword (Production Menu Control), 9-71 station window control, 9-4
PGU (Pattern Generator Unit), read memory size, station window properties, 3-34
26-304 PMCtool, 9-1
PGUP keyword (Production Menu Control), 9-71 initial screen, 9-24
PIB ID, reading, 26-529 starting, 9-4
Pin arrays, 26-284 pmctool command, 9-4
Pin Map Record, see PMR .pmctool_defaults file, 9-6
Pin names, 26-305 PMM (Precision Multimeter)
Pin numbers, 26-285, 26-305 alarms, 22-15
Pinmaps, 13-4, 14-6 calibration, 21-8, 21-44
compatibility with hardware, 4-18 connect to matrix, 26-149
create test modules without, 14-26 disconnect from matrix, 26-150
during compiling, 7-26 GPIB, 11-2, 11-4, 11-13
in multisite test, 17-2, 17-3 simulator database, 12-3
skeleton, 3-9, 4-10 PMR (Pin Map Record), 24-29, 26-186
viewing with IMAGE Control window, 4-10 Pointers, 7-59, 13-25
PIR (Part Information Record), 6-47, 24-6, 24-27 printing, 7-63
PLFDIG (Precision Low Frequency Digitizer) Population limits in histograms, 6-130
alarms, 22-9 Portrait images, printing, 3-22
calibration, 21-7, 21-16, 21-31, 21-43, 26-306 PostScript files
optimized setup for, 26-306 from a wafermap, 10-14
read voltage range, 26-94 printing to, 3-20
simulator database, 12-3 pr command, 2-25
PLFSRC (Precision Low Frequency Source) Precision AC Subsystem, see PACS
alarms, 22-9 Precision AC Subsystem, see PACSS
calibration, 21-8, 21-16, 21-31, 21-43, 26-306 Precision Low Frequency Digitizer, see PLFDIG
connect to delta bus, 26-306 Precision Low Frequency Source, see PLFSRC
connect to waveform bus, 26-312 Precision modifier, in datalog, 6-75
filter correction, 26-307, 26-308, 26-309 Precision Multimeter, see PMM
read input bits, 26-94 Preview file, 10-4, 10-13
Plot boundaries in histograms, 6-130 Print button, 3-19
PMC (Production Menu Control), 9-1 Print button and command, 7-63
command sequence, 9-10 PRINT keyword, 8-23, 8-37
control buttons, 9-9 PRINT keyword (Production Menu Control), 9-72
customizing, 9-6 PRINT_N keyword, 8-37
datalogging, 6-38 PRINT_N keyword (Production Menu Control),
IMAGE Solutions V8.3 Index-25
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
9-72 operating with menus, 8-2, 8-15, 8-19, 8-20
printenv command, 3-2 customizing, 8-20
Printer queue, 2-24 executing commands, 8-28
printf function, 6-76, 14-14, 14-24, 16-2, 16-4 finishing a lot, 8-20
conversion specification, 16-5 loading test programs, 8-19
field width, 16-6 main menu, 8-17
Printing, 2-24 overview, 8-17
color, 3-20, 3-40 starting IMAGE, 3-3, 8-15
default for datalog, 3-39 operating with mouse, 8-2, 8-5
DSP memory and buffer, 26-187 starting IMAGE, 3-3, 8-5
grayscale, 3-20 password file, 8-4, 8-16
landscape, 3-22 quitting windows, 8-9
portrait, 3-22 reading, 26-327
setting properties, 3-21 running test programs, 5-25
station windows, 3-23 setting, 26-369
string to summary report, 26-142 setting up files, 8-4
variables in station window, 7-63 standard directories, 8-46
wafermap, 10-14 station window control panel, 8-6
windows, 3-19 station windows, 8-3, 8-6
defaults, 3-39 switch between modes, 8-16
Priority mode, UNIX, 16-4 switch between windows, 8-6, 8-16
Prober coordinate system, 10-25 switch to engineering mode, 8-5, 8-42
Probing wafers, 26-250 using different languages, 8-31
Process ID, 6-6, 6-8, 26-330, 26-375 production_station_buttons file, 3-47, 8-10
prod button, 3-14, 3-48, 8-5, 8-12 production_window_info file, 8-8
production command, 3-48, 8-5 profile command, 5-41
Production Menu Control, see PMC Profiling
Production mode, 3-2, 3-14, 8-1 writing data from, 5-47
change to, 3-48 Profiling functions, 26-310, 26-311
changing scroll mode, 8-9 Profiling test programs, 5-39
common commands, 8-7 ProGen utility, 3-13, 7-38
customizing, 8-8 Program definitions (Production Menu Control),
control panel, 8-10 9-43
font, 8-10 Program name, setting, 26-376
station window control panel, 3-47 Programs menu item, 3-6
window sizes and positions, 8-8 Prompt, login, 3-23
data directory, 6-46, 6-102, 8-47 Properties
font, 3-34 IMAGE, 3-6, 3-33
load directory, 3-37, 8-46 OpenWindows, 3-6, 3-33
lockout, 8-5, 8-16 wafermap, 10-16
logging alarms and errors, 3-37 Properties menu item, 3-6
menu description file, 8-20 Properties window, IMAGE, 3-33
moving and resizing windows, 8-9 Protection code, setting, 26-377
namestripe indicator, 3-12 Protection for files and directories, 2-24
IMAGE Solutions V8.3 Index-26
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Prototypes, of functions, 13-33 read_cdig_failed function, 26-51
PRR (Part Results Record), read_cdig_failed_segment function, 26-52
6-47, 24-6, 24-27, 26-373 read_cdig_failed_slot function, 26-53
PTR (Parametric Test Result Record), read_cdig_n_fail_vectors function, 26-53
6-105, 15-11, 24-6, 24-24 read_cdig_n_fail_vectors_pin function, 26-54
Pulse Driver read_cdig_timing_range function, 26-55
calibration, 21-8, 21-45 read_cdig_timing_range_pin function, 26-55
putc function, 16-2, 16-12 read_configuration_status function, 4-19, 26-56
putchar function, 16-2, 16-4, 16-7 read_current_site function, 17-25, 26-56
pwd command, 2-17 read_databits function, 26-56
PWD environment variable, 8-26 read_databits_true function, 26-57
read_dps_amm_pin_status function, 26-57
Q read_dps_dib_ctrl_data function, 26-58
Quad Opamp channel card read_dps_low_i_n function, 26-59
alarms, 26-74, 26-297 read_dps_low_i_time function, 26-60
Quick Help, 3-25 read_dps_meter_pin_status function, 26-61
QUIT_MENU_ON_SELECTION keyword, read_dps_pin function, 26-62
8-32, 8-38 read_dps_pin_n function, 26-62
QUIT_MENU_ON_SELECTION keyword read_dps_pin_nostrobe function, 26-63
(Production Menu Control), 9-73 read_dps_pin_status function, 26-63
QUITITEM_NAME keyword, 8-38 read_dps_pin_time function, 26-64
Quotes, in the Bourne shell, 8-29 read_fail_vectors function, 26-65
QVS (Quad Voltage Source) read_funct_halt function, 26-65
alarms, 22-12 read_h50_code function, 26-66
calibration, 21-8, 21-45 read_h50_code_nac function, 26-66
read_hfdig_vrng function, 26-67
R read_hram_loc function, 26-67
.rauto file, 19-22 read_hram_scm function, 26-68
rdelay function, 15-2, 26-43 read_hsd50_results function, 26-68
rdelay_time function, 26-43 read_lfdig_vrng function, 26-69
read_ac_clock function, 26-43 read_lowest_bin_at_fail function, 26-70
read_ac_freq_pin function, 26-44 read_lowest_open_bin function, 15-11, 26-70
read_ac_vrng function, 26-44 read_measurement function, 26-70
read_ac_vrng_chan function, 26-45 read_measurement_n function, 26-71
read_ac_vrng_slot function, 26-45 read_measurement_nostrobe function, 26-71
read_apu function, 26-45 read_measurement_time function, 26-71
read_apu_pin function, 26-46, 26-521 read_measurement_time_and_n function, 26-72
read_apu_pin_multisite function, 26-47 read_meter function, 26-72
read_apu_pin_status function, 26-48 read_meter_n function, 26-73
read_apu_status function, 26-48 read_meter_nostrobe function, 26-73
read_bin_is_open function, 15-12, 26-49 read_meter_time function, 26-73
read_bin_is_pass function, 15-12, 26-49 read_meter_time_and_n function, 26-73
read_cdig_all_fail_vectors function, 26-50 read_opamp_loop_alarm function, 26-74
read_cdig_all_fail_vectors_pin function, 26-51 read_opamp_osc_alarm function, 26-74
IMAGE Solutions V8.3 Index-27
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
read_ovi_amm_pin_status function, 26-75 read_sitemask_failed_sequencer function,
read_ovi_amm_status function, 26-75 17-26, 26-96
read_ovi_i function, 26-76 read_sitemask_sleep function, 17-26, 26-96
read_ovi_i_n function, 26-77 read_spec function, 26-96
read_ovi_i_nostrobe function, 26-77 read_spec_max function, 26-97
read_ovi_i_pin function, 26-77 read_spec_min function, 26-97
read_ovi_i_pin_n function, 26-78 read_test_condition function, 26-98
read_ovi_i_pin_nostrobe function, 26-78 read_test_condition_name function, 15-30, 26-98
read_ovi_i_pin_time function, 26-79 read_test_status function, 14-20, 26-99
read_ovi_i_time function, 26-79 read_test_status_alarm function, 14-21, 26-99
read_ovi_meter_pin_status function, 26-80 read_tjd_sample_count function, 26-99
read_ovi_meter_status function, 26-81 read_tjd_status function, 26-100
read_ovi_r function, 26-82 read_tset_num function, 26-100
read_ovi_v function, 26-83 read_uwport_one_port function, 26-100
read_ovi_v_i function, 26-83 read_uwport_one_port_cal_std function, 26-101
read_ovi_v_i_n function, 26-84 read_uwport_one_port_cal_std_slot function,
read_ovi_v_i_nostrobe function, 26-84 26-103
read_ovi_v_i_pin function, 26-85 read_uwport_raw_one_port function, 26-104
read_ovi_v_i_pin_n function, 26-85 read_uwport_raw_one_port_slot function,
read_ovi_v_i_pin_nostrobe function, 26-86 26-103, 26-104
read_ovi_v_i_pin_time function, 26-87 read_uwport_raw_two_port_s11 function, 26-105
read_ovi_v_i_time function, 26-88 read_uwport_raw_two_port_s11_slot function,
read_ovi_v_n function, 26-90 26-106
read_ovi_v_nostrobe function, 26-90 read_uwport_raw_two_port_s21 function, 26-107
read_ovi_v_pin function, 26-91 read_uwport_raw_two_port_s21_slot function,
read_ovi_v_pin_n function, 26-91 26-108
read_ovi_v_pin_nostrobe function, 26-92 read_uwport_raw_two_port_s22 function, 26-109
read_ovi_v_pin_time function, 26-92 read_uwport_raw_two_port_s22_slot function,
read_ovi_v_time function, 26-93 26-110
read_ovi_vm_pin_status function, 26-88 read_uwport_two_port_cal_std_forward function,
read_pacs_clock function, 26-93 26-110
READ_PASSWORD keyword, 8-38 read_uwport_two_port_cal_std_forward_slot
READ_PASSWORD keyword (Production Menu function, 26-113
Control), 9-73 read_uwport_two_port_cal_std_reverse function,
read_plfdig_vrng function, 26-94 26-7, 26-115
read_plfs_integrator function, 26-94 read_uwport_two_port_cal_std_reverse_slot
read_proto_slot_reg function, 26-94 function, 26-117
read_qvs_low_i function, 26-95 read_uwport_two_port_s11 function, 26-118
READ_RESPONSE command, 8-25, 8-39 read_uwport_two_port_s11_slot function, 26-119
READ_RESPONSE keyword (Production Menu read_uwport_two_port_s12 function, 26-119
Control), 9-23, 9-74 read_uwport_two_port_s12_slot function, 26-120
read_sitemask_all function, 17-26, 26-95 read_uwport_two_port_s21 function, 26-121
read_sitemask_disabled function, 17-26, 26-95 read_uwport_two_port_s21_slot function, 26-122
read_sitemask_enabled function, 17-26, 26-95 read_uwport_two_port_s22 function, 26-122
IMAGE Solutions V8.3 Index-28
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
read_uwport_two_port_s22_slot function, 26-123 Reading open bin, 26-70
read_uwrecv_amp function, 26-124 Reading status of configuration check, 26-55
read_uwrecv_amp_array function, 26-125 Reading status of tests, 14-20
read_uwrecv_amp_array_slot function, 26-125 Reading Terabus address, 26-146
read_uwrecv_amp_byif function, 26-126 Reading test conditions, 26-98
read_uwrecv_amp_slot function, 26-127 Real Time Wafermap, 10-2
read_uwrecv_amp_slot_byif function, 26-128 color in, 10-4
read_uwrecv_cal_const function, 26-128 connecting to station, 10-4
read_uwrecv_cal_const_array function, 26-128 File menu, 10-13
read_uwrecv_cal_const_array_slot function, preview file, 10-4, 10-13
26-129 printing, 10-18
read_uwrecv_cal_const_slot function, 26-129 properties, 10-16
read_uwrecv_fs function, 26-130 scramble file, 10-4, 10-8, 10-13
read_uwrecv_fs_slot function, 26-130 setup, 10-2
read_uwrecv_if function, 26-130 starting, 10-3
read_uwrecv_if_slot function, 26-131 Station menu, 10-15
read_uwrecv_phase_noise_PSD function, view mask, 10-17
26-131 View menu, 10-14
read_uwrecv_phase_noise_PSD_array function, window, 10-10
26-131 writing test program, 10-9
read_uwrecv_phase_noise_PSD_array_slot Real Time Yiled Trend Monitor, 6-112
function, 26-132 Reboot always IMAGE Properties option, 19-30
read_uwrecv_phase_noise_PSD_slot function, reboot_sys command, 2-32
26-133 reboot_tst command, 2-33
read_uwrecv_PSD, 26-133 Rebooting, 2-32
read_uwrecv_PSD_array function, 26-134 before auto checker run, 3-38, 19-30
read_uwrecv_PSD_array_slot function, 26-134 tester computer, 2-33
read_uwrecv_PSD_slot function, 26-135 user computer, 2-33
read_uwrecv_sample_size function, 26-136 Recompiling, 7-26
read_uwrecv_sample_size_slot function, 26-136 Recovering errors, 7-36
read_uwrecv_uncal_amp function, 26-136 Recovering summary reports after power failure,
read_uwrecv_uncal_amp_array function, 26-137 6-104
read_uwrecv_uncal_amp_byif function, 26-138 Redirection of files, 2-22
read_uwrecv_uncal_amp_slot function, 26-138 Redirection operators, 2-22, 6-93
read_uwrecv_uncal_amp_slot_byif function, refresh command, 8-8
26-138 Relational operators, 13-14, 13-16
read_uwrecv_uncal_array_slot function, 26-137 Relative path, 2-5
read_uwrecv_uncal_PSD function, 26-139 Remote server, use with IMAGE, 3-67
read_uwrecv_uncal_PSD_array function, 26-140 Remote station window, 3-17, 3-72
read_uwrecv_uncal_PSD_array_slot function, Remote terminals, using IMAGE from, 3-67
26-140 Renaming files, 2-23
read_uwrecv_uncal_PSD_slot function, 26-141 Repeat value, 14-14
read_vmcu function, 26-142 repeat, in sequencer line, 14-17
Reading databits, 26-56, 26-57 Reserved words, 8-26
IMAGE Solutions V8.3 Index-29
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Resetting Runtime statistics, 5-22, 5-43
handler interface, 26-40 Runtime/Binning display screen (Production
RESULT_COLLECTION keyword (Production Menu Control), 9-34
Menu Control), 9-74 runtotrap command, 7-16
RESULT_VARIABLE keyword (Production Menu
Control), 9-40, 9-75 S
Retest code, 6-8, 26-331, 26-378 Safety signal, check if asserted, 26-403
Retest, forcing, 26-42 Sample limit
Retesting a device, 5-21 datalog, 6-22, 6-33, 6-52
Retrieve functions, multisite test, 17-18 histogram plots, 6-122, 6-123
retrieve statement, 17-17 Sample rate, datalog, 6-22, 6-33, 6-51
Return statement in a function, 13-7 Sampled datalog, 6-47
revert command, 7-23, 7-34, 7-37 save command, 7-23, 7-31
Reverting to older version of test program, save statement, 17-17
7-34, 7-37 Save test program menu item, 7-31
Revision ID, 6-6, 6-8, 26-324, 26-533 Save Workspace menu item, 3-44
rm command, 2-20, 2-23 Saving test program changes, 5-30, 7-31, 7-37
rmdir command, 2-20 Saving test programs, 7-31
Root directory, 2-3 SBCC (Serial Bus Channel Card)
Rooted path, 2-5 alarms, 22-16
ROW keyword (Production Menu Control), 9-75 calibration, 21-8, 21-30, 21-46, 26-168
RS232 interface check for stopped hardware, 26-515, 26-516
close device, 26-343 read failing vectors, 26-49, 26-50
open device, 26-343 read pattern failures,
read from device, 26-345 26-51, 26-52, 26-53, 26-54
sending commands, 26-253 set timing ranges, 26-55
set ink bins, 26-364 SBR (Software Bin Record), 24-7, 24-31, 24-32
write to device, 26-345 Scale factors, in IMAGE, 13-17
run button, 3-13 scanf function, 16-2, 16-4, 16-8, 16-11
run button and command, 5-21, 5-31, 8-6, 8-12 conversion characters, 16-8
RUN control button (Production Menu Control), SCHOME environment variable, 8-26
9-10 Scientific notation
Runtime errors, 15-31 in IMAGE, 13-11
changing default action, 15-31 variables display, 7-56, 7-58, 7-63
debug displays, 3-36, 7-54 Scramble file, 10-4, 10-8, 10-13
debugging program, 15-35 SCRIPT keyword (Production Menu Control),
defining, 15-34 9-76
intercepting, 15-32 Scroll bars, 3-12
logging messages, 8-43 Scrollable station window, 3-17, 3-35
messages, 8-43 command log, 3-18, 3-35
setting breaktraps, 7-11, 7-12, 7-13 enabling and disabling, 3-19, 8-9
stepping to, 7-17 selecting, 3-18
RUNTIME keyword (Production Menu Control), Scrolling, 2-2
9-75 SDB (Stored databits)
IMAGE Solutions V8.3 Index-30
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
alarms, 22-16 Serial blocks, 17-8, 17-24
reading, 26-56 Serial Bus Channel Card, see SBCC
.sdb files, 12-2 set all alarm statement, 22-3
SDR (Site Description Record), set bins close statement, 15-11
24-6, 24-30, 26-363, 26-364 set bins open statement, 15-11
Searching for files, 2-26 set button, 7-11, 8-13
SECS wafer map, 10-23 set error bin statement, 15-31
SECS/GEM set error default statement, 15-32
send string message, 26-346 set error force_bin statement, 15-31
secs_map command, 10-35 set error force_fail statement, 15-31
SEGMENT data type, 13-11 set error handler statement, 15-32
select command, 3-23, 8-6, 8-8 set error ignore statement, 15-31
Select datalog menu item, 8-18 set error statement, 15-36
Select handler/insertion menu item, 8-18 set history command, 2-28
Select lot id menu item, 8-18 set hsd cal_set statement, 21-37
Select test condition menu item, 8-18 set noclobber command, 2-22
Select test program menu item, 8-18, 8-19 set pmm cal_mode statement, 21-44
SELECT_FIELD keyword (Production Menu Set program termination mode menu item, 5-24
Control), 9-40, 9-77 set site_disable statement, 17-22
SELECT_SUBSET keyword (Production Menu set site_disable_all statement, 17-22
Control), 9-78 set site_enable statement, 17-22
Selecting stations, 8-19 set site_enable_all statement, 14-23, 17-22
SELECTION_ERROR keyword, 8-39 set site_sleep statement, 17-22
SELECTION_PROMPT keyword, 8-40 set site_sleep_all statement, 17-22
SEMF (Standard Event Message Format) set site_swap_sleep statement, 17-22
use with FIRMS, 3-76 set site_wake statement, 17-22
Semicolons, in IMAGE, 13-6 set site_wake_all statement, 17-22
Sending bin command to handler, 26-520 set sleep_mode statement, 17-23
Sequencer functions, set testf_cond statement, 14-21
13-3, 13-5, 14-2, 14-3, 14-10 set wafer statement, 10-9, 10-19
multisite test, 17-6 setauto command, 6-89, 6-96
profiling, 5-39 settrap command, 7-12, 7-13
STDF files, 24-4, 24-12, 24-34 setup button, 8-6
Sequencer Profiler, 5-39, 5-41, 5-43 Shared tester resources, 17-8
Sequencer statements, 14-11, 18-29 SHELL environment variable, 8-26
examples, 14-16 Shell station, 3-17, 3-73
Sequencers auto checker run, 19-32
compound, 14-12, 14-16, 14-20 opening, 3-16
disqualify binning, 15-8 starting IMAGE, 3-3
profiling, 5-39 Shell variables, 2-27
simple, 14-12, 14-19 Shell, see C shell
Simulator DataBase files, 12-7 Shift operators, 13-15
syntax, 14-12 short data type, 13-11
test conditions, 15-28 Show Caret at Top menu item in Source Window,
IMAGE Solutions V8.3 Index-31
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
7-24 Software bins, 6-89, 15-6, 15-12
show_tconfig command, 4-9 get number, 26-219
Showing datalog setup, 6-36 histogram, 6-135
showlot command, 6-11, 8-8 monitoring consecutive failures, 15-18
Sigma values read device count, 26-217
in histogram plots, 6-129, 6-135 STDF files, 24-31
in summary statistics, 6-7, 6-9, 6-105 wafer mapping, 10-3
simdbase command, 12-4 Solaris 2, 1-3
Simulator, 12-1, 26-435 ANSI C, 13-10
configuring, 4-1 binary files, 7-27, 7-31, 7-32, 7-35, 7-40, 7-43
licenses, 3-61 IMAGE, 13-29
simulating hardware measurements, 12-2 sort bin statement, 13-4, 14-9, 15-14, 26-329
simulation of capture memory, 12-10 multisite test, 17-6, 17-27
Simulator DataBase file, 12-2 Source files, 5-2, 5-5, 5-11, 13-2
Simulator DataBase adding, 7-8
compound sequencers, 12-7 in debug, 7-3
creating files, 12-4 saving, 7-32
display, 12-4 Source window, 3-12, 7-1, 7-3
examples, 12-6 changing insertion point, 3-35
files, 12-1, 12-5 control panel, 7-5
help, 3-26 editing, 7-23
looping tests, 12-8 help on, 3-26
multisite test, 12-2, 12-8 iconify behavior, 3-35
records, 12-5 menu, 7-6
Single quotes, in IMAGE, 13-6 message area, 7-5
Site Description Record, see SDR namestripe, 7-5
Site masks, 17-25 opening, 7-5
sites command, 17-19, 17-20, 26-388 text pane, 7-5
Sites in multisite test, viewing test programs, 7-7
5-5, 17-3, 17-19, 17-21, 26-388, 26-389, 26- SPACE keyword, 8-11
434 Spaces, in IMAGE, 13-6
change default, 26-170 Spot Help, 2-6, 3-29
get site number, 26-181 sprintf function, 16-3, 16-14
reading, 26-56 SPS (Synchronized Power Subsystem)
Simulator DataBase, 12-2, 12-8 alarms, 26-390, 26-391
wafer mapping, 10-3 disconnect from meter, 26-391
SIZE keyword (Production Menu Control), 9-79 resetting instruments, 26-398
Skeleton pinmaps, 3-9, 4-10 set gate bits, 26-391
Sleep state, 17-21 Sscanf function, 16-14
smprintf function, 6-105, 14-25, 26-142 sscanf function, 16-3, 16-14
snapshot option to halt command, 7-19 Stack space in test programs, 5-38
Snapshot tool, 3-23 Standalone compiler, 7-38
Software bin numbers, 5-22, 8-7, 8-16 .load files, 7-39
Software Bin Record, see SBR STANDARD, 8-13
IMAGE Solutions V8.3 Index-32
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Standard deviation, in summary statistics, Starting a device lot, 6-7
6-7, 6-9, 6-105 Starting IMAGE, production mode with menus,
Standard Event Message Format, see SEMF, 8-15
3-76 Starting testing, 26-155, 26-156
Standard production directories, setting up, 8-46 startlot button, 8-6
Standard Test Data Format, see STDF startlot command,
STANDARD_ABORT_BUTTON keyword, 8-12 6-7, 6-11, 6-106, 8-8, 15-27, 15-29, 26-328,
STANDARD_CATD_BUTTON keyword, 8-12 26-534
STANDARD_CHECKER_BUTTON keyword, STDF files, 24-19
8-13 STARTUP keyword, 8-25, 8-40
STANDARD_COMMUNICATIONS_BUTTON STARTUP keyword (Production Menu Control),
keyword, 8-13 9-79
STANDARD_CONT_BUTTON keyword, 8-13 Statements, in IMAGE, 13-6
STANDARD_DATAC_BUTTON keyword, 8-12 Static configuration, creating for checkers, 19-43
STANDARD_DEBUG_BUTTON keyword, 8-12 Static variables, 13-13
STANDARD_DISPLAY_BUTTON keyword, 8-12 station button, 8-7
STANDARD_HALT_BUTTON keyword, 8-13 station command, 3-16, 3-23
STANDARD_HELP_BUTTON keyword, 8-12 Station login prompt, 3-23
STANDARD_LOAD_BUTTON keyword, 8-12 Station monitor window, 8-7, 8-16, 8-49
STANDARD_LOOP_BUTTON keyword, 8-12 customizing, 8-50
STANDARD_NEXT_BUTTON keyword, 8-13 large font, 8-54
STANDARD_PROD_ENG_BUTTON keyword, messages, 8-54
8-12 selecting fonts, 8-53
STANDARD_RUN_BUTTON keyword, 8-12 showing first failure, 8-54
STANDARD_SETTRAP_BUTTON keyword, 8-13 writing, 26-399
STANDARD_STEP_BUTTON keyword, 8-13 yield monitor, 8-54
STANDARD_TOTRAP_BUTTON keyword, 8-13 Station number, 3-12, 3-14, 26-333
STANDARD_UNSET_BUTTON keyword, 8-13 Station Plot window, 6-137
STANDARD_UPOWER_BUTTON keyword, 8-12 Station trouble indicator, 26-530
STANDARD_USER_BUTTON keyword, 8-12 Station windows, 2-8, 3-4, 3-12
start apu cal statement, 21-36 auxiliary stations, 3-13, 3-17, 5-10, 19-1
start cdig cal statement, 21-46 Catalyst, 3-15, 3-17
start gigadig:cal statement, 21-40 Catalyst Tiger, 3-15, 3-17
start gpib statement, 11-11 control panel, 3-12, 3-13, 8-6
start lca cal statement, 21-41 controlling sizes and positions, 8-8
start loop button, 3-13, 5-26, 8-12 deleting test programs, 5-30
start plfsrc cal statement, 21-43 displaying information, 3-14
start pulse cal statement, 21-45 icon, 3-4, 3-12, 4-9
Start Switch, 5-22 in debug, 7-3
start tms cal statement, 21-47 login, 2-8, 3-23
start uhfsrc cal statement, 21-42 login prompt, 3-23
start vhfawg cal statement, 21-49 logout, 2-9
start vhfcw cal statement, 21-49 namestripe, 3-12
start wf:cal statement, 21-36 new, 3-15
IMAGE Solutions V8.3 Index-33
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
opening, 3-23 in IMAGE, 24-11
printing, 3-19, 3-23 test data fields, 24-10
production mode, 8-3, 8-6 STDF Utilities and Filters
regions, 3-12 filter types, 25-26
remote stations, 3-17 filter_datalog, 25-28
scroll bars, 3-12 filter_extra, 25-31
scrollable, 3-17 filter_failed_devices, 25-29
selecting with menus, 8-19 filter_ftr, 25-32
shell station, 3-17 filter_hbr_bin, 25-29
source window, 3-12 filter_nsigma, 25-30
terminal pane, 3-12, 3-14 filter_record, 25-27
test stations, 3-17 filter_sbr_bin, 25-29
STATION_HOST environment variable, 8-26 filter_test, 25-28
station_info command, 3-14, 5-2, 7-3, 8-8 read_stdf, 25-8
STATION_NUMBER environment variable, read_stdf_v3, 25-9
8-26, 10-4 read_stdftool, 25-2
Stations menu item, 3-10, 3-23 reading STDF files, 25-2
Statistics retest_by_part_id, 25-30
summary, 6-7, 6-9, 6-105 retest_by_xy_coordinate, 25-30
test program, 5-22, 5-43, 26-195 stdf filters, 25-25
statmon command, 8-49 stdf_merge, 25-23
statmon.data file, 8-50, 8-52 stdf_print_field, 25-11
STATUS_ITEM keyword (Production Menu stdf_print_yield, 25-14
Control), 9-79 stdf_repair, 25-16
STDF (Standard Test Data Format), 3-76, 24-1 stdf3_to_4, 25-18
reading version, 24-15 stdf4_to_3, 25-21
time functions, 26-221 stdf-atdf conversions, 25-18
STDF files stdf_merge command, 6-105
ASCII text, 24-39 step button and command, 7-16, 8-13
creation, 24-7 Stepping through test programs, 7-16
datalogging, 3-39, 6-18, 6-37, 24-2 stop loop button, 5-26, 8-12
datalogging to, 6-78 Stop on fail program termination mode,
from summary reports, 6-95, 6-96, 24-2 5-24, 14-22
hardware bins, 24-17 Stopping the test system, 2-32
histogram files, 6-120, 6-123, 24-2 Stopsign icon, for breaktraps, 7-12
merging, 6-105 Store as new file window, 7-31
order of records, 24-8 store command, 7-32
recovering after power failure, 6-104 Storing test program in new file, 7-31
sending datastream, 6-49, 6-54 strcmp function, 6-78
sending summary report, 6-92 Strict Conformance of STDF Filenames property,
wafer map, 10-4, 10-13 6-19
STDF records, 24-6 String constants, 13-12
header fields, 24-9 Strings, input and output, 16-14
IMAGE custom, 24-37 Structures, 7-27, 7-59, 13-10, 13-26, 13-34
IMAGE Solutions V8.3 Index-34
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Subdirectories, 2-3 SUN3 computers
Sublot ID, 6-3, 6-5, 6-8, 6-9, 26-193, 26-323 binary files, 5-10, 7-27, 7-31, 7-32, 7-35, 7-40
in station monitor window, 8-7, 8-16 running IMAGE on, 3-68
incrementing, 6-4 SUN4 computers
reading, 26-331 binary files, 5-10, 7-27, 7-31, 7-32, 7-35, 7-40
setting, 26-368, 26-378, 26-534, 26-535 SunOS operating system, 2-1
Sublots, incrementing, 6-4 commands, help, 2-6, 3-26
SUBMENU keyword, 8-23, 8-40 diff command, 7-34
SUBMENU keyword (Production Menu Control), make facility, 5-12
9-28, 9-80 standard object files, 7-42
Submenus, setting, 3-34 Text Editor, 7-6
sumfmt command, 6-104 Supervisor name, 6-6, 6-8, 26-333, 26-381
sumfmt summary filter, 6-103 SUPPRESS keyword (Production Menu Control),
Summary button, 6-89, 6-91 9-10, 9-81
summary command, 6-91, 26-193 Suppressing error message output, 8-29
STDF files, 24-2, 24-17, 24-23, 24-31, 24-32 switch statement, 13-19, 13-22, 13-34
Summary filters, custom, 6-103 Switch variables, 5-5, 7-46
Summary output, 3-14 Switches, command, 2-19
Summary reports, 6-89 Switching between windows, 8-6
accumulated, 6-89, 6-93, 6-100 switchvar command, 7-46
automatic, 6-94, 6-96 Sync pulse display, help, 3-26
reading, 26-185 Synchronized Power Subsystem, see SPS
reading setup, 26-196 SYSCOM_HOST environment variable, 8-26
setup, 6-98, 26-347 System and Copyright Information window, 3-10
bin totals, 6-89 System Check menu item, 19-7
checkpoint frequency, 6-92, 6-104
directory, specifying, 6-98 T
failing tests, 3-38 Tabs, in IMAGE, 13-6
final, 6-89, 6-90, 6-93, 6-104 tconfig command, 4-7
format, 6-103 Terabus
generating, 6-89, 26-193 get pointer, 26-402
header, 6-89 read address, 26-146
manipulating from test program, 6-105 read data, 26-313
partial, 6-89, 6-93, 8-20 settling timer, 26-43
printing string, 26-142 using the timer, 26-43, 26-402
properties, 3-38 write to address, 26-146
recovering after power failure, 6-104 TERM environment variable, 8-26
statistics, 6-7, 6-9, 6-105 Terminal input and output, 16-4
STDF files, 6-95, 6-96, 24-23, 24-32 Terminal Interface, 19-32
suppressing, 6-7, 6-8 Terminal pane, 3-12, 3-14
test summary, 6-89 Termination modes of test programs, 5-24
writing, 14-25 Test codes, 26-334, 26-381
Sun Microsystems workstations, 1-2 Test computer, 1-2
locking, 3-7 Test conditions, 14-12, 14-16, 15-27
IMAGE Solutions V8.3 Index-35
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
declaring, 15-27 malloc data space, 5-38
interrogating, 15-29 modules without pinmap, 14-26
reading, 24-21, 26-98 name, 3-12, 3-13, 26-217, 26-323, 26-366
sequencers, 15-28 revision, 6-6, 6-8, 26-366
set in test program, 26-381 revision ID, 26-324, 26-533
setting, 6-6, 6-8, 6-10, 15-29, 26-382 running, 7-20
setting during a lot, 6-10, 26-371, 26-382 saving changes, 7-31
setting from command line, 6-10 setting name, 26-376
Test data directory, specifying, source files, 5-5
3-37, 6-46, 6-56, 6-98, 6-123 stack space, 5-38
Test functions, startup function, 26-435
13-3, 13-5, 14-2, 14-3, 14-11, 14-12, 14-18, statistics, 5-22, 5-43, 26-195
18-29 stepping through, 7-16, 7-20
multisite test, 17-8, 17-9 storing in new file, 7-31
timing, 5-39 structure, 13-2, 13-3, 14-1, 14-3
Test head termination modes, 5-24, 26-383
attaching to station windows, 3-17 text space, 5-22, 5-37
selecting type, 5-3, 5-6, 5-10 timing, 5-22, 5-31, 15-2
test stations, 3-17 Test results, and STDF files, 24-15
Test In Progress signal, 5-34 Test statements, 14-11, 14-18, 18-29
Test labels, 14-14, 26-511 changing default behavior of, 14-20
Test limits, read number, 26-402
14-10, 14-12, 14-13, 14-15, 26-322, 26-326 Test stations, 3-15, 3-17
disqualify binning, 15-10 Test status, 5-33, 26-99
repeated, 14-17 Test summary, in summary reports, 6-89
setting, 26-510, 26-512 Test Synopsis Record, see TSR
Test numbers, 14-12, 14-13, 26-318 Test system and copyright information, 3-10
breaktraps, 7-11 Test time, 5-22, 5-31, 5-39
changing, 26-509 test_conditions declaration, 15-27
datalog statement, 14-24 testcond command, 6-10, 15-27, 15-29, 26-334
Test parameter list, 14-12, 14-13 STDF files, 24-4, 24-21
Test programs Tester API, 28-1
compiling, 7-24 Tester computer
continuing, 7-18, 7-20 connection, 2-35
creating new, 5-3, 5-5 halting, 2-34
data space, 5-22, 5-37 rebooting, 2-33
deleting, 5-30 Tester executive, read version, 26-320
displaying name of loaded, 3-15 Tester memory, 5-22
editing, 7-23 allocation, 5-37
going to next executable line, 7-18, 7-20 stack space, 5-38
halting, 5-28, 7-19, 7-20, 7-24 usage, 5-37
initializing, 26-283 Tester name, in station window, 3-12
listing versions, 7-33 Tester node name, reading, 26-328
loading, 1-6, 5-2, 5-35, 17-20 Tester number, reading, 26-224
IMAGE Solutions V8.3 Index-36
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Tester resources, sharing, 17-8 calculate deviations from clock, 26-416
Tester type, reading, 3-15, 24-21, 26-335 calculate event intervals, 26-417
Tester utilities menu item, 8-19 calculate maximum list of numbers, 26-417
Tester utilization events, 3-38, 5-34 calculate mean list of numbers, 26-418
TESTER_NUMBER environment variable, calculate minimum list of numbers, 26-418
8-26, 10-5 calculate peak-to-peak, 26-419
testhead command, 5-10 calculate periods between time stamps, 26-418
Testing-in-progress options menu item, 8-19 calculate standard deviation, 26-419
Tests calibration, 21-8, 21-46
breaktraps in, 7-11 read status, 26-100
forcing to pass or fail, 5-27 .tl files, see Source files
reading status of, 14-20 tl_add_datalog_output function,
Text Editor, 3-2, 7-6 6-57, 6-67, 26-143
Text space in test programs, 5-22, 5-37 tl_add_datastream function, 26-143
Text strings datalog, 6-76 tl_addr_r function, 26-146
Text utilities, 2-24 tl_addr_w function, 26-146
comparing files, 2-26 tl_alarmcheck function, 22-21, 26-146
formatting, 2-25 tl_alarminfo function, 22-21
locating files, 2-25 TL_ALL macro, 6-79
printing, 2-24 tl_apu_cal_set_interval function, 21-30, 26-147
searching for files, 2-26 tl_apu_read_pin function, 26-522
Time datalogging started, reading, 24-20 tl_apu_read_pin_status function, 26-148
Time functions, 26-221 tl_apucal_subr function, 26-523
Time lot started, reading, 24-20, 26-333 tl_apucal_time function, 21-36, 26-147
Time Measurement Subsystem, see ATMS tl_asu_present function, 26-148
Time Measurement Subsystem, see TMS tl_asu_read_ad function, 26-149
Time of loading, reading, 5-35, 26-332 tl_asu_read_code function, 26-149
Time-Jitter Digitizer, see TJD tl_asu_read_lsb function, 26-149
Timing tl_asy_conn_pmm_vmdiff function, 26-149
advanced mixed-signal example, 5-33 tl_asy_disc_pmm function, 26-150
linear example, 5-32 tl_ath_area_size function, 26-150
test functions, 5-39 tl_ath_measure_data_pin_freq function, 26-150
test programs, 5-22, 5-31, 15-2 tl_ath_measure_gate_pin_freq function, 26-151
tip hardwire command, 2-36 tl_ath_read_capacitance function, 26-152
TIP signal, 5-34 tl_ath_read_counter function, 26-152
TITLE keyword, 8-21, 8-41 tl_ath_read_frequency function, 26-152
TITLE keyword (Production Menu Control), tl_awg4800_max_fs_to_6400 function, 26-153
9-25, 9-82 tl_awg4800_vca_map_debug function, 26-153
TJA (Time-Jitter Analyzer) tl_bbac_disable_clock_error_messages function,
alarms, 22-15 26-153
calibration, 21-8, 21-46 tl_bbac_disable_dut_connects function, 26-154
TJD (Time-Jitter Digitizer) tl_bbac_disable_linearity_corrections function,
alarms, 22-15 26-154
calculate clock period, 26-415 tl_bbac_enable_clock_error_messages function,
IMAGE Solutions V8.3 Index-37
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
26-155 tl_datalog_start_new_device function, 26-177
tl_bbac_enable_dut_connects function, 26-155 TL_DATALOG_STATWIN macro, 6-78
tl_bbac_enable_linearity_corrections function, TL_DATALOG_STDF macro, 6-78
26-155 tl_dc_cal_set_interval function,
tl_begin_lot function, 26-156, 26-193, 26-534 21-30, 21-39, 26-178
tl_begin_new_lot function, 26-156 tl_dc_meter_tsy_digitize function, 26-180
tl_bin_fail function, 26-157 tl_dccal_dump_constants function, 26-177
tl_bin_pass function, 26-157 tl_dccal_meter function, 26-178
tl_cal_get_autocal_mode function, 21-24, 26-158 tl_dccal_src function, 26-178
tl_cal_get_autocal_state function, tl_dccal_status function, 21-39, 26-179
21-27, 21-28, 26-159 tl_dccal_subr function, 21-39, 26-179
tl_cal_get_inst_crit function, 21-29, 26-160 tl_dccal_time function, 21-39, 26-180
tl_cal_get_inst_mode function, 21-27, 26-160 tl_dcvm_cal_status function, 26-181
tl_cal_get_inst_state function, tl_debug_site function, 26-181
21-27, 21-28, 26-162 tl_declare_event function, 26-181
tl_cal_get_remaining function, 21-29, 26-163 tl_define_bins function, 28-5
tl_cal_inst function, 21-25, 26-163 tl_define_sites function, 28-6
tl_cal_report function, 21-20, 26-163 tl_delay function, 26-182
tl_cal_set_autocal_mode function, 21-22, 26-164 tl_dfc_disable function, 26-182
tl_cal_set_inst_crit function, 21-29, 26-166 tl_dfc_enable function, 26-183
tl_cal_set_inst_mode function, 21-25, 26-166 tl_dfc_fail_run function, 26-183
tl_cal_set_uncal function, 21-25, 26-167 tl_dfc_inst_status function, 26-183
tl_cdig_set_cal_interval function, 21-30, 26-168 tl_dfc_request function, 26-183
tl_change_auto function, 26-168 tl_disable_hp_after_rte_off function,
tl_change_datalog function, 6-57, 6-66, 26-169 21-30, 26-184
tl_change_datastream function, 26-170 tl_disable_hp_after_rte_on function,
tl_change_site function, 26-170 21-30, 26-184
tl_close_mux function, 26-171 tl_disable_hp_after_rte_state function,
tl_cmu_get_roi_height function, 26-171 21-30, 26-185
tl_cmu_get_roi_width function, 26-171 tl_display_autosum_setup function, 26-185
tl_cmu_get_roi_x_pos function, 26-171 tl_dlg_endwafer function, 10-10, 26-185
tl_cmu_get_roi_y_pos function, 26-172 tl_dlg_startwafer function, 26-185
tl_create_tsr_for_ival function, 26-172 tl_dps_set_hotswitch_protection function, 26-186
tl_d_dump_all_patterns function, 26-173 tl_dsp_check_mem function, 26-187
tl_d_no_timing_reset function, 26-173 tl_dsp_dump_info function, 26-187
tl_d_share_enable function, 26-173 tl_dsp_get_buffer_address function, 26-188
tl_databits_address_set_board function, 26-174 tl_dsp_get_mem_size function, 26-188
tl_databits_unlock_code_set function, 26-174 tl_dsp_query_ap_type function, 26-189
tl_databits_unlock_code_set_board function, tl_dsp_sync function, 26-189
26-175 tl_dump_configuration function, 26-189
TL_DATALOG_DATAWIN macro, 6-78 tl_dump_data function, 6-46, 26-186, 26-190
tl_datalog_endseq_on_fail function, 6-77, 26-175 tl_edge_binary_search function, 26-190
TL_DATALOG_FILE macro, 6-78 tl_edge_linear_search function, 26-191
tl_datalog_ival function, 26-176 tl_efd_is_enabled function, 26-193
IMAGE Solutions V8.3 Index-38
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
tl_endlot function, tl_get_last_seq_bin function, 17-27, 26-213
24-2, 24-17, 24-23, 24-31, 24-32, 26-193 tl_get_load_id function, 26-214
tl_error_user function, 15-34, 26-193 tl_get_load_path function, 5-9, 26-214
tl_exch_comment function, 26-194 tl_get_load_typ function, 26-214
tl_exch_is_dvx_mode function, 26-194 tl_get_number_of_testheads function, 26-215
tl_exch_is_enabled function, 26-195 tl_get_oper_frq function, 26-215
TL_FAIL macro, 6-79 tl_get_part_datalogged function, 26-215
TL_FAILANALOG macro, 6-79 tl_get_pkg_typ function, 26-216
TL_FAILDIGITAL macro, 6-79 tl_get_prb_typ function, 26-216
tl_fflush_nowait function, 16-16, 26-195 tl_get_prog_nam_fullpath function, 26-217
tl_force_jobstats function, 26-195 tl_get_radians_d function, 26-217
tl_fvs_cal_dump function, 26-196 tl_get_radians_f function, 26-217
tl_get_autocal_on function, 21-22, 26-196 tl_get_sbin_device_count function, 26-217
tl_get_autosetup function, 26-196 tl_get_seq_bin function,
tl_get_burn_tim function, 26-198 15-12, 15-14, 17-27, 26-218
tl_get_cabl_id function, 26-198 tl_get_setup_id function, 26-219
tl_get_cabl_typ function, 26-199 tl_get_slot_from_pin function, 26-219
tl_get_cont_id function, 26-199 tl_get_sort_bin function, 15-12, 17-27, 26-219
tl_get_cont_typ function, 26-199 tl_get_sort_hbin function, 15-12, 17-27, 26-220
tl_get_data_collection_state function, 26-199 tl_get_spec_nam function, 26-220
tl_get_data_collection_streams function, tl_get_spec_ver function, 26-220
6-78, 26-200 tl_get_stream_criteria function, 6-79, 26-221
tl_get_datalog function, 6-57, 6-68, 26-201 tl_get_stream_filename function, 6-80, 26-223
tl_get_datalog_directory function, 6-80, 26-203 tl_get_stream_sample_info function,
tl_get_datalog_directory_for_stream function, 6-79, 26-223
6-80, 26-204 tl_get_tester_number function, 26-224
tl_get_degrees_d function, 26-207 tl_get_tst_temp function, 26-224
tl_get_degrees_f function, 26-208 tl_get_user_power function, 26-224
tl_get_dib_typ function, 26-208 tl_get_wavefile_sample_size function, 26-225
tl_get_dsgn_rev function, 26-209 tl_getstdftimeofday function, 26-221
tl_get_extr_id function, 26-209 tl_gigadig_report_ac_corr_spectrum function,
tl_get_extr_typ function, 26-210 26-225
tl_get_facil_id function, 26-210 tl_gigadig_report_chan_mismatch_data function,
tl_get_famly_id function, 26-210 26-225
tl_get_floor_id function, 26-210 tl_gigadig_report_err function, 26-226
tl_get_flow_id function, 26-211 tl_gigadig_skew_clock function, 26-226
tl_get_hbin_device_count function, 26-211 tl_gpib_dump_bus_info function, 26-227
tl_get_hp_name function, 26-211 tl_gpib_dump_gpibcap_info function, 26-227
tl_get_hp_type function, 26-212 tl_gpib_get_ifc_at_reset function, 26-227
tl_get_hsd_type function, 26-212 tl_gpib_set_ifc_at_reset function, 26-227
tl_get_inker function, 26-212 tl_h50_channel_to_pin function, 26-228
tl_get_lasr_id function, 26-213 tl_h50_check_pattern_running function, 26-228
tl_get_lasr_typ function, 26-213 tl_h50_debug_pmtrc function,
tl_get_last_image_error_ofunc function, 28-7 26-229, 26-230, 26-231
IMAGE Solutions V8.3 Index-39
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
tl_h50_define_scan_headers function, 26-229 tl_hp_move_absolute_die function, 26-245
tl_h50_dsim_roundtrip_delay_time function, tl_hp_move_relative_die function, 26-246
26-230 tl_hp_move_relative_machine function, 26-246
tl_h50_get_pin_name function, 26-230 tl_hp_move_z_down function, 26-247
tl_h50_get_site_from_chan function, 26-231 tl_hp_move_z_to_given_height function, 26-247
tl_h50_highest_chan function, 26-231 tl_hp_move_z_up function, 26-247
tl_h50_mcfreq function, 26-231 tl_hp_output_full_status function, 26-248
tl_h50_pin_to_channel function, 26-231 tl_hp_parallel_clear_alarm function, 26-249
tl_h50_read_dmc_divider function, 26-232 tl_hp_parallel_clear_all_start function, 26-248
tl_h50_supclk_to_dc function, 26-232 tl_hp_parallel_clear_autosum function, 26-248
tl_hand_id variable, 26-523 tl_hp_parallel_clear_reject function, 26-249
tl_handlerprober_cond_eoc function, 10-10 tl_hp_parallel_clear_start function, 26-249
tl_handlerprober_cond_eol function, 10-10 tl_hp_parallel_read_all_start function, 26-249
tl_handlerprober_cond_eow function, 10-10 tl_hp_parallel_set_eos function, 26-250
tl_handlerprober_exec_action function, 26-233 tl_hp_probe_wafer function, 26-250
tl_hcps_connect_pinmap function, 26-233 tl_hp_request_dut_id function, 26-251
tl_hcps_debug_kelvin_pin function, 26-234 tl_hp_request_error_code function, 26-251
tl_hcps_set_connect_ilim function, 26-234 tl_hp_request_error_msg function, 26-252
tl_hcu_override function, 26-235 tl_hp_request_peripheral_id function, 26-252
tl_hcucal_src function, 26-235 tl_hp_request_start function, 26-253
tl_hfdig_report_err function, 26-235 tl_hp_send_command function, 26-253
tl_hfsc_ramp_cal function, 21-40, 26-236 tl_hp_send_request function, 26-254
tl_hfsc_set_ramp_cal_duration function, 21-31 tl_hp_unload_wafer function, 26-255
TL_HISTOGRAMMING macro, 6-78 tl_hpd_user_fprintf function, 26-255
tl_hp_abort_probing function, 26-236 tl_hpd_user_printf function, 26-255
tl_hp_assign_good_die_bins function, 26-236 tl_hpm_reset function, 26-256
tl_hp_assign_good_die_bins functions, 26-236 tl_hsd_connect_pin_to_thads function, 26-256
tl_hp_assign_logical_ink function, 26-237 tl_hsd_disconnect_pin_from_thads function,
tl_hp_bin_to_category function, 26-238 26-257
tl_hp_break_device_contact function, 26-238 tl_hsd_flush_stat_cache function, 26-257
tl_hp_clear_alarm function, 26-239 tl_hsd50_calibrate_all function, 26-256
tl_hp_get_prober_info function, 26-239 tl_hsd50_set_cal_interval function, 21-31
tl_hp_gpib_sendcmd function, 26-240 tl_hsds_dsim_clear function, 26-524
tl_hp_gpib_sendvarcmd function, 26-241 tl_hsds_dsim_clutch1 function, 26-524
tl_hp_handler_isconnected function, 26-243 tl_hsds_dsim_clutch2 function, 26-524
tl_hp_handler_isenabled function, 26-243 tl_hsds_dsim_cond1 function, 26-525
tl_hp_handlerconf_flags function, 26-242 tl_hsds_dsim_cond2 function, 26-525
tl_hp_handlerconf_show function, 26-243 tl_hsds_dsim_cond3 function, 26-526
tl_hp_input_empty_status function, 26-243 tl_hsds_dsim_cycles_per_pass function, 26-526
tl_hp_is_handler function, 26-244 tl_hsds_dsim_fail function, 26-526
tl_hp_is_prober function, 26-244 tl_hsds_dsim_io_timing function, 26-527
tl_hp_load_setup function, 26-244 tl_hsds_dsim_max_cycles function, 26-527
tl_hp_load_wafer function, 26-245 tl_hsds_dsim_nopatsim function, 26-527
tl_hp_make_device_contact function, 26-245 tl_hsds_dsim_pass function, 26-527
IMAGE Solutions V8.3 Index-40
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
tl_hsds_dsim_patsim function, 26-528 tl_ibcac function, 11-15
tl_hw_settle function, 26-258 tl_ibcmd function, 11-15
tl_i2c_construct_msg function, 26-258 tl_ibcmd2 function, 11-15
tl_i2c_construct_msg_burst function, 26-259 tl_ibgts function, 11-15
tl_i2c_construct_msg_pin function, 26-260 tl_ibon1 function, 11-15
tl_i2c_construct_msg_setup function, 26-261 tl_ibrd function, 11-15
tl_i2c_construct_msg_setup_pin function, 26-262 tl_ibrd_eoi function, 11-15
tl_i2c_data_test function, 26-264 tl_ibsic function, 11-15
tl_i2c_data_test_burst function, 26-264 tl_ibsre function, 11-15
tl_i2c_data_test_pin function, 26-265 tl_ibwait function, 11-15
tl_i2c_data_test_setup function, 26-265 tl_ibwrt function, 11-15
tl_i2c_data_test_setup_pin function, 26-266 tl_ibwrt2 function, 11-15
tl_i2c_extended_addr_check function, 26-267 tl_init function, 21-3, 26-283
tl_i2c_extended_addr_check_pin function, tl_input_adjust function, 15-20, 26-283
26-268 tl_job_is_in_debug function, 26-284
tl_i2c_free_string_memory function, 26-268 tl_lcacal_status function, 21-41
tl_i2c_rcv_data_rpt_test function, 26-269 tl_legal_pin_array function, 26-284
tl_i2c_rcv_data_rpt_test_burst function, 26-269 tl_legal_pin_number function, 26-285
tl_i2c_rcv_data_rpt_test_pin function, 26-270 tl_lfac_disable_dut_connects function, 26-286
tl_i2c_rcv_data_rpt_test_setup function, 26-270 tl_lfac_enable_dut_connects function, 26-287
tl_i2c_rcv_data_rpt_test_setup_pin function, tl_lfacd_02_move_alarm_bit function, 26-285
26-271 tl_lfacdig_set_precharge_time function, 26-285
tl_i2c_rcv_data_test function, 26-272 tl_lfacs_conn_deltabus function, 26-288
tl_i2c_rcv_data_test_burst function, 26-273 tl_lfacs_get_wave_fs function, 26-288
tl_i2c_rcv_data_test_pin function, 26-273 tl_lfacs_multitone_ac_crest_factor function,
tl_i2c_rcv_data_test_setup function, 26-274 26-288
tl_i2c_rcv_data_test_setup_pin function, 26-274 tl_lfacs_sinxx_amp function, 26-289
tl_i2c_single_addr_check function, 26-275 tl_lfacsrc_get_grow_dir function, 26-288
tl_i2c_single_addr_check_burst function, 26-276 tl_locate_site function, 28-6
tl_i2c_single_addr_check_burst_pin function, tl_log_custom_record function, 24-37
26-276 tl_matrix_bank_force function, 26-289
tl_i2c_single_addr_check_pin function, 26-277 tl_mcfd_clear_counter function, 15-18, 26-290
tl_i2c_single_addr_check_rcv function, 26-277 tl_mcfd_disable_site function, 15-18, 26-290
tl_i2c_single_addr_check_rcv_burst function, tl_mcfd_init function, 15-17, 26-291
26-278 tl_mcfd_monitor_hbin function, 15-18, 26-292
tl_i2c_single_addr_check_rcv_pin function, tl_mcfd_monitor_sbin function, 15-18, 26-293
26-279 tl_mcfd_monitoring_on function, 15-18, 26-292
tl_i2c_single_addr_check_rcv_setup function, tl_mcfd_switch_off function, 15-17, 26-293
26-279 tl_mcfd_switch_on function, 15-17, 26-293
tl_i2c_single_addr_check_rcv_setup_pin tl_measure_calibrate function, 26-294
function, 26-280 tl_measure_calibrate_n function, 26-294
tl_i2c_single_addr_check_setup function, 26-281 tl_measure_sample_period function, 26-294
tl_i2c_single_addr_check_setup_pin function, tl_memman_recompact_off function, 26-295
26-282 tl_memman_recompact_on function, 26-295
IMAGE Solutions V8.3 Index-41
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
tl_memman_recompact_pattern function, 26-296 tl_profile_end, 26-310
tl_meter_ave_time_and_n function, 26-296 tl_profile_end function, 5-39, 5-45, 26-310
tl_meter_filter_info function, 26-296 tl_profile_mark, 26-311
TL_NOTEXIST macro, 6-79 tl_profile_mark function, 5-39, 5-45, 26-311
tl_opamp_read_loop_alarm function, 26-297 tl_psrr_lfacsrc_slot function, 26-311
tl_opamp_read_osc_alarm function, 26-297 tl_psrr_plfsrc_slot function, 26-312
tl_open_mux function, 26-297 tl_psrr_plfsrc_to_wave function, 26-312
tl_ovi_alarm_disable function, 26-298 tl_ptr_r function, 26-313
tl_ovi_local_meter_reset function, 26-298 tl_ptr_w function, 26-313
tl_ovi_set_hotswitch_protection function, 26-299 tl_qsc_map_dump function, 26-313
tl_ovi_set_thads_atten function, 26-299 tl_qsc_state function, 26-314
tl_ovi_set_wave_gain function, 26-300 tl_qvs_alarm_disable function, 26-314
tl_pacs_sinxx_amp function, 26-302 tl_qvs_combine function, 26-315
tl_pacs2_cal_debug_flag function, 26-300 tl_qvs_set_hotswitch_protection function, 26-315
tl_pacs2_clk_cal function, 26-301 tl_read_and_set_dib_info function, 26-316
tl_pacs2_fetch_cal_val function, 26-301 tl_read_and_set_prb_info function, 26-317
tl_pacs2cal_dump_cal_tables function, 26-300 tl_read_char function, 16-16
TL_PASS macro, 6-79 tl_read_char_nowait and debugging, 16-17
TL_PASSANALOG macro, 6-79 tl_read_char_nowait function, 16-16
TL_PASSDIGITAL macro, 6-79 tl_read_cmod_cod function, 26-318
tl_pause_data_collection function, 26-303 tl_read_datnum function, 26-318
tl_pgu_change_loop function, 26-303, 26-304 tl_read_device function, 26-319
tl_pgu_change_repeat function, 26-303 tl_read_dib_id function, 26-528
tl_pgu_pattern_memory_size function, 26-304 tl_read_disable_nowait function, 16-16
tl_pgu_read_repeat function, 26-304 tl_read_disp_cod function, 26-320
tl_pin_for_pin_id function, 26-304 tl_read_enable_nowait function, 16-16
tl_pin_id_for_pin function, 26-305 tl_read_exec_typ function, 26-320
TL_PINFIELD keyword, 14-26 tl_read_format function, 26-320
TL_PINMAP keyword, 14-26 tl_read_gigadig_hpfilt_slot function, 26-321
tl_pinmap_name_for_dchan function, 26-305 tl_read_hand_id function, 26-321, 26-528
tl_pinmap_name_for_pin function, 26-305 tl_read_hbin_is_pass function, 26-322
TL_PINNAME keyword, 14-26 tl_read_hfdig_hpfilt function, 26-322
tl_plfd_cal_interval function, 21-31, 26-306 tl_read_hfdig_hpfilt_slot function, 26-322
tl_plfd_set_optimization function, 26-306 tl_read_highlim function, 26-322, 26-326
tl_plfs_cal_interval function, 21-31, 26-306 tl_read_ids function, 26-323
tl_plfs_conn_deltabus function, 26-306 tl_read_job_nam function, 26-323
tl_plfs_get_amp_filt function, 26-307 tl_read_job_rev function, 26-324
tl_plfs_get_amp_filt_spec function, 26-308 tl_read_label function, 26-325
tl_plfs_undo_amp_filt function, 26-309 tl_read_label_size function, 26-325
tl_plfs_undo_amp_filt_spec function, 26-309 tl_read_label_truncate function, 26-326
tl_plfsrc_get_type_slot function, 26-309 tl_read_lot_id function, 26-326
tl_pmm_dump_cal_times function, 21-45 tl_read_lowlim function, 26-326
tl_powerup variable, 4-15, 26-309, 26-539 tl_read_meter_n_wmd_set function, 26-327
tl_prod_init function, 26-310 tl_read_mode_cod function, 26-327
IMAGE Solutions V8.3 Index-42
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
tl_read_node_nam function, 26-328 tl_send_to_SECS_GEM, 26-346
tl_read_oper_nam function, 26-328 tl_set_alarm_msg_mode function, 8-44, 26-346
tl_read_part_cnt function, 26-329 tl_set_autocal_onoff function, 21-22, 26-347
tl_read_part_id function, 26-329 tl_set_autosummary function, 6-98, 26-347
tl_read_part_typ function, 26-330 tl_set_burn_tim function, 26-349
tl_read_prb_card function, tl_set_cabl_id function, 26-350
26-156, 26-157, 26-529 tl_set_cabl_typ function, 26-350
tl_read_proc_id function, 26-330 tl_set_cmod_cod function, 26-351
tl_read_prot_cod function, 26-330 tl_set_cont_id function, 26-351
tl_read_rtst_cod function, 26-331 tl_set_cont_typ function, 26-352
tl_read_sbin_is_pass function, 26-331 tl_set_datalog function, 6-57, 26-352
tl_read_sblot_id function, 26-331 tl_set_datalog_disk_usage function, 26-355
tl_read_setup_t function, 26-332 tl_set_device function, 26-329, 26-355
tl_read_start_t function, 26-332 tl_set_disp_cod function, 26-357
tl_read_station_num function, 26-333 tl_set_dlg_enable function, 26-357
tl_read_supr_nam function, 26-333 tl_set_dsgn_verv function, 26-358
tl_read_test_cod function, 26-334 tl_set_efd_datalog() function, 6-62
tl_read_tja function, 26-334 tl_set_eng_id function, 26-359
tl_read_tja_array function, 26-335 tl_set_extr_id function, 26-360
tl_read_tmscal_status function, 26-335 tl_set_extr_typ function, 26-360
tl_read_tstr_typ function, 26-336 tl_set_facil_id function, 26-361
tl_read_user_eeprom_all_data function, 26-336 tl_set_famly_id function, 26-361
tl_read_user_eeprom_id_data function, 26-336 tl_set_floor_id function, 26-362
tl_read_usr_desc function, 26-337 tl_set_flow_id function, 26-362
tl_read_uwrecv_digslot function, 26-337 tl_set_hand_id function, 26-529
tl_read_uwrecv_digslot_slot function, 26-338 tl_set_hp_name function, 26-363
tl_read_uwrecv_thads function, 26-338 tl_set_hp_type function, 26-364
tl_read_uwrecv_thads_slot function, 26-338 tl_set_inker_map function, 26-364
tl_read_wafer function, 26-339 tl_set_job_nam function, 26-366
tl_read_wafer_mapping_ink_bin function, 26-339 tl_set_job_rev function, 26-366
tl_remove_datalog_output function, 6-57, 26-339 tl_set_lasr_id function, 26-366
tl_remove_datastream function, 26-340 tl_set_load_id function, 26-367
tl_reprobing_device function, 26-340 tl_set_load_typ function, 26-367
tl_restore_site_state function, 26-341 tl_set_lot_id function, 26-368
tl_resume_data_collection function, 26-341 tl_set_lot_ids function, 26-368
tl_retesting_device function, 26-341 tl_set_mode_cod function, 26-369
tl_retrieve_d function, 17-18, 26-342 tl_set_msg_mode function, 26-370
tl_retrieve_i function, 17-18, 26-342 tl_set_next_device function, 26-370
tl_rs232_close function, 26-343 tl_set_ONLY_test_condition function, 26-371
tl_rs232_open function, 26-343 tl_set_oper_frq function, 26-371
tl_rs232_read function, 26-345 tl_set_oper_nam function, 26-372
tl_rs232_write function, 26-346 tl_set_part_datalogged function, 26-372
tl_run_test_program function, 28-4 tl_set_part_fix function, 26-373
tl_run_test_program_cached function, 28-4 tl_set_part_typ function, 26-373
IMAGE Solutions V8.3 Index-43
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
tl_set_pkg_typ function, 26-374 tl_sps_ammeter_reset function, 26-391
tl_set_plfdig_legacy_filter_settling_times tl_sps_discon_meter_input function, 26-391
function, 26-374 tl_sps_gateoff function, 26-391
tl_set_prb_card function, 26-356, 26-375 tl_sps_gateon function, 26-392
tl_set_prb_typ function, 26-356, 26-375 tl_sps_get_amm_cal_stat function, 26-392
tl_set_proc_id function, 26-376 tl_sps_get_amm_cal_time function, 26-392
tl_set_prog_nam function, 26-376 tl_sps_get_fvs_status function, 26-392
tl_set_prot_cod function, 26-377 tl_sps_get_hccs_status function, 26-393
tl_set_rom_cod function, 26-377 tl_sps_get_hcvs_status function, 26-393
tl_set_rtst_cod function, 26-378 tl_sps_get_hpvi_status function, 26-394
tl_set_sblot_id function, 26-378 tl_sps_get_hvs_status function, 26-394
tl_set_serl_num function, 26-379 tl_sps_hccs_comp function, 26-394
tl_set_setup_id function, 26-379 tl_sps_hccs_connect function, 26-395
tl_set_spec_nam function, 26-380 tl_sps_hccs_disconnect function, 26-395
tl_set_spec_ver function, 26-380 tl_sps_hcvs_comp function, 26-395
tl_set_supr_nam function, 26-381 tl_sps_hcvs_connect function, 26-396
tl_set_test_cod function, 26-381 tl_sps_hcvs_disconnect function, 26-396
tl_set_test_condition function, 15-29, 26-382 tl_sps_hpvcc_alarm_clear function, 26-396
tl_set_test_condition_during_lot function, 26-382 tl_sps_hpvcc_connect function, 26-396
tl_set_tmode function, 5-25, 26-383 tl_sps_hpvcc_connect_bvcs function, 26-396
tl_set_trigger_timeout function, 26-181 tl_sps_hpvcc_disconnect function, 26-397
tl_set_trouble_indicator function, 26-530 tl_sps_hpvcc_gateoff function, 26-397
tl_set_tsr_test_tim function, 26-383 tl_sps_hpvcc_gateon function, 26-397
tl_set_tst_temp function, 26-384 tl_sps_hpvcc_reset function, 26-397
tl_set_user_power function, 26-384 tl_sps_hpvi_comp function, 26-398
tl_set_usr_desc function, 26-384 tl_sps_hvs_connect function, 26-398
tl_set_wafer function, 26-385, 26-537 tl_sps_hvs_disconnect function, 26-398
tl_set_wafer_id function, 10-10, 26-385 tl_sps_reset function, 26-398
tl_set_wafer_mapping_ink_bin function, tl_sps_set_ammeter function, 26-399
10-24, 26-386 tl_sps_set_hpvcc function, 26-399
tl_set_wait function, 15-4, 26-386 tl_sps_testfor_safety function, 26-399
tl_set_wait_timeout function, 26-387 tl_statmon_memo function, 8-54, 26-399
tl_simwave_name function, 26-387 tl_switchvar function, 28-7
tl_sinxx_amp function, 26-388 tl_system function, 26-400
tl_site variable, 17-6, 26-388 tl_system_timeout function, 26-401
tl_site_active function, 14-23, 17-28, 26-388 tl_t_delay_cal_all function, 21-48
tl_site_shutdown function, 17-21, 26-389 tl_tach_trg_ctrl function, 26-401
tl_smem_read_wave_sample_max function, tl_tapi_hp_connect function, 28-9
26-389 tl_tapi_hp_disable function, 28-10
tl_smem_set_wave_sample_max function, tl_tapi_hp_disconnect function, 28-9
26-390 tl_tapi_hp_disconnect_all function, 28-10
tl_sps_ammeter_connect function, 26-390 tl_tapi_hp_enable function, 28-9
tl_sps_ammeter_disable_alarm function, 26-390 tl_tapi_hp_exec_callback function, 28-12
tl_sps_ammeter_enable_alarm function, 26-391 tl_tapi_hp_get_start function, 28-11
IMAGE Solutions V8.3 Index-44
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
tl_tapi_hp_send_binning function, 28-13 tl_turbo_disable_linearity_corrections function,
tl_tba_read_timer function, 26-402 26-423
tl_tba_settle function, 22-2, 22-21 tl_turbo_enable_dut_connects function, 26-424
tl_tba_settle_wait function, 22-2, 26-43 tl_turbo_enable_linearity_corrections function,
tl_tbase_addr function, 26-402 26-424
tl_tdef_remaining function, 26-402 tl_turbo_get_1knotch_compensation function,
tl_testfor_safety function, 26-403 26-424
tl_tj306_aabus2_delta function, 26-403 tl_turbo_get_downconverter_compensation
tl_tj306_delta_drives_wave function, 26-403 function, 26-425
tl_tja_calc_avg_clock function, 26-404 tl_turbo_measure_src_vrms function, 26-425
tl_tja_calc_deviations function, 26-405 tl_turbo_set_cw_cal_amp_tolerance function,
tl_tja_calc_intervals function, 26-405 26-426
tl_tja_calc_max function, 26-406 tl_turbo_set_cw_cal_freq_tolerance function,
tl_tja_calc_mean function, 26-406 26-426
tl_tja_calc_min function, 26-407 tl_turbosrc_lp_filter_auto_set function, 26-427
tl_tja_calc_periods function, 26-407 tl_turn_multi_threaded function, 26-427
tl_tja_calc_pkpk function, 26-408 tl_ubvi100_set_supply_reset_state function,
tl_tja_calc_std_dev function, 26-408 26-427
tl_tja_num_stamps_captured function, 26-409 tl_uhfmm_read_freq function, 26-428
tl_tja_read_event_count function, 26-410 tl_uhfmm_read_if_freq function, 26-428
tl_tja_read_frequency function, 26-410 tl_uhfsrc_cal_interval function, 21-31, 26-428
tl_tja_read_ration_count function, 26-413 tl_uhfsrc_get_freq function, 26-429
tl_tja_read_status function, 26-414 tl_uhfsrc_level_table_valid function, 26-429
tl_tjd_calc_avg_clock function, 26-416 tl_uhfsrc_level_table_valid_slot function, 26-429
tl_tjd_calc_deviations function, 26-416 tl_uhfsrc_max_freq function, 26-430
tl_tjd_calc_intervals function, 26-417 tl_uhfsrc_max_mod_freq function, 26-430
tl_tjd_calc_max function, 26-418 tl_uhfsrc_set_table_size function, 26-431
tl_tjd_calc_mean function, 26-418 tl_update_data_collection_state function,
tl_tjd_calc_min function, 26-418 6-77, 26-431
tl_tjd_calc_periods function, 26-418 tl_user_datalog_changed function, 26-432
tl_tjd_calc_pkpk function, 26-419 tl_user_eeprom_present function, 26-432
tl_tjd_calc_std_dev function, 26-419 tl_user_endlot function, 26-433
tl_tms_cal_has_run function, 21-48, 26-420 tl_user_mcfd_handler function, 15-18, 26-433
tl_tms_cal_set_interval function, 21-31, 26-420 tl_user_postautocal function, 21-5, 26-434
tl_touch_pages_record_faults function, 26-530 tl_user_preautocal function, 21-5, 26-434
TL_TSTHD_AMS keyword, 14-29 tl_user_resetall function, 26-434
TL_TSTHD_MS keyword, 14-29 tl_user_shutdown function, 26-434
tl_tsy_cpu_trg_clr function, 26-421 tl_user_startup function, 26-435
tl_tsy_trg_ctrl function, 26-421 tl_using_simulator function, 26-435
tl_turbo_apply_downconverter_compensation tl_uwmm_dump function, 26-435
function, 26-422 tl_uwms_present function, 26-436
tl_turbo_apply_downconverter_compensation_ful tl_uwms_present_slot function, 26-436
l function, 26-422 tl_uwport_cal_s_params function, 26-439
tl_turbo_disable_dut_connects function, 26-423 tl_uwport_caldib_find_interpolated_ENR function,
IMAGE Solutions V8.3 Index-45
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
26-437 tl_uwport_read_match_and_source_gain
tl_uwport_caldib_find_interpolated_system_NF function, 26-469
function, 26-438 tl_uwport_read_match_and_source_gain_slot
tl_uwport_config function, 26-439 function, 26-470
tl_uwport_current_pin function, 26-440 tl_uwport_read_power_de_embed function,
tl_uwport_current_pin_slot function, 26-441 26-470
tl_uwport_do_s11 function, 26-441 tl_uwport_read_power_de_embed_slot function,
tl_uwport_do_spar_proc function, 26-444 26-471
tl_uwport_dump function, 26-446 tl_uwport_read_s1p function, 26-471
tl_uwport_dump_1port function, 26-448 tl_uwport_read_s2p function, 26-471
tl_uwport_dump_closest_freq function, 26-449 tl_uwport_receiver_slot function, 26-472
tl_uwport_dump_closest_freq_slot function, tl_uwport_s_param_sample_size function,
26-449 26-478
tl_uwport_dump_de_embed_file function, 26-449 tl_uwport_s_param_snr_test_enable function,
tl_uwport_dump_de_embed_file_slot function, 26-478
26-449 tl_uwport_set_gain_error_limits function, 26-473
tl_uwport_dump_fixture function, 26-450 tl_uwport_set_gain_error_limits_slot function,
tl_uwport_dump_fixture_slot function, 26-450 26-473
tl_uwport_dump_one_port function, 26-451 tl_uwport_set_interpolation_frequency_range
tl_uwport_dump_one_port_slot function, 26-454 function, 26-474
tl_uwport_dump_port function, 26-454 tl_uwport_simulate_capture function, 26-475
tl_uwport_dump_s_param_timing function, tl_uwport_simulate_capture_slot function, 26-476
26-458 tl_uwport_source_freq_range function, 26-476
tl_uwport_dump_two_port function, 26-459 tl_uwport_source_freq_range_slot function,
tl_uwport_dump_two_port_slot function, 26-462 26-477
tl_uwport_free_data function, 26-462 tl_uwport_sparam_timer function, 26-479
tl_uwport_get_num_chans_slot function, 26-463 tl_uwport_sparam_timer_slot function, 26-479
tl_uwport_hw_version function, 26-463 tl_uwport_std_cal_one_port function, 26-531
tl_uwport_inst_slot function, 26-463 tl_uwport_std_cal_one_port_slot function, 26-532
tl_uwport_invalidate_s_param_cal function, tl_uwport_user_cal_std_func function, 26-480
26-464, 26-465 tl_uwport_write_s1p function, 26-483
tl_uwport_invalidate_s_param_cal_all function, tl_uwport_write_s1p_fmt function, 26-483
26-464 tl_uwport_write_s2p function, 26-484
tl_uwport_lna function, 26-465 tl_uwport_write_s2p_fmt function, 26-485
tl_uwport_noise_source_present function, 26-466 tl_uwrecv_ap_read_uncal_amp function, 26-486
tl_uwport_noise_source_present_slot function, tl_uwrecv_cal_interval function, 21-31
26-466 tl_uwrecv_characterize_phase_noise_PSD
tl_uwport_num_user_chans function, 26-466 function, 26-487
tl_uwport_pin_to_slot_and_schan function, tl_uwrecv_czt function, 26-488
26-467 tl_uwrecv_get_PSD_use_AP function, 26-489
tl_uwport_read_match_and_measure_gain tl_uwrecv_phase_noise_signal_check function,
function, 26-467 26-489
tl_uwport_read_match_and_measure_gain_slot tl_uwrecv_read_ampval function, 26-490
function, 26-468 tl_uwrecv_read_ampval_slot function, 26-490
IMAGE Solutions V8.3 Index-46
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
tl_uwrecv_read_level function, 26-490 tl_wf_cal_temp_diff function, 26-505
tl_uwrecv_set_PSD_turbo_avg function, 26-491 tl_wf_cal_time_interval function, 21-32, 26-505
tl_uwrecv_set_PSD_use_AP function, 26-492 tl_wf_disable_80MHz_clock, 26-507
tl_uwrecv_spectrum_reversed function, 26-492 tl_wf_enable_80MHz_clock, 26-507
tl_uwrecv_spectrum_reversed_slot function, tl_wfcap_current_bank function, 26-506
26-493 tl_wfcap_get_actual_sample_rate function,
tl_uwrecv_suggest_digitizer function, 26-493 26-506
tl_uwrecv_suggest_digitizer_slot function, 26-493 tl_wfcap_num_samples_captured function,
tl_uwsrc_read_connection_slot function, 26-494 26-506
tl_uwsrc_read_freq_slot function, 26-494, 26-495 tl_wfcap_num_samples_overranged function,
tl_vhfawg_cal_interval function, 26-495 26-507
tl_vhfawg_fs_sclk_cond function, 26-495 tl_wfsrc_get_crest_factor function, 26-507
tl_vhfawg_get_dccal_size function, 26-496 tl_wfsrc_get_frequency function, 26-508
tl_vhfawg_get_dccal_size_slot function, 26-496 tl_wfsrc_get_last_sample_rate function, 26-508
tl_vhfawg_get_level_table_size function, 26-496 tl_wfsrc_get_sample_rate function, 26-508
tl_vhfawg_get_level_table_size_slot function, tl_wfsrc_get_segment_data function, 26-508
26-497 tl_wfsrc_get_segment_memory_size function,
tl_vhfawg_get_pll_value function, 26-497 26-509
tl_vhfawg_get_type function, 26-498 tl_wfsrc_get_segment_size function, 26-509
tl_vhfawg_get_type_slot function, 26-498 tl_wfsrc_show_segment_info function, 26-509
tl_vhfawg_level_table_valid function, 26-498 tl_write_datnum function, 26-510
tl_vhfawg_level_table_valid_slot function, 26-499 tl_write_device function, 26-533
tl_vhfawg_move_event function, 26-499 tl_write_dib_id_to_stdf function, 26-529, 26-533
tl_vhfawg_segment_ltable_valid function, 26-499 tl_write_format function, 26-510
tl_vhfawg_segment_ltable_valid_slot function, tl_write_highlim function, 24-4, 26-510
26-500 tl_write_job_rev function, 26-534
tl_vhfawg_set_dccal_size function, 26-500 tl_write_label function, 14-17, 26-511
tl_vhfawg_set_level_size function, 26-500 tl_write_lot_id function, 6-3, 24-4, 26-534
tl_vhfawg_sine_gen_debug function, 26-501 tl_write_lot_ids function, 26-535
tl_vhfawg_wave_freq function, 26-501 tl_write_lowlim function, 26-512
tl_vhfawg_wave_fs function, 26-501 tl_write_newtest function, 26-535
tl_vhfawg_wave_size function, 26-502 tl_write_sblot_id function, 6-3, 26-534, 26-535
tl_vhfcw_cal_interval function, 21-31, 26-502 tl_write_user_eeprom_all_data function, 26-512
tl_vhfcw_level_table_valid function, 26-502 tl_write_user_eeprom_id_data function, 26-513
tl_vhfcw_level_table_valid_slot function, 26-502 tl_write_wafer function, 26-537
tl_vhfcw_set_dccal_size function, 26-503 tl_write_wavefile function, 26-537
tl_vhfcw_set_level_max function, 26-503 tl_write_wavefile_struct function, 26-537
tl_vmcu_busy_wait function, 26-503 tl_xachan function, 26-513
tl_vreg_dutsrc_to_channel function, 26-503 tl_xath function, 26-514
tl_vreg_dutsrc_to_slot function, 26-504 tl_xcc function, 26-514
tl_vreg_image_dump function, 26-504 tl_xpacs function, 26-514
tl_vreg_slot_to_dutsrc function, 26-504 tl_xvb function, 26-515
tl_wait function, 26-504 tlerror.h header file, 15-33
tl_wait_wait function, 15-4, 15-5, 26-505 tmode command, 5-24, 15-36
IMAGE Solutions V8.3 Index-47
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
TMS (Time Measurement Subsystem) unsettrap command, 7-14
calibration, 26-420 UNSHOW_SERVICE keyword (Production Menu
simulator database, 12-3 Control), 9-84
test modules without pinmap, 14-28 unsigned data type qualifier, 13-11
to trap button, 7-15, 8-13 up command, 7-19
toolplaces command, 8-9 -usage switch, 3-25
TOTAL_RECORDS keyword (Production Menu user button, 3-14, 3-45, 8-12
Control), 9-40, 9-83 User computer
TOTAL_UNIQUE_VALUES keyword (Production halting, 2-34
Menu Control), 9-40, 9-83 rebooting, 2-33
Traps, see Breaktraps User description text string, reading, 26-337
Trigger bus USER environment variable, 8-26
connect to test head, 26-421 User power
Trigger switchyard read state, 26-224
clear latches, 26-421 setting, 26-384
connect trigger buses, 26-401 user power button, 3-13, 5-28, 8-12
digitizing, 26-180 User/network computer, 1-2
Trigger Walking Delay Generator Using a list of tests in a file, 6-40
calibration, 21-8, 21-48 usrpower command, 5-29, 8-8
TSR (Test Synopsis Record), Utilities menu item, 3-6
24-7, 24-31, 24-32, 24-33, 26-172, 26-383 Utilization of tester, measuring, 5-34
TSTC environment variable, 8-26 UWPORT (Microwave Port)
TSTC0 environment variable, 8-26 calibration,
TurboAC 21-7, 21-41, 26-100, 26-464, 26-531
downconverter functions, 26-422 convert pin to slot, 26-467
type definition, 7-27 get capture, 26-475, 26-476
read .s2p file, 26-471
U read lna, 26-449, 26-465
UBVI (Universal Backplane V/I Source) reading, 26-100
alarms, 22-13 write .s1p files, 26-483
change reset state, 26-427 write .s2p files, 26-484, 26-485
#undef compiler directive, 13-9 UWRECV (Microwave Receiver)
Unions, 7-27, 7-59, 13-10 calibration, 21-7, 21-31, 21-42
Units strings, 13-18, 14-14 read calibration constant, 26-128, 26-129
in datalog, 6-75 read digitizer, 26-337, 26-338
Units, in IMAGE, 13-10, 13-17 read frequency, 26-130, 26-131
UNITS_TESTED keyword (Production Menu read sample size, 26-135, 26-136
Control), 9-84 read spectrum reversed, 26-492, 26-493
UNIX operating system, 1-3, 2-1 read THADS, 26-338
commands, help, 3-26 UWSRC (Microwave Source)
high priority mode, 5-22 calibration, 21-7, 21-31, 21-42, 26-429
UNLOAD_MDL_FILE keyword (Production Menu read frequency, 26-429
Control), 9-84 read leveling table, 26-429
unset button, 8-13 returning frequency, 26-430
IMAGE Solutions V8.3 Index-48
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
set table size, 26-431 VHFAWG (Very High Frequency Arbitrary
Waveform Generator)
V calibration, 21-8, 21-31, 21-48, 26-495, 26-500
VALUE keyword (Production Menu Control), 9-85 leveling, 26-500
vardisp command, 7-56 leveling sine generation, 26-500
VARIABLE keyword (Production Menu Control), preventing race condition, 26-495
9-85 read leveling table, 26-498, 26-499
Variables, 13-11, 13-12 read phase-lock loop value, 26-497
active, 7-62 VHFCW (Very High Frequency Continuous Wave
array, 13-24 Source)
assigning values, 13-16, 13-19 calibration, 21-8, 21-31, 21-49, 26-502, 26-503
datalog, 6-76, 14-24 leveling, 26-503
declarations, breaktraps, 7-21 read leveling table, 26-502
declaring, 13-12 VHFDIG (Very High Frequency Digitizer)
during compiling, 7-26 alarms, 22-9
external, 13-4, 13-13, 14-4 calibration, 21-8
global, 13-4, 13-9, 13-13, 14-4 Video Memory and Control Unit, see VMCU
initializing, 13-12 View mask, in Real Time Wafermap, 10-17
local, 13-13 Viewing files, 2-23
names, 13-7, 13-12 VMCU (Video Memory and Control Unit), reading,
PMC, 9-11, 9-22 26-142
pointer, 13-25 Voltage range, reading, 26-44, 26-45
printing in station window, 7-63 Vreg (Voltage Regulation Front End)
scaling, 7-59 calibration, 21-8, 21-50
scope, 13-13
shell, 2-27 W
specifying radix, 7-60 Wafer configuration files, 10-23
static, 13-13 in .load files, 10-33
switch, 5-5, 7-46 Wafer Configuration Record, see WCR
variables display, 7-58 Wafer coordinates
Variables display, 7-56 reading and setting,
active variables, 7-62 24-28, 26-339, 26-385, 26-537
contents, 7-57 setting checking frequency, 10-35
error messages, 7-62 Wafer ID setting, 26-385
invoking, 7-56 Wafer Information Record, see WIR
requesting and unrequesting variables, 7-61 Wafer mapping, 10-19
scientific notation, 7-56, 7-58, 7-63 configuration file, 10-23
variables, 7-58 datalogging information, 6-22, 6-37, 6-47
versions command, 7-33 enabling, 10-34
Versions menu item, 7-33 for off-line inking, 10-23
Very High Frequency Arbitrary Waveform generating SECS map, 10-35
Generator, see VHFAWG ink lists, 10-29
Very High Frequency Continuous Wave Source, preview file, 10-4, 10-13
see VHFCW probe lists, 10-28
IMAGE Solutions V8.3 Index-49
IMAGE Base Language: Index
Table of Contents Index Home Master Index Search Help
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
prober coordinate system, 10-25 workstations
Real Time Wafermap, 10-2 Writing to a datalog report, 26-41, 26-42
row lists, 10-27 Writing to Terabus address, 26-146
scramble file, 10-4, 10-8, 10-13 WRR (Wafer Results Record),
skip lists, 10-29 10-10, 10-19, 24-36, 26-185
Wafer probe patterns, 10-28
Wafer Results Record, see WRR X
Wafer setup files, 10-32 X Window System, 1-3, 3-67
and .load files, 10-33 using X platforms with IMAGE, 3-70
wafermap command, 10-3 .Xdefaults file, 3-43, 3-47, 22-5, 29-1, 8-46
Wafers xlock command, 3-7, 19-12
datalogging end, 26-185
datalogging start, 26-185 Y
loading, 26-245 Yield
mapping, 10-1 cumulative, 8-7, 8-17, 8-55
probing, 26-250 cumulative by site, 8-55
STDF, 24-34, 24-36 current, 8-7, 8-17, 8-55
unloading, 26-255 current by site, 8-55
Wait functions, 15-4, 26-386, 26-387, 26-505 Yield monitor, 8-54
wait statement, 15-2 alarms, 8-62
wait_until_cdig_halt function, 26-515 setup file, 6-86, 8-57
wait_until_cdig_halt_slot function, 26-516 Yield Monitor, Real Time, 6-112
Waiting for handler/prober start, 26-521 yield_monitor.yield file, 6-86, 8-54, 8-55, 8-57
Waking sites, 17-22 Yield-by-site information, 8-55
Wave display yielddisp command, 6-113
help, 3-26
sample size, reading, 26-389
Z
sample size, setting, 26-390
Z stage, movement, 26-247
Waveform files, 5-9
Z stage, moving, 26-247
get sample size, 26-225
Zoom
writing, 26-520, 26-537
histogram plots, 6-131, 6-132
WCR (Wafer Configuration Record),
10-9, 10-19, 24-34
where command, 7-18, 7-20
while statement, 13-19, 13-21
Wildcards, 2-20
Windows
help, 3-26
printing, 3-19, 3-23
WINSIZE keyword, 8-59
WIR (Wafer Information Record),
10-9, 10-19, 24-36, 26-186, 26-386
Workspace menu, see IMAGE Workspace menu
Workstations, see Sun Microsystems
IMAGE Solutions V8.3 Index-50
You might also like
- Oracle Database Administration Interview Questions You'll Most Likely Be Asked: Job Interview Questions SeriesFrom EverandOracle Database Administration Interview Questions You'll Most Likely Be Asked: Job Interview Questions Series5/5 (1)
- C# For Beginners: An Introduction to C# Programming with Tutorials and Hands-On ExamplesFrom EverandC# For Beginners: An Introduction to C# Programming with Tutorials and Hands-On Examples5/5 (1)
- Appendix A: VPG Version 3.1 RADIOSS / LS-DYNA / NASTRAN ConversionNo ratings yetAppendix A: VPG Version 3.1 RADIOSS / LS-DYNA / NASTRAN Conversion28 pages
- Computer Science: Learn about Algorithms, Cybersecurity, Databases, Operating Systems, and Web DesignFrom EverandComputer Science: Learn about Algorithms, Cybersecurity, Databases, Operating Systems, and Web DesignNo ratings yet
- Software Suite: Revolutionizing Computer Vision with the Ultimate Software SuiteFrom EverandSoftware Suite: Revolutionizing Computer Vision with the Ultimate Software SuiteNo ratings yet
- Getting Started With Quick Test Professional (QTP) And Descriptive ProgrammingFrom EverandGetting Started With Quick Test Professional (QTP) And Descriptive Programming4.5/5 (2)
- Software Testing Interview Questions You'll Most Likely Be AskedFrom EverandSoftware Testing Interview Questions You'll Most Likely Be AskedNo ratings yet
- Professional Application Lifecycle Management with Visual Studio 2012From EverandProfessional Application Lifecycle Management with Visual Studio 2012No ratings yet
- SAS Programming Guidelines Interview Questions You'll Most Likely Be AskedFrom EverandSAS Programming Guidelines Interview Questions You'll Most Likely Be AskedNo ratings yet
- Improved Performance Research Integration Tool User Guide - Version 4.6From EverandImproved Performance Research Integration Tool User Guide - Version 4.6No ratings yet
- Visual SourceSafe 2005 Software Configuration Management in PracticeFrom EverandVisual SourceSafe 2005 Software Configuration Management in PracticeNo ratings yet
- JAVA PROGRAMMING FOR BEGINNERS: Master Java Fundamentals and Build Your Own Applications (2023 Crash Course)From EverandJAVA PROGRAMMING FOR BEGINNERS: Master Java Fundamentals and Build Your Own Applications (2023 Crash Course)No ratings yet
- The Datadog Handbook: A Guide to Monitoring, Metrics, and TracingFrom EverandThe Datadog Handbook: A Guide to Monitoring, Metrics, and TracingNo ratings yet
- Python Automation for Beginners: A Practical Guide with ExamplesFrom EverandPython Automation for Beginners: A Practical Guide with ExamplesNo ratings yet
- Mastering Nikto: A Comprehensive Guide to Web Vulnerability Scanning: Security BooksFrom EverandMastering Nikto: A Comprehensive Guide to Web Vulnerability Scanning: Security BooksNo ratings yet
- Microsoft AZ-400: Designing and Implementing Microsoft DevOps Solutions - Certification Exam PrepFrom EverandMicrosoft AZ-400: Designing and Implementing Microsoft DevOps Solutions - Certification Exam PrepNo ratings yet
- Mastering Go Network Automation: Automating Networks, Container Orchestration, Kubernetes with Puppet, Vegeta and Apache JMeterFrom EverandMastering Go Network Automation: Automating Networks, Container Orchestration, Kubernetes with Puppet, Vegeta and Apache JMeterNo ratings yet
- Coding Basics with Microsoft Visual Studio: A Step-by-Step Guide to Microsoft Cloud ServicesFrom EverandCoding Basics with Microsoft Visual Studio: A Step-by-Step Guide to Microsoft Cloud ServicesNo ratings yet
- Learning Dynamics NAV Patterns: Create solutions that are easy to maintain, are quick to upgrade, and follow proven concepts and designFrom EverandLearning Dynamics NAV Patterns: Create solutions that are easy to maintain, are quick to upgrade, and follow proven concepts and designNo ratings yet
- Image Collection Exploration: Unveiling Visual Landscapes in Computer VisionFrom EverandImage Collection Exploration: Unveiling Visual Landscapes in Computer VisionNo ratings yet
- C++ Debugging from Scratch: A Practical Guide with ExamplesFrom EverandC++ Debugging from Scratch: A Practical Guide with ExamplesNo ratings yet
- PLC: Programmable Logic Controller – Arktika.: EXPERIMENTAL PRODUCT BASED ON CPLD.From EverandPLC: Programmable Logic Controller – Arktika.: EXPERIMENTAL PRODUCT BASED ON CPLD.No ratings yet
- Mastering Shell for DevOps: Automate, streamline, and secure DevOps workflows with modern shell scriptingFrom EverandMastering Shell for DevOps: Automate, streamline, and secure DevOps workflows with modern shell scriptingNo ratings yet
- Installation and Configuration of IBM Watson Analytics and StoredIQ: Complete Administration Guide of IBM Watson, IBM Cloud, Red Hat OpenShift, Docker, and IBM StoredIQ (English Edition)From EverandInstallation and Configuration of IBM Watson Analytics and StoredIQ: Complete Administration Guide of IBM Watson, IBM Cloud, Red Hat OpenShift, Docker, and IBM StoredIQ (English Edition)No ratings yet
- Java / J2EE Interview Questions You'll Most Likely Be AskedFrom EverandJava / J2EE Interview Questions You'll Most Likely Be AskedNo ratings yet
- C++ Basics for New Programmers: A Practical Guide with ExamplesFrom EverandC++ Basics for New Programmers: A Practical Guide with ExamplesNo ratings yet
- IT Inventory and Resource Management with OCS Inventory NG 1.02From EverandIT Inventory and Resource Management with OCS Inventory NG 1.02No ratings yet
- Mastering Terraform A Comprehensive Guide to Infrastructure As CodeFrom EverandMastering Terraform A Comprehensive Guide to Infrastructure As CodeNo ratings yet
- Automation of Avionics Integration TestNo ratings yetAutomation of Avionics Integration Test15 pages
- (1997) Model Driven Testing (Bergel, Et Al)No ratings yet(1997) Model Driven Testing (Bergel, Et Al)4 pages
- MBA:1 Semester It Skills Lab-1 Sushil Kumar Assistant Professor100% (1)MBA:1 Semester It Skills Lab-1 Sushil Kumar Assistant Professor22 pages
- 80 Linux Monitoring Tools For SysAdmins - Server Density BlogNo ratings yet80 Linux Monitoring Tools For SysAdmins - Server Density Blog25 pages
- Final PROPERTY SUPPLY MANAGEMENT SYSTEMNo ratings yetFinal PROPERTY SUPPLY MANAGEMENT SYSTEM71 pages
- Chapter 1: Measurement and Extraction of BSIM4 Model ParametersNo ratings yetChapter 1: Measurement and Extraction of BSIM4 Model Parameters66 pages
- BCA_3rd Sem_TBC304_Python Programming_Punitha_updatedNo ratings yetBCA_3rd Sem_TBC304_Python Programming_Punitha_updated3 pages
- Cycle), Which Moves The Concentration From The Problem Domain To TheNo ratings yetCycle), Which Moves The Concentration From The Problem Domain To The55 pages
- Building Automation Software & Servers: Member of TheNo ratings yetBuilding Automation Software & Servers: Member of The11 pages
- LAB 5 - Configuring A Site-to-Site IPsec VPNNo ratings yetLAB 5 - Configuring A Site-to-Site IPsec VPN23 pages
- Esri-Sap Integration For Utilities GISconnex Experience PDFNo ratings yetEsri-Sap Integration For Utilities GISconnex Experience PDF30 pages
