Programmer’s Manual Producing Custom Software for Data Acquisition Systems IOtech 25971 Cannon Road Cleveland, OH 44146-1833 Phone: (440) 439-4091 Fax: (440) 439-4093 E-mail (Product Information): [email protected] E-mail (Technical Support): [email protected] Internet: www.iotech.com Programmer’s Manual Producing Custom Software for Data Acquisition Systems p/n 1008-0901 Rev. 10.4 *372195A-01* 372195A-01 © 2003 through 2007 by IOtech 958293 Documents Related to Daq Products Note: During software installation, Adobe® PDF versions of user’s manuals will automatically install onto your hard drive as a part of product support. The default location is in the Programs group, which can be accessed from the Windows Desktop. Initial navigation is as follows: Start [Desktop “Start” pull-down menu] ⇒ Programs ⇒ IOtech DaqX Software You can also access the PDF documents directly from the data acquisition CD by using the <View PDFs> button located on the opening screen. Refer to the PDF documentation for details regarding hardware and software pertinent to your data acquisition system. A copy of the Adobe Acrobat Reader® is included on your CD. The Reader provides a means of reading and printing the PDF documents. Note that hardcopy versions of the manuals can be ordered from the factory. How to use this Manual This manual is for individuals who write their own programs. If you prefer to use existing out-of-the box software such as DaqView, ViewXL, DASYLab, SnapMaster, you do not need to read this manual. This manual explains how to program data acquisition systems using various APIs. The programming languages used in the examples are C/C++ and Visual Basic. In addition to the information in this manual, you need to refer to your hardware user’s manual. It may be helpful to read the DaqView user’s manual to appreciate how a user-friendly data acquisition system looks from the user’s point of view. You may also need to consult documentation pertaining to your specific computer system and programming environment. In regard to this manual, you should read chapter 1, and then refer to additional chapters that are relevant to your programming environment. The manual is organized as follows: 1. Introduction - The manual begins with an overview of issues related to data acquisition programming and takes a look at the options available for making the task as easy as possible. 2. API Programming – General Models – discusses aspects of the data acquisition environment, provides several API models and a summary of selected API functions. The chapter includes a section entitled, Seven Easy Steps to Data Acquisition. 3. Using Multiple Devices 4. Daq API Command Reference Appendix A – Appendix Removed. Outdated material. Appendix B, Using Borland C++ Appendix C, Custom OEM Installation, explains the procedures required for custom reseller hardware and driver installation and distribution. Appendix D, daq9513… Commands, this appendix only applies to DaqBook/100 Series, DaqBook/200 Series, DaqBoard/100 Series and DaqBoard/200 Series devices. The appendix includes an API programming model for 9513 counter-timer chip devices and includes API reference material for the daq9513… command prototypes. Note: During software installation, Adobe® PDF versions of user manuals will automatically install onto your hard drive as a part of product support. The default location is in the Programs directory, which can be accessed from the Windows Desktop. Refer to the PDF documentation for details regarding both hardware and software. A copy of the Adobe Acrobat Reader® is included on your CD. The Reader provides a means of reading and printing the PDF documents. Note that hardcopy versions of the manuals can be ordered from the factory. Reference Note: The readme.file on your install CD-ROM identifies the location of program examples that are included on the CD. Programmer’s Manual 908494 vii This page is intentionally blank. viii 908494 Programmer’s Manual Table of Contents 1- Introduction 4 - API Command Reference API Features......1-1 Overview …… 4.1-1 Language Support......1-2 Command Information Layout......4.1-2 Driver Installation......1-2 Predefined Parameter Definitions......4.1-4 A Note Regarding API Command Mask and Flag Definitions......4.1-6 Applicability …… 1-3 Setting/Constructing Mask & Flag Values....4.1-6 Reading/Interpreting Mask & Flag Values....4.1-7 2- API Programming - General Models API Commands Alphabetic Listing......4.1-8 Data Acquisition Environment……2-1 Grouped by Function......4.1-9 Application Programming Interface (API) ……2-1 Hardware Capabilities and Constraints……2-1 The API Commands, In Detail......4.1-13 Signal Environment……2-2 API Error Codes......4.7-1 Seven Easy Steps to Data Acquisition …… 2-2 Models Initialization and Error Handling……2-9 One-Step Command Acquisitions ……2-11 Counted Acquisitions Using Linear Buffers…2-12 Appendix A – Removed, Outdated Material Indefinite Acquisition, Direct-To-Disk Using Circular Buffers……2-14 Analog Output……2-16 Appendix B – Using Borland C++ Generating DAC FIFO Waveforms …2-18 Digital I/O on P2……2-19 Appendix C – Custom OEM Installation Using DBK Card Calibration Files……2-20 Zero Compensation……2-23 Linear Conversion……2-25 Appendix D – daq9513… Commands 3- Using Multiple Devices Glossary Overview…… 3-1 Asynchronous Operation ……3-1 Synchronous Operation ……3-1 Asynchronous Operation of Multiple Devices …… 3-1 Synchronous Operation of Multiple Devices ……3-3 Internal Clock Method…… 3-4 Master Clock Method…… 3-5 External Clock Method……3-7 Reference Note: The readme.file on your install CD provides the location of program examples that are included on the CD. Programmer’s Manual 908494 ix This page is intentionally blank. x 908494 Programmer’s Manual Introduction 1 API Features...... 1-1 Language Support...... 1-2 Driver Installation...... 1-2 A Note Regarding Devices and API Command Applicability …… 1-3 Reference Note: Your companion user’s manual discusses hardware installation and setup, theory of operation, troubleshooting, and ready-to-run software. If you plan to use DaqView software [shipped with Daq device products], or you plan to use other ready-to-run software such as DASYLab or SnapMaster, you will not need to use this manual. Programmers can use the Applications Program Interface (API) to customize software. To create effective programs, programmers must be familiar with the hardware and operation as described in the previous chapters of this document. Note: The readme files on the install CD-ROM will keep you up-to-date as APIs continue to evolve. Note: Daq PCMCIA is not supported under Windows95/NT drivers. This manual serves both novice and experienced programmers. • As a tutorial - The Programming Models chapter explains how to combine commands to do useful work in a typical data acquisition environment. Program excerpts illustrate concepts and can be modified as needed to use in your programs. • As a reference – A great portion of the manual pertains to API commands. API definitions and parameter values are important to ensure proper syntax, and that software functions perform as intended. Reference Note: This manual contains no computer programming tutorials. You may need to consult additional documentation. API Features The install CD-ROM includes several “drivers” to accommodate various programming environments. The API has several features: • Multi-device - can concurrently handle up to 4 devices of the Daq device family • Larger buffer - can handle up to 2 billion samples at a time • Enhanced acquisition and trigger modes • Direct-to-disk capabilities • Wait-on-event features • Uses multi-tasking advantages of Windows 95/98/Me/NT/2000/XP Programmer’s Manual 908494 Introduction 1-1 Language Support The following three languages are supported: C/C++ Visual Basic The Programming Language Support folder is located in your installation directory. You can access program-related files from Windows Explorer. If you used the install default directory setting, the support folder will be located under a program folder name (such as DaqX) under the Program Files folder on the C: drive. The figure below illustrates the default install location for your C/C++ and Visual Basic (VB) programming language support. In the illustration, the 32-Bit Enhanced API folder (for C/C++ support) has been expanded to reveal its contents. Default Install Locations for Programming Language Support Note 1: In addition to folders labeled “Dynamic Loading,” “Include,” and “Lib,” the 32-bit Enhanced API folder includes program examples for primary data acquisition units (main units) and for DBKs. 1-2 Introduction 908494 Programmer’s Manual Driver Installation Driver installation uses a 32-bit setup on a Windows 95/98/Me or Windows NT/2000/XP system. When run, the setup routine will automatically detect the correct operating system and will install the appropriate driver. A Note Regarding Devices and API Command Applicability API commands cannot be used universally with all products. For example, a command that pertains only to analog output is of no use to a device that does not support analog I/O, or to a device that supports analog input, but not analog output. Thus it is important that you understand the features and capabilities of your hardware before using API Commands. Prior awareness can save a great deal of programming time and avoid possible frustration. One category of functionality that sometimes causes confusion is that of waveform/pattern output. The following table indicates which of the 4 types of waveform output apply to various product groups. Waveform output definitions follow the table. Waveform/Pattern Output Device Capabilities Product * Static Dynamic Waveform Streamed Digital Waveform Waveform Output from Pattern Output Disk DaqBoard/500 Series Yes No No No DaqBoard/1000 Series Yes Yes Yes No DaqBoard/2000 Series Yes Yes Yes Yes DaqBook/2000 Series Yes No No No DaqLab/2000 Series Yes No No No DaqScan/2000 Series Yes No No No /3000 Series Devices Yes Yes Yes Yes * Not all devices in a series have static waveform output capability.