National Instruments NI-488.2M User manual

© Copyright 1993, 1995 National Instruments Corporation.
All Rights Reserved.
NI-488.2M™
Software Reference Manual
for OS/2
January 1995 Edition
Part Number 370950A-01

National Instruments Corporate Headquarters
6504 Bridge Point Parkway
Austin, TX 78730-5039
[phone]
Technical support fax: [phone]
[phone]
Branch Offices:
Australia [phone], Austria [phone], Belgium 02/757.00.20,
Canada (Ontario) [phone], Canada (Québec) [phone],
Denmark 45 76 26 00, Finland (90) 527 2321, France (1) 48 14 24 24,
Germany 089/741 31 30, Italy 02/48301892, Japan [phone],
Mexico 95 800 010 0793, Netherlands 03480-33466, Norway 32-84 84 00,
Singapore 2265886, Spain (91) 640 0085, Sweden 08-730 49 70,
Switzerland 056/20 51 51, Taiwan 02 377 1200, U.K. 0635 523545

Limited Warranty
The media on which you receive National Instruments software are
warranted not to fail to execute programming instructions, due to defects in
materials and workmanship, for a period of 90 days from date of shipment,
as evidenced by receipts or other documentation. National Instruments will,
at its option, repair or replace software media that do not execute
programming instructions if National Instruments receives notice of such
defects during the warranty period. National Instruments does not warrant
that the operation of the software shall be uninterrupted or error free.
A Return Material Authorization (RMA) number must be obtained from the
factory and clearly marked on the outside of the package before any
equipment will be accepted for warranty work. National Instruments will
pay the shipping costs of returning to the owner parts which are covered by
warranty.
National Instruments believes that the information in this manual is
accurate. The document has been carefully reviewed for technical accuracy.
In the event that technical or typographical errors exist, National
Instruments reserves the right to make changes to subsequent editions of
this document without prior notice to holders of this edition. The reader
should consult National Instruments if errors are suspected. In no event
shall National Instruments be liable for any damages arising out of or
related to this document or the information contained in it.
EXCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO
WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS
ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. CUSTOMER'S RIGHT TO RECOVER DAMAGES
CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF NATIONAL
INSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE
PAID BY THE CUSTOMER. NATIONAL INSTRUMENTS WILL NOT BE
LIABLE FOR DAMAGES RESULTING FROM LOSS OF DATA, PROFITS,
USE OF PRODUCTS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES,
EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This limitation of the
liability of National Instruments will apply regardless of the form of action,
whether in contract or tort, including negligence. Any action against
National Instruments must be brought within one year after the cause of
action accrues. National Instruments shall not be liable for any delay in
performance due to causes beyond its reasonable control. The warranty
provided herein does not cover damages, defects, malfunctions, or service
failures caused by owner's failure to follow the National Instruments

installation, operation, or maintenance instructions; owner's modification of
the product; owner's abuse, misuse, or negligent acts; and power failure or
surges, fire, flood, accident, actions of third parties, or other events outside
reasonable control.
Copyright
Under the copyright laws, this publication may not be reproduced or
transmitted in any form, electronic or mechanical, including photocopying,
recording, storing in an information retrieval system, or translating, in
whole or in part, without the prior written consent of National Instruments
Corporation.
Trademarks
NI-488®, NI-488.2™, and NI-488.2M™are trademarks of National
Instruments Corporation.
Product and company names listed are trademarks or trade names of their
respective companies.
Warning Regarding Medical and Clinical Use
of National Instruments Products
National Instruments products are not designed with components and testing
intended to ensure a level of reliability suitable for use in treatment and
diagnosis of humans. Applications of National Instruments products
involving medical or clinical treatment can create a potential for accidental
injury caused by product failure, or by errors on the part of the user or
application designer. Any use or application of National Instruments
products for or involving medical or clinical treatment must be performed by
properly trained and qualified medical personnel, and all traditional medical
safeguards, equipment, and procedures that are appropriate in the particular
situation to prevent serious injury or death should always continue to be
used when National Instruments products are being used. National
Instruments products are NOT intended to be a substitute for any form of
established process, procedure, or equipment used to monitor or safeguard
human health and safety in medical or clinical treatment.

© National Instruments Corp. v NI-488.2M SRM for OS/2
Contents
About This Manual ..........................................................................xi
Organization of This Manual......................................................xi
Conventions Used in This Manual.............................................xii
How to Use This Manual Set......................................................xiv
Related Documentation ..............................................................xv
Customer Communication..........................................................xv
Chapter 1
NI-488.2M Software Description................................................1-1
The NI-488.2M Software Package.............................................1-1
NI-488.2M Driver and Driver Utilities ........................1-1
Language Files.............................................................1-2
Example Program Files................................................1-2
API-Related Files.........................................................1-3
How the NI-488.2M Software Works with OS/2.......................1-4
GPIB Overview ..........................................................................1-5
The IEEE 488 Standard and GPIB...............................1-5
Talkers, Listeners, and Controllers ..............................1-5
Controller-In-Charge and System Controller...............1-6
Sending Messages Across the GPIB............................1-6
Data Lines......................................................1-6
Handshake Lines............................................1-6
Interface Management Lines .........................1-7
Setting Up and Configuring Your System...................1-7
Controlling More Than One Board..............................1-9
Chapter 2
Application Examples.....................................................................2-1
Example 1: Basic Communication ............................................2-2
Example 2: Clearing and Triggering Devices...........................2-4
Example 3: Asynchronous I/O...................................................2-6
Example 4: End-of-String Mode...............................................2-8
Example 5: Service Requests.....................................................2-10
Example 6: Basic Communication with IEEE 488.2
Compliant Devices.................................................2-14
Example 7: Serial Polls Using NI-488.2 Routines ....................2-16
Example 8: Parallel Polls...........................................................2-18
Example 9: Non-Controller Example........................................2-21

Contents
NI-488.2M SRM for OS/2 vi © National Instruments Corp.
Chapter 3
Developing Your Application.......................................................3-1
Choosing a Programming Method..............................................3-1
Using the NI-488.2 Language Interface.......................3-1
Using NI-488 Functions: One Device for
Each Board.....................................................3-2
NI-488 Device-Level Functions......3-2
NI-488 Board-Level Functions .......3-3
Using NI-488.2 Routines: Multiple Boards
and/or Multiple Devices.................................3-3
Using the OS/2 API Interface.......................................3-4
Checking Status with Global Variables......................................3-4
Status Word—ibsta ......................................................3-4
Error Variable—iberr...................................................3-6
Count Variables—ibcnt and ibcntl...............................3-6
Using ibic to Communicate with Devices..................................3-7
Writing Your NI-488 Application..............................................3-7
Items to Include............................................................3-7
NI-488 Program Shell ..................................................3-8
General Program Steps and Examples.........................3-9
Writing Your NI-488.2 Application...........................................3-13
Items to Include............................................................3-13
NI-488.2 Program Shell...............................................3-14
General Program Steps and Examples.........................3-15
Compiling and Linking Your Program.......................................3-20
32-Bit C Applications...................................................3-20
16-Bit C Applications...................................................3-21
Running Your Application Program...........................................3-21
Chapter 4
Debugging Your Application.......................................................4-1
Running ibtest.............................................................................4-1
Presence Test of Driver................................................4-1
Presence Test of GPIB Board.......................................4-2
Incorrect Interrupt Level ..............................................4-2
GPIB Cables Connected...............................................4-2
Debugging with the Global Status Variables .............................4-3
Debugging with ibic...................................................................4-3
GPIB Error Codes.......................................................................4-3
Configuration Errors...................................................................4-4
Reconfiguring the NI-488.2M Software ......................4-5
Timing Errors .............................................................................4-5

Contents
© National Instruments Corp. vii NI-488.2M SRM for OS/2
Communication Errors ...............................................................4-6
Repeat Addressing .......................................................4-6
Termination Method.....................................................4-6
Chapter 5
ibic—Interface Bus Interactive Control Utility....................5-1
Overview.....................................................................................5-1
Starting ibic.................................................................................5-1
Exiting ibic .................................................................................5-2
ibic Syntax..................................................................................5-2
Adding End-of-String Characters...............................................5-9
Status Word Return.....................................................................5-9
Error Codes Return.....................................................................5-10
Count Return...............................................................................5-10
Common NI-488.2 Routines in ibic ...........................................5-11
Send..............................................................................5-11
Receive.........................................................................5-12
Common NI-488 Functions in ibic.............................................5-13
ibfind ............................................................................5-13
ibdev.............................................................................5-13
ibwrt .............................................................................5-16
ibrd ...............................................................................5-17
Auxiliary Functions....................................................................5-18
Set (Select Device or Board)........................................5-19
Help (Display Help Information).................................5-20
! (Repeat Previous Function) .......................................5-21
- (Turn OFF Display) and + (Turn ON Display) .........5-21
n* (Repeat Function n Times)......................................5-22
$ (Execute Indirect File)...............................................5-23
Print (Display the ASCII String)..................................5-24
ibic Examples .............................................................................5-24
NI-488.2 Routines Example.........................................5-24
NI-488 Device Functions Example..............................5-28
NI-488 Board Functions Example ...............................5-31
Chapter 6
GPIB Programming Techniques................................................6-1
Termination of Data Transfers ...................................................6-1
Waiting for GPIB Conditions.....................................................6-2
Device-Level Calls and Bus Management.................................6-2
Serial Polling ..............................................................................6-3
Service Requests from IEEE 488 Devices...................6-3
Service Requests from IEEE 488.2 Devices................6-4

Contents
NI-488.2M SRM for OS/2 viii © National Instruments Corp.
Automatic Serial Polling..............................................6-4
Autopolling and the Stuck SRQ State ...........6-5
Autopolling and Interrupts.............................6-5
SRQ and Serial Polling with NI-488 Device
Functions......................................................................6-6
SRQ and Serial Polling with NI-488.2 Routines .........6-6
Example 1 ......................................................6-7
Example 2 ......................................................6-8
Parallel Polling ...........................................................................6-9
Implementing a Parallel Poll........................................6-9
Parallel Polling with NI-488.2 Routines........6-9
Parallel Polling with NI-488 Functions.........6-10
Chapter 7
ibconf—Interface Bus Configuration Utility.........................7-1
Overview.....................................................................................7-1
Starting ibconf ............................................................................7-1
Levels of ibconf..........................................................................7-2
Input Selection Level ...................................................7-2
Map Level ....................................................................7-4
Device Map of the Boards.............................7-5
Help................................................................7-5
Rename ..........................................................7-5
(Dis)connect...................................................7-6
Edit.................................................................7-6
Exit.................................................................7-6
Description Level.........................................................7-7
Change Characteristics...................................7-8
Next Board/Device.........................................7-8
Help................................................................7-8
Reset Value....................................................7-8
Return to Map................................................7-8
Output Selection Level.................................................7-9
Board and Device Configuration Options ..................................7-9
Primary GPIB Address.................................................7-10
Secondary GPIB Address.............................................7-10
Timeout Setting............................................................7-10
Terminate Read on EOS...............................................7-11
Set EOI with EOS on Write.........................................7-11
Type of Compare on EOS............................................7-11
EOS Byte......................................................................7-11
Send EOI at End of Write ............................................7-12
GPIB-Specific Errors...................................................7-12

Contents
© National Instruments Corp. ix NI-488.2M SRM for OS/2
System Controller.........................................................7-12
Assert REN when SC...................................................7-12
Enable Auto Serial Polling...........................................7-13
Enable CIC Protocol.....................................................7-13
Bus Timing...................................................................7-13
Parallel Poll Duration...................................................7-13
Use This GPIB Interface ..............................................7-14
Base I/O Address .........................................................7-14
DMA Channel ..............................................................7-14
Interrupt Jumper Setting...............................................7-15
DMA Transfer Mode ...................................................7-15
Serial Poll Timeout.......................................................7-15
Enable Repeat Addressing ...........................................7-15
Default Configurations in ibconf................................................7-16
Exiting ibconf.............................................................................7-17
Appendix A
Status Word Conditions.................................................................A-1
Appendix B
Error Codes and Solutions............................................................B-1
Appendix C
Customer Communication............................................................C-1
Glossary.................................................................................................G-1
Index.......................................................................................................I-1

Contents
NI-488.2M SRM for OS/2 x © National Instruments Corp.
Figures
Figure 1-1. How the NI-488.2M Software Works with OS/2 ............1-4
Figure 1-2. Linear and Star System Configuration.............................1-8
Figure 1-3. Example of Multiboard System Setup.............................1-9
Figure 2-1. Program Flowchart for Example 1...................................2-3
Figure 2-2. Program Flowchart for Example 2...................................2-5
Figure 2-3. Program Flowchart for Example 3...................................2-7
Figure 2-4. Program Flowchart for Example 4...................................2-9
Figure 2-5. Program Flowchart for Example 5...................................2-12
Figure 2-6. Program Flowchart for Example 6...................................2-15
Figure 2-7. Program Flowchart for Example 7...................................2-17
Figure 2-8. Program Flowchart for Example 8...................................2-20
Figure 2-9. Program Flowchart for Example 9...................................2-22
Figure 3-1. General Program Shell Using NI-488 Device
Functions..........................................................................3-8
Figure 3-2. General Program Shell Using NI-488.2 Routines ...........3-14
Figure 7-1. Input Selection Level of ibconf .......................................7-2
Figure 7-2. Map Level of ibconf ........................................................7-4
Figure 7-3. Description Level of ibconf.............................................7-7
Figure 7-4. Output Selection Level of ibconf.....................................7-9
Tables
Table 1-1. GPIB Handshake Lines....................................................1-6
Table 1-2. GPIB Interface Management Lines .................................1-7
Table 3-1. Status Word (ibsta) Layout..............................................3-5
Table 4-1. GPIB Error Codes............................................................4-4
Table 5-1. Syntax for NI-488 Functions in ibic ................................5-3
Table 5-2. Syntax for NI-488.2 Routines in ibic...............................5-5
Table 5-3. Auxiliary Functions in ibic ..............................................5-18
Table A-1. Status Word (ibsta) Layout..............................................A-1
Table B-1. GPIB Error Codes............................................................B-1