Tektronix DAS-Scan Function Call Driver Users Guide

DAS-Scan Function Call Driver

USER’S GUIDE

DAS-Scan

Function Call Driver

User’s Guide

Revision A – July 1996

Part Number: 94890

New Contact Information

Keithley Instruments, Inc.

28775 Aurora Road

Cleveland, OH 44139

Technical Support: 1-888-KEITHLEY

Monday – Friday 8:00 a.m. to 5:00 p.m (EST)

Fax: (440) 248-6168

Visit our website at http://www.keithley.com

The information contained in this manual is believed to be accurate and reliable. However, Keithley Instruments, Inc., assumes no responsibility for its use or for any infringements of patents or other rights of third parties that may result from its use. No license is granted by implication or otherwise under any patent rights of Keithley Instruments, Inc.

KEITHLEY INSTRUMENTS, INC., SHALL NO T BE LIABLE FOR ANY SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RELATED TO THE USE OF THIS PRODUCT. THIS PRODUCT IS NOT DESIGNED WITH COMPONENTS OF A LEVEL OF RELIABILITY SUITABLE FOR USE IN LIFE SUPPORT OR CRITICAL APPLICATIONS.

Refer to your Keithley Instruments license agreement for speciﬁc warranty and liability information.

MetraByte is a trademark of Keithley Instruments, Inc. All other brand and product names are trademarks or registered trademarks of their respective companies.

All rights reserved. Reproduction or adaptation of any part of this documentation beyond that permitted by Section 117 of the 1976 United States Copyright Act without permission of the Copyright owner is unlawful.

Keithley MetraByte Division

Keithley Instruments, Inc.

440 Myles Standish Blvd. Taunton, MA 02780

FAX: (508) 880-0179

Telephone: (508) 880-3000

●

Preface

The DAS-Scan Function Call Driver User’s Guide provides information to help you write application programs for the DAS-Scan system using the DAS-Scan Function Call Dri ver. The DAS-Scan Function Call Driver supports the following Windows  -based languages:

●

Microsoft Borland

●

Microsoft Visual Basic

●



Visual C++  (up to Version 1.52)



C/C++ (Version 4.0 and 4.5)



for Windows (Version 3.0 and Version 4.0)

The manual is intended for application programmers using a DAS-Scan system with an IBM



PC AT



or compatible computer. It is assumed that you have read the DAS-Scan User’ s Guide to familiarize yourself with the system’s features, and that you have completed the appropriate hardware installation and conﬁguration. It is also assumed that you are experienced in programming in your selected language and that you are familiar with data acquisition principles.

The DAS-Scan Function Call Driver User’s Guide is organized as follows:

●

Chapter 1 contains the information needed to install the DAS-Scan Function Call Driver, a summary of the DAS-Scan Function Call Driver functions typically used when programming a DAS-Scan system, a series of ﬂow diagrams illustrating the procedures typically used when programming a DAS-Scan system, and information on how to get help.

Chapter 2 contains conceptual information about the DAS-Scan

●

Function Call Driver functions typically used when programming a DAS-Scan system.

vii

Chapter 3 contains conceptual information about additional

●

DAS-Scan Function Call Driver functions you can use when programming a DAS-Scan system.

Appendix A contains instructions for con v erting counts to voltage and

●

for converting counts to temperature.

An index completes this manual.

Keep the following conventions in mind as you use this manual:

●

References to Windows apply to Windows 3.1, Windows 3.11 for Workgroups, and Windows 95. When a feature applies to a speciﬁc Windows version, the complete version name is used.

●

Keyboard keys are represented in bold.

viii

Table of Contents

Preface

1

Getting Started

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2

Setup and Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2

Summary of Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4

Programming Flow Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . .1-6

Preliminary Steps for All Analog Input Operations . . . . . . . .1-7

Steps for a Single-Mode Analog Input Operation. . . . . . . . . .1-8

Steps for a DMA-Mode Analog Input Operation . . . . . . . . . .1-9

Getting Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-14

Available Operations

2

System Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

Initializing the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

Initializing a Board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2

Generating a Windows Event . . . . . . . . . . . . . . . . . . . . . . . . .2-3

Retrieving Revision Levels . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4

Analog Input Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Operation Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Single Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

DMA Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Accessing a Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7

Memory Allocation and Management. . . . . . . . . . . . . . . . . . .2-9

Gains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11

Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12

Addressing Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12

Specifying a Single Channel . . . . . . . . . . . . . . . . . . . . . .2-17

Specifying a Group of Consecutive Logical Channels. . .2-17

Specifying Channels in a Channel-Gain Queue. . . . . . . .2-18

Pacer Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-19

Internal Pacer Clock. . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20

External Pacer Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-21

iii

Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-22

Internal Trigger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-23

External Digital Trigger. . . . . . . . . . . . . . . . . . . . . . . . . .2-23

Hardware Gate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24

3

Additional Features

Summary of Additional Functions. . . . . . . . . . . . . . . . . . . . . . . .3-2

Additional Programming Flow Diagrams . . . . . . . . . . . . . . . . . .3-3

Preliminary Steps for All Analog Input Operations . . . . . . . .3-4

Steps for a Single-Mode Analog Input Operation. . . . . . . . . .3-5

Steps for an Interrupt-Mode Analog Input Operation. . . . . . .3-6

Steps for a DMA-Mode Analog Input Operation . . . . . . . . .3-12

Performing an Interrupt-Mode Operation . . . . . . . . . . . . . . . . .3-19

Accessing a Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20

Reserving Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20

Specifying Channels and Gains . . . . . . . . . . . . . . . . . . . . . .3-22

Specifying a Pacer Clock . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23

Specifying a Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23

Enabling a Hardware Gate . . . . . . . . . . . . . . . . . . . . . . . . . .3-23

Specifying Continuous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . .3-23

Reserving Large or Multiple Memory Buffers . . . . . . . . . . . . .3-24

Specifying Burst Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-25

Using the Burst Mode Conversion Clock . . . . . . . . . . . . . . . . .3-26

Specifying Pre-Trigger Acquisition . . . . . . . . . . . . . . . . . . . . . .3-26

Specifying About-Trigger Acquisition. . . . . . . . . . . . . . . . . . . .3-28

A

Data Formats

Converting Counts to Voltage. . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Converting Counts to Temperature . . . . . . . . . . . . . . . . . . . . . . A-3

Index

iv

List of Figures

Figure 2-1. Frame-Based Operation. . . . . . . . . . . . . . . . . . . . .2-7

Figure 2-2. Digital Trigger Conditions. . . . . . . . . . . . . . . . . .2-23

List of Tables

Table 1-1. Summary of Functions. . . . . . . . . . . . . . . . . . . . . .1-4

Table 2-1. A/D Frame Elements . . . . . . . . . . . . . . . . . . . . . . .2-9

Table 2-2. Analog Input Ranges . . . . . . . . . . . . . . . . . . . . . .2-11

Table 2-3. Virtual Boards and Logical Channels . . . . . . . . .2-13

Table 3-1. Summary of Additional Functions. . . . . . . . . . . . .3-2

Table 3-2. Functions Used to Assign Starting Addresses

in Interrupt Mode. . . . . . . . . . . . . . . . . . . . . . . . .3-22

Table A-1. Span Values For Data Conversion Equations . . . A-2

v

Table 1-1. Summary of Functions. . . . . . . . . . . . . . . . . . . . . .1-3

Table 2-1. A/D Frame Elements . . . . . . . . . . . . . . . . . . . . . . .2-5

Table 2-2. Functions Used to Assign Starting Address . . . .2-14

Table 2-3. Analog Input Ranges . . . . . . . . . . . . . . . . . . . . . .2-15

Table 2-4. Virtual Boards and Logical Channels . . . . . . . . .2-16

Table 3-1. Functions Used to Assign Starting Addresses. . . .3-4

Table A-1. Span Values For Data Conversion Equations . . . A-2

Figure 2-1. Interrupt-Mode Operation . . . . . . . . . . . . . . . . . . .2-4

Figure 2-2. Analog Trigger Conditions . . . . . . . . . . . . . . . . .2-27

Figure 2-3. Using a Hysteresis Value. . . . . . . . . . . . . . . . . . .2-29

Figure 2-4. Digital Trigger Conditions. . . . . . . . . . . . . . . . . .2-30

1

Getting Started

This chapter contains the following sections:

Overview - a description of the DAS-Scan Function Call Driver.

●

Setup and Installation - a list of the tasks you should perform before

using the DAS-Scan Function Call Driver.

●

Summary of Functions - a brief description of the DAS-Scan

Function Call Driver functions that are typically used when programming a DAS-Scan system.

●

Programming Flow Diagrams - an illustration of the procedures

you will typically follow when programming a DAS-Scan system using the DAS-Scan Function Call Driver.

●

Getting Help - information on how to get help when installing or

using the DAS-Scan Function Call Driver.

1-1

Overview

The DAS-Scan Function Call Driver is a library of data acquisition and control functions that is part of the ASO-SCAN software package. The ASO-SCAN software package includes the following:

●

Dynamic Link Libraries (DLLs) of Function Call Driver functions for Microsoft Visual C++, Borland C/C++, and Microsoft Visual Basic for Windo ws.

●

Support ﬁles, containing program elements, such as function prototypes and deﬁnitions of variable types, that are required by the Function Call Driver functions.

Utility programs that allow you to conﬁgure, calibrate, and test the

●

functions of the DAS-Scan system.

●

Language-speciﬁc example programs.

Setup and Installation

Before you use the DAS-Scan Function Call Driver to program your DAS-Scan system, make sure that you have performed the following tasks. Refer to the DAS-Scan User’s Guide for more information.

1. Unpack and inspect the components of your DAS-Scan system.

2. Create a channel map indicating the input signals you want to attach to each of the channels in your DAS-Scan system.

3. Conﬁgure the hardware components, as follows: – On the SCAN-AD-HR board, set the base I/O address switch

(S1) to indicate the appropriate base I/O address, and, if appropriate, set the J6 jumper to indicate an external pacer clock or an external digital trigger/hardware gate.

– On each SCAN-BRD assembly, set the address thumbwheels to

indicate the appropriate assembly address.

– If you are using SCAN-STP-TC screw terminal panels, set the J2

jumpers on each panel to indicate whether you are using cold junction compensation (CJC).

1-2 Getting Started

4. Mount the SCAN-STP screw terminal panels on DIN rails.

5. Attach the input signals to the appropriate SCAN-STP screw terminal panels.

6. Mount the SCAN-CH chassis in a 19-inch rack.

7. Attach one end of each SCAN-CAB-64 cable to the appropriate position in the SCAN-CH chassis. (Do not attach the other end of the SCAN-CAB-64 cables at this point.)

8. Attach a power cord to the power-supply panel of each SCAN-CH chassis.

9. Check the operation of the power supply in each SCAN-CH chassis.

10. Install the SCAN-BRD assemblies in the appropriate SCAN-CH chassis.

11. Make sure that power to the computer is turned OFF.

12. Install the SCAN-AD-HR board in your computer.

13. Attach the SCAN-AD-HR board to your ﬁrst SCAN-CH chassis using the S-1802/M cable.

14. Daisy-chain multiple SCAN-CH chassis, if required, using S-1802/MM cables.

15. Attach the other end of each SCAN-CAB-64 cable to the appropriate SCAN-STP screw terminal panel.

16. Connect an external pacer clock, external digital trigger, or hardware gate, if required, to the J5 connector on the SCAN-AD-HR board using a CAB-SMA-BNC cable.

17. Plug the power cords into the wall, and then power up your computer, the SCAN-CH chassis, and any equipment attached to the SCAN-STP screw terminal panels.

18. Install the ASO-SCAN software package.

19. Specify the conﬁguration options for your DAS-Scan system in the DAS-Scan Conﬁguration Utility.

20. Test the functions of the DAS-Scan system using the DAS-Scan Control Panel.

21. Look at the example programs provided with the ASO-SCAN software package. Refer to the FILES.TXT ﬁle in the installation directory for a list and description of the example programs.

Setup and Installation 1-3

Summary of Functions

Table 1-1 describes the functions in the DAS-Scan Function Call Driver that are typically used to program a DAS-Scan system. For more detailed information about the functions, refer to Chapter 2 of this manual and to the DAS-Scan Function Call Driver online help ﬁle (SCANFCD.HLP).

Table 1-1. Summary of Functions

Type of Function Name of Function Description

Initialization K_OpenDriver Initializes a Function Call Driver.

K_CloseDriver Closes a Function Call Driver. K_GetDevHandle Initializes a virtual board. K_FreeDevHandle Frees a device handle. K_DASDevInit Reinitializes a virtual board.

Operation K_ADRead Reads a single analog input value.

K_DMAStart Starts a DMA-mode operation. K_DMAStatus Gets the status of a DMA-mode operation. K_DMAStop Stops a DMA-mode operation. DASSCAN_EventEnable Enables the generation of a Windows event

(C/C++).

DASSCAN_EventDisable Disables the generation of a Windows event

(C/C++).

Frame management K_GetADFrame Accesses a frame for an analog input operation.

K_FreeFrame Frees a frame. K_ClearFrame Sets all frame elements to their default values.

1-4 Getting Started

Table 1-1. Summary of Functions (cont.)

Type of Function Name of Function Description

Memory management

Buffer address K_SetDMABuf Speciﬁes the address of a dynamically

Channel and gain K_SetChn Speciﬁes a single logical channel.

K_DMAAlloc Dynamically allocates a memory buffer for a

DMA-mode operation.

K_DMAFree Frees a memory buffer that was dynamically

allocated for a DMA-mode operation.

K_MoveBufToArray Transfers data from a dynamically allocated

memory buffer to a local array (Visual Basic for Windows).

allocated memory buffer.

K_SetStartStopChn Speciﬁes the ﬁrst and last logical channels in a

group of consecutive logical channels.

K_SetG Speciﬁes the gain for a group of consecutive

logical channels.

K_SetStartStopG Speciﬁes the ﬁrst and last logical channels in a

group of consecutive logical channels and the gain for all channels in the group.

K_SetChnGAry Speciﬁes the starting address of a channel-gain

queue.

K_FormatChnGAry Converts the format of a channel-gain queue

(Visual Basic for Windows).

K_RestoreChnGAry Restores a converted channel-gain queue

(Visual Basic for Windows).

K_SetADMode Speciﬁes the input range type (bipolar or

unipolar).

K_GetADMode Gets the input range type (bipolar or unipolar).

Clock K_SetClk Speciﬁes the pacer clock source.

K_SetClkRate Speciﬁes the clock rate for the internal pacer

clock. K_GetClkRate Gets the clock rate for the internal pacer clock. K_SetExtClkEdge Speciﬁes the active edge of an external pacer

clock.

Summary of Functions 1-5

Table 1-1. Summary of Functions (cont.)

Type of Function Name of Function Description

Trigger K_SetTrig Speciﬁes the trigger source.

K_SetDITrig Sets up a digital start trigger.

Gate K_SetGate Speciﬁes the status of a hardware gate. Miscellaneous K_GetErrMsg Gets the address of an error message string

(C/C++). K_GetVer Gets revision numbers. K_GetShellVer Gets the current DAS shell version.

Programming Flow Diagrams

This section contains a series of programming ﬂow diagrams illustrating the procedures you will typically follow when programming a D AS-Scan system using the DAS-Scan Function Call Driver. For more detailed information about the programming procedures, refer to the DAS-Scan Function Call Driver online help ﬁle (SCANFCD.HLP).

Although error checking is not shown in the ﬂow diagrams, it is recommended that you check the error/status code returned by each function used in your application program.

1-6 Getting Started

Preliminary Steps for All Analog Input Operations

Install all required ﬁles,

including the function and

variable type deﬁnition ﬁle

Declare and initialize program

variables

Initialize the driver

(K_OpenDriver)

Initialize a virtual board

(K_GetDevHandle)

Using another virtual board?

No

Perform the steps appropriate to your

operation (see the operation-speciﬁc

ﬂow diagrams)

Yes

Programming Flow Diagrams 1-7

Steps for a Single-Mode Analog Input Operation

Declare a variable in which

to store a single analog

input value

Read the count value

(K_ADRead)

Convert the count value

to voltage or degrees

Operation complete

1-8 Getting Started

Steps for a DMA-Mode Analog Input Operation

Access a frame for a virtual board

(K_GetADFrame)

Allocate a buffer

(K_DMAAlloc)

Specify the starting address

of the buffer

(K_SetDMABuf)

Continued on next page

Programming Flow Diagrams 1-9

Steps for a DMA-Mode Analog Input Operation (cont.)

Continued from previous page

Using a

channel-

gain

No

Using a

group of

consecutive

channels?

Yes

Specify the starting address

of the channel-gain queue

Deﬁne the

channel-gain

queue

Using

Visual

Basic?

(K_SetChnGAry)

Yes

No

Specify the ﬁrst and last channels

and the gain for all channels

K_SetStartStopChn and K_SetG)

Yes

(K_SetStartStopG or

Format the

channel-gain queue

(K_FormatChnGAry)

Modify the

channel-

gain

queue?

No

Yes

Restore the

channel-gain queue

(K_RestoreChnGAry)

No

Specify a single channel

(K_SetChn)

Specify the gain

for the single channel

(K_SetG)

Continued on next page

1-10 Getting Started

Steps for a DMA-Mode Analog Input Operation (cont.)

Continued from previous page

Specify the clock source

(K_SetClk)

Using

internal

clock?

Specify the external clock edge

(K_SetExtClkEdge)

Using an

external

digital start

trigger?

Specify an internal start trigger

(K_SetTrig)

Using a

hardware

gate?

Yes

No

Yes

No

Yes

Set the clock rate

(K_SetClkRate)

Specify an external start trigger

(K_SetTrig)

Specify digital

trigger conditions

(K_SetDITrig)

Specify the gate polarity

(K_SetGate)

No

Disable the gate

(K_SetGate)

Continued on next page

Programming Flow Diagrams 1-11

Steps for a DMA-Mode Analog Input Operation (cont.)

Continued from previous page

Setting up

another

virtual board?

No

Start the DMA-mode operation

(K_DMAStart)

Monitor the status of the operation

(K_DMAStatus)

Scanning

another

virtual board?

No

Yes

Access a frame for the virtual board;

go to the top of page 1-9

Continued on next page

1-12 Getting Started

Steps for a DMA-Mode Analog Input Operation (cont.)

Continued from previous page

Using Visual

Basic?

No

Read data

from each buffer

Convert data

from each buffer

Free each buffer

(K_DMAFree)

Free each frame

Yes

Transfer data from each

buffer to a local array (K_MoveBufToArray)

Read data

from each array

Convert data

from each array

Operation complete

Programming Flow Diagrams 1-13

Getting Help

If you need help installing or using the DAS-Scan Function Call Driver, call your local sales ofﬁce or call the following number for technical support:

(508) 880-3000 Monday - Friday, 8:00

An applications engineer will help you diagnose and resolve your problem over the telephone. Please make sure that you hav e the follo wing information available before you call:

SCAN-AD-HR board conﬁguration

SCAN-BRD assembly conﬁguration

A.M.

- 6:00

Serial # Revision code Base address setting Interrupt level setting DMA channel(s) External clock, trigger, or gate

Model Serial # Revision code Address setting (0h to 3Fh) Unipolar or bipolar mode

P.M.

, Eastern Time

_______________________ _______________________ _______________________ _______________________ _______________________ _______________________

_______________________ _______________________ _______________________ _______________________ _______________________

SCAN-BRD assembly conﬁguration

1-14 Getting Started

Model Serial # Revision code Address setting (0h to 3Fh) Unipolar or bipolar mode

_______________________ _______________________ _______________________ _______________________ _______________________

SCAN-BRD assembly conﬁguration

Model Serial # Revision code Address setting (0h to 3Fh) Unipolar or bipolar mode

_______________________ _______________________ _______________________ _______________________ _______________________

SCAN-BRD assembly conﬁguration

Getting Help 1-15

Model Serial # Revision code Address setting (0h to 3Fh) Unipolar or bipolar mode

_______________________ _______________________ _______________________ _______________________ _______________________

SCAN-BRD assembly conﬁguration

Model Serial # Revision code Address setting (0h to 3Fh) Unipolar or bipolar mode

_______________________ _______________________ _______________________ _______________________ _______________________

Computer

Operating system Compiler

1-16 Getting Started

Manufacturer CPU type Clock speed (MHz) KB of RAM Video system BIOS type

Windows version _______________________ Language

Manufacturer Version

_______________________ _______________________ _______________________ _______________________ _______________________ _______________________

_______________________ _______________________ _______________________

Tektronix DAS-Scan Function Call Driver Users Guide

Specifications and Main Features

Frequently Asked Questions

User Manual