Tektronix DAS-TC Function Call Driver Users Guide

DAS-TC
Function Call Driv er

USER’S GUIDE

DAS-TC

Function Call Driver

User’s Guide

Revision A – March 1996

Part Number: 84080

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: [phone]

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 specific 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.

© Copyright Keithley Instruments, Inc., 1996.

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: [phone]

Telephone: [phone]

●

Preface

The DAS-TC Function Call Driver User’s Guide describes how to write
application programs for DAS-TC and DAS-TC/B boards using the
DAS-TC Function Call Driver. The DAS-TC Function Call Driver
supports the following DOS-based languages:

●

Microsoft



QuickBasic  (Version 4.5)

Microsoft Professional Basic (Version 7.0 and higher)

●

Microsoft C/C++ (Version 7.0 and higher)

●

Borland

●

●

Borland Turbo Pascal



C/C++ (Version 4.0 and higher)



for DOS (Version 6.0 and higher)

The DAS-TC Function Call Driver also supports the following
Windows  -based languages:

●

Microsoft C/C++ (Version 7.0 and higher)
Borland C/C++ (Version 4.0 and higher)

●

Microsoft Visual Basic for Windows

●

●

Microsoft Visual C++  (Version 1.5)

●

Borland Turbo Pascal for Windows (Version 1.0)



(Version 3.0 and higher)

The manual is intended for application programmers using a DAS-TC or
DAS-TC/B board in an IBM



PC AT



or compatible computer. Before
using this manual, read the user’s guide for your board to familiarize
yourself with the board’s features and complete the appropriate hardw are
installation and configuration. It is assumed that you are experienced in
programming in your selected language and that you are familiar with
data acquisition principles.

vii

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

Chapter 1 contains the information needed to get started using the

●

DAS-TC Function Call Driver and to get help.

●

Chapter 2 contains the background information needed to use the
functions included in the DAS-TC Function Call Driver.

●

Chapter 3 contains programming guidelines and language-specific
information related to using the DAS-TC Function Call Driver.

●

Chapter 4 contains detailed descriptions of the DAS-TC Function
Call Driver functions, arranged in alphabetical order.

●

Appendix A contains a list of the error codes returned by DAS-TC
Function Call Driver functions.

Appendix B contains information on the data formats used.

●

An index completes this manual.

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

●

References to BASIC apply to all DOS-based BASIC languages
(Microsoft QuickBasic and Microsoft Professional Basic). When a
feature applies to a specific language, the complete language name is
used. References to Visual Basic for Windows apply to Microsoft
Visual Basic for Windows.

Keyboard keys are represented in bold.

●

viii

Table of Contents

Preface

1

Getting Started

2

Available Operations

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

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

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

Retrieving Revision Levels . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3

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

Analog Input Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4

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

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

Synchronous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

Interrupt Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

Memory Allocation and Management. . . . . . . . . . . . . . . . . . .2-7

Dimensioning a Local Array . . . . . . . . . . . . . . . . . . . . . . .2-7

Dynamically Allocating a Memory Buffer. . . . . . . . . . . . .2-8

Assigning the Starting Address . . . . . . . . . . . . . . . . . . . . .2-9

Channels, Gains, and Inputs . . . . . . . . . . . . . . . . . . . . . . . . .2-10

Specifying a Single Channel or a Group of Consecutive

Channels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11

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

Buffering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13

Programming with the Function Call Driver

3

How the Driver Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1

Programming Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5

Preliminary Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6

Analog Input Programming Tasks . . . . . . . . . . . . . . . . . . . . . . . .3-6

Single-Mode Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6

Synchronous-Mode Operations. . . . . . . . . . . . . . . . . . . . . . . .3-7

Interrupt-Mode Operations . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9

iii

C/C++ Programming Information . . . . . . . . . . . . . . . . . . . . . . .3-11

Dimensioning and Assigning a Local Array . . . . . . . . . . . . .3-11

Dynamically Allocating and Assigning a Memory Buffer . .3-12

Allocating a Memory Buffer . . . . . . . . . . . . . . . . . . . . . .3-12

Accessing the Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13

Creating a Channel-Gain Queue . . . . . . . . . . . . . . . . . . . . . .3-13

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-14

Programming in Microsoft C/C++ (for DOS). . . . . . . . . . . .3-15

Programming in Microsoft C/C++ (for Windows) . . . . . . . .3-16

Programming in Borland C/C++ (for DOS) . . . . . . . . . . . . .3-17

Programming in Borland C/C++ (for Windows). . . . . . . . . .3-18

Turbo Pascal Programming Information . . . . . . . . . . . . . . . . . .3-20

Dimensioning and Assigning a Local Array . . . . . . . . . . . . .3-20

Dynamically Allocating and Assigning a Memory Buffer . .3-20

Reducing the Memory Heap . . . . . . . . . . . . . . . . . . . . . .3-21

Allocating a Memory Buffer . . . . . . . . . . . . . . . . . . . . . .3-22

Accessing the Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23

Creating a Channel-Gain Queue . . . . . . . . . . . . . . . . . . . . . .3-23

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-24

Programming in Borland Turbo Pascal (for DOS) . . . . . . . .3-24

Programming in Borland Turbo Pascal for Windows . . . . . .3-25

Visual Basic for Windows Programming Information. . . . . . . .3-26

Dimensioning and Assigning a Local Array . . . . . . . . . . . . .3-26

Dynamically Allocating and Assigning a Memory Buffer . .3-26

Allocating a Memory Buffer . . . . . . . . . . . . . . . . . . . . . .3-27

Accessing the Data from Buffers with Fewer than

64K Bytes3-27

Accessing the Data from Buffers with More than

64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-28

Creating a Channel-Gain Queue . . . . . . . . . . . . . . . . . . . . . .3-30

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-31

Programming in Microsoft Visual Basic for Windows . . . . .3-31

BASIC Programming Information. . . . . . . . . . . . . . . . . . . . . . .3-32

Dimensioning and Assigning a Local Array . . . . . . . . . . . . .3-32

Dynamically Allocating and Assigning a Memory Buffer . .3-32

Reducing the Memory Heap . . . . . . . . . . . . . . . . . . . . . .3-33

Allocating a Memory Buffer . . . . . . . . . . . . . . . . . . . . . .3-33

Accessing the Data from Buffers with Fewer

than 64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34

Accessing the Data from Buffers with More

than 64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34

Creating a Channel-Gain Queue . . . . . . . . . . . . . . . . . . . . . .3-37

iv

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-38

Programming in Microsoft QuickBasic . . . . . . . . . . . . . . . .3-39

Programming in Microsoft Professional Basic . . . . . . . . . . .3-40

Function Reference

4

DASTC_DevOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5

DASTC_GETCJC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-8

DASTC_GetDevHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11

K_ADRead. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13

K_ADReadL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16

K_ADReadR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19

K_ClearFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22

K_CloseDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24

K_ClrContRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-26

K_DASDevInit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-28

K_FormatChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-30

K_FreeDevHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32

K_FreeFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-34

K_GetADFrame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-36

K_GetDevHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38

K_GetErrMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40

K_GetShellVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-42

K_GetVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-45

K_IntAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-48

K_IntFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-51

K_IntStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-53

K_IntStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-55

K_IntStop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-58

K_MoveBufToArrayL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-61

K_MoveBufToArrayR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-63

K_OpenDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-65

K_RestoreChnGAry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-68

K_SetBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-70

K_SetBufL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-72

K_SetBufR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-74

K_SetChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-76

K_SetContRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-79

K_SetStartStopChn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-81

K_SyncStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-84

v

vi

Error/Status Codes

A

B

Data Formats

Integer Number Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Floating-Point Number Types . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

Index

List of Figures

Figure 3-1. Single-Mode Function . . . . . . . . . . . . . . . . . . . . . .3-2

Figure 3-2. Interrupt-Mode Operation . . . . . . . . . . . . . . . . . . .3-3

List of Tables

Table 2-1. Supported Operations . . . . . . . . . . . . . . . . . . . . . .2-1

Table 2-2. Input Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10

Table 2-3. Gain Codes for Voltage Inputs . . . . . . . . . . . . . .2-11

Table 3-1. A/D Frame Elements . . . . . . . . . . . . . . . . . . . . . . .3-4

Table 3-2. Setup Functions for Synchronous-Mode

Analog Input Operations . . . . . . . . . . . . . . . . . . . .3-8

Table 3-3. Setup Functions for Interrupt-Mode

Analog Input Operations . . . . . . . . . . . . . . . . . . . .3-9

Table 3-4. Protected-Mode Memory Architecture . . . . . . . .3-28

Table 3-5. Real-Mode Memory Architecture . . . . . . . . . . . .3-35

Table 4-1. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2

Table 4-2. Data Type Prefixes. . . . . . . . . . . . . . . . . . . . . . . . .4-4

Table A-1. Error/Status Codes. . . . . . . . . . . . . . . . . . . . . . . . A-1

Table B-1. Integer Input Error Conditions. . . . . . . . . . . . . . . B-2

Table B-2. Floating-Point Input Error Conditions. . . . . . . . . B-2

1

Getting Started

The DAS-TC Function Call Driver is a library of data acquisition and
control functions (referred to as the Function Call Driver or FCD
functions). It is part of the following two software packages:

●

DAS-TC standard software package - This is the software package

that is shipped with the DAS-TC and DAS-TC/B boards; it includes
the following:

– Libraries of FCD functions for Microsoft QuickBasic and

Microsoft Professional Basic.

– Support files, containing program elements, such as function

prototypes and definitions of variable types, that are required by
the FCD functions.

– Utility programs (DOS-based only) that allow you to configure

and test the features of DAS-TC and DAS-TC/B boards.

– Language-specific example programs.

ASO-TC software package - This is the advanced software option

●

for the DAS-TC boards. It includes the following:
– Libraries of FCD functions for Microsoft C/C++, Borland

C/C++, and Borland Turbo Pascal.

– Dynamic Link Libraries (DLLs) of FCD functions for Microsoft

C/C++, Borland C/C++, Microsoft Visual Basic for Windows,
Microsoft Visual C++, and Borland Turbo Pascal for Windows.

– Support files, containing program elements, such as function

prototypes and definitions of variable types, that are required by
the FCD functions.

1-1

– Utility programs (DOS-based and Windows-based) that allow

you to configure and test the features of the DAS-TC and
DAS-TC/B boards.

– Language-specific example programs.

Before you use the Function Call Driver, make sure that you have
installed the software and your board using the procedures described in
the user’s guide for your board.

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

[phone]
Monday - Friday, 8:00

A.M.

- 6:00

P.M.

, Eastern Time

An applications engineer will help you diagnose and resolve your
problem over the telephone.

1-2 Getting Started

Please make sure that you have the follo wing information av ailable before
you call:

DAS-TC/B board

Computer

Operating
system

Software
package

Compiler
(if applicable)

Model
Serial #
Revision code
Base Address
Interrupt Level
Thermocouple type

Manufacturer
CPU type
Clock speed (MHz)
Math coprocessor
Amount of RAM
Video system
BIOS type
Memory manager

DOS version
Windows version

Name
Serial #
Version
Invoice/Order #

Language
Manufacturer
Version

_____________________
_____________________
_____________________
_____________________
_____________________
_____________________

_____________________
386 486 Pentium ____
____________________
Yes No
_____________________
EGA VGA SVGA
_____________________
_____________________

_____________________

3.0 3.1 95
_____________________

_____________________
_____________________
_____________________

_____________________
_____________________
_____________________

Accessories

Type/Number
Type/Number
Type/Number
Type/Number
Type/Number
Type/Number
Type/Number
Type/Number

_____________________
_____________________
_____________________
_____________________
_____________________
_____________________
_____________________
_____________________

1-3

2

Available Operations

This chapter contains the background information you need to use the
FCD functions to perform operations on DAS-TC and D AS-TC/B boards.
Table 2-1 lists the supported operations.

System Operations

This section describes the miscellaneous and general maintenance
operations that apply to DAS-TC and DAS-TC/B boards and to the
DAS-TC Function Call Driver. It includes information on the following
operations:

Initializing the driver

●

Initializing a board

●

●

Retrieving revision levels

●

Handling errors

Table 2-1. Supported Operations

Operation Page Reference

System page 2-1
Analog input page 2-4

System Operations 2-1

Initializing the Driver

You must initialize the DAS-TC Function Call Driver and any other
Keithley DAS Function Call Drivers you are using in your application
program. To initialize the drivers, use the K_OpenDriver function. You
specify the driver you are using and the configuration file that defines the
use of the driver. The driver returns a unique identifier for the driver; this
identifier is called the driver handle.

You can specify a maximum of 30 driver handles for all the Keithley
MetraByte drivers initialized from all your application programs. If you
no longer require a driver and you want to free some memory or if you
have used all 30 driver handles, you can use the K_CloseDriver function
to free a driver handle and close the associated driver.

If the driver handle you free is the last driver handle specified for a
Function Call Driver, the driver is shut down. (For Windows-based
languages only, the DLLs associated with the Function Call Driver are
shut down and unloaded from memory.)

Note:

K_OpenDriver and K_CloseDriver are not available. You must use the
DASTC_DevOpen function instead. DASTC_DevOpen initializes the

DAS-TC Function Call Driver according to the configuration file you
specify. Refer to page 4-5 for more information. In BASIC and Turbo
Pascal, closing the DAS-TC Function Call Driver is not required.

Initializing a Board

The DAS-TC Function Call Driver supports up to two DAS-TC or
DAS-TC/B boards. You must use the K_GetDevHandle function to
specify the boards you want to use. The driver returns a unique identifier
for each board; this identifier is called the device handle.

Device handles allow you to communicate with more than one Keithley
MetraByte DAS board. You use the device handle returned by

K_GetDevHandle in subsequent function calls related to the board.

If you are programming in BASIC or Turbo Pascal,

2-2 Available Operations

You can specify a maximum of 30 device handles for all the Keithley
MetraByte DAS boards accessed from all your application programs. If a
board is no longer being used and you want to free some memory or if
you have used all 30 device handles, you can use the K_FreeDevHandle
function to free a device handle.

Note:

K_GetDevHandle and K_FreeDevHandle are not available. You must

use the DASTC_GetDevHandle function instead. Refer to page 4-11 for
more information. In BASIC or Turbo Pascal, freeing a device handle is
not required.

Use K_GetDevHandle or DASTC_GetDevHandle the first time you
initialize a DAS-TC or DAS-TC/B board only. Once you have a device
handle, you can reinitialize a board as needed by using the

K_DASDevInit function.

If you are programming in BASIC or Turbo Pascal,

Retrieving Revision Levels

If you are using functions from different Keithley DAS Function Call
Drivers in the same application program or if you are having problems
with your application program, you may want to verify which versions of
the Function Call Driver, Keithley DAS Driver Specification, and
Keithley DAS Shell are used by your Keithley MetraByte DAS board.

The K_GetVer function allows you to get both the revision number of the
Function Call Driver and the re vision number of the K eithley DAS Driver
Specification to which the driver conforms.

The K_GetShellVer function allows you to get the revision number of
the Keithley DAS Shell (the Keithley DAS Shell is a group of functions
that are shared by all Keithley MetraByte DAS boards).

System Operations 2-3

Handling Errors

Each FCD function returns a code indicating the status of the function. To
ensure that your application program runs successfully, it is
recommended that you check the returned code after the execution of
each function. If the status code equals 0, the function executed
successfully and your program can proceed. If the status code does not
equal 0, an error occurred; ensure that your application program takes the
appropriate action. Refer to Appendix A for a complete list of error codes.

Each supported language uses a different procedure for error checking;
refer to the following pages for more information:

C/C++ page 3-14
Turbo Pascal page 3-24
Visual Basic for Windows page 3-31
BASIC page 3-38

For C-language application programs only, the Function Call Driver
provides the K_GetErrMsg function, which gets the address of the string
corresponding to an error code.

Analog Input Operations

This section describes the following:

●

Analog input operation modes available.
How to allocate and manage memory for analog input operations.

●

●

How to specify the following for an analog input operation:
– Channels and input range
– Buffering mode

2-4 Available Operations

Operation Modes

The operation mode determines which attributes you can specify for an
analog input operation and how data is transferred from the D AS-TC and
DAS-TC/B boards to computer memory. You can perform analog input
operations in single mode, synchronous mode, and interrupt mode, as
described in the following sections.

Single Mode

In single mode, the board acquires a single sample from an analog input
channel. The driver initiates the con v ersion; you cannot perform any other
operation until the single-mode operation is complete.

Use the K_ADRead function that is appropriate to your programming
language to start an analog input operation in single mode. For each
function you specify the board you want to use, the analog input channel
to read, the gain for that channel (for voltage inputs only), and the
variable in which to store the converted data.

Note:

for thermocouple inputs.

Depending on your configuration, the data is returned as a single voltage
or temperature value in engineering units. Refer to Appendix B for more
information on the format of the data returned.

If you wish, you can use a K_ADRead function with software looping to
acquire more than one value from one or more channels. Typically, when
acquiring more than one value you want more control over the data
transfer than is possible with a single-mode function; in such cases, use
either synchronous or interrupt mode, described in the next sections.

Note:

channel, use the single-mode function DASTC_GETCJC . You can use
the resulting value to correct a temperature reading when you want to
perform your own linearization.

Analog Input Operations 2-5

For thermocouple inputs, specify 0 for the gain; the gain is ignored

To read the value of the CJC (cold junction compensation)

Synchronous Mode

In synchronous mode, the board acquires a single sample or multiple
samples from one or more analog input channels. After transferring the
specified number of samples to computer memory, the driver returns
control to the application program. You cannot perform any other
operation until a synchronous-mode operation is complete.

The DAS-TC and DAS-TC/B boards transfer data in blocks, where the
block size equals the number of channels specified. Suppose, for
example, you requested 43 samples using 10 channels. The Function Call
Driver actually acquires 50 values in five blocks of 10 samples each. The
first 40 values are transferred from the first four blocks that were acquired
and the remaining three samples are transferred from the fifth acquired
block of 10 samples.

Interrupt Mode

Use the K_SyncStart function to start an analog input operation in
synchronous mode.

Depending on your configuration, the data is returned as voltage or
temperature values in engineering units. Refer to Appendix B for more
information on the format of the data returned.

In interrupt mode, the board acquires a single sample or multiple samples
from one or more analog input channels. Once the analog input operation
begins, control returns to your application program. The hardware
transfers the data from the board to a user-defined buffer in computer
memory using an interrupt service routine.

As in synchronous mode, in interrupt mode, the DAS-TC and DAS-TC/B
boards transfer data in blocks, where the block size equals the number of
channels specified.

Use the K_IntStart function to start an analog input operation in
interrupt mode.

Depending on your configuration, the data is returned as voltage or
temperature values in engineering units. Refer to Appendix B for more
information on the format of the data returned.

2-6 Available Operations

You can specify either single-cycle or continuous buffering mode for
interrupt-mode operations. Refer to page 2-13 for more information on
buffering modes. Use the K_IntStop function to stop a continuous-mode
interrupt operation. Use the K_IntStatus function to determine the
current status of an interrupt operation.

Memory Allocation and Management

Synchronous-mode and interrupt-mode analog input operations on the
DAS-TC and DAS-TC/B boards require a single array or memory buffer
in which to store acquired data. The ways you can allocate and manage
memory are described in the following sections.

Dimensioning a Local Array

For the DAS-TC and DAS-TC/B boards, the simplest way to reserve a
memory buffer is to dimension an array within your application program.
The advantage of this method is that the array is directly accessible to
your application program. The limitations of this method are as follows:

Certain programming languages limit the size of local arrays.

●

Local arrays occupy permanent memory areas; these memory areas

●

cannot be freed to make them available to other programs or
processes.

Make sure that the array you dimension matches the data type (long
integer or floating point) specified in the configuration file. A single
sample is four bytes long. Therefore, you should declare a local array as
an array of four byte elements, the size of which is at least equal to the
number of samples you are acquiring. For example, if you want to acquire
16,384 samples, you must dimension a 64K byte array.

Analog Input Operations 2-7

Dynamically Allocating a Memory Buffer

If you wish, you can also reserve a memory buffer by allocating it
dynamically outside of your application program’s memory area. The
advantages of this method are as follows:

●

The size of the buffer is limited by the amount of free physical
memory available in your computer at run time.

A dynamically allocated memory buffer can be freed to make it

●

available to other programs or processes.

The limitation of this method is that for Visual Basic for Windows and
BASIC, the data in a dynamically allocated memory buffer is not directly
accessible to your program. You must use the K_MoveBufToArrayL
function (for long integer arrays) or the K_MoveBufToArrayR function
(for floating-point arrays) to move the data from the dynamically
allocated memory buffer to the program’s local array. For Visual Basic for
Windows, refer to page 3-26 for more information; for BASIC, refer to
page 3-32 for more information.

Use the K_IntAlloc function to dynamically allocate a memory buffer for
a synchronous-mode or interrupt-mode operation. You specify the
operation requiring the buffer and the number of samples to store in the
buffer. The driver returns the starting address of the buffer and a unique
identifier for the buffer; this identifier is called the memory handle. When
the buffer is no longer required, you can free the b uf fer for another use by
specifying this memory handle in the K_IntFree function.

Make sure that the pointers to the buffers allocated by K_IntAlloc are
appropriate to the number type (long integer or floating point) specified in
the configuration file.

2-8 Available Operations

Notes:

For DOS-based languages, the area used for dynamically
allocated memory buffers is referred to as the far heap; for
Windows-based languages, this area is referred to as the global heap.
These heaps are areas of memory left unoccupied as your application
program and other programs run.

For DOS-based languages, the K_IntAlloc function uses the DOS Int 21h
function 48h to dynamically allocate far heap memory. For
Windows-based languages, the K_IntAlloc function calls the

GlobalAlloc API function to allocate the desired buffer size from the

global heap.

For Windows-based languages, dynamically allocated memory is
guaranteed to be fixed and locked in memory.

Assigning the Starting Address

After you dimension your array or allocate your buffer, you must assign
the starting address of the array or buffer and the number of samples to
store in the array or buffer. Each supported programming language
requires a particular function and procedure for assigning the starting
address; refer to the following table for more information:

Language Function Refer to

C/C++ K_SetBuf page 3-11
Turbo Pascal K_SetBuf page 3-20
Visual Basic for Windows K_SetBufL

K_SetBufR

BASIC K_SetBufL

K_SetBufR

Notes

1

Use K_SetBufL for long integer arrays or buffers; use

K_SetBufR for floating-point arrays or buffers.

Analog Input Operations 2-9

1

page 3-26

page 3-32

Channels, Gains, and Inputs

DAS-TC and DAS-TC/B boards are software-configurable for up to 16
differential analog input channels (numbered 0 through 15). You can mix
and match thermocouple and voltage inputs. You configure the channels
using the DASTCCFG.EXE configuration utility; refer to the user’s guide
for your board for more information. Table 2-2 lists the input types
supported by the DAS-TC and DAS-TC/B boards.

Table 2-2. Input Types

Voltage Inputs − 2.5 V to 10 V

20 mV to 80 mV
15 mV to 60 mV

6.25 mV to 25 mV

−

−

−

Thermocouple
Inputs

Type J
Type K
Type E
T ype T
Type R
Type S
Type B

The input range is usually determined by the settings in the configuration
file. However, for voltage inputs only, you can specify an input range
using the gain and gain code, shown in Table 2-3. (The gain code is used
by the FCD functions to represent the gain.) For thermocouple inputs, the
gain is ignored; specify a gain code of 0 for thermocouple inputs.

2-10 Available Operations

Table 2-3. Gain Codes for Voltage Inputs

−

−

Gain
Code Gain

0 1
1 125
2 166.67 −15 mV to 60 mV
3 400 −6.25 mV to 25 mV

Voltage
Input Range

2.5 V to 10 V
20 mV to 80 mV

Depending on the settings in the configuration file, data is returned in
volts, degrees Celsius, or degrees Fahrenheit, as appropriate for the input
types configured. Refer to Appendix B for information on the data
formats.

How you specify a channel and the input range differs depending on the
operation mode and the sequence of channels you want to use, as
described in the following sections.

Specifying a Single Channel or a Group of Consecutive Channels

For single-mode operations, you can acquire a single sample from a
single channel. Use the K_ADRead function appropriate to your
programming language to specify an analog input channel and the gain
for the channel (for voltage inputs only).

Note:

For thermocouple inputs, the gain is ignored; specify a gain code

of 0 for channels configured as thermocouple inputs.

For synchronous-mode and interrupt-mode analog input operations, you
can acquire samples from a single channel or a group of consecutive
channels. Use the K_SetStartStopChn function to specify the first and
last channels in the group; to read a single channel, specify the same
channel as both the start and the stop channel. The input ranges of the
channels are determined by the settings in the configuration file.

Analog Input Operations 2-11

The channels are sampled in order from the first to the last. For example,
if the start channel is 10 and the stop channel is 15, the channels are
sampled in the following order: 10, 11, 12, 13, 14, 15. If the start channel
is 10 and the stop channel is 3, the channels are sampled in the following
order: 10, 11, 12, 13, 14, 15, 0, 1, 2, 3. The channels are repeatedly
sampled in the specified order until the required number of samples is
read.

Note: When you use the K_SetStartStopChn function, the Function

Call Driver reads the configuration file to determine whether the signal
connected to the specified channel is a voltage input or a thermocouple
input and to determine the appropriate gain for that channel. If you want
to change the gain without changing the configuration file, use a
channel-gain queue, as described in the next section.

Specifying Channels in a Channel-Gain Queue

For synchronous-mode and interrupt-mode analog input operations, you
can acquire samples from channels in a software channel-gain queue. In
the channel-gain queue, you specify the channels you want to sample, the
gain for the channels (voltage inputs only), and the order in which you
want to sample them.

Note: For thermocouple inputs, the gain is ignored; specify a gain code

of 0 for channels configured as thermocouple inputs.

You can set up the channels in a channel-gain queue either in consecutive
or nonconsecutive order . You can also specify the same channel more than
once.

The channels are sampled in order from the first channel in the queue to
the last channel in the queue; the channels in the queue are then sampled
again until the specified number of samples is read.

2-12 Available Operations

The way that you specify the channels in a channel-gain queue depends
on the language you are using. Refer to the following pages for more
information:

C/C++ page 3-13
Turbo Pascal page 3-23
Visual Basic for Windows page 3-30
BASIC page 3-37

After you create the channel-gain queue in your program, use the
K_SetChnGAry function to specify the starting address of the
channel-gain queue.

Buffering Modes

The buffering mode determines how the driver stores the converted data
in the array or buffer. For interrupt-mode analog input operations, you can
specify one of the following buffering modes:

● Single-cycle mode- In single-cycle mode, after the board con verts the

specified number of samples and stores them in the array or buffer,
the operation stops automatically. Single-cycle mode is the default
buffering mode. To reset the buffering mode to single-cycle, use the
K_ClrContRun function.

● Continuous mode - In continuous mode, the board continuously

converts samples and stores them in the array or buffer until it
receives a stop function; any values already stored in the array or
buffer are overwritten. Use the K_SetContRun function to specify
continuous buffering mode.

If you are using continuous buffering, as soon as the last block of
samples is transferred, the following occur:

– the transfer count and buffer pointer are reset to zero
– K_IntStatus returns zero instead of the requested sample size in

the index parameter

– the driver begins to overwrite your buffer’s data

Analog Input Operations 2-13

Therefore, if your application requires consecutive blocks of data,
you should begin processing the buffer before the buffer is full, using
K_IntStatus to determine how many blocks have been transferred
(this function’s index parameter increments by the block size).

Note: Buffering modes are not meaningful for synchronous-mode

operations, since only single-cycle mode applies.

2-14 Available Operations

3

Programming with the

Function Call Driver

This chapter contains an overview of the structure of the Function Call
Driver, as well as programming guidelines and language-specific
information to assist you when writing application programs with the
Function Call Driver.

How the Driver Works

When writing application programs, you can use functions from one or
more Keithley MetraByte DAS Function Call Drivers. You initialize each
driver according to a particular configuration file. If you are using more
than one driver or more than one configuration file with a single driver,
the driver handle uniquely identifies each driver or each use of the driver.

You can program one or more boards in your application program. Up to
two DAS-TC or DAS-TC/B boards are supported. You initialize each
board using a unique device handle to identify each board. Each device
handle is associated with a particular driver.

The Function Call Driver allows you to perform operations in various
operation modes. For single mode, the operation is performed with a
single call to a function; the attributes of the operation are specified as
arguments to the function. Figure 3-1 illustrates the syntax of the
single-mode, analog input operation function K_ADRead . The

K_ADReadL and K_ADReadR functions have the same syntax.

How the Driver Works 3-1

Single-Mode Function

K_ADRead (

board

,

channel
gain
buffer

,

,

)

Figure 3-1. Single-Mode Function

Attributes of Operation

Board number
Analog input channel
Gain applied to channel
Buffer for data

For other operation modes, such as interrupt mode, the driver uses frames
to perform the operation. A frame is a data structure whose elements
define the attributes of the operation. Each frame is associated with a
particular board, and therefore, with a particular driver.

Frames help you create structured application programs. You set up the
attributes of the operation in advance, using a separate function call for
each attribute, and then start the operation at an appropriate point in your
program.

Frames are useful for operations that have many defining attrib utes, since
providing a separate argument for each attribute could make a function’s
argument list unmanageably long. In addition, some attributes, such as the
buffering mode, are available only for operations that use frames.

You indicate that you want to perform an operation by getting an
available frame for the dri ver. The driver returns a unique identifier for the
frame; this identifier is called the frame handle. You then specify the
attributes of the operation by using setup functions to define the elements
of the frame associated with the operation. For example, to specify the
channels on which to perform an operation, you would use the

K_SetStartStopChn setup function.

3-2 Programming with the Function Call Driver

You use the frame handle you specified when accessing the frame in all
setup functions and other functions related to the operation. This ensures
that you are defining the same operation.

When you are ready to perform the operation you have set up, you can
start the operation in the appropriate operation mode, referencing the
appropriate frame handle. Figure 3-2 illustrates the syntax of the
interrupt-mode operation function K_IntStart .

K_IntStart (

Start Channel
Stop Channel
Buffering Mode

Frame

.
.
.

frameHandle

)

Attributes of Operation

First analog input channel
Last analog input channel
Single cycle or continuous

.
.
.

Figure 3-2. Interrupt-Mode Operation

For DAS-TC and DAS-TC/B boards, synchronous-mode and
interrupt-mode analog input operations require frames, called A/D
(analog-to-digital) frames. Use the K_GetADFrame function to access
an available A/D frame.

If you want to perform a synchronous-mode or interrupt-mode analog
input operation and all A/D frames have been accessed, you can use the

K_FreeFrame function to free a frame that is no longer in use. You can

then redefine the elements of the frame for the next operation.

When you access a frame, the elements are set to their default values. You
can also use the K_ClearFrame function to reset all the elements of a
frame to their default values.

How the Driver Works 3-3