23.11.2014 Views

CompuScope SDK Manua.. - Egmont Instruments

CompuScope SDK Manua.. - Egmont Instruments

CompuScope SDK Manua.. - Egmont Instruments

SHOW MORE
SHOW LESS

Create successful ePaper yourself

Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.

Volume II:<br />

<strong>CompuScope</strong> Applications<br />

Programming Interface<br />

(API) Reference <strong>Manua</strong>l<br />

Supporting the<br />

<strong>CompuScope</strong> <strong>SDK</strong> for C/C++ for<br />

Windows<br />

for all Gage <strong>CompuScope</strong> models<br />

For <strong>SDK</strong> Version 3.50+<br />

P/N: 0045032<br />

Reorder #: MKT-SWM-<strong>SDK</strong>25<br />

0404


© Copyright Gage Applied Technologies, Inc. 2002<br />

Fourth Edition (May 2002)<br />

GAGE, GAGESCOPE, GAGEBIT, GAGEPCI, GAGEP500, COMPUSCOPE, COMPUSCOPE 85G, COMPUSCOPE 85GC, COMPUSCOPE<br />

82G, COMPUSCOPE 8500, COMPUSCOPE 12100, COMPUSCOPE 1250, COMPUSCOPE 14100, COMPUSCOPE 14100C, COMPUSCOPE<br />

1450, COMPUSCOPE 1602, COMPUSCOPE 1610, COMPUSCOPE 1610C, GSINST, PCIINST, P500INST, 85DETECT, MULTI-<br />

CARD, COMPUGEN, CGWIN, COMPUGEN 1100, and INSTRUMENT MANAGER, are registered trademarks of Gage Applied<br />

Technologies, Inc.<br />

MS-DOS, WINDOWS, WINDOWS 95, WINDOWS 98, WINDOWS NT, WINDOWS ME, AND WINDOWS XP are trademarks of<br />

Microsoft Incorporated. MATLAB is a trademark of TheMathWorks Inc. LABVIEW and LABWINDOWS/CVI are trademarks of<br />

National <strong>Instruments</strong> Corp. IBM, IBM PC, IBM PC/XT, IBM PC AT and PC-DOS are trademarks of International Business<br />

Machines Corporation.<br />

Changes are periodically made to the information herein; these changes will be incorporated into new editions of the<br />

publication. Gage Applied Technologies, Inc. may make improvements and/or changes in the products and/or programs<br />

described in this publication at any time.<br />

Copyright © 2002 Gage Applied Technologies, Inc. All Rights Reserved, including those to reproduce this publication or parts<br />

thereof in any form without permission in writing from Gage Applied Technologies, Inc.<br />

The installation program used to install the the <strong>CompuScope</strong> <strong>SDK</strong>s for Windows, InstallShield, is licensed software provided by<br />

InstallShield Software Corp., 900 National Parkway, Ste. 125, Schaumburg, IL. InstallShield is Copyright ©1998 by<br />

InstallShield Software Corp., which reserves all copyright protection worldwide. InstallShield is provided to you for the<br />

exclusive purpose of installing the <strong>CompuScope</strong> <strong>SDK</strong>s. In no event will InstallShield Software Corp. be able to provide any<br />

technical support for <strong>CompuScope</strong> <strong>SDK</strong>s.<br />

How to reach Gage Applied Technologies, Inc.<br />

Product Manager - <strong>CompuScope</strong> <strong>SDK</strong>s<br />

Gage Applied Technologies, Inc.<br />

How to reach Gage from outside North America<br />

Tel: (514) 633-7447<br />

Fax: (514) 633-0770<br />

Toll-free phone: (800) 567-4243<br />

Toll-free fax: (800) 780-8411<br />

Online technical support form:<br />

E-mail: prodinfo@gage-applied.com<br />

Website: http://www.gage-applied.com<br />

www.gage-applied.com/support.asp<br />

Please complete the following section and keep it handy when calling Gage Applied Technologies, Inc. for technical support:<br />

Owned by: ___________________________<br />

Serial Number: ___________________________<br />

Purchase Date: ___________________________<br />

Purchased From: ___________________________<br />

You must also have the following information when you call:<br />

. Software Driver and Application version<br />

. Software Development Kit type and version<br />

· Brand name and type of computer<br />

· Processor and bus speed<br />

· Total memory size<br />

· Information on all other hardware in the computer


Gage Applied Technologies, Inc. Software & Documentation License Agreement<br />

CAREFULLY READ THE FOLLOWING TERMS AND CONDITIONS BEFORE OPENING THE<br />

COMPUSCOPE <strong>SDK</strong> PACKAGE. OPENING THE COMPUSCOPE <strong>SDK</strong> PACKAGE INDICATES<br />

ACCEPTANCE OF THESE TERMS AND CONDITIONS. IF YOU DO NOT AGREE WITH THEM,<br />

PROMPTLY RETURN THE PACKAGE UNOPENED AND YOUR MONEY WILL BE REFUNDED.<br />

Title to the media on which the program is recorded and to documentation in support thereof is transferred to you,<br />

but title to the program is retained by Gage Applied Technologies, Inc. You assume responsibility for the selection<br />

of the program to achieve your intended results, and for the installation, use, and results obtained from the<br />

program.<br />

LICENSE<br />

Under the terms and conditions of this License Agreement you may:<br />

a) use the program on a single machine;<br />

b) copy the program into any machine-readable or printed form for backup or modification purposes in support of<br />

your use of the program on the single machine. Copying of documentation and other printed material is<br />

prohibited;<br />

c) modify the program and/or merge it into another program for your use on the single machine (any portion of<br />

this program merged into another program will continue to be subject to the terms and conditions of this<br />

Agreement); and<br />

d) transfer the program and license to another party if the other party agrees to accept the terms and conditions of<br />

this Agreement. If you transfer the program, you must at the same time either transfer all copies whether in<br />

printed or machine-readable form to the same party or destroy any copies not transferred; this includes all<br />

modifications and portions of the program contained or merged into other programs.<br />

You must reproduce and include the copyright notice on any copy, modification or portion merged into another<br />

program.<br />

You may not use, copy, modify, or transfer the program, or any copy, modification or merged portion, in whole or<br />

in part, except as expressly provided for in this License Agreement.<br />

If you transfer possession of any copy, modification or merged portion of the program to another party, your<br />

license is automatically terminated.<br />

TERMS<br />

The license is effective until terminated. You may terminate it at any time by destroying the program together with<br />

all copies, modifications and merged portions in any form. The license will also terminate upon conditions set<br />

forth elsewhere in this Agreement or if you fail to comply with any term or condition of this Agreement. You<br />

agree upon such termination to destroy the program together with all copies, modifications and merged portions in<br />

any form.<br />

LIMITED WARRANTY<br />

Gage Applied Technologies, Inc. warrants the media on which the program is furnished to be free from defects in<br />

materials and workmanship under normal use for a period of one year from the date of delivery to you as<br />

evidenced by a copy of your receipt.<br />

THE PROGRAM IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR<br />

IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY<br />

AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK TO THE QUALITY AND<br />

PERFORMANCE OF THE PROGRAMS LIES WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,<br />

YOU (AND NOT GAGE APPLIED TECHNOLOGIES, INC.) ASSUME THE ENTIRE COST OF ALL<br />

NECESSARY SERVICING, REPAIR OR CORRECTION.<br />

SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE<br />

ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY GIVES YOU SPECIFIC LEGAL<br />

RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS WHICH VARY FROM ONE JURISDICTION TO<br />

ANOTHER.<br />

Continued on next page


Continued from previous page<br />

Gage Applied Technologies, Inc. does not warrant that the functions contained in the program will meet your<br />

requirements or that the operation of the program will be uninterrupted or error free. However, Gage Applied<br />

Technologies, Inc. warrants the media on which the program is furnished to be free from defects in materials and<br />

workmanship under normal use for a period of one year from the date of delivery to you as evidenced by a copy of<br />

your receipt.<br />

LIMITATIONS OF REMEDIES<br />

Gage Applied Technologies, Inc.’s entire liability and your exclusive remedy shall be:<br />

a) with respect to defective media during the warranty period, Gage Applied Technologies, Inc. will replace<br />

media not meeting Gage Applied Technologies, Inc.’s “Limited Warranty” if returned to Gage Applied<br />

Technologies, Inc. or its authorized representative with a copy of your receipt, or<br />

b) if Gage Applied Technologies, Inc. or its representative is unable to deliver replacement media free of defects<br />

in materials and workmanship, you may terminate the Agreement by returning the program and your money<br />

will be refunded.<br />

IN NO EVENT WILL GAGE APPLIED TECHNOLOGIES, INC. BE LIABLE FOR ANY DAMAGES,<br />

INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL<br />

DAMAGES ARISING OUT OF THE USE OF OR INABILITY TO USE SUCH PROGRAM, EVEN IF GAGE<br />

APPLIED TECHNOLOGIES, INC. OR ITS AUTHORIZED REPRESENTATIVE HAS BEEN ADVISED OF<br />

THE POSSIBILITY OF SUCH DAMAGES, OR ANY CLAIM BY ANY OTHER PARTY.<br />

SOME JURISDICTIONS DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY FOR<br />

INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATION OR EXCLUSION MAY<br />

NOT APPLY TO YOU.<br />

GENERAL<br />

You may not sublicense, assign or transfer the license or the program except as expressly provided in this<br />

Agreement. Any attempt otherwise to sublicense, assign or transfer any of the rights, duties or obligations<br />

hereunder is void.<br />

This Agreement is governed by the laws of the Province of Quebec, Canada.<br />

The parties agree that this Agreement be written in English. Les partis consentent à ce que cette entente soit<br />

rédigée en anglais.<br />

Should you have any questions concerning this Agreement, you may contact Gage Applied Technologies, Inc. in<br />

writing. Please check the Gage website (http://www.gage-applied.com/aboutgag/contact.htm) for the most current<br />

address.<br />

YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT, UNDERSTAND IT AND AGREE<br />

TO BE BOUND BY ITS TERMS AND CONDITIONS. YOU FURTHER AGREE THAT IT IS THE<br />

COMPLETE AND EXCLUSIVE STATEMENT OF THE AGREEMENT BETWEEN US WHICH<br />

SUPERSEDES ANY PROPOSAL OR PRIOR AGREEMENT, ORAL OR WRITTEN, AND ANY OTHER<br />

COMMUNICATIONS BETWEEN US RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.


Global Table of Contents<br />

Volume I <strong>CompuScope</strong> C/C++ Software Development Kit<br />

<strong>Manua</strong>l<br />

Chapter 1<br />

Chapter 2<br />

Chapter 3<br />

Chapter 4<br />

Chapter 5<br />

Appendices<br />

<strong>CompuScope</strong> <strong>SDK</strong> for C/C++ for Windows Preface<br />

Basic <strong>CompuScope</strong> Operation<br />

Introduction to <strong>CompuScope</strong> Windows Drivers and<br />

C/C++ <strong>SDK</strong><br />

Writing a C Application for <strong>CompuScope</strong> Cards<br />

Sample Programs<br />

Data Structures Used by <strong>CompuScope</strong> drivers<br />

<strong>CompuScope</strong> Power Management<br />

Compiling CompuSCope <strong>SDK</strong> C/C++ Sample<br />

Programs under LabWindows CVI<br />

CompuGen Cards<br />

Volume II <strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

<strong>CompuScope</strong> API Routines<br />

Appendices Comparison of Various Data Transfer Routines<br />

Frequently Asked Questions<br />

Multiple/Independent Mode Operation<br />

Multiple Record Mode Operation


Table of Contents - <strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

III COMPUSCOPE API ROUTINES 4<br />

Recommended <strong>CompuScope</strong> API Subroutines 5<br />

Recommended Routines - Quick Summary 6<br />

Driver, System and Board Location Routines 7<br />

Parameter Control Routines 7<br />

Address Routines 7<br />

Data Transfer Routines 8<br />

Multiple/Independent Mode Routines 8<br />

Multiple Record Mode Routines 9<br />

Miscellaneous Routines 9<br />

Recommended API Routines that Support <strong>CompuScope</strong> 85G and 85GC 10<br />

Recommended <strong>CompuScope</strong> API Subroutines - Detailed Description 11<br />

gage_abort 12<br />

gage_abort_capture 13<br />

gage_board_abort_capture 14<br />

gage_board_force_capture 15<br />

gage_board_start_capture 16<br />

gage_board_type_size_to_text 17<br />

gage_busy 18<br />

gage_calculate_addresses 19<br />

gage_calculate_mra_addresses 20<br />

gage_calculate_mr_addresses 22<br />

gage_capture_mode 24<br />

gage_delay_trigger_32 26<br />

gage_driver_initialize 28<br />

gage_driver_remove 31<br />

gage_force_capture 32<br />

gage_get_config_filename 33<br />

gage_get_driver_info 34<br />

gage_get_driver_info_structure 35<br />

gage_get_error_code 36<br />

gage_get_independant_operation 37<br />

gage_input_control 38<br />

gage_mem_read_master 39<br />

gage_multiple_record 40<br />

gage_multiple_record_acquisitions_32 41<br />

gage_need_ram 42


gage_normalize_address 43<br />

gage_power_control 44<br />

gage_read_config_file 45<br />

gage_select_board 47<br />

gage_set_ext_clock_variables 48<br />

gage_set_independant_operation 49<br />

gage_software_trigger 50<br />

gage_start_capture 51<br />

gage_transfer_buffer 52<br />

gage_transfer_buffer_3 53<br />

gage_trigger_control_2 55<br />

gage_triggered 58<br />

Legacy <strong>CompuScope</strong> API Subroutines - Detailed Description 59<br />

gage_acquire_average 60<br />

gage_detect_multiple_record 63<br />

gage_get_boards_found 64<br />

gage_get_data 65<br />

gage_get_records 66<br />

gage_get_status 67<br />

gage_get_trigger_address 68<br />

gage_get_trigger_view_offset 69<br />

gage_gpib_command 70<br />

gage_init_clock 71<br />

gage_mem_read_chan_a 72<br />

gage_mem_read_chan_b 73<br />

gage_mem_read_dual 74<br />

gage_mem_read_single 75<br />

gage_multiple_record_acquisitions 76<br />

gage_offset_adjust 77<br />

gage_read_cal_table 78<br />

gage_read_master_status 79<br />

gage_set_delay_trigger 80<br />

gage_set_records 81<br />

gage_set_trigger_depth 82<br />

gage_set_trigger_view_offset 83<br />

gage_support_to_text 84<br />

gage_transfer_buffer_2 85<br />

gage_trigger_address 86<br />

gage_trigger_control 87<br />

gage_trigger_view_transfer 89<br />

gage_trigger_view_transfer_2 90<br />

gage_trigger_view_transfer_3 91<br />

gage_use_cal_table 92<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 2


IV APPENDICES 93<br />

Appendix A Comparison of Various Data Transfer Routines 94<br />

Buffered Access Routines 94<br />

Single Sample Access Routines 96<br />

Appendix B Frequently Asked Questions 97<br />

Appendix C Multiple/Independent Mode Operation 100<br />

Appendix D Multiple Record Mode Operation 102<br />

Hardware Perspective 102<br />

Turning ON Multiple Record 105<br />

Downloading Multiple Record Data 105<br />

Embedded Enhanced Trigger Bits 106<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

3


III<br />

<strong>CompuScope</strong> API<br />

Routines<br />

This section deals with the Applications Programming Interface (API) C sub-routines that are supported by<br />

the <strong>CompuScope</strong> drivers. These routines are used to control all <strong>CompuScope</strong> hardware functionality and<br />

are all that a programmer needs to use to get <strong>CompuScope</strong> hardware up and running. Sample programs<br />

that illustrate how to use the API subroutines are provided with the <strong>CompuScope</strong> C/C++ <strong>SDK</strong>. These<br />

programs are described in Volume I.<br />

The <strong>CompuScope</strong> C/C++ <strong>SDK</strong> is intended for use with a Windows C compiler. While other environments<br />

are not officially supported, an intermediate programmer should be able to use the Gage API subroutines<br />

from other environments. For instance, while Visual Basic is not officially supported, Visual Basic sample<br />

programs are available from Gage upon request. Furthermore, Visual Basic prototypes are listed for all<br />

API subroutines in the manual. In addition, C sample programs can be compiled from LabWindows CVI<br />

by following the guidelines laid out in Volume I of this manual. In fact, the API routines can be called<br />

from any environment that allows functions within a Dynamically Linked Library (DLL) to be called. The<br />

user need only make function calls to the gage_drv.dll, the main Gage <strong>CompuScope</strong> driver DLL, using the<br />

C sample programs as a guide to subroutine call sequencing.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 4


Recommended<br />

<strong>CompuScope</strong> API<br />

Subroutines<br />

The Recommended <strong>CompuScope</strong> API Subroutines are the most frequently used routines for application<br />

programs operating <strong>CompuScope</strong> hardware. These routines allow all frequently used hardware<br />

functionality to be optimally exploited. The Recommended routines are used by Gage <strong>SDK</strong>s and standalone<br />

software and so are regularly and thoroughly tested.<br />

The functionality of the Recommended Subroutines are virtually never changed and any changes will be<br />

documented appropriately in future releases of the drivers. New Recommended Subroutines, however,<br />

may be added from time to time in order to exploit new features on <strong>CompuScope</strong> hardware. Please read<br />

the readme text files installed with the <strong>CompuScope</strong> drivers and C/C++ <strong>SDK</strong>s for information relating to<br />

changes in the API routines.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

5


Recommended Routines<br />

- Quick Summary<br />

The recommended <strong>CompuScope</strong> API Routines are divided in the following categories:<br />

• Driver, System and Board Location Routines<br />

• Parameter Control Routines<br />

• Addresses Routines<br />

• Data Transfer Routines<br />

• Multiple/Independent Mode Operation Routines<br />

• Multiple Record Mode Operation Routines<br />

• Miscellaneous Routines<br />

The following tables give the name and brief description of the recommended <strong>CompuScope</strong> API routines:<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 6


Driver, System and Board Location Routines<br />

Name of the Routine<br />

gage_driver_initialize<br />

gage_driver_remove<br />

gage_get_config_filename<br />

gage_get_driver_info<br />

gage_get_driver_info_structure<br />

gage_read_config_file<br />

gage_select_board<br />

Description<br />

Fully configures each board found in the system.<br />

Removes all the data structures from the memory that were<br />

created by the drivers or the DLL.<br />

Determines the complete path to the configuration file that<br />

contains the board location data.<br />

Fills a structure or record with the relevant information<br />

from the driver variables as to the current settings for the<br />

current <strong>CompuScope</strong> board.<br />

Returns the relevant information about the main structure<br />

used by the driver and also retrieves the driver version and<br />

number.<br />

Reads the configuration file and stores the data in an array<br />

of words.<br />

Sets the driver so that the current board is the board<br />

identified by the number passed to the routine.<br />

Parameter Control Routines<br />

Name of the Routine<br />

gage_capture_mode<br />

gage_input_control<br />

gage_delay_trigger_32<br />

gage_set_ext_clock_variables<br />

gage_trigger_control_2<br />

Sets the data capture mode.<br />

Description<br />

Used to set up the input channels of the <strong>CompuScope</strong><br />

boards.<br />

Ignores the trigger for a specified amount of time<br />

Sets the needed variables when using an external clock.<br />

Takes advantage of certain <strong>CompuScope</strong> boards’ ability to<br />

have 2 different trigger inputs (source, slope and level) and<br />

is used to set up the trigger parameters of the <strong>CompuScope</strong><br />

boards.<br />

Address Routines<br />

Name of the Routine<br />

gage_calculate_addresses<br />

gage_calculate_mra_addresses<br />

gage_calculate_mr_addresses<br />

Description<br />

Returns the start, trigger and end addresses.<br />

Corrects the trigger address based on the ETB bit<br />

information located in the data acquired from the card at the<br />

raw calculated trigger address.<br />

Returns the start, trigger and end addresses for the specified<br />

channel of the current board to the calling routine.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

7


Data Transfer Routines<br />

Name of the Routine<br />

gage_mem_read_master<br />

gage_transfer_buffer<br />

gage_transfer_buffer_3<br />

Description<br />

Reads one sample out of <strong>CompuScope</strong> board’s memory for<br />

channel A of the master <strong>CompuScope</strong> board.<br />

Copies the number of sample points of the <strong>CompuScope</strong><br />

board’s memory space from the specified channel to the<br />

supplied buffer.<br />

Similar to the gage_transfer_buffer_2. Returns an offset<br />

to the beginning of the dword aligned buffer used by the<br />

driver.<br />

Multiple/Independent Mode Routines<br />

Name of the Routine<br />

gage_abort_capture<br />

gage_board_abort_capture<br />

gage_board_force_capure<br />

gage_board_start_capture<br />

gage_force_capture<br />

gage_get_independant_operation<br />

gage_set_independant_operation<br />

gage_start_capture<br />

Description<br />

Used to regain control of the <strong>CompuScope</strong> board(s). This<br />

routine is reconfigured when in Multiple/Independent mode<br />

to work with independent boards. This reconfiguration is<br />

done automatically when the<br />

gage_set_independant_operation routine is called.<br />

Used to regain the control of the selected <strong>CompuScope</strong><br />

board when in Multiple/Independent mode.<br />

Used to force the capture of data by the selected<br />

<strong>CompuScope</strong> board when in Multiple/Independent mode.<br />

Used to force the capture of data by the selected<br />

<strong>CompuScope</strong> board when in Multiple/Independent mode.<br />

Forces the capture of data by the <strong>CompuScope</strong> board(s).<br />

This routine is reconfigured when in Multiple/Independent<br />

mode to work with independent boards. This<br />

reconfiguration is done automatically when the<br />

gage_set_independent_operation routine is called.<br />

Used to check if the boards are in Multiple/Independent<br />

mode or not.<br />

Sets the driver to initialize the Multiple/Independent mode.<br />

Prepares the <strong>CompuScope</strong> hardware for data acquisition.<br />

This routine is reconfigured when in Multiple/Independent<br />

mode to work with independent boards. This<br />

reconfiguration is done automatically when the<br />

gage_set_independent_operation routine is called.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 8


Multiple Record Mode Routines<br />

Name of the Routine<br />

gage_calculate_mra_addresses<br />

gage_calculate_mr_addresses<br />

gage_multiple_record<br />

gage_multiple_record_acquisitions_32<br />

Description<br />

Corrects the trigger address based on the ETB bit<br />

information located in the data acquired from the card at the<br />

raw calculated trigger address.<br />

Returns the starting, trigger and ending addresses for the<br />

specified channel of the current board to the calling routine.<br />

Allows the application program to force the <strong>CompuScope</strong><br />

hardware to capture only the depth specified when the<br />

trigger event occurs. The card then re-arms automatically<br />

itself to accept another trigger event and record that data<br />

immediately following the first capture.<br />

Sets the number of Multiple Record groups that will be<br />

taken by the <strong>CompuScope</strong> hardware.<br />

Miscellaneous Routines<br />

Name of the Routine<br />

gage_abort<br />

gage_abort_capture<br />

gage_board_type_size_to_text<br />

gage_busy<br />

gage_force_capture<br />

gage_get_error_code<br />

gage_need_ram<br />

gage_normalize_address<br />

gage_power_control<br />

gage_software_trigger<br />

gage_start_capture<br />

gage_triggered<br />

Description<br />

Used to regain control of the <strong>CompuScope</strong> board(s).<br />

Used to regain control of the <strong>CompuScope</strong> board(s).<br />

Returns the pointer to the string that contains the<br />

information about the installed <strong>CompuScope</strong> board.<br />

Determines if <strong>CompuScope</strong> board is busy capturing the data<br />

or not.<br />

Forces the capture of data by the <strong>CompuScope</strong> board(s).<br />

Returns the error code associated with the last call to the<br />

<strong>CompuScope</strong> driver.<br />

Allows the application program to access the <strong>CompuScope</strong><br />

hardware’s RAM buffers.<br />

Calculates the logical address for the <strong>CompuScope</strong><br />

hardware.<br />

Used to control the automatic power management available<br />

on the <strong>CompuScope</strong>s equipped with this feature.<br />

Will trigger the hardware when the trigger source has been<br />

set to GAGE_SOFTWARE.<br />

Prepares the <strong>CompuScope</strong> hardware for data acquisition.<br />

Determines if the <strong>CompuScope</strong> hardware has encountered a<br />

trigger event or not.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

9


Recommended API<br />

Routines that Support<br />

<strong>CompuScope</strong> 85G and<br />

85GC<br />

Gage API subroutines were created for <strong>CompuScope</strong>s that have traditional <strong>CompuScope</strong> architecture. The<br />

<strong>CompuScope</strong> 85G and 85GC has drastically different internal architecture since it was created from<br />

Tektronix chipsets with their own software protocols. Consequently, support for the CS85G and CS85GC<br />

was added by “wrapping” existing 85G chipset protocols with existing Gage API subroutine calls. Only a<br />

subset of the Recommended API subroutines is supported for the CS85G and CS85GC. None of the<br />

Legacy subroutines are supported for the CS85G and CS85GC. Please note that the CS85G and CS85GC<br />

do not support PCI bus-mastering data transfer. Consequently, the PCI bus-mastering data transfer<br />

routines, do not actually do bus-mastering for these <strong>CompuScope</strong> models. Below is a list of the<br />

recommended subroutines that are supported for the CS85G and CS85GC.<br />

gage_abort_capture<br />

gage_busy<br />

gage_calculate_addresses<br />

gage_capture_mode<br />

gage_delay_trigger_32<br />

gage_driver_initialize<br />

gage_driver_remove<br />

gage_force_capture<br />

gage_get_driver_info<br />

gage_input_control<br />

gage_start_capture<br />

gage_transfer_buffer<br />

gage_transfer_buffer_3<br />

gage_triggered<br />

gage_trigger_control_2<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 10


Recommended<br />

<strong>CompuScope</strong> API<br />

Subroutines - Detailed<br />

Description<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

11


gage_abort<br />

Syntax<br />

C:<br />

void GAGEAPI gage_abort (void);<br />

Visual BASIC:<br />

sub gage_abort ()<br />

Remarks<br />

gage_abort is used to regain control of a <strong>CompuScope</strong> board, primarily in the event that the <strong>CompuScope</strong><br />

does not finish capturing in the expected time period. This is rare and may indicate hardware problems,<br />

such as an external clock signal that unexpectedly went inactive. gage_abort forces the board to stop<br />

capturing data and enter a not busy state. After a gage_abort, valid data in on-board memory may still be<br />

available for download. Some users have intentionally issued the gage_abort command when they know<br />

that the signal of interest has already been captured. In order to do another capture, the <strong>CompuScope</strong><br />

hardware must be rearmed using, say, the gage_start_capture command.<br />

Note that gage_abort routine will only abort the current board, which has to be selected by calling the<br />

gage_select_board routine.<br />

Return Value<br />

None.<br />

See Also<br />

gage_busy, gage_abort_capture and gage_select_board.<br />

Examples<br />

C:<br />

gage_abort ();<br />

Visual BASIC:<br />

Call gage_abort ()<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 12


gage_abort_capture<br />

Syntax<br />

C:<br />

void GAGEAPI gage_abort_capture (int16 reset_trigger_source);<br />

Visual BASIC:<br />

sub gage_abort_capture (ByVal reset_trigger_source As Integer)<br />

Remarks<br />

gage_abort is used to regain control of a <strong>CompuScope</strong> board, primarily in the event that the <strong>CompuScope</strong><br />

does not finish capturing in the expected time period. gage_abort_capture forces the board to stop<br />

capturing data and enter a not busy state. The gage_abort_capture routine is similar to gage_abort,<br />

except that it wipes out the contents of <strong>CompuScope</strong> on-board memory. In order to do another capture, the<br />

<strong>CompuScope</strong> hardware must be rearmed using, say, the gage_start_capture command.<br />

gage_abort_capture also works for multiple <strong>CompuScope</strong> board configurations. If data recovery is not<br />

important in aborting capture using a multiple board <strong>CompuScope</strong> system, gage_abort_capture should<br />

usually be used.<br />

The reset_trigger_source parameter is used to re-initialize the trigger source after the hardware has been<br />

aborted. This is normally set to the initial trigger source used, which is one of the constants<br />

(GAGE_CHAN_A, GAGE_CHAN_B, GAGE_EXTERNAL or GAGE_SOFTWARE) defined in the file<br />

GAGE_DRV.H.<br />

Return Value<br />

None.<br />

See also<br />

gage_busy and gage_forced_trigger_capture.<br />

Examples<br />

C:<br />

gage_abort_capture (GAGE_CHAN_A);<br />

Visual BASIC:<br />

Call gage_abort_capture (GAGE_CHAN_A)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

13


gage_board_abort_capture<br />

Syntax<br />

C:<br />

void GAGEAPI gage_board_abort_capture (int16 mi_board);<br />

Visual BASIC:<br />

Sub gage_board_abort_capture (ByVal mi_board As Integer)<br />

Remarks<br />

gage_board_abort_capture has identical functionality to the gage_ abort_capture routine, but is used to<br />

control <strong>CompuScope</strong>s operating in Multiple Independent mode.<br />

mi_board is used to specify the <strong>CompuScope</strong> to which the command will be applied.<br />

Return Value<br />

None<br />

See also<br />

gage_abort_capture, gage_select_board, gage_set_independant_operation, gage_board_force_capture,<br />

gage_board_start_capture and Appendix: Multiple/Independent Mode Operation.<br />

Examples<br />

C:<br />

gage_board_abort_capture (mi_board);<br />

Visual BASIC:<br />

Call gage_board_abort_capture (mi_board)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 14


gage_board_force_capture<br />

Syntax<br />

C:<br />

void GAGEAPI gage_board_force_capture (int16 mi_board);<br />

Visual BASIC:<br />

Sub gage_board_force_capture (ByVal mi_board As Integer)<br />

Remarks<br />

gage_board_force_capture has identical functionality to the gage_force_capture routine, but is used to<br />

control <strong>CompuScope</strong>s operating in Multiple Independent mode.<br />

mi_board is used to specify the <strong>CompuScope</strong> to which the command will be applied.<br />

Return Value<br />

None<br />

See also<br />

gage_force_capture, gage_select_board, gage_set_independant_operation, gage_board_force_capture,<br />

gage_board_start_capture and Appendix: Multiple/Independent Mode Operation..<br />

Examples<br />

C:<br />

gage_board_force_capture (mi_board);<br />

Visual BASIC:<br />

Call gage_board_force_capture (mi_board)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

15


gage_board_start_capture<br />

Syntax<br />

C:<br />

void GAGEAPI gage_board_start_capture (int16 mi_board, int16 auto_trigger);<br />

Visual BASIC:<br />

Sub gage_board_start_capture (ByVal mi_board As Integer, ByVal auto_trigger As Integer)<br />

Remarks<br />

gage_board_start_capture has identical functionality to the gage_start_capture routine, but is used to<br />

control <strong>CompuScope</strong>s operating in Multiple Independent mode.<br />

mi_board is used to specify the <strong>CompuScope</strong> to which the command will be applied.<br />

Return Value<br />

None<br />

See also<br />

gage_start_capture, gage_select_board, gage_set_independant_operation, gage_board_force_capture,<br />

gage_board_start_capture and Appendix: Multiple/Independent Mode Operation..<br />

Examples<br />

C:<br />

gage_board_start_capture (mi_board, board.source == GAGE_SOFTWARE);<br />

Visual BASIC:<br />

Call gage_board_start_capture (mi_board, auto_trigger)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 16


gage_board_type_size_to_text<br />

Syntax<br />

C:<br />

LPSTR GAGEAPI gage_board_type_size_to_text (LPSTR string, uInt32 string_size, uInt32 action,<br />

uInt32 board, uInt32 far *bt, uInt32 far *eeopt,<br />

uInt32 far *ver, uInt32 far *max_mem);<br />

Remarks<br />

The gage_board_type_size_to_text routine is used to convert the board type parameter, returned by the<br />

drivers, into a text string that indicates the corresponding <strong>CompuScope</strong> model and/or memory size.<br />

The parameter string is a pointer to the string into which the <strong>CompuScope</strong> name will be returned by the<br />

routine. string_size is the size of the string pointed to by string.<br />

action can be one of the following constants defined in GAGE_DRV.H file:-<br />

GAGE_GBTSTT_BOARD<br />

GAGE_GBTSTT_MEMORY<br />

GAGE_GBTSTT_BOTH<br />

GAGE_GBTSTT_LONG_NAME<br />

GAGE_GBTSTT_ALL_UPPER_CASE<br />

0x01<br />

0x02<br />

0x03<br />

0x04<br />

0x08<br />

These constants determine in which format the string is returned. The constants can be ‘ORed’ together in<br />

order to request, say, <strong>CompuScope</strong>’s LONG_NAME in ALL_UPPER_CASE..<br />

board is the <strong>CompuScope</strong> board number from which information is to be requested (referred to as the<br />

“currently selected <strong>CompuScope</strong>”). If this parameter is 0 then the installed hardware is ignored and the<br />

returned string contents are determined by the following four parameters.<br />

*bt returns the type of the currently selected <strong>CompuScope</strong>. This will be a combination of predefined<br />

constants GAGE_ASSUME_XXXXX, where XXXXX is a board type. Board type constants are defined in<br />

GAGE_DRV.H file.<br />

*eeopt returns the available eeprom options for the currently selected <strong>CompuScope</strong>. The options are<br />

represented by one or more constants “ORed” together. The available constants are defined in EEPROM.H<br />

*ver returns the hardware version of the currently selected <strong>CompuScope</strong>.<br />

*max_mem returns the size of the memory on the currently selected <strong>CompuScope</strong>.<br />

If *bt, *eeopt, *ver and *max_mem values are NULL, the routine will fill them.<br />

Return Value<br />

Returns the pointer to the string with above-mentioned parameters.<br />

See Also: gage_support_to_text<br />

Examples C: gage_board_type_size_to_text (str, sizeof(str), 1L, 1,NULL, NULL, NULL, NULL);<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

17


gage_busy<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_busy (void);<br />

Visual BASIC:<br />

function gage_busy () As Integer<br />

Remarks<br />

gage_busy determines if the <strong>CompuScope</strong> board is busy capturing data. The on-board memory of the<br />

<strong>CompuScope</strong> board cannot be accessed while the board is capturing the data. Generally, therefore,<br />

gage_busy is repeatedly called until it returns a 0 before download of data from on-board <strong>CompuScope</strong><br />

memory is attempted.<br />

Return Value<br />

A non-zero or true value is returned if the board is busy (capturing data); otherwise a 0 value is returned.<br />

See also<br />

gage_triggered<br />

Examples<br />

C:<br />

is_busy = gage_busy ();<br />

Visual BASIC:<br />

is_busy = gage_busy<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 18


gage_calculate_addresses<br />

Syntax<br />

C:<br />

void GAGEAPI gage_calculate_addresses (int16 chan, int16 op_mode, float tbs, int32 far *trig,<br />

int32 far *start, int32 far *end);<br />

Visual BASIC:<br />

Sub gage_calculate_addresses (ByVal chan As Integer, ByVal op_mode As Integer, ByVal tbs As Single,<br />

trig As Long, start As Long, ending As Long)<br />

Remarks<br />

gage_calculate_addresses gives back the on-board <strong>CompuScope</strong> memory addresses that are used to<br />

retrieve the captured samples from the <strong>CompuScope</strong> on-board memory. This routine returns three<br />

important addresses - the trigger address, the start address, and the end address - for the specified channel<br />

of the current <strong>CompuScope</strong> to the calling routine. The programmer must make sure that the current<br />

<strong>CompuScope</strong> board is selected by calling gage_select_board prior to calling gage_calculate_address<br />

routine. In this manner, the addresses for the current <strong>CompuScope</strong> card are retrieved.<br />

The chan parameter controls which channel's addresses on the current board are calculated and returned.<br />

This parameter should be set to GAGE_CHAN_A. Addresses for both channel A and channel B on a dualchannel-only<br />

board will always be the same.<br />

op_mode is either GAGE_SINGLE_CHAN or GAGE_DUAL_CHAN constant for analog input<br />

<strong>CompuScope</strong>s. Digital input <strong>CompuScope</strong>s also support GAGE_QUAD_CHAN constant. Use the value<br />

that controlled the most recent data capture.<br />

tbs is the "Time Between Samples" in nanoseconds for the captured signal. For example, if you have<br />

sampled the signal at 10 MS/s then this value would be 100.0. Similarly, a signal sampled at 1 KS/s would<br />

require this value to be set to 1000000.0.<br />

*trig is the address where the trigger event occurred.<br />

*start will be the first valid address of the most recent data capture. The address holds the first pre-trigger<br />

data point.<br />

*end will be the last valid address of the most recent data capture. The address holds the last post-trigger<br />

data point.<br />

For a Master/Slave <strong>CompuScope</strong> system, the trigger, start and end addresses should be calculated using<br />

gage_calculate_addresses first for all <strong>CompuScope</strong>s in the system before a data transfer routine is called.<br />

Return Value<br />

None.<br />

See also: gage_normalize_address<br />

Examples<br />

C:<br />

gage_calculate_addresses (GAGE_CHAN_A, gdi.mode, tbs, &trig_addr, &start_addr, &end_addr);<br />

Visual BASIC:<br />

Call gage_calculate_addresses (GAGE_CHAN_A, board.opmode, srtable(board.srindex).calc,<br />

trigger_address, starting_address, ending_address)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

19


gage_calculate_mra_addresses<br />

Syntax<br />

C:<br />

int32 GAGEAPI gage_calculate_mra_addresses (int16 board_type, uInt16 version, int16 chan,<br />

int16 op_mode, float tbs, int32 far *trig, int32 far *start,<br />

int32 far *end, int16 data);<br />

Visual BASIC:<br />

Function gage_calculate_mra_addresses (ByVal board_type As Integer, ByVal version As Integer,<br />

ByVal chan As Integer, ByVal op_mode As Integer,<br />

ByVal tbs As Single, trig As Long, start As Long,<br />

ending As Long, ByVal ad_data As Integer) As Long<br />

Remarks<br />

This routine corrects the trigger addresses when reading the data from a <strong>CompuScope</strong> Multiple Record<br />

capture. Due to the architecture of the hardware, the lowest few significant bits (depending on the<br />

<strong>CompuScope</strong> model) of the trigger address are not maintained. These bits are called Enhanced Trigger<br />

Bits (ETBs). With the appropriate <strong>CompuScope</strong> hardware modification, these bits are embedded within an<br />

early data point (typically the first) of each Multiple Record group. The gage_calculate_mra_addresses<br />

routine is used to adjust the trigger address according to the Embedded ETBs.<br />

Embedded ETBs is a standard feature on most PCI and cPCI <strong>CompuScope</strong>s. In order to determine if your<br />

<strong>CompuScope</strong> manual supports embedded ETBs, run a board information query using the <strong>CompuScope</strong><br />

configuration utility as described in the Driver Installation Guide for <strong>CompuScope</strong> Cards. The feature will<br />

show up as MULTIPLE_RECORD_ADJUST.<br />

The gage_calculate_mra_addresses routine must be called after the raw Multiple Record trigger address<br />

has been determined by calling the gage_calculate_mr_addresses routine. For a <strong>CompuScope</strong> with<br />

embedded ETBs, the trigger address returned by gage_calculate_mr_addresses actually contains the<br />

address of the data point containing the embedded ETBs. The user then downloads the data point at this<br />

location and passes it to gage_calculate_mra_addresses as the data parameter.<br />

gage_calculate_mra_addresses then returns the true adjusted start, trigger and end addresses.<br />

board_type is the type of the <strong>CompuScope</strong> hardware being used. The <strong>CompuScope</strong> board type can be<br />

determined by calling gage_get_driver_info routine and passing the board_type field to this routine.<br />

version is the hardware version of the current <strong>CompuScope</strong>. The <strong>CompuScope</strong> board version can be<br />

determined by calling gage_get_driver_info routine and passing the board_version field to<br />

gage_calculate_mra_addresses routine.<br />

chan is set to 0 for getting addresses for channel A on current <strong>CompuScope</strong>, and is set to 1 for getting<br />

addresses for channel B on current <strong>CompuScope</strong>.<br />

op_mode is the mode that was set when calling gage_capture_mode routine. Use the value that<br />

controlled the most recent data capture, either GAGE_SINGLE_CHAN or GAGE_DUAL_CHAN.<br />

GAGE_QUAD_CHAN can also be used for digital input <strong>CompuScope</strong>s such as CS3200.<br />

tbs is the "Time Between Samples" in nanoseconds for the captured signal. For example, if you have<br />

sampled the signal at 10 MS/s then this value would be 100.0. Similarly, a signal sampled at 1 kS/s would<br />

require this value to be set to 1000000.0.<br />

*trig is the adjusted trigger address.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 20


*start is the adjusted start address.<br />

*end is the adjusted end address.<br />

data is the data located at the raw trigger address. The raw trigger address was returned by an earlier call<br />

to gage_calculate_mr_addresses. The data parameter was then obtained by downloading the<br />

<strong>CompuScope</strong> data point at the raw trigger address. Gage recommends that this be done using the<br />

gage_mem_read_master routine, which correctly handles Master/Slave <strong>CompuScope</strong> systems.<br />

Return Value<br />

The return value is equal to the Enhanced Trigger Bits (ETBs) located in the data sample passed to this<br />

routine.<br />

See also<br />

gage_multiple_record, gage_calculate_mr_addresses and the Appendix entitled Multiple Record Mode<br />

Operation.<br />

Examples<br />

C:<br />

/* Get the raw addresses. */<br />

gage_calculate_addresses (GAGE_CHAN_A, gdi.mode, tbs, &trig_addr, &start_addr, &end_addr);<br />

/* Read the data at the raw trigger address to retrieve the enhanced trigger bits. */<br />

data = gage_mem_read_single (trig_addr);<br />

/* trig, start and end now hold the adjusted addresses. */<br />

gage_calculate_mra_addresses ( gage_driver_info.board_type, gage_driver_info.version, 0,<br />

GAGE_SINGLE_CHAN, srtable[board.srindex].sr_calc, &trig, &start,<br />

&end, data);<br />

Visual BASIC:<br />

‘ Get the raw addresses.<br />

Call gage_calculate_addresses(GAGE_CHAN_A, board.opmode, srtable(board.srindex).calc,<br />

trigger_address, starting_address, ending_address)<br />

‘ Read the data at the raw trigger address to retrieve the enhanced trigger bits.<br />

data = gage_mem_read_single (trigger_address)<br />

‘ trig, start and end now hold the adjusted addresses.<br />

gage_calculate_mra_addresses(gage_driver_info.board_type, gage_driver_info.version, 0,<br />

GAGE_SINGLE_CHAN, srtable(board.srindex).sr_calc, trigaddr,<br />

startaddr, endaddr,data)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

21


gage_calculate_mr_addresses<br />

Syntax<br />

C:<br />

int32 GAGEAPI gage_calculate_mr_addresses (int32 group, int16 board_type, int32 depth, int32<br />

memory, int16 chan, int16 op_mode, float tbs, int32 far<br />

*trig, int32 far *start, int32 far *end);<br />

Visual BASIC:<br />

Function gage_calculate_mr_addresses (ByVal group As Long, ByVal board_type As Integer,<br />

ByVal depth As Long, ByVal memory As Long,<br />

ByVal chan As Integer, ByVal op_mode As Integer,<br />

ByVal float As Single, trig As Long, startaddr As Long,<br />

endaddr As Long) As Long<br />

Remarks<br />

gage_calculate_mr_addresses gives back three important addresses - the trigger address, the start address,<br />

and the end address - for the specified channel of the current CopuScope to the calling routine. The<br />

<strong>CompuScope</strong> board must have been set to Multiple Record mode with a call to gage_multiple_record<br />

routine before the data acquisition. After a Multiple Record acquisition, <strong>CompuScope</strong> on-board memory<br />

will contain several sequentially stacked captured records, each referred to as a “group”, each of which<br />

consist only of post-trigger data. Remember to set the current board, using gage_select_board, prior to<br />

calling gage_calculate_mr_addresses so that the addresses for the proper <strong>CompuScope</strong> card are retrieved.<br />

The group parameter is the requested group number for which the addressed will be returned. If the group<br />

parameter is 1, addresses for the first Multiple Record group are returned. Similarly, -1 returns addresses<br />

for the last group and n returns addresses for the nth group. A 0 will return the addresses for the entire<br />

acquisition without regard for the group numbering, treating all the groups as one big acquisition. If the<br />

group parameter is out of range then the last Multiple Record group is returned.<br />

board_type is the type of the <strong>CompuScope</strong> hardware being used. This can be determined by calling<br />

gage_get_driver_info and passing the board_type field to this routine.<br />

The depth parameter must be equal to the requested trigger depth for the most recent Multiple Record<br />

acquisition. Note that this depth refers to the depth of each individual group and not the depth of the entire<br />

acquisition. For instance, if a user acquired 2048 groups of 1024 points each, then the depth should be set<br />

to 1024 and not to 1024 x 2048.<br />

memory is the total amount of memory available during the Multiple Record capture. It is the full depth of<br />

the channel memory, which depends on the current capture mode, DUAL or SINGLE. This value can be<br />

obtained from the gage_driver_info_type structure in the max_available_memory field. It will be the full<br />

memory depth of the <strong>CompuScope</strong> in single channel mode and half the memory depth in dual channel<br />

mode.<br />

chan parameter controls whether a hardware or software Multiple Record is performed. If chan equals 0, a<br />

hardware Multiple Record address calculation is performed. In hardware multiple record mode, the<br />

<strong>CompuScope</strong> card acquires the specified amount of post-trigger data points for the first record, stores the<br />

record in on-board <strong>CompuScope</strong> memory, rearms itself and gets ready to capture the next record. This<br />

process is repeated until the specified number of records are captured and stored in <strong>CompuScope</strong> on-board<br />

memory. All data records are stacked sequentially in <strong>CompuScope</strong> on-board memory. Some extra<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 22


padding between records exists and this padding is accounted for in the address calculation if chan is set<br />

equal to 0<br />

The chan equals –1 mode refers to the software multiple record. This option is provided primarily as a<br />

means of reading Multiple Record SIG files, stored by GageScope ® or by another Gage software utility.<br />

After a Multiple Record capture, <strong>CompuScope</strong> memory contains stacked multiple records separated by a<br />

few points of padding, which varies depending on the <strong>CompuScope</strong> model. GageScope ® is capable of<br />

storing all Multiple Records within a single SIG file. For simplicity, GageScope ® removes the inter-record<br />

padding. So, for instance, for a Multiple Record capture of 2048 records of 1024 points each, GageScope ®<br />

stores exactly 2048 x 1024 points to the SIG file. If a user wanted to read such a Multiple Record SIG file<br />

and to calculate the record addresses within the file, he or she should call gage_calculate_mr_addresses<br />

with chan equals –1. Such a Multiple Record file with no inter-record padding is sometimes called a<br />

“Software Multiple Record SIG file”. The SIG file header contains a field that indicates that it is a<br />

Software Multiple Record SIG file. Refer to the GageScope ® manual for the SIG file format information.<br />

op_mode is the mode that was set when calling gage_capture_mode routine. Use the value that<br />

controlled the most recent data capture, either GAGE_SINGLE_CHAN or GAGE_DUAL_CHAN.<br />

GAGE_QUAD_CHAN can also be used for digital input <strong>CompuScope</strong>s.<br />

tbs is the "Time Between Samples" in nanoseconds for the captured signal. For example, if you have<br />

sampled the signal at 10 MS/s then this value would be 100.0. Similarly, a signal sampled at 1 kS/s would<br />

require this value to be set to 1000000.0.<br />

*trig will be the address where trigger event occurred. It may be adjusted in software, depending on the<br />

type of hardware being used.<br />

*start will be the first valid address of the group requested for the most recent data capture.<br />

*end will be the last valid address of the group requested for the most recent data capture.<br />

In Multiple Record mode, the start and trigger addresses will typically be the same. In the hardware<br />

multiple record, the difference between the trigger and end addresses may be larger then the requested<br />

depth, depending upon the <strong>CompuScope</strong> hardware being used. This is due to the architecture of the<br />

hardware and the sample rate being used.<br />

For a Master/Slave <strong>CompuScope</strong> system, the trigger, start and end addresses should be calculated using<br />

gage_calculate_mr_addresses first for all <strong>CompuScope</strong>s in the system before a data transfer routine is<br />

called.<br />

Return Value<br />

The return value is equal to the Multiple Record group number that corresponds to the returned addresses.<br />

Normally, this return value will be equal to the group parameter. If the group parameter exceeds the<br />

actual number of groups, however, then the maximum Multiple Record group number is returned.<br />

See also:<br />

gage_multiple_record and the Appendix entitled Multiple Record Mode Operation.<br />

Examples<br />

C: group = gage_calculate_mr_addresses (0L, gage_driver_info.board_type,<br />

gage_driver_info.trigger_depth, gage_driver_info.max_available_memory, 0, GAGE_DUAL_CHAN,<br />

srtable[board.srindex].sr_calc, *trig, *start, *end);<br />

Visual BASIC: group = gage_calculate_mr_addresses(0, gage_driver_info.board_type,<br />

gage_driver_info.trigger_depth, gage_driver_info.max_available_memory, 0, GAGE_DUAL_CHAN,<br />

srtable(board.srindex).sr_calc, trigaddr, startaddr, endaddr)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

23


gage_capture_mode<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_capture_mode (int16 mode, int16 rate, int16 multiplier);<br />

Visual BASIC:<br />

function gage_capture_mode (ByVal mode As Integer, ByVal rate1 As Integer,<br />

ByVal multiplier As Integer): As Integer<br />

Remarks<br />

The gage_capture_mode routine is used to set the mode and sampluing rate that will be used for the next<br />

<strong>CompuScope</strong> acquisition.<br />

mode is the desired mode of capture, either single (GAGE_SINGLE_CHAN) or dual<br />

(GAGE_DUAL_CHAN). Some <strong>CompuScope</strong> models may only support one of the two modes.<br />

GAGE_QUAD_CHAN can also be used for digital input <strong>CompuScope</strong>s like the CS3200.<br />

The rate and multiplier values together form the requested sample rate. For example, to request a 10<br />

MS/s sample rate, the rate would be set to 10 (or preferably GAGE_RATE_10) and multiplier to<br />

GAGE_MHZ.<br />

The rate can be any valid value. Check your <strong>CompuScope</strong> Hardware <strong>Manua</strong>l for valid rates for your<br />

<strong>CompuScope</strong> model. The valid multiplier values are as follows and are defined in GAGE_DRV.H file.<br />

#define GAGE_HZ 1<br />

#define GAGE_KHZ 2<br />

#define GAGE_MHZ 3<br />

#define GAGE_GHZ 4<br />

#define GAGE_EXT_CLK 5<br />

The multiplier value GAGE_EXT_CLK is used to set the <strong>CompuScope</strong> external clock mode, if your<br />

<strong>CompuScope</strong> is equipped with the external clock feature. When using external clock, the rate should<br />

normally be set to 0. The actual external clock rate should be set before calling gage_capture_mode<br />

routine with a call to gage_set_ext_clock_variables routine. This is an important step, since the drivers<br />

must know what the actual external clock frequency is in order to appropriately set internal low level<br />

timing values on the <strong>CompuScope</strong> hardware.<br />

On some <strong>CompuScope</strong> boards (for example CS8500) the values 1, 2, 4, 8 for rate can also be used with<br />

external clock (multiplier value = GAGE_EXT_CLK). These non-zero settings will decimate thesupplied<br />

external clock signal by the rate factor, if supported.<br />

The gage_capture_mode routine is generally only called once before a series of acquisitions in order to set<br />

the input mode and sampling rate. The call to gage_capture_mode is generally made in conjunction with<br />

calls to gage_set_ext_clock_variables (if using external clock), gage_multiple_record (if using Multiple<br />

Record mode), gage_input_control (to control input settings) and gage_trigger_control (to set trigger<br />

parameters) in order to set up the <strong>CompuScope</strong> hardware for the next acquisition. These routines need<br />

only be called once unless you need to change any parameters for a subsequent acquisition.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 24


Return Value<br />

If the function is successful then a 1 is returned , which indicates that the requested parameters have been<br />

successfully set in the <strong>CompuScope</strong>hardware. If the function fails, then the routine will return a 0 and no<br />

changes to previous <strong>CompuScope</strong> settings are made. gage_get_error_code may be called to obtain the<br />

error code. Possible causes of errors are an invalid mode or invalid sample rate selection.<br />

See Also<br />

gage_input_control, gage_trigger_control_2, gage_set_ext_clock_variables and gage_multiple_record.<br />

Examples<br />

C:<br />

gage_capture_mode (GAGE_SINGLE_CHAN, GAGE_RATE_10, GAGE_KHZ);<br />

Visual BASIC:<br />

dummy = gage_capture_mode (GAGE_SINGLE_CHAN, GAGE_RATE_10, GAGE_KHZ)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

25


gage_delay_trigger_32<br />

Syntax<br />

C:<br />

uInt32 GAGEAPI gage_delay_trigger_32 (int16 action, uInt32 *DelayLow, uInt32 *DelayHigh);<br />

Visual BASIC:<br />

Function gage_delay_trigger_32 (ByVal action As Integer, ByVal DealyLow As Long, ByVal DealyHigh<br />

As Long) As Long<br />

Remarks<br />

The gage_delay_trigger_32 routine, when invoked, ignores the trigger for a specified amount of time or<br />

number of samples. Normally, pre-trigger data will only be captured until an event fulfilling the trigger<br />

conditions occurs. Ensuring that a specific amount of pre-trigger data are captured can be done by using<br />

the gage_delay_trigger_32 routine and then calling gage_start_capture. gage_start_capture will then<br />

ignore triggers until the specified amount of pre-trigger data has been acquired. gage_delay_trigger_32<br />

allows the amount of pre-trigger data to be specified in points or time.<br />

GAGE_SET_DELAY_TIME<br />

This parameter sets the delay time in 100’s of microseconds (µs). For example, when a delay of 1<br />

millisecond (ms) is desired, this parameter should be set to 10 since 10*100 µs = 1000 µs which<br />

comes out to be precisely one millisecond.<br />

GAGE_GET_DELAY_TIME<br />

When this parameter is specified, the gage_delay_trigger_32 routine returns the value of the<br />

delay in units of 100’s of µs previously set in the drivers. This value is passed back as the<br />

DelayLow variable. One effective use of this feature would be to first call<br />

gage_delay_trigger_32 routine with GAGE_SET_DELAY_SAMPLES parameter, specifying the<br />

number of samples in delay. Immediately after, the gage_delay_trigger_32 routine could be<br />

called again with GAGE_GET_DELAY_TIME to retrieve the delay time in 100s of µs.<br />

GAGE_SET_DELAY_SAMPLES<br />

This parameter sets the delay time in number of samples.<br />

GAGE_GET_DELAY_SAMPLES<br />

When this parameter is specified, the gage_delay_trigger_32 routine returns the value of the<br />

delay in number of samples previously set in the drivers.<br />

The DelayLow parameter can be used as an input or output parameter for the delay in time or in number of<br />

samples.<br />

As an input, DelayLow is the actual delay value in time (units of 100 µs) when<br />

GAGE_SET_DELAY_TIME is specified as the action parameter. DelayLow is the delay value in<br />

number of samples when GAGE_SET_DELAY_SAMPLES is specified as the action parameter.<br />

DelayLow is the output when the trigger delay time is to be read back. User must specify the<br />

corresponding value of the trigger delay either in time or number of samples. In case<br />

GAGE_GET_DELAY_TIME is specified as action parameter, the value of the delay t time will be returned<br />

as Delaylow in units of 100s of microseconds. Similarly, if GAGE_GET_DELAY_SAMPLES, then<br />

Delaylow will contain the dealy in samples.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 26


The DelayHigh parameter is reserved for future use.<br />

Return Value<br />

Returns a 0 if the delay values are passed correctly. Returns an unsigned 32 bit integer otherwise.<br />

See also<br />

None<br />

Examples<br />

C:<br />

gage_delay_trigger_32 (GAGE_SET_DELAY_TIME, &Delay_Time, &Delay_High);<br />

Visual BASIC:<br />

gage_delay_trigger_32 (GAGE_SET_DELAY_TIME, DelayLowAddr, DelayHighAddr);<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

27


gage_driver_initialize<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_driver_initialize (uInt16 far *records, uInt16 memory);<br />

Visual BASIC:<br />

function gage_driver_initialize (records As Integer, ByVal memory As Integer) As Integer<br />

Remarks<br />

The gage_driver_initialize routine fully configures each <strong>CompuScope</strong> found in the system and initializes<br />

the drivers. From then on, a call to gage_select_board will be required to access any <strong>CompuScope</strong>.<br />

Below is a detailed description of the values returned by gage_driver_initialize. These values are used<br />

internally by other <strong>CompuScope</strong> API subroutines. Understanding these values is not necessary for most<br />

users who need only call gage_driver_initialize once and move on.<br />

The records parameter is a word (2 byte) array, which must be provided by the calling program. Before<br />

the gage_driver_initialize routine is called, the first half of the records variable must have been<br />

previously initialized to contain the segment / index for each <strong>CompuScope</strong> in the system. This is best done<br />

with a call to the gage_read_config_file routine. Also before the gage_driver_initialize routine is called,<br />

the second half of the records variable should contain all zeros. The array gage_board_location has been<br />

made available within the drivers to be passed as the records parameter and is<br />

GAGE_B_L_BUFFER_SIZE words long.<br />

<strong>CompuScope</strong> gage_board_location (defined in GAGE_DRV.H file) array “pseudo structure”<br />

GAGE_B_L_ELEMENT_SIZE<br />

GAGE_B_L_STATUS_SIZE<br />

array index: 0 1 2 3 ... 30 31 32 33 34 35 ... 62 63<br />

meaning: S1 I1 S2 I2 ... S16 I16 B1 E1 B2 E2 ... B16 E16<br />

GAGE_B_L_STATUS_START<br />

where: Sx = segment for <strong>CompuScope</strong> x,<br />

Ix = index for <strong>CompuScope</strong> x,<br />

Bx = returned board type for <strong>CompuScope</strong> x,<br />

Ex = returned status error for <strong>CompuScope</strong> x.<br />

/* <strong>CompuScope</strong> definitions for gage_board_location sizing. */<br />

#define GAGE_B_L_MAX_CARDS 16<br />

#define GAGE_B_L_SIZEOF_ELEMENT 2<br />

#define GAGE_B_L_ELEMENT_SIZE 2<br />

#define GAGE_B_L_STATUS_SIZE 2<br />

#define GAGE_B_L_STATUS_START (GAGE_B_L_MAX_CARDS *<br />

GAGE_B_L_ELEMENT_SIZE)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 28


#define GAGE_B_L_BUFFER_SIZE (GAGE_B_L_MAX_CARDS *<br />

(GAGE_B_L_ELEMENT_SIZE +<br />

GAGE_B_L_STATUS_SIZE))<br />

The recommended method of setting up the gage_board_location array with the <strong>CompuScope</strong> board<br />

indices and memory segments is to call the gage_read_config_file routine with a filename argument that<br />

was determined by a call to by gage_get_config_filename .<br />

uInt16 gage_board_location[GAGE_B_L_BUFFER_SIZE];<br />

The first segment and I/O index locations are:<br />

gage_board_location[0] = segment;<br />

gage_board_location[1] = index;<br />

/* “segment” is a word that is set to equal the desired<br />

segment for board 1. */<br />

/* “index” is a word that is set to equal the desired I/O index<br />

for board 1. */<br />

The format of the array is that the first GAGE_B_L_STATUS_START words contain the <strong>CompuScope</strong><br />

segment and index values, each sequential pair occupying GAGE_B_L_ELEMENT_SIZE words - one for<br />

each of the possible GAGE_B_L_MAX_CARDS <strong>CompuScope</strong>s.<br />

A status field is provided for each potential board location, which is GAGE_B_L_STATUS_SIZE words in<br />

length. The values for the status field are constants, which correspond to bit positions in the status field<br />

and must be masked to determine which errors occurred when initializing the <strong>CompuScope</strong> hardware. The<br />

low nibble (4 bits) is for problems with the segment and index. GAGE_BAD_LSB_SEGMENT means<br />

that the low order byte of the segment was not equal to zero. GAGE_BAD_MSB_SEGMENT is used<br />

when the segment is either less then A000 hex or greater then DF00 hex (the valid area in the memory map<br />

reserved for slot resources is 0A0000 hex to 0DFFFF hex). GAGE_BAD_LSB_INDEX is set when the<br />

least significant bit of the index is not zero. GAGE_BAD_MSB_INDEX is used when the high order byte<br />

of the index is either equal to 00 hex or greater then 03 hex (the valid area in the I/O map reserved for slot<br />

resources is 0100 hex to 03ff hex).<br />

If the status bits are zero after the above test, then the board initialization continues. If the expected board<br />

does not properly respond, then the GAGE_DETECT_FAILED bit is set and initialization stops. If the<br />

board is found then the board's memory is checked and sized. If any byte of memory does not match its<br />

preset value then the GAGE_MEMORY_FAILED bit is set and initialization of this board stops.<br />

The status board word contains the board type found during initialization. This word is set after the driver<br />

tries to detect the hardware. Therefore, this word could be set but the board is not initialized due to a<br />

memory error. There is a constant GAGE_ASSUME_XXXXX (where XXXXX is board type) available<br />

that can be masked with the status word to determine the board type.<br />

The memory parameter allows the memory self-test to be disabled by supplying the size of the memory in<br />

kilobytes of the installed board(s). The constant GAGE_MEMORY_SIZE_TEST will force the memory<br />

test to be performed. Note that the memory size for all installed boards in the master/slave configuration<br />

must be the same or a conflict can occur and the data returned may be invalid for the boards with the<br />

incorrect memory size assigned.<br />

Several memory size constants are available for specifying default memory size for any of the current<br />

<strong>CompuScope</strong> cards; GAGE_MEMORY_SIZE_016K, GAGE_MEMORY_SIZE_032K,<br />

GAGE_MEMORY_SIZE_064K, GAGE_MEMORY_SIZE_128K, GAGE_MEMORY_SIZE_256K,<br />

GAGE_MEMORY_SIZE_512K, GAGE_MEMORY_SIZE_001M, GAGE_MEMORY_SIZE_002M,<br />

GAGE_MEMORY_SIZE_004M, GAGE_MEMORY_SIZE_008M and GAGE_MEMORY_SIZE_016M.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

29


The constant GAGE_MEMORY_SIZE_TEST will force the memory test to be performed. If an incorrect<br />

memory size is found then the status field for the segment and index record in question will have the<br />

GAGE_BAD_MEMORY_SIZE bit set. If the status is zero and the corresponding segment and index<br />

record are non-zero, then this particular board was properly initialized. If, however, the status is zero and<br />

the segment and index record are also zero then the "board" is the premature end of the records array. By<br />

default the first board found will be selected.<br />

A local data structure in the driver is created for each board. To allow access to this structure the routine<br />

gage_get_driver_info has been implemented. gage_get_driver_info queries the driver about information<br />

on the current selected board. This method should be maintained for compatibility with future releases of<br />

the <strong>CompuScope</strong> drivers, rather than using the internal driver variables directly.<br />

The last area of the status word returns the type of <strong>CompuScope</strong> board found. These maskable bits can be<br />

detected by using the GAGE_ASSUME_XXXXX (where XXXXX is a board type) constant. This is<br />

useful in case the driver could not detect the memory size but was able to detect the <strong>CompuScope</strong> board<br />

type.<br />

Return Value<br />

The value returned is the number of active <strong>CompuScope</strong> boards found. If one or more of the boards was<br />

expected but not found, the number of found boards will be returned as a negative number with the<br />

absolute value equal to the number of boards actually initialized. A return of zero (0) indicates that either<br />

no boards are found or there is a problem with the array that has been passed to this routine, preventing<br />

initialization.<br />

See also<br />

gage_read_config_file, gage_get_driver_info and gage_select_board<br />

Examples<br />

C:<br />

gage_driver_initialize((uInt16 far *)gage_board_location, GAGE_MEMORY_SIZE_TEST);<br />

Visual BASIC:<br />

boards = gage_driver_initialize(gage_board_location(0), GAGE_MEMORY_SIZE_TEST)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 30


gage_driver_remove<br />

Syntax<br />

C:<br />

void GAGEAPI gage_driver_remove (void);<br />

Visual BASIC:<br />

Sub gage_driver_remove ()<br />

Remarks<br />

gage_driver_remove is used to remove from memory all data structures that were created by the<br />

<strong>CompuScope</strong> drivers. This routine should be used upon exit from a <strong>CompuScope</strong> application program.<br />

Using gage_driver_remove ensures that the memory allocated by the drivers is returned to the operating<br />

system for use by other applications.<br />

Return Value<br />

None.<br />

See also<br />

gage_driver_initialize<br />

Examples<br />

C:<br />

gage_driver_remove ();<br />

Visual BASIC:<br />

Call gage_driver_remove ();<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

31


gage_force_capture<br />

Syntax<br />

C:<br />

void GAGEAPI gage_force_capture (int16 reset_trigger_source);<br />

Visual BASIC:<br />

Sub gage_force_capture (ByVal reset_trigger_source As Integer)<br />

Remarks<br />

gage_force_capture is used to force the capture of data by the <strong>CompuScope</strong> hardware. The routine is<br />

primarily used when a trigger event has not occurred in an expected time period. gage_force_capture<br />

send a electrical signal the <strong>CompuScope</strong> hardware so that it triggers as if a real trigger event had occurred.<br />

The reset_trigger_source parameter specifies the trigger source that will be used for the next acquisition<br />

after gage_force_capture. This is normally set to the initial trigger source used.<br />

gage_force_capture should be used for single boards or for multiple boards in a Master/Slave<br />

configuration. Multiple/Independent boards should use the routine gage_board_force_capture, since<br />

gage_force_capture will force all boards in a Multiple/Independent system to trigger.<br />

Return Value<br />

None<br />

See also<br />

gage_board_force_capture<br />

Examples<br />

C:<br />

gage_force_capture (board.source);<br />

Visual BASIC:<br />

Call gage_force_capture (board.source)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 32


gage_get_config_filename<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_get_config_filename (LPSTR cfgfn);<br />

Visual BASIC:<br />

function gage_get_config_filename (ByVal cfgfn As String) As Integer<br />

Remarks<br />

gage_get_config_filename determines the complete path to the configuration file that contains the board<br />

location data created by a Windows-based configuration utility (such as Gage Config or Instrument<br />

Manager). The configuration file is called GAGESCOP.INC and resides in the same Windows directory<br />

as the <strong>CompuScope</strong> driver DLL (gage_drv.dll).<br />

cfgfn is a string variable that must be long enough to hold the returned path.<br />

Return Value<br />

A true value is returned, if the routine successfully returned the configuration filename.<br />

See also<br />

gage_read_config_file<br />

Examples<br />

C:<br />

ret = gage_get_config_filename ((LPSTR)(board_loc_file));<br />

Visual BASIC:<br />

i = gage_get_config_filename (board_loc_file)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

33


gage_get_driver_info<br />

Syntax<br />

C:<br />

void GAGEAPI gage_get_driver_info ((gage_driver_info_type far *)(driver_info));<br />

Visual BASIC:<br />

Sub gage_get_driver_info (driver_info As gage_driver_info_type)<br />

Remarks<br />

gage_get_driver_info fills a structure or record with driver variables that describe the current settings nn<br />

the current <strong>CompuScope</strong> hardware.<br />

The driver_info structure is a subset of the record used by the driver and includes only those values that<br />

have meaning to the control program.<br />

It is recommended that the gage_get_driver_info_structure subroutine be used to determine the size of<br />

the structure of type gage_driver_info_type, so that it can be dynamically allocated. For further details on<br />

this structure type, please see the Appendix: Data Structures Used by Gage Drivers in the <strong>CompuScope</strong><br />

C/C++ <strong>SDK</strong> <strong>Manua</strong>l.<br />

Return Value<br />

None.<br />

See Also<br />

gage_get_driver_info_structure<br />

Examples<br />

C:<br />

gage_get_driver_info ((gage_driver_info_type far*)(&driver_info));<br />

Visual BASIC:<br />

Call gage_get_driver_info (driver_info)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 34


gage_get_driver_info_structure<br />

Syntax<br />

C:<br />

void GAGEAPI gage_get_driver_info_structure (uInt16 far *major_version, uInt16 far *minor_version,<br />

uInt16 far *board_support, gage_driver_info_type far * far * gdi,<br />

int32 far *gdi_size);<br />

Visual BASIC:<br />

Sub gage_get_driver_info (major_version As Integer, minor_version As Integer, board_support As<br />

Integer, gdi As gage_driver_info_type, gdi_size As Long)<br />

Remarks<br />

gage_get_driver_info_structure returns relevant information about the main structure of type<br />

gage_driver_info_type that is used by the <strong>CompuScope</strong> drivers. It is recommended that<br />

gage_get_driver_info_structure be called before calling gage_get_driver_info in order to determine the<br />

size of the gage_driver_info_type structure type for memory allocation purposes. This procedure will<br />

maintain compatibility with future versions of the <strong>CompuScope</strong> drivers, where the size of the<br />

gage_driver_info_type may increase.<br />

The major_version and minor_version parameters return the current <strong>CompuScope</strong> driver version.<br />

board_support returns the <strong>CompuScope</strong> boards that are supported by the current <strong>CompuScope</strong> drivers.<br />

This will be a combination of predefined constants GAGE_ASSUME_XXXXX, where XXXXX is a board<br />

type. Board type constants are defined in the file GAGE_DRV.H.<br />

The gdi parameter returns a pointer to the structure of type gage_driver_info_type that is allocated and<br />

filled by the <strong>CompuScope</strong> drivers. This structure is a subset of the more complete record used by the<br />

drivers and includes only those values that have meaning to the control program.<br />

gdi_size is the current size of to a structure of type gage_driver_info_type in the current version of the<br />

<strong>CompuScope</strong> drivers. gdi_size can be used to allocate the proper amount of memory to hold a structure of<br />

type gage_driver_info_type,. This variable is very useful since the size of gage_driver_info_type can<br />

increase with newer driver versions. Using gdi_size ensures that an application program can be easily<br />

updated for newer <strong>CompuScope</strong> driver versions. The new drivers can then be used without having to<br />

recompile the application program. Note that any new fields will be unavailable to the application program<br />

until it is recompiled with the new header files.<br />

Return Value<br />

None.<br />

See Also: gage_get_driver_info<br />

Examples<br />

C:<br />

gage_get_driver_info_structure ((uInt16 far *)(&major_version), (uInt16 far *)(&minor_version),<br />

(uInt16 far *)(&board_support),(gage_driver_info_type far * far *)(&gdi),<br />

(int32 far *)(&gdi_size));<br />

Visual BASIC:<br />

Call gage_get_driver_info_structure(major_version, minor_version, board_support, gdi, gdi_size)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

35


gage_get_error_code<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_get_error_code(void);<br />

Visual BASIC:<br />

Function gage_get_error_code () As Integer<br />

Remarks<br />

gage_get_error_code returns the error code associated with the last call to the <strong>CompuScope</strong> drivers.<br />

Return Value<br />

The return value is a combination of the error that occurred and the <strong>CompuScope</strong> board that caused the<br />

error. The function returns a value, which is encoded with the high byte containing the <strong>CompuScope</strong> board<br />

in error, and the low byte is set equal to the defined error constant. These error code constants are defined<br />

in gage_drv.h – one of the common <strong>CompuScope</strong> driver files. For instance, GAGE_NO_ERROR indicates<br />

that no error actually occurred, while GAGE_NO_SUCH_COUPLING indicates that the requested input coupling was<br />

not available on the selected <strong>CompuScope</strong>.<br />

Examples<br />

C:<br />

error = gage_get_error_code ();<br />

Visual BASIC:<br />

ret = gage_get_error_code()<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 36


gage_get_independant_operation<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_get_independant_operation (void);<br />

Visual BASIC:<br />

Function gage_get_independant_operation () As Integer<br />

Remarks<br />

gage_get_independant_operation is used to check if the boards are in Multiple/Independent mode.<br />

Return Value<br />

A non-zero value is return if the boards are in Multiple/Independent mode, and a zero is returned if they are<br />

not in Multiple/Independent mode.<br />

See also<br />

gage_set_independant_operation and Appendix: Multiple/Independent Mode Operation.<br />

Examples<br />

C:<br />

independent = gage_get_independant_operation();<br />

Visual BASIC:<br />

independent = gage_get_independant_operation<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

37


gage_input_control<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_input_control (int16 channel, int16 enable, int16 coupling, int16 gain);<br />

Visual BASIC:<br />

Function gage_input_control (ByVal channel As Integer, ByVal enable As Integer,<br />

ByVal coupling As Integer, ByVal gain As Integer) As Integer<br />

Remarks<br />

gage_input_control is used to set up the input parameters for each signal input channel on <strong>CompuScope</strong><br />

hardware.<br />

The channel parameter is either channel A (constant GAGE_CHAN_A defined in GAGE_DRV.H) or<br />

channel B (constant GAGE_CHAN_B defined in GAGE_DRV.H).<br />

The enable parameter either enables the channel to capture data or disables the data capture on that<br />

channel. The constants GAGE_INPUT_ENABLE or GAGE_INPUT_DISABLE should be used. This<br />

functionality is not useful on modern <strong>CompuScope</strong>s and the user should simply enable all channels.<br />

coupling controls the input coupling (either DC or AC ) and is set using the constants GAGE_DC and<br />

GAGE_AC.<br />

The gain parameter controls the input ranges for each input channel. Possible constants are listed in the<br />

Appendix: Data Structures Used by <strong>CompuScope</strong> Drivers in the <strong>CompuScope</strong> C/C++ <strong>SDK</strong> <strong>Manua</strong>l. For<br />

instance, in order to set the input range to ±1 Volts, the user should assign GAGE_PM_1_V to the gain<br />

parameter.<br />

In single channel mode, both channels should be set to the same parameters.<br />

To set the impedance for an input channel, the gain should be bitwise "ORed" with the desired impedance,<br />

either GAGE_1_MOHM_INPUT or GAGE_50_OHM_INPUT. For instance, in order to set the input<br />

range to ±1 Volts with an input impedance of 50 Ohms, the user should assign (GAGE_PM_1_V |<br />

GAGE_50_OHM_INPUT) to the gain parameter, where "|" is C syntax for bit-wise OR.<br />

Some <strong>CompuScope</strong>s, such as the <strong>CompuScope</strong> 1610, support two input types: single-ended or differential.<br />

To set the input type for an input channel, the gain should be bitwise "ORed" with the desired input type,<br />

either GAGE_SINGLE_ENDED_INPUT or GAGE_DIFFERENTIAL_INPUT. For instance, in order to<br />

set the input range to ±1 Volts and input type of differential, the user should assign (GAGE_PM_1_V |<br />

GAGE_DIFFERENTIAL_INPUT) to the gain parameter, where "|" is C syntax for bit-wise OR.<br />

Return Value<br />

A 1 is returned if the routine has successfully set the requested input control parameters. A 0 is returned if<br />

the routine fails to implement requested input control parameters. gage_get_error_code may be called to<br />

obtain the error code. You should always check the return value.<br />

See also: gage_trigger_control_2 and gage_capture_mode<br />

Examples<br />

C: gage_input_control (GAGE_CHAN_A, GAGE_INPUT_ENABLE, GAGE_DC, GAGE_PM_1_V |<br />

GAGE_1_MOHM_INPUT);<br />

Visual BASIC: dummy = gage_input_control (GAGE_CHAN_A, GAGE_INPUT_ENABLE,<br />

GAGE_DC,GAGE_PM_1_V OR GAGE_1_MOHM_INPUT)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 38


gage_mem_read_master<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_mem_read_master (int32 location);<br />

Visual BASIC:<br />

Function gage_mem_read_master (ByVal location As Long) As Integer<br />

Remarks<br />

gage_mem_read_master reads one sample out of the on-board memory of the Master <strong>CompuScope</strong> in a<br />

Master/Slave <strong>CompuScope</strong> system. It can used in a loop to retrieve data from a range of addresses from<br />

the Master <strong>CompuScope</strong> board.<br />

location is an address in the <strong>CompuScope</strong> memory from which a single sample point will be retrieved.<br />

The gage_calculate_addresses routine is very useful for determining the range of <strong>CompuScope</strong> on-board<br />

memory addresses that contains valid data from the latest acquisition. gage_calculate_addresses returns<br />

the start, trigger and end address for the last <strong>CompuScope</strong> acquisition.<br />

Return Value<br />

The return value is the raw data sample downloaded from the address location in the on-board memory of<br />

the Master <strong>CompuScope</strong>.<br />

See also<br />

gage_calculate_addresses.<br />

Examples<br />

C:<br />

data = gage_mem_read_master (address);<br />

Visual BASIC:<br />

data = gage_mem_read_master (address)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

39


gage_multiple_record<br />

Syntax<br />

C:<br />

void GAGEAPI gage_multiple_record (uInt16 mode);<br />

Visual BASIC:<br />

Sub gage_multiple_record (ByVal mode As Integer)<br />

Remarks:<br />

gage_multiple_record is used to put the CompuSCope hardware in Multiple Record Mode. In Multiple<br />

Record mode, the <strong>CompuScope</strong> hardware captures a record of the specified depth after a trigger event<br />

occurs. After an acquisition, the <strong>CompuScope</strong> then re-arms itself to accept another trigger event and<br />

record the data immediately following the first capture. Sequential data records are stacked in<br />

<strong>CompuScope</strong> on-board memory. The Multiple Record process continues until a previously specified<br />

number of Multiple Records has been captured. Throughout Multiple Record operation, the <strong>CompuScope</strong><br />

BUSY signal remains active.<br />

The <strong>CompuScope</strong> TRIGGER signal can be monitored using the gage_triggered routine. This monitoring<br />

can used during the Multiple Record operation in order to how many Multiple Records have been acquired,<br />

if the trigger repetition rate is slow enough. The <strong>CompuScope</strong> board cannot be busy when accessing onboard<br />

memory. Consequently, data cannot be downloaded until the Multiple Record operation has been<br />

terminated. The BUSY status must be checked with the gage_busy routine in order to verify that Multiple<br />

Record operation is complete before downloading data.<br />

The mode parameter must be set to 1 in order to enable Multiple Record Mode. The mode parameter must<br />

be set to 0 in order to return to conventional Single Record Mode. By default, the <strong>CompuScope</strong> drivers set<br />

the hardware to be in Single Record Mode upon initialization.<br />

VERY IMPORTANT: When the Multiple Record feature is to be used, the gage_capture_mode,<br />

gage_input_control and gage_trigger_control_2 routines must be called (to set internal variables) after<br />

calling gage_multiple_record, regardless of whether the <strong>CompuScope</strong> settings need to be changed.<br />

Multiple Record capability is standard only on some <strong>CompuScope</strong> models. Check your <strong>CompuScope</strong><br />

hardware manual in order to determine if Multiple Record mode is available on your <strong>CompuScope</strong> model.<br />

Return Value: None<br />

See also<br />

gage_start_capture, gage_busy, gage_triggered, gage_multiple_record_acquisitions_32 and Appendix:<br />

Multiple Record Mode Operation.<br />

Examples<br />

C:<br />

gage_multiple_record (1);<br />

Visual BASIC:<br />

Call gage_multiple_record (1)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 40


gage_multiple_record_acquisitions_32<br />

Syntax<br />

C:<br />

uInt32 GAGEAPI gage_multiple_record_acquisitions_32 (uInt32 number);<br />

Visual BASIC:<br />

Function gage_multiple_record_acquisitions_32 (ByVal number As Integer) As Integer<br />

Remarks:<br />

gage_multiple_record_acquisitions_32 sets the number of Multiple Record groups that will be acquired<br />

by the <strong>CompuScope</strong> hardware during the next Multiple Record acquisition. This routine is only available<br />

for PCI and cPCI CompuSocpes (the CP500-class boards)<br />

number is the number of Multiple Record groups.<br />

This routine should be called immediately after calling the gage_multiple_record routine.<br />

Return Value<br />

Returns the number of groups requested. If the number of groups requested exceeds the maximum<br />

possible supported by the <strong>CompuScope</strong> hardware, the routine then returns the maximum supported number<br />

of groups.<br />

See also<br />

gage_multiple_record and Appendix: Multiple Record Mode Operation.<br />

Examples<br />

C:<br />

gage_multiple_record_acquisition_32 (10);<br />

Visual BASIC:<br />

Call gage_multiple_record_acquisitions_32 (10)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

41


gage_need_ram<br />

Syntax<br />

C:<br />

void GAGEAPI gage_need_ram (int16 need);<br />

Visual BASIC:<br />

Sub gage_need_ram (ByVal need As Integer)<br />

Remarks<br />

gage_need_ram allows the application program to access the <strong>CompuScope</strong> hardware’s RAM buffers to<br />

download the data that have been captured by the board. The routine is primarily used to turn off the<br />

power to <strong>CompuScope</strong> analog conversion circuitry when the power mode is set to AUTO, as controlled by<br />

the gage_power_control routine.<br />

need can be either 1 or 0.<br />

gage_need_ram(1) allows the application program to access the <strong>CompuScope</strong> board’s memory.<br />

gage_need_ram(0) connects the <strong>CompuScope</strong> memory back to the acquisition bus, allowing data capture.<br />

The gage_need_ram routine must be called with a value of 1 before using any of the data transfer routines<br />

to allow access to the <strong>CompuScope</strong> memory. When finished, gage_need_ram(0) should be called to allow<br />

data capture to occur again.<br />

You must get all trigger addresses using the gage_calculate_addresses routines before you call<br />

gage_need_ram(1). Also, for a Master/Slave <strong>CompuScope</strong> Multi-card system, the trigger addresses<br />

should be calculated first for all <strong>CompuScope</strong>s in the system before gage_need_ram(1) is called.<br />

Return Value<br />

None.<br />

See also<br />

gage_busy<br />

Examples<br />

C:<br />

gage_need_ram (TRUE);<br />

Visual BASIC:<br />

Call gage_need_ram (TRUE)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 42


gage_normalize_address<br />

Syntax<br />

C:<br />

int32 GAGEAPI gage_normalize_address (int32 start, int32 address, int32 ram_size);<br />

Visual BASIC:<br />

Function gage_normalize_address (ByVal start As Long, ByVal address As Long,<br />

ByVal ram_size As Long) As Long<br />

Remarks<br />

gage_normalize_address calculates the distances between <strong>CompuScope</strong> memory addresses to allow the<br />

application programmer to compare different addresses obtained from the gage_calculate_addresses<br />

function. This routine manipulates the addresses obtained from gage_calculate_addresses to allow the<br />

application program to compare their values accounting for the memory rollover that occurs with the<br />

circular buffer architecture used by all versions of the <strong>CompuScope</strong> hardware.<br />

For instance, suppose that there a <strong>CompuScope</strong> with 1 MegaSample of on-board memory had been filled<br />

with pre-trigger data. In this case, we might encounter a situation where the memory rollover occurred<br />

during the capture of post-trigger data. In this case, the trigger address might be 950,000 while the end<br />

address was 50,000. Determining the number of post-trigger points by subtracting the trigger address from<br />

the end address would incorrectly yield a negative number. The correct number of points could be<br />

calculated by calling gage_normalize_address with arguments of the trigger address, the ending address<br />

and the amount of on-board <strong>CompuScope</strong> memory.<br />

start is the address from where you want to start calculating.<br />

address is any address that is of interest in the <strong>CompuScope</strong> memory.<br />

ram_size is the size of the <strong>CompuScope</strong> memory on the card in question. This size can be determined with<br />

a call to the gage_get_driver_info routine.<br />

Return Value<br />

The return value is the difference between address and start accounting for any memory buffer rollover<br />

that may have occurred as determined by ram_size. Note that start does not necessarily need to be the<br />

starting address. Any two addresses can be compared using this routine.<br />

See also<br />

gage_calculate_addresses and gage_get_driver_info<br />

Examples<br />

C:<br />

address = gage_normalize_address (trigger_address, end_address, max_available_memory);<br />

Visual BASIC:<br />

address = gage_normalize_address (trigger_address, end_address , max_available_memory)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

43


gage_power_control<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_power_control (int16 mode);<br />

Visual BASIC:<br />

Function gage_power_control (mode As Integer) As Integer<br />

Remarks<br />

gage_power_control is used to control the automatic power management available on some <strong>CompuScope</strong><br />

models. These models are able to power down the high power analog conversion circuitry when it is not in<br />

use for power conservation and for minimizing wear and tear on the circuitry. By default, <strong>CompuScope</strong><br />

models that consume a lot of power, such as the CS8500 and CS82G, are set to AUTO mode. In this<br />

mode, the conversion circuitry power is automatically turned on before an acquisition and then is turned<br />

off after the acquisition.<br />

For the acquisition of multiple triggers with a high repeat rate, the user may want to change the power<br />

mode to ON, from its default of AUTO. This way, the power is left on through the multiple acquisitions,<br />

so that no time is wasted turning the power on and off between acquisitions, which may take several<br />

milliseconds. The user must take care to return the power to AUTO mode after the multiple trigger<br />

acquisitions are finished.<br />

The mode can be one of three predefined constants, which can either be GAGE_POWER_ON (1),<br />

GAGE_POWER_OFF (0) or GAGE_POWER_AUTO_MASK (0x0002) defined in GAGE_LOW.H file.<br />

GAGE_POWER_ON turns on the power to <strong>CompuScope</strong> analog conversion circuitry leaves it on. In this<br />

mode, power is not turned off by calling gage_need_ram(TRUE). This mode is useful for fast repetitive<br />

capture, where the user does not want to waste time controlling the power between acquisitions.<br />

GAGE_POWER_OFF turns off the power. This mode is useful if your computer is left on but the<br />

<strong>CompuScope</strong> board is not in use.<br />

GAGE_POWER_AUTO_MASK turns the <strong>CompuScope</strong> board on and off automatically when<br />

appropriate, thereby conserving power. The <strong>CompuScope</strong> conversion circuitry is turned on when<br />

<strong>CompuScope</strong> capture begins by the gage_start_capture routine and is turned off when<br />

gage_need_ram(TRUE) is called and before data transfer is initiated.<br />

Return Value<br />

The return value is the mode passed to the board. If the mode is invalid or power control is not supported<br />

on the board, a negative value is returned.<br />

See also: gage_need_ram<br />

Examples: C: pw = gage_power_control (GAGE_POWER_AUTO_MASK);<br />

Visual BASIC: pw = gage_power_control (GAGE_POWER_AUTO_MASK)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 44


gage_read_config_file<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_read_config_file (LPSTR filename, uInt16 far *records);<br />

Visual BASIC:<br />

Function gage_read_config_file (ByVal filename As String, records As Integer) As Integer<br />

Remarks<br />

gage_read_config_file reads a file and stores the data in an array of words.<br />

filename is a text string that tells the routine the name of the file that contains the indices and starting<br />

segment values for each of the installed <strong>CompuScope</strong> boards. This filename is usually determined by<br />

calling gage_get _config_filename, which provides the full path and filename of the GAGESCOP.INC<br />

file that the Windows drivers use for locating the <strong>CompuScope</strong> hardware. Alternatively, the filename can<br />

be explicitly passed to the gage_read_config_file routine, if the user wishes to use an alternate<br />

configuration file.<br />

The records parameter is assumed to be an uninitialized word (2 byte) array. The array is initialized by<br />

gage_read_config_file with the values found in the configuration file. The status elements of records are<br />

all initialized to 0. The array gage_board_location has been made available within the drivers to be passed<br />

as the records parameter and is GAGE_B_L_BUFFER_SIZE words long.<br />

Please note that <strong>CompuScope</strong> memory segment and index values are variable for ISA and ISA/PCI<br />

<strong>CompuScope</strong>s only. For PCI (CP500) <strong>CompuScope</strong>s, the memory segments and index values will always<br />

be returned as 0xffff (65535 decimal).<br />

<strong>CompuScope</strong> gage_board_location (defined in GAGE_DRV.H file) array “pseudo structure”<br />

GAGE_B_L_ELEMENT_SIZE<br />

GAGE_B_L_STATUS_SIZE<br />

array index: 0 1 2 3 ... 30 31 32 33 34 35 ... 62 63<br />

meaning: S1 I1 S2 I2 ... S16 I16 B1 E1 B2 E2 ... B16 E16<br />

where: Sx = segment for <strong>CompuScope</strong> x,<br />

Ix = index for <strong>CompuScope</strong> x,<br />

Bx = returned board type for <strong>CompuScope</strong> x,<br />

Ex = returned status error for <strong>CompuScope</strong> x.<br />

/* <strong>CompuScope</strong> definitions for gage_board_location sizing. */<br />

#define GAGE_B_L_MAX_CARDS 16<br />

#define GAGE_B_L_SIZEOF_ELEMENT 2<br />

#define GAGE_B_L_ELEMENT_SIZE 2<br />

#define GAGE_B_L_STATUS_SIZE 2<br />

GAGE_B_L_STATUS_START<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

45


#define GAGE_B_L_STATUS_START (GAGE_B_L_MAX_CARDS *<br />

GAGE_B_L_ELEMENT_SIZE)<br />

#define GAGE_B_L_BUFFER_SIZE (GAGE_B_L_MAX_CARDS *<br />

(GAGE_B_L_ELEMENT_SIZE +<br />

GAGE_B_L_STATUS_SIZE))<br />

The format of the array is: first GAGE_B_L_STATUS_START words are for the <strong>CompuScope</strong> segment<br />

and index values, each pair occupying GAGE_B_L_ELEMENT_SIZE words, for each of the possible<br />

GAGE_B_L_MAX_CARDS boards. A status field is provided for each potential <strong>CompuScope</strong> location<br />

that is GAGE_B_L_STATUS_SIZE words in length. The values for the status fields are initialized to 0 by<br />

gage_get _config_filename. The status fields are updated by the gage_driver_initialize routine, whose<br />

description explains their meaning.<br />

Return Value<br />

If the return value is greater than 0, it represents the number of records initialized.<br />

If the number is less than zero, it corresponds to the error encountered. The errors are:<br />

-1 file does not exist.<br />

-2 file cannot be opened.<br />

-3 file size cannot be determined.<br />

-4 file size module four is not zero.<br />

-5 file size indicates that more boards than the driver supports are present.<br />

-6 file cannot be read successfully.<br />

-7 file cannot be closed.<br />

(0 is reserved for future use.)<br />

See also<br />

gage_driver_initialize and gage_get_config_filename<br />

Examples<br />

C:<br />

expected = gage_read_config_file ((char far*)("GAGESCOP.INC"),<br />

(uInt16 far*)(&gage_board_location));<br />

Visual BASIC:<br />

expected = gage_read_config_file (board_loc_file, gage_board_location (0))<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 46


gage_select_board<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_select_board (int16 board);<br />

Visual BASIC:<br />

Function gage_select_board (ByVal board As Integer) As Integer<br />

Remarks<br />

The gage_select_board routine is for use with a Multi-Card <strong>CompuScope</strong> system. Once called with an<br />

argument that specifies the board number, gage_select_board directs subsequent subroutine calls to this<br />

specified board.<br />

In a Master/Slave <strong>CompuScope</strong> system, the Master controls many functions, such as the sampling rate and<br />

trigger controls. Furthermore, only the Master <strong>CompuScope</strong> needs to be sent the gage_start_capture<br />

command and only the Master needs to be polled with gage_triggered and gage_busy. Commands that<br />

control these functionalities that are managed by the Master <strong>CompuScope</strong> are automatically only sent to<br />

the Master <strong>CompuScope</strong>. However, the captured data must be downloaded separately from each<br />

<strong>CompuScope</strong> in the Master/Slave system. Also, channel parameters, such as input range, coupling and<br />

terminating impedance must be separately sent to each <strong>CompuScope</strong>, after calling the gage_select_board<br />

routine.<br />

In a Multiple/Independent <strong>CompuScope</strong> system, all functions (i.e. the initialization, setup, capture and data<br />

transfer) must be performed separately for each <strong>CompuScope</strong>, using gage_select_board routine.<br />

The board number is the <strong>CompuScope</strong> board to which all subsequent subroutines call will be applied. The<br />

board number assignments can be determined using a <strong>CompuScope</strong> configuration utility, such as Gage<br />

Config or Instrument Manager.<br />

Return Value<br />

The integer returned equals the value passed to the function as board. If an error occurs or the value<br />

passed to the function exceeds the number of boards installed in the system then the return value does not<br />

equal board and gage_get_error_code may be called to obtain the error code.<br />

See also<br />

gage_driver_initialize<br />

Examples<br />

C:<br />

current_board = gage_select_board (i);<br />

Visual BASIC:<br />

current_board = gage_select_board (i)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

47


gage_set_ext_clock_variables<br />

Syntax<br />

C:<br />

void GAGEAPI gage_set_ext_clock_variables (int16 op_mode, uInt16 external_clock_delay,<br />

float external_clock_rate);<br />

Visual BASIC:<br />

Sub gage_set_ext_clock_variables (ByVal op_mode As Integer, ByVal external_clock_delay As Integer,<br />

ByVal exterrnal_clock_rate As Single)<br />

Remarks<br />

gage_set_ext_clock_variables is used to set the required variables for use of an external clock. Signal.<br />

Not all <strong>CompuScope</strong>s are equipped with an external clock input. On some <strong>CompuScope</strong> models, such as<br />

the CS12100, it is an optional modification, which must be purchased with the <strong>CompuScope</strong>.<br />

gage_set_ext_clock_variables should be called before the gage_capture_mode routine. If you are using<br />

an external clock, you must use the GAGE_EXTERNAL_CLOCK constant as the rate and multiplier<br />

values when calling the gage_capture_mode routine.<br />

op_mode is a current CopmuScope operating mode, which should be set using the constants<br />

GAGE_SINGLE_CHAN or GAGE_DUAL_CHAN (or GAGE_QUAD_CHAN for digital <strong>CompuScope</strong>s).<br />

The external_clock_delay parameter sets the clock delay to synchronize the external clock to the<br />

<strong>CompuScope</strong> board. Using a value of -1 will let the drivers calculate this value. Use another value to<br />

override this option. The values calculated by the driver will be 0 if the sample rate is greater than 5 MHz<br />

or the maximum of 1 and 10,000 / external_clock_rate otherwise. It is recommended that –1 be used for<br />

the external_clock_delay.<br />

external_clock_rate is frequency of the signal connected to the EXTERNAL CLOCK input of the<br />

<strong>CompuScope</strong>. It is important that this value be set correctly, since the <strong>CompuScope</strong> hardware needs to<br />

know this value so that the drivers can set internal <strong>CompuScope</strong> timing parameters.<br />

The frequency at which sampled data will be stored in memory may differ from the external_clock_rate.<br />

For instance for the CS1602, the sampling rate is one-eighth of the external_clock_rate. For the CS12100<br />

with the regular external clock upgrade, the sampling rate is one-half of the external_clock_rate, when the<br />

CS12100 is in dual channel mode.<br />

Return Value: None<br />

See also: gage_capture_mode<br />

Examples: C:<br />

gage_set_ext_clock_variables (GAGE_SINGLE_CHAN,-1, 10000000.0);<br />

Visual BASIC:<br />

Call gage_set_ext_clock_variables (GAGE_SINGLE_CHAN,-1, 10000000.0)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 48


gage_set_independant_operation<br />

Syntax<br />

C:<br />

void GAGEAPI gage_set_independant_operation (int16 independant);<br />

Visual BASIC:<br />

Sub gage_set_independant_operation (ByVal independant As Integer)<br />

Remarks<br />

gage_set_independant_operation sets the driver to initialize the Multiple/Independent <strong>CompuScope</strong><br />

operation mode. In Multiple/Independent mode, two or more <strong>CompuScope</strong>s can be operated completely<br />

independently of each other with completely different <strong>CompuScope</strong> parameters.<br />

Before initializing the <strong>CompuScope</strong> hardware, with the gage_driver_initialize routine, the<br />

gage_set_independant_operation routine must be called to enable Multiple/Independent <strong>CompuScope</strong><br />

operation. Before setting up each board with the desired parameters, you should select the board by calling<br />

the gage_select_board routine.<br />

When operating <strong>CompuScope</strong>s in Multiple/Independent mode, the routines; gage_board_start_capture,<br />

gage_board_force_capture and gage_board_abort_capture should be used in place of<br />

gage_start_capture, gage_force_capture and gage_abort_capture, respectively. These routines select<br />

the appropriate board internally.<br />

The independant parameter when used with a non-zero value will set the <strong>CompuScope</strong> hardware for<br />

Multiple/Independent operation.<br />

Once the <strong>CompuScope</strong> hardware has been set for independent mode the routine<br />

gage_set_independant_operation with the value 0 for the independant parameter can be called to disable<br />

Multiple/Independent operation. gage_set_independant_operation must be called before calling the<br />

gage_driver_initialize routine when independent operation mode is required.<br />

Return Value<br />

None<br />

See also<br />

gage_get_independant_operation, gage_board_start_capture, gage_board_force_capture,<br />

gage_board_abort_capture and Appendix H: Multiple/Independent Mode Operation.<br />

Examples<br />

C:<br />

gage_set_independant_operation (1);<br />

Visual BASIC:<br />

Call gage_set_independant_operation (1)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

49


gage_software_trigger<br />

Syntax<br />

C:<br />

void GAGEAPI gage_software_trigger (void);<br />

Visual BASIC:<br />

Sub gage_software_trigger ()<br />

Remarks<br />

A call to the gage_software_trigger routine will trigger the hardware immediately, if the trigger source<br />

has been previously set to GAGE_SOFTWARE.<br />

The gage_start_capture routine will automatically software trigger the <strong>CompuScope</strong> hardware, if it is<br />

passed a non-zero argument.<br />

Return Value<br />

None.<br />

See also<br />

gage_trigger_control_2 and gage_start_capture<br />

Examples<br />

C:<br />

gage_software_trigger ();<br />

Visual BASIC:<br />

Call gage_software_trigger ()<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 50


gage_start_capture<br />

Syntax<br />

C:<br />

void GAGEAPI gage_start_capture (int16 auto_trigger);<br />

Visual BASIC:<br />

Sub gage_start_capture (ByVal auto_trigger As Integer)<br />

Remarks<br />

gage_start_capture is used to start the <strong>CompuScope</strong> hardware acquiring pre-trigger data and awaiting a<br />

trigger event.. The hardware must have been previously configured for the desired operation mode, input<br />

ranges and trigger conditions with calls to gage_capture_mode, gage_input_control and<br />

gage_trigger_control_2.<br />

In a Master/Slave <strong>CompuScope</strong> system, gage_start_capture starts acquisition on all <strong>CompuScope</strong>s in the<br />

system.<br />

The auto_trigger parameter, when assigned a non-zero value, causes gage_start_capture to trigger the<br />

<strong>CompuScope</strong> hardware immediately after starting data capture. The trigger source must have been<br />

previously set to GAGE_SOFTWARE for this parameter to have a predictable effect with all versions of<br />

<strong>CompuScope</strong> boards. Please note that is the auto_trigger parameter, which must be set to 0 for software<br />

triggering and not the trigger source. If software triggering is not required, then the auto_trigger value<br />

should be set to 1.<br />

Return Value<br />

None.<br />

See also<br />

gage_trigger_control_2<br />

Examples<br />

C:<br />

gage_start_capture (GAGE_SOFTWARE == board.source);<br />

Visual BASIC:<br />

Call gage_start_capture (auto_trigger)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

51


gage_transfer_buffer<br />

Syntax<br />

C:<br />

void GAGEAPI gage_transfer_buffer (int32 ta, int16 channel, void far *buffer, int32 nsamples);<br />

Visual BASIC:<br />

Sub gage_transfer_buffer (ByVal ta As Long, ByVal channel As Integer, buffer As Integer, ByVal<br />

nsamples As Integer)<br />

Remarks<br />

gage_transfer_buffer is used to copy nsamples points from the specified channel to the supplied buffer<br />

beginning from <strong>CompuScope</strong> on-board memory address ta. The channel can be either GAGE_CHAN_A<br />

or GAGE_CHAN_B, and refers to the A/D converter memory bank. The relevant addresses can be<br />

obtained by calling gage_calculate_addresses. The buffer must have been previously typecast to the<br />

appropriate size. For 8 bit <strong>CompuScope</strong>s, the buffer should typecast for uInt8 values. For <strong>CompuScope</strong>s<br />

with more than 8 bit resolution, the buffer should typecast for int16 values.<br />

gage_transfer_buffer uses a CPU mediated PCI data transfer method. For the fastest PCI bus-mastering<br />

data transfer, use gage_transfer_buffer_3.<br />

For all <strong>CompuScope</strong> boards with two channels operating in single channel mode, both A/D converters are<br />

used. The two converters are connected to the conditioned input from the Channel A BNC and are clocked<br />

180 O out of phase. Data from each converter are then stored in their respective memory banks, as usual.<br />

After capture, gage_transfer_buffer must then be used to download the data from both memory banks.<br />

This is done by calling gage_transfer_buffer twice, once with channel equal to GAGE_CHAN_A , which<br />

transfer the even points, and once with channel equal to GAGE_CHAN_B, which transfer the odd points..<br />

The user must then interleave the two downloaded data sets in order to reconstruct the complete data<br />

record.<br />

Return Value<br />

None.<br />

See also<br />

gage_transfer_buffer_3 and Appendix: Comparison of Various Data Transfer Routines.<br />

Example<br />

C:<br />

gage_transfer_buffer (current_address, GAGE_CHAN_A, (uInt8 far *)(buffer), 512);<br />

Visual Basic:<br />

gage_transfer_buffer (ByVal ta As Long, ByVal channel As Integer, buffer As Integer, ByVal nsamples As<br />

Integer)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 52


gage_transfer_buffer_3<br />

Syntax<br />

C:<br />

uInt32 GAGEAPI gage_transfer_buffer_3 (int32 ta, int16 channel, void far *buffer, int32 nsamples);<br />

Visual BASIC:<br />

Function gage_transfer_buffer_3 (ByVal ta As Long, ByVal channel As Integer, buffer As Integer, ByVal<br />

nsamples As Integer) As Integer<br />

Remarks<br />

gage_transfer_buffer_3 is used to copy nsamples points from the specified channel to the supplied<br />

buffer beginning from address ta. The channel can be either GAGE_CHAN_A or GAGE_CHAN_B. The<br />

relevant addresses can be obtained by calling gage_calculate_addresses. . The buffer must have been<br />

previously typecast to the appropriate size. For 8 bit <strong>CompuScope</strong>s, the buffer should typecast for uInt8<br />

values. For <strong>CompuScope</strong>s with more than 8 bit resolution, the buffer should typecast for int16 values.<br />

The <strong>CompuScope</strong> PCI boards will use PCI bus-mastering if available in hardware, otherwise a CPU<br />

mediated PCI data transfer method is used. PCI bus-mastering is the fastest possible PCI data transfer<br />

method.<br />

The buffer must be padded so that it is slightly longer than the memory required to store nsample samples.<br />

The required amount of padding is different for different <strong>CompuScope</strong> models. The best padding method<br />

is to use the variable user_buffer_padding, which is returned by the drivers and is the amount of extra<br />

padding in Bytes required for the current <strong>CompuScope</strong> model.. Simply add user_buffer_padding to the<br />

amount of memory to be allocated.<br />

Unlike gage_transfer_buffer, in single channel mode gage_transfer_buffer_3 automatically downloads<br />

data from both <strong>CompuScope</strong> A/D converter memories and internally interleaves them. Consequently,<br />

the user application does not need to interleave the data when the acquisition has been performed in<br />

single channel mode using gage_transfer_buffer_3. In single channel mode, gage_transfer_buffer_3<br />

need only be called once with channel equal to GAGE_CHAN_A<br />

Return Value<br />

Returns an offset from the beginning of the dword-aligned buffer that the driver uses.<br />

Internally using PCI bus-mastering, PCI <strong>CompuScope</strong> hardware can only transfer data from a d-word (4<br />

byte) boundary in <strong>CompuScope</strong> on-board memory. For instance, data can be downloaded starting from<br />

hexadecimal addresses 0x3000 or 3004, but not starting from hexadecimal addresses 0x3001.<br />

The returned offset gives the byte address location of the address ta, specified in the call to<br />

gage_transfer_buffer_3. For instance, if ta were equal to hex 0x3003, then the <strong>CompuScope</strong> would be<br />

forced to download data from hexadecimal addresses 0x3000. The offset would then be returned as<br />

0x3003 – 0x3000 = 3.<br />

See also: gage_transfer_buffer and Appendix: Comparison of Various Data Transfer Routines.<br />

Examples:<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

53


C:<br />

offset = gage_transfer_buffer_3(current_address, GAGE_CHAN_A, (uInt8 far *)(buffer), 512);<br />

new_ptr = (uInt8 *)(buffer+offset);<br />

first_value = new_ptr[0];<br />

Visual BASIC:<br />

gage_transfer_buffer_3 (ByVal ta As Long, ByVal channel As Integer, buffer As Integer, ByVal nsamples<br />

As Integer)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 54


gage_trigger_control_2<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_trigger_control_2 (int16 source_1, int16 source_2, int16 ext_coupling,<br />

int16 ext_gain, int16 slope_1, int16 slope_2, int16 level_1,<br />

int16 level_2, int32 depth, int16 trigger_from_bus, int16 trigger_to_bus);<br />

Visual BASIC:<br />

Function gage_trigger_control_2 (ByVal source_1 As Integer, ByVal source_2 As Integer,<br />

ByVal ext_coupling As Integer, ByVal ext_gain As Integer,<br />

ByVal slope_1 As Integer, ByVal slope_2 As Integer,<br />

ByVal level_1 As Integer, ByVal level_2 As Integer,<br />

ByVal depth As Long, ByVal trigger_from_bus As Integer,<br />

ByVal trigger_to_bus As Integer) As Integer<br />

Remarks<br />

gage_trigger_control_2 is used to set the trigger parameters and capture depth on <strong>CompuScope</strong> hardware.<br />

The routine accepts two sets of values for the three main trigger parameters, the trigger source, the trigger<br />

level and the trigger slope.<br />

Some <strong>CompuScope</strong> models, such as the CS14100, have two separate trigger circuits. The two sets of<br />

trigger parameters are used to control each of these trigger circuits. The outputs of each circuit are<br />

logically ORed together to specify the trigger event. The two trigger circuits may be used, for instance, to<br />

effect "absolute value triggering" on channel A. This is done by setting both source_1 and source_2 to<br />

GAGE_CHAN_A, setting level_1 and level_2 values that correspond to equal and opposite voltages and<br />

setting slope_1 and slope_2 to GAGE_POSITIVE and GAGE_NEGATIVE, respectively. In this way, the<br />

<strong>CompuScope</strong> will trigger whenever the voltage on the channel A input goes above level_1 or below<br />

level_2.<br />

In order to disable the second trigger circuit, simply set source_2 to GAGE_SOFTWARE. For<br />

<strong>CompuScope</strong>s that are not equipped with two trigger circuits, the "_2" parameters have no effect.<br />

source_1 and source_2 can be either channel A, B, external trigger or software trigger. The constants<br />

GAGE_CHAN_A, GAGE_CHAN_B, GAGE_EXTERNAL and GAGE_SOFTWARE should be used to<br />

specify their respective sources. The two sources do not have to be the same. To disable one of the<br />

triggers, set it to GAGE_SOFTWARE. If a software trigger is desired, then both trigger sources must be<br />

set to GAGE_SOFTWARE.<br />

ext_coupling controls the coupling of the EXTERNAL TRIGGER BNC input on the <strong>CompuScope</strong><br />

hardware. ext_coupling can be set to either DC or AC by using the constants GAGE_DC and GAGE_AC,<br />

respectively. If the trigger source is not external, this parameter will be ignored, although it should be set<br />

to a valid value.<br />

ext_gain controls the input sensitivity of the EXTERNAL TRIGGER BNC input on the <strong>CompuScope</strong><br />

hardware. ext_gain can be set to either ±5 Volt or ±1 Volt by using the constants GAGE_PM_5_V and<br />

GAGE_PM_1_V, respectively. If the trigger source is not external, this parameter will be ignored,<br />

although it should be set to a valid value.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

55


slope_1 and slope_2 are the trigger slopes and can be either positive or negative. The constants<br />

GAGE_POSITIVE and GAGE_NEGATIVE should be used.<br />

The level_1 and level_2 parameters can be any value between 0 and 255 for 8-bit <strong>CompuScope</strong>s. The<br />

values are scaled internally to match the trigger input range selected. The minimum input level is 0 while<br />

the maximum trigger level is 255. The trigger level voltage can be calculated from the equation:<br />

TRIGGER LEVEL VOLTAGE = [(level – 128)/128] * INPUT SENSITIVITY OF TRIGGER SOURCE<br />

For instance, suppose the trigger source was channel A and channel A was set to the ±200 milliVolt input<br />

range. If level_1 was set to 192, then the trigger level voltage is calculated as:<br />

TRIGGER LEVEL VOLTAGE = [(192– 128)/128] * 200 mV = 100 mV<br />

For <strong>CompuScope</strong>s with more than 8-bit resolution, the level_1 and level_2 parameters can be any value<br />

between 0 and 4096. The values are scaled internally to match the trigger input range selected. The<br />

minimum input level is 0 while the maximum trigger level is 4095. The trigger level voltage can be<br />

calculated from the equation:<br />

TRIGGER LEVEL VOLTAGE = [(level – 2048)/2048] * INPUT SENSITIVITY OF TRIGGER SOURCE<br />

For instance, suppose the trigger source was external trigger and ext_gain was set to GAGE_PM_5_V. If<br />

level_1 was set to -1024, then the trigger level voltage is calculated as:<br />

TRIGGER LEVEL VOLTAGE = [(1024– 2048)/2048] * 5V = -2.5V<br />

The depth parameter sets the trigger depth, which is the number of samples to be captured after the trigger<br />

event. The minimum value varies for different <strong>CompuScope</strong> models and operating modes. For instance,<br />

for the CS14100 in single record/single channel mode the minimum depth is 512 samples, while in<br />

multiple record/dual channel mode the minimum depth is 256. See your <strong>CompuScope</strong> hardware manual<br />

for the valid minimum settings.<br />

Increments to the capture depth cannot be 1. There is a minimum depth increment for each different<br />

<strong>CompuScope</strong> model and operating mode. For instance for the CS14100 in single record/single channel<br />

mode, the depth may be increased from the minimum of 512 points in increments of 256 points. See your<br />

<strong>CompuScope</strong> hardware manual for the valid increment settings.<br />

Several defined constants are available to the application programmer in order to set the depth. These are<br />

listed in gage_drv.h and in the <strong>CompuScope</strong> C/C++ <strong>SDK</strong> manual. For instance, the constant<br />

GAGE_POST_4K can be used to set the depth to 4096 points. Direct numeric values can also be used to<br />

specify the depth.<br />

If the specified depth parameter does not conform to the minimum and increment requirements of the<br />

<strong>CompuScope</strong> hardware, the driver will adjust the depth to an appropriate allowed value.<br />

The trigger_from_bus parameter should always be set to TRUE (non-zero). For normal operation in a<br />

Master/Slave Multi-Card <strong>CompuScope</strong> system, the trigger_to_bus parameter should be set to TRUE (nonzero)<br />

for the Master <strong>CompuScope</strong> and to FALSE (zero) for the Slave <strong>CompuScope</strong>(s). With these settings,<br />

the Master <strong>CompuScope</strong> will serve as the Master trigger source and will pass its trigger signal to all Slave<br />

<strong>CompuScope</strong>s. Some <strong>CompuScope</strong> models support triggering from Slave <strong>CompuScope</strong>s. For these<br />

models, the trigger_to_bus parameter may be set to 1 for the Slave <strong>CompuScope</strong>(s). With these settings,<br />

a trigger event on any Slave <strong>CompuScope</strong>, with its own trigger settings, will cause the whole Master/Slave<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 56


system to trigger. This is useful, for instance, in some nuclear particle detection experiments, where a<br />

particle pulse can occur on any channel of a multi-channel system.<br />

Please note that, whatever causes the trigger event in a Master/Slave <strong>CompuScope</strong> system, all<br />

<strong>CompuScope</strong>s in the Master/Slave system will always be triggered together.<br />

Return Value<br />

A one is returned if execution of the routine was successful. A zero is returned when the routine fails, and<br />

gage_get_error_code may be called to obtain the error code.<br />

See also<br />

gage_capture_mode, gage_input_control and see the Appendix: Data Structures Used by Gage Drivers in<br />

the <strong>CompuScope</strong> C/C++<strong>SDK</strong> <strong>Manua</strong>l.<br />

Examples:<br />

C:<br />

gage_trigger_control_2 (GAGE_CHAN_A, GAGE_EXTERNAL, GAGE_DC, GAGE_PM_1_V,<br />

GAGE_POSITIVE, GAGE_NEGATIVE, 160, 100, GAGE_POST_16K, TRUE,<br />

TRUE );<br />

Visual BASIC:<br />

dummy = gage_trigger_control_2 (GAGE_CHAN_A, GAGE_EXTERNAL, GAGE_DC,<br />

GAGE_PM_1_V, GAGE_POSITIVE, GAGE_NEGATIVE, 160, 100,<br />

GAGE_POST_16K, TRUE, TRUE )<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

57


gage_triggered<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_triggered (void);<br />

Visual BASIC:<br />

Function gage_triggered () As Integer<br />

Remarks<br />

gage_triggered determines if a trigger event has occurred on the <strong>CompuScope</strong> hardware<br />

Return Value<br />

A non-zero or true value is returned if the <strong>CompuScope</strong> hardware has been triggered, otherwise a false<br />

value is returned.<br />

See also<br />

gage_busy<br />

Examples<br />

C:<br />

triggered = gage_triggered ();<br />

Visual BASIC:<br />

triggered = gage_triggered<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 58


Legacy <strong>CompuScope</strong><br />

API Subroutines -<br />

Detailed Description<br />

The section describes the Legacy <strong>CompuScope</strong> API Subroutines. These routines are supported but are not<br />

frequently used for application programs. Generally, the functionality of the Legacy routines is available<br />

with a Recommended routine and the Legacy routines are maintained only in order to provide<br />

compatibility with older customer software applications. The Legacy routines are generally not used<br />

within Gage <strong>SDK</strong>s or stand-alone software and are, therefore, not regularly tested. Furthermore, the<br />

documentation of the Legacy routines has not been updated and includes references to currently<br />

unavailable <strong>CompuScope</strong>s models. It is strongly advised that only the Recommended routines be used in<br />

new software designs. Please read the readme text files contained in the <strong>CompuScope</strong> driver disk(s) for<br />

information relating to any changes in the API routines.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

59


gage_acquire_average<br />

Syntax<br />

C:<br />

int32 GAGEAPI gage_acquire_average (int16 channel, int32 nsamples, int32 naverages, int16 sum,<br />

int32 far *avg_buffer, void far *data_buffer,<br />

int32 data_buffer_size, int32 timeout);<br />

Visual BASIC:<br />

Function gage_acquire_average (ByVal channel As Integer, ByVal nsamples As Long,<br />

ByVal naverages As Long, ByVal sum As Integer,<br />

avg_buffer As Long, data_buffer As Any,<br />

data_buffer_size As Long, timeout As Long) As Long<br />

Remarks<br />

gage_acquire_capture finds the average of a number of acquisitions. This routine does the entire capture<br />

and transfer of data internally and does not return until either all captures are completed or an error has<br />

occurred.<br />

channel is the channel where the acquisitions will take place. It has a value of 1 for Board 1 Channel A, 2<br />

for Board 1 Channel B, 3 for Board 2 Channel A, 4 for Board 2 Channel B, etc.<br />

nsamples is the number of points to be sampled for each acquisition.<br />

naverages is the number of traces to sum. The routine will not complete until this number has been<br />

captured by the digitizer.<br />

sum is a flag that is set to one to skip the division by naverages. This will allow an application to make use<br />

of the unaveraged data to increase dynamic range. Normally the average is performed.<br />

*avg_buffer is a pointer to a buffer containing either the sum of all the data traces or the averaged data,<br />

depending on the value of the sum flag. The size of this buffer must be at least nsamples*sizeof(int32).<br />

The buffer must allocated by the calling program.<br />

*data_buffer is a pointer to a buffer for use by this routine to store data points returned from the digitizer<br />

before they are summed into data_buffer. This buffer must be at least as large as (data_buffer_size) and<br />

sized to the sample size of the <strong>CompuScope</strong> card being used (data_buffer_size * 1 byte for the 8-bit<br />

<strong>CompuScope</strong> cards and data_buffer_size * 2 bytes per sample for the 12/16-bit <strong>CompuScope</strong> cards). This<br />

buffer must be allocated by the calling program. This buffer is not used by the calling program, but is only<br />

a scratch space for this routine.<br />

data_buffer_size is the size of the buffer (data_buffer).<br />

timeout is the amount of time the software should wait for the hardware to respond to a trigger event. The<br />

resolution of the timeout is in hundreds of microseconds. A minus one (all bits set) will cause the software<br />

to wait indefinitely for the trigger event to occur (therefore, if no trigger ever occurs then the software will<br />

appear to hang since it is waiting for an event to happen that never will).<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 60


Return Value<br />

1 if no error and a negative number if an error occurs.<br />

The following is a list of return codes including possible errors.<br />

Constant in GAGE_DRV.H<br />

Value, description<br />

============================================================================<br />

GAGE_AA_SUCCESSFUL<br />

1L The routine completed correctly and the average<br />

buffer, "avg_buffer", contains the averaged of<br />

summed data.<br />

GAGE_AA_ROUTINE_UNAVAILABLE<br />

GAGE_AA_INVALID_TRIGGER_SOURCE<br />

GAGE_AA_INVALID_TRIGGER_DEPTH<br />

GAGE_AA_INVALID_BUFFER_SIZES<br />

GAGE_AA_INVALID_CHANNEL<br />

GAGE_AA_UNAVAILABLE_CHANNEL<br />

GAGE_AA_INVALID_AVERAGE_NUM<br />

0L The routine is not implemented and the task<br />

could not be performed. This is temporary return<br />

value until all cards have had this routine<br />

implemented.<br />

-1L This routine will not function with a software<br />

controlled trigger. Only a valid hardware trigger<br />

source is allowed. This can be channel A, channel B<br />

or the external trigger input.<br />

-2L Board returned a different number of points than<br />

requested, the acquisition depth is less than the<br />

requested average number of samples.<br />

-3L The "data_buffer_size" parameter is not at least<br />

as large as the number of samples required for each<br />

average.<br />

-4L The channel specified does not currently exist.<br />

Example: channel 3 (board 2 channel A) was<br />

specified and the current <strong>CompuScope</strong> installed<br />

system has only one board.<br />

-5L The channel specified is not currently available<br />

or enabled, therefore it does not have any valid data<br />

to be averaged. Example: channel 2 (board 1 channel<br />

B)was specified and the current acquisition mode is<br />

single channel mode.<br />

-6L This value is returned when the number of<br />

averages (naverages) is greater than the maximum<br />

32-bit integer (0x7fffffff hex or 2,147,483,647<br />

decimal) divided by the size of the sample resolution<br />

(256 for 8-bit cards and 4096 for 12-bit cards). This<br />

is calculated by using 0x7fffffff and shifting it to the<br />

right by the number of bits of sample resolution<br />

(8 or 12).<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

61


GAGE_AA_INVALID_SAMPLE_NUM<br />

GAGE_AA_TRIGGER_TIMEOUT<br />

GAGE_AA_BUSY_TIMEOUT<br />

-7L This value is returned when the number of<br />

samples (nsamples) is greater than the maximum<br />

transfer allowed using the implemented transfer<br />

method. Currently this is 4K/8K samples for all<br />

boards except the CS2125, which is 8K/16K samples<br />

for dual/single mode acquisition, respectively. This<br />

will be increased to 64K for 16-bit environments and<br />

4G for 32-bit environments when the arbitrary length<br />

transfer_buffer routines are implemented on all<br />

boards.<br />

-8L Board was not triggered within the board's<br />

time-out time period.<br />

-9L Board did not become non-busy within the<br />

board's time-out period.<br />

If an error occurs, the routine aborts immediately and returns to the calling program.<br />

See also<br />

gage_peak_detect().<br />

Examples<br />

C:<br />

result = gage_acquire_average (channel, nsamples, naverages, sum, avg_buffer, data_buffer,<br />

nsamples, timeout);<br />

Visual BASIC:<br />

result = gage_acquire_average (channel, nsamples, naverages, sum, avg_buffer(0), data_buffer(0),<br />

nsamples, timeout)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 62


gage_detect_multiple_record<br />

Syntax:<br />

C:<br />

int16 GAGEAPI gage_detect_multiple_record (void);<br />

Visual BASIC:<br />

function gage_detect_multiple_record () As Integer<br />

Remarks<br />

gage_detect_multiple_record is used to determine if a <strong>CompuScope</strong> board has Multiple Record<br />

capability. Multiple record capability is standard only on some <strong>CompuScope</strong> boards. This feature is<br />

available on all the CSx012, CSx012/PCI boards, CS8500, CS12100, CS1250, CS2125 and CS265, and it<br />

is optional on CS250 and CS220 boards.<br />

Return Value<br />

A TRUE (non-zero) value is returned if the <strong>CompuScope</strong> hardware has Multiple Record capability and a<br />

FALSE (zero) otherwise.<br />

See also<br />

gage_multiple_record and Appendix I: Multiple Record Mode Operation.<br />

Examples<br />

C:<br />

mr_available = gage_detect_multiple_record;<br />

Visual BASIC:<br />

mr_available = gage_detect_multiple_record<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

63


gage_get_boards_found<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_get_boards_found(void);<br />

Visual BASIC:<br />

Function gage_get_boards_found () As Integer<br />

Remarks<br />

gage_get_boards_found determines and returns the number of <strong>CompuScope</strong> boards that were detected<br />

when the last call to the gage_driver_initialize routine was made.<br />

Return Value<br />

The number of <strong>CompuScope</strong> boards currently installed by the driver.<br />

See also<br />

gage_driver_initialize<br />

Examples<br />

C:<br />

boards_found = gage_get_boards_found ();<br />

Visual BASIC:<br />

boards_found = gage_get_boards_found<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 64


gage_get_data<br />

Syntax<br />

C:<br />

void GAGEAPI gage_get_data (void);<br />

Visual BASIC:<br />

Sub gage_get_data ()<br />

Remarks<br />

gage_get_data sets the <strong>CompuScope</strong> board in its capture mode. After this call the <strong>CompuScope</strong> is<br />

digitizing the input data and placing the values into the on-board memory while waiting for a trigger event.<br />

Once the trigger event has occurred, the <strong>CompuScope</strong> will capture a number of samples specified by the<br />

depth parameter passed to gage_trigger_control before terminating. Instead of gage_get_data, the<br />

gage_start_capture routine should normally be used in order o fully support all possible <strong>CompuScope</strong><br />

hardware configurations, especially when using multiple <strong>CompuScope</strong>s.<br />

gage_get_data may be used in some cases, after a call to gage_init_clock, in order to speed up the rearming<br />

of the <strong>CompuScope</strong> hardware. Note that using this method does not allow the amount of pretrigger<br />

data to be ensured. Pre-trigger data will only be captured until an event fulfilling the trigger<br />

conditions occurs. Ensuring a specific number of pre-trigger data points can only be done by setting this<br />

number of points using the gage_delay_trigger_32 routine and then calling gage_start_capture. Using<br />

this method, gage_start_capture will ignore triggers until the specified amount of pre-trigger data has been<br />

acquired.<br />

Return Value<br />

None.<br />

See also<br />

gage_abort , gage_trigger_control and gage_init_clock<br />

Examples<br />

C:<br />

gage_get_data ();<br />

Visual BASIC:<br />

gage_get_data<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

65


gage_get_records<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_get_records (uInt16 far *records, int16 record, uInt16 far *segment,<br />

uInt16 far *index, uInt16 far *typename, uInt16 far *status);<br />

Visual BASIC:<br />

Function gage_get_records (records As Integer, ByVal record As Integer, segment As Integer,<br />

index As Integer, typename As Integer, status As Integer) As Integer<br />

Remarks<br />

gage_get_records can be used to read the gage_board_location array. The array must be allocated by the<br />

calling program. The array is initialized by using a call to either gage_set_records or<br />

gage_read_config_file.<br />

The record parameter is the board number of the record to be read, beginning with 0.<br />

The segment, index, typename and status parameters are the values in the gage_board_location array for<br />

that particular board.<br />

segment and index are the values that were set by the GSINST.EXE or GAGECFG.EXE configuration<br />

program.<br />

The typename and status parameters return the board type and the initialization status of the board as one<br />

of the predefined constants (GAGE_ASSUME_XXXXX, where XXXXX is a board type, etc.) declared in<br />

the file GAGE_DRV.H.<br />

The status parameter will hold any errors that occurred during board initialization.<br />

Return Value<br />

The return value is one if the record parameter is in the range (0 to GAGE_B_L_MAX_CARDS - 1) and<br />

zero otherwise. If the return value is one, the segment, index, typename and status parameters will<br />

contain valid values for the specified record.<br />

See also<br />

gage_set_records, gage_driver_initialize and gage_read_config_file<br />

Examples<br />

C:<br />

gage_get_records ((uInt16 far *)gage_board_location), 0, (uInt16 far *)(&segment),<br />

(uInt16 far *)(&index), (uInt16 far *)(&typename), (uInt16 far *)(status));<br />

Note: the typecasts may not be necessary, depending on the memory model used.<br />

Visual BASIC:<br />

ret = gage_get_records (gage_board_location (0), 0, segment, index, typename, status)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 66


gage_get_status<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_get_status (void);<br />

Visual BASIC:<br />

Function gage_get_status () As Integer<br />

Remarks<br />

This routine is used to read back various control signals generated by the currently selected <strong>CompuScope</strong><br />

board. The routine thus provides the application writer feedback about the current board’s operational<br />

state. It is recommended that the gage_triggered and gage_busy routines be used instead, since they<br />

provide a more consistent interface for all hardware.<br />

Return Value<br />

Returns the Status register. Please see your hardware manual, if applicable, for information on the status<br />

register. It will be different for different <strong>CompuScope</strong> boards.<br />

See also<br />

gage_busy, gage_triggered and gage_read_master_status<br />

Examples<br />

C:<br />

status = gage_get_status();<br />

Visual BASIC:<br />

ret = gage_get_status<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

67


gage_get_trigger_address<br />

Syntax<br />

C:<br />

int32 GAGEAPI gage_get_trigger_address (void);<br />

Visual BASIC:<br />

Function gage_get_trigger_address () As Long<br />

Remarks<br />

This routine gets the trigger address in the <strong>CompuScope</strong> board. Once a trigger event is detected, the<br />

address into which the data was being written is tagged as the trigger address. It is recommended that the<br />

gaeg_calculate_addresses routines routine now be used for this propose.<br />

Return Value<br />

Returns the trigger address.<br />

See also<br />

gage_calculate_addresses and gage_trigger_address<br />

Examples<br />

C:<br />

address = gage_get_trigger_address();<br />

Visual BASIC:<br />

address = gage_get_trigger_address<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 68


gage_get_trigger_view_offset<br />

Syntax<br />

C:<br />

void GAGEAPI gage_get_trigger_view_offset (int32 far *offset);<br />

Visual BASIC:<br />

Sub get_trigger_view_offset (offset As Long)<br />

Remarks<br />

gage_get_trigger_view_offset can be used to get the current trigger view offset when using the routines<br />

gage_trigger_view_transfer, gage_trigger_view_transfer_2 and gage_trigger_view_transfer_3.<br />

The default value of the offset parameter is 0, which means that capture will start at the trigger address.<br />

This value can be changed to transfer pre-trigger data, for example by using the routine<br />

gage_set_trigger_view_offset.<br />

Return Value<br />

None.<br />

See also<br />

gage_set_trigger_view_offset<br />

Examples<br />

C:<br />

gage_get_trigger_view_offset ((int32 far *)offset);<br />

Note: the typecast is unnecessary if the application program is large model<br />

Visual BASIC:<br />

Call gage_get_trigger_view_offset (offset)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

69


gage_gpib_command<br />

Syntax<br />

C:<br />

int32 GAGEAPI gage_gpib_command (char* strCommand, int nByteSize, char* rvBuffer, int<br />

nBufferSize);<br />

Remarks<br />

gage_gpib_command allows the application program to access functionality built into the on-board<br />

digitization module, that is not available through the standard Gage API, FOR THE COMPUSCOPE 85G<br />

OR 85GC ONLY. For instance, gage_gpib_command is used to implement TV triggering on the CS85GC.<br />

strCommand is a string, initialized by the user, that contains the command to be sent to the CS85G or<br />

85GC digitization module.<br />

nByteSize is the length, initialized by the user, of the string that contains the command to be sent (the<br />

strCommand argument above).<br />

rvBuffer is a string that may be returned by the CS85G or 85GC digitization module, upon execution of<br />

the latest command. This string is often empty.<br />

nBufferSize is the length of the string that may be returned by the CS85G or 85GC digitization module<br />

(the rvBuffer argument above).<br />

Return Value<br />

The return value is a signed 32 bit integer. A return value of 0 indicates that the gage_gpib_command<br />

routine has been implemented properly. Any other value signifies an error while implementing the routine.<br />

Examples<br />

C:<br />

gage_gpib_command (strCmd, strlen(strCmd), strQueryInf, sizeof(strQueryInf));<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 70


gage_init_clock<br />

Syntax<br />

C:<br />

void GAGEAPI gage_init_clock (void);<br />

Visual BASIC:<br />

Sub init_clock ()<br />

Remarks<br />

gage_init_clock is used to initialize the <strong>CompuScope</strong> clock circuitry. This routine should be called before<br />

initiating data capture with gage_get_data. It is recommended that the gage_start_capture routine, which<br />

calls gage_init_clock internally, be used instead.<br />

gage_init_clock can be used, in some cases, in conjunction with gage_get_data in order to speed up the<br />

re-arming of the <strong>CompuScope</strong> hardware. Note that using this method does not allow the amount of pretrigger<br />

data to be ensured. Pre-trigger data will only be captured until an event fulfilling the trigger<br />

conditions occurs. Ensuring a specific number of pre-trigger data points can only be done by setting this<br />

number of points using the gage_delay_trigger_32 routine and then calling gage_start_capture. Using<br />

this method, gage_start_capture will ignore triggers until the specified amount of pre-trigger data has been<br />

acquired.<br />

Return Value<br />

None.<br />

See also<br />

gage_get_data and gage_start_capture<br />

Examples<br />

C:<br />

gage_init_clock ();<br />

Visual BASIC:<br />

Call gage_init_clock ()<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

71


gage_mem_read_chan_a<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_mem_read_chan_a (int32 location);<br />

Visual BASIC:<br />

Function gage_mem_read_chan_a (ByVal location As Long) As Integer<br />

Remarks<br />

gage_mem_read_chan_a reads one sample out of the <strong>CompuScope</strong> memory for channel A in dual<br />

channel mode and returns it as an integer. It is usually used in a loop to retrieve data from a range of<br />

addresses from a <strong>CompuScope</strong> board.<br />

location is an address in the <strong>CompuScope</strong> memory and usually starts at the trigger address. It can precede<br />

and/or follow the trigger address as set by the current trigger depth.<br />

The gage_calculate_addresses routine is very useful for determining the valid addresses and should be<br />

used instead of directly invoking the gage_trigger_address routine for future compatibility with the<br />

<strong>CompuScope</strong> drivers.<br />

When using the gage_mem_read_chan_a routine, access to the <strong>CompuScope</strong> memory must be obtained<br />

by calling gage_need_ram(1) beforehand, and released by calling gage_need_ram(0) when finished.<br />

Return Value<br />

The byte (or integer) corresponding to the specified location for channel A is returned as an unsigned<br />

integer (0 - 255) for 8 bit <strong>CompuScope</strong>s, a signed 12 bit integer (-2048 - 2047) for the 12 bit <strong>CompuScope</strong>s<br />

and a signed 16 bit integer (-32768 to 32767) for the 16 bit <strong>CompuScope</strong>s.<br />

See also<br />

gage_mem_read_chan_b, gage_mem_read_dual, gage_mem_read_single, gage_need_ram,<br />

gage_calculate_addresses and Appendix: Comparison of Various Data Transfer Routines.<br />

Examples<br />

C:<br />

data = gage_mem_read_chan_a (address);<br />

Visual BASIC:<br />

data = gage_mem_read_chan_a (address)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 72


gage_mem_read_chan_b<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_mem_read_chan_b (int32 location);<br />

Visual BASIC:<br />

Function gage_mem_read_chan_b (ByVal location As Long) As Integer<br />

Remarks<br />

gage_mem_read_chan_b reads one sample out of the <strong>CompuScope</strong> memory for channel B in dual<br />

channel mode and returns it as an integer. It is usually used in a loop to retrieve data from a range of<br />

addresses from a <strong>CompuScope</strong> board.<br />

location is an address in the <strong>CompuScope</strong> memory and usually starts at the trigger address. It can precede<br />

and/or follow the trigger address as set by the current trigger depth.<br />

The gage_calculate_addresses routine is very useful for determining the valid addresses and should be<br />

used instead of directly invoking the gage_trigger_address routine for future compatibility with the<br />

<strong>CompuScope</strong> drivers.<br />

When using gage_mem_read_chan_a, access to the <strong>CompuScope</strong> memory must be obtained by calling<br />

gage_need_ram(1) beforehand, and released by calling gage_need_ram(0) when finished.<br />

Return Value<br />

The byte (or integer) corresponding to the specified location for channel B is returned as an unsigned<br />

integer (0 - 255) for 8 bit <strong>CompuScope</strong>s, as a signed 12 bit integer (-2048 - 2047) for the 12 bit<br />

<strong>CompuScope</strong>s and a signed 16 bit integer (-32768 to 32767) for the 16 bit <strong>CompuScope</strong>s.<br />

See also<br />

gage_mem_read_chan_a, gage_mem_read_dual, gage_mem_read_single, gage_calculate_addresses and<br />

Appendix : Comparison of Various Data Transfer Routines.<br />

Examples<br />

C:<br />

data = gage_mem_read_chan_b (address);<br />

Visual BASIC:<br />

data = gage_mem_read_chan_b (address)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

73


gage_mem_read_dual<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_mem_read_dual (int16 channel, int32 location);<br />

Visual BASIC:<br />

Function gage_mem_read_dual (ByVal channel As Integer, ByVal location As Long) As Integer<br />

Remarks<br />

gage_mem_read_dual reads one sample out of <strong>CompuScope</strong> memory in dual channel mode and returns it<br />

as an integer. It is usually used in a loop to retrieve data from a range of addresses from a <strong>CompuScope</strong><br />

board.<br />

channel can be one of the constants GAGE_CHAN_A or GAGE_CHAN_B.<br />

location is an address in the <strong>CompuScope</strong> memory and usually starts at the trigger address. It can precede<br />

and/or follow the trigger address as set by the current trigger depth.<br />

The gage_calculate_addresses routine is very useful for determining the valid addresses and should be<br />

used instead of directly invoking the gage_trigger_address routine for future compatibility with the<br />

<strong>CompuScope</strong> drivers.<br />

When using gage_mem_read_dual, access to the <strong>CompuScope</strong> memory must be obtained by calling<br />

gage_need_ram(1) beforehand, and released by calling gage_need_ram(0) when finished.<br />

Return Value<br />

The byte (or integer) corresponding to the specified location for channel A or channel B is returned as an<br />

unsigned integer (0 - 255) for 8 bit <strong>CompuScope</strong>s, as a signed 12 bit integer (-2048 - 2047) for the 12 bit<br />

<strong>CompuScope</strong>s and a signed 16 bit integer (-32768 to 32767) for the 16 bit <strong>CompuScope</strong>s.<br />

See also<br />

gage_mem_read_single, gage_mem_read_chan_a, gage_mem_read_chan_b, gage_calculate_addresses and<br />

Appendix: Comparison of Various Data Transfer Routines.<br />

Examples<br />

C:<br />

data = gage_mem_read_dual (GAGE_CHAN_A, address);<br />

Visual BASIC:<br />

data = gage_mem_read_dual (GAGE_CHAN_A, address)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 74


gage_mem_read_single<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_mem_read_single (int32 location);<br />

Visual BASIC:<br />

Function gage_mem_read_single (ByVal location As Long) As Integer<br />

Remarks<br />

gage_mem_read_single reads one byte out of <strong>CompuScope</strong> memory in single channel mode and returns it<br />

as an integer. It is usually used in loop to retrieve data from a range of addresses from a <strong>CompuScope</strong><br />

board.<br />

location is an address in the <strong>CompuScope</strong> memory and usually starts at the trigger address. It can precede<br />

and/or follow the trigger address as set by the current trigger depth.<br />

The gage_calculate_addresses routine is very useful for determining the valid addresses and should be<br />

used instead of directly invoking the gage_trigger_address routine for future compatibility with the<br />

<strong>CompuScope</strong> drivers.<br />

When using gage_mem_read_single, access to the <strong>CompuScope</strong> memory must be obtained by calling<br />

gage_need_ram(1) beforehand, and released by calling gage_need_ram(0) when finished.<br />

Return Value<br />

The byte (or integer) corresponding to the specified location for channel A returned as an unsigned integer<br />

(0 - 255) for 8 bit <strong>CompuScope</strong>s, as a signed 12 bit integer (-2048 - 2047) for the 12 bit <strong>CompuScope</strong>s and<br />

a signed 16 bit integer (-32768 to 32767) for the 16 bit <strong>CompuScope</strong>s.<br />

See also<br />

gage_mem_read_dual, gage_mem_read_chan_a, gage_mem_read_chan_b, gage_calculate_addresses and<br />

Appendix: Comparison of Various Data Transfer Routines.<br />

Examples<br />

C:<br />

data = gage_mem_read_single (address);<br />

Visual BASIC:<br />

data = gage_mem_read_single (address)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

75


gage_multiple_record_acquisitions<br />

Syntax<br />

C:<br />

void GAGEAPI gage_multiple_record_acquisitions (uInt16 number);<br />

Visual BASIC:<br />

Sub gage_multiple_record_acquisitions (ByVal number As Integer)<br />

Remarks:<br />

gage_multiple_record_acquisitions sets the number of Multiple Record groups that will be acquired by<br />

the <strong>CompuScope</strong> hardware. This routine is only available for the CP500-class boards.<br />

number is the number of Multiple Record groups.<br />

This routine should be called immediately after calling the gage_multiple_record routine.<br />

Return Value<br />

None.<br />

See also<br />

gage_multiple_record and Appendix I: Multiple Record Mode Operation.<br />

Examples<br />

C:<br />

gage_multiple_record_acquisition (10);<br />

Visual BASIC:<br />

Call gage_multiple_record_acquisitions (10)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 76


gage_offset_adjust<br />

Syntax<br />

C:<br />

void GAGEAPI gage_offset_adjust (int16 channel, int16 offset_adjust);<br />

Remarks<br />

gage_offset_adjust is used to adjust the input DC offset on <strong>CompuScope</strong> models for which this<br />

functionality is available.<br />

The channel parameter can be either GAGE_CHAN_A or GAGE_CHAN_B.<br />

For <strong>CompuScope</strong>s with more than 8 bit resolution, the offset_adjust parameter will cause the DC offset<br />

value to change by the specified amount. So, if the gage_offset_adjust is called repeatedly with the same<br />

value of offset_adjust, then the input DC offset will change by the same amount upon each call.<br />

For all available <strong>CompuScope</strong> boards with DC offset adjust capability except the CS8500, the<br />

offset_adjust can be any integer between -2047 and +2047. The -2047 setting will provide the largest<br />

possible negative DC offset available for the current <strong>CompuScope</strong> input range. Similarly, the +2047 setting<br />

will provide the largest possible positive DC offset available for the current <strong>CompuScope</strong> input range. If<br />

the value of offset_adjust is set to 0, the routine performs an automatic calibration of the <strong>CompuScope</strong><br />

board, if the autocalibration capability is available. In this case, the inputs of the <strong>CompuScope</strong> board must<br />

be connected to the ground of the circuit under test.<br />

Note that the gage_offset_adjust routine should be called whenever the input range or operation mode<br />

(SINGLE or DUAL) are changed. Also, some <strong>CompuScope</strong> models require that gage_offset_adjust be<br />

called after changing the sampling rate.<br />

For the <strong>CompuScope</strong> 8500, the offset_adjust parameter specifies an absolute, rather than a relative, DC<br />

offset. The offset_adjust parameter is passed as a percentage between -100% and +100% of the full-scale<br />

input range. Values greater than or equal to +100 will change the offset by 100% and values less than or<br />

equal to -100 will change the offset by -100%. Any values exceeding +/- 100 will have no further effect on<br />

the signal offset or position. Therefore, a value of 100 will yield a 100 percent offset and a value of -100<br />

will yield a -100 percent offset and 0 will be zero. For example, calling this routine twice with an offset of<br />

10% will leave the offset at 10%.<br />

Note that, unlike for the higher resolution <strong>CompuScope</strong> models, the offset set by gage_offset_adjust<br />

remains in effect on the CS8500 when the input range is changed by calling the gage_input_control<br />

routine.<br />

Return Value: None.<br />

Example: C:<br />

gage_offset_adjust (GAGE_CHAN_A, offset_adjust);<br />

Visual BASIC: This routine is currently not supported under Visual BASIC.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

77


gage_read_cal_table<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_read_cal_table (LPSTR caltable_name);<br />

Visual BASIC:<br />

Sub gage_read_cal_table (ByVal caltable_name As String) As Integer<br />

Remarks<br />

This routine reads a calibration file that can be used to prevent 12 bit <strong>CompuScope</strong> boards from<br />

autocalibrating every time the gain or mode is changed with the gage_input_control or<br />

gage_capture_mode routines.<br />

caltable_name is the name of the file or the file name with full path. By default, the name of the file is<br />

CALTABLE.DAC. It can be created with TESTCALB.EXE, which is included on the <strong>SDK</strong> distribution<br />

disk. The file can also be created with GageScope ® for DOS, GagePCI and GageP500 (go to the Capture<br />

menu and to the Calib table item). Just follow the prompts to create the file. If the file is not found in the<br />

same directory as the executable, the driver will force the board to autocalibrate when gain is changed.<br />

This routine should be called after gage_driver_initialize and before calling gage_capture_mode.<br />

This method can eliminate the delays that can occur during the autocalibration of some <strong>CompuScope</strong><br />

boards. The calibration is system-dependent. A calibration table made on one computer may not be<br />

accurate on another computer, even if the same <strong>CompuScope</strong> board is used.<br />

Note: The CSx012/PCI <strong>SDK</strong> for Win NT will automatically detect the CALTABLE.DAC file and use it, if<br />

it is found in the WINNT\SYSTEM32\DRIVERS directory. Therefore, there is no reason to use this<br />

routine with the CSx012/PCI <strong>SDK</strong> for Win NT.<br />

Return Value<br />

Returns a 1 if successful, a 0 otherwise.<br />

See also<br />

gage_use_cal_table<br />

Examples<br />

C:<br />

ret = gage_read_cal_table (“caltable.dac”);<br />

Visual BASIC:<br />

ret = gage_read_cal_table (“caltable.dac”)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 78


gage_read_master_status<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_read_master_status (void);<br />

Visual BASIC:<br />

Function gage_read_master_status () As Integer<br />

Remarks<br />

gage_read_master_status reads the status bits from the Master card, regardless of how many<br />

<strong>CompuScope</strong> boards are in the system.<br />

Return Value<br />

The integer returned equals the status bits from the Master board status register. This value is currently an<br />

integer from 0 to 7, with bit 0 representing the busy bit, bit 1 representing the ram full bit and bit 2<br />

representing the trigger bit. These bit patterns may or may not match the hardware status register pattern.<br />

See also<br />

gage_busy and gage_triggered<br />

Examples<br />

C:<br />

status = gage_read_master_status ();<br />

Visual BASIC:<br />

status = gage_read_master_status<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

79


gage_set_delay_trigger<br />

Syntax<br />

C:<br />

uInt16 GAGEAPI gage_set_delay_trigger (int16 action, uInt16 delay_trigger);<br />

Visual BASIC:<br />

Function gage_set_delay_trigger (ByVal action As Integer, ByVal delay_trigger As Integer) As Integer<br />

Remarks<br />

gage_set_delay_trigger ignores the trigger for the amount of time specified.<br />

The action parameter, if equal to 1, ignores the trigger for the specified delay trigger.<br />

delay_trigger is in 1/10 ms = 100 us.<br />

If action is 0 then the routine returns only the current value of the delay. The default delay is 0.<br />

Return Value<br />

Returns the current value of the trigger delay.<br />

See also<br />

None<br />

Examples<br />

C:<br />

trig_delay = gage_set_delay_trigger (1, 100);<br />

Visual BASIC:<br />

trig_delay = gage_set_delay_trigger (1, 100)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 80


gage_set_records<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_set_records (uInt16 far *records, int16 record, uInt16 segment, uInt16 index,<br />

uInt16 typename, uInt16 status);<br />

Visual BASIC:<br />

Function gage_set_records (records As Integer, ByVal record As Integer, ByVal segment As Integer,<br />

ByVal index As Integer, ByVal typename As Integer, ByVal status As Integer)<br />

As Integer<br />

Remarks<br />

gage_set_records is used to initialize the gage_board_location array when the configuration file<br />

(GAGESCOP.INC) is either not found or not used. Using this routine is preferred because the format of<br />

the gage_board_location file is subject to change. The array gage_board_location should be allocated by<br />

the calling program and should be large enough (64 words) to hold the initialization for<br />

GAGE_B_L_MAX_CARDS boards.<br />

The record parameter is the number of the board to be initialized.<br />

The segment, index, typename and status parameters are the desired values for that particular board.<br />

segment and index are the values that are used by the GSINST.EXE, PCIINST.EXE, P500INST.EXE and<br />

GAGECFG.EXE configuration programs.<br />

The typename and status should be zero in a call to gage_set_records.<br />

Return Value<br />

The return value is one if the record parameter is in the range (0 to GAGE_B_L_MAX_CARDS - 1) and<br />

zero otherwise.<br />

See also<br />

gage_driver_initialize and gage_get_records<br />

Examples<br />

C:<br />

gage_set_records ((uInt16 far *)gage_board_location, 0, seg, ind, , 0, 0);<br />

Visual BASIC:<br />

dummy = gage_set_records (gage_board_location (0), 0, seg, ind, , 0, 0)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

81


gage_set_trigger_depth<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_set_trigger_depth (int32 depth);<br />

Visual BASIC:<br />

This routine is currently not supported under Visual BASIC.<br />

Remarks<br />

gage_set_trigger_depth is used to set up one of the trigger parameters for the <strong>CompuScope</strong> board.<br />

The depth parameter sets the trigger depth, that is the number of samples captured after the trigger event.<br />

The resolution of this parameter is 64 samples in dual channel mode and 128 samples in single channel<br />

mode for the <strong>CompuScope</strong> boards, except 16 samples for the <strong>CompuScope</strong> LITE and a power of two for<br />

the <strong>CompuScope</strong> 220. The trigger resolution in Multiple Record mode is twice that of non-Multiple<br />

Record mode.<br />

Setting the trigger depth can help reduce the capturing overhead when only a screen’s worth of data is<br />

required. Several defined constants are available to the application programmer to illustrate the use of this<br />

parameter. The constants GAGE_POST_0K, GAGE_POST_1K, GAGE_POST_2K, GAGE_POST_4K,<br />

GAGE_POST_8K, GAGE_POST_16K, GAGE_POST_32K, GAGE_POST_64K, GAGE_POST_128K,<br />

GAGE_POST_256K, GAGE_POST_512K, GAGE_POST_1M, GAGE_POST_2M, GAGE_POST_4M<br />

and GAGE_POST_8M are for the trigger depths of 0, 1024, 2048, 4096, 8192, 16384, 32768, 65536,<br />

131072, 262144, 524288, 1048576, 2097152, 4194304 and 8388608 bytes, respectively. Other values can<br />

be used. If the trigger depth is not a multiple of the trigger resolution, it is rounded up to the nearest<br />

multiple.<br />

It is recommended that the gage_trigger_control or gage_trigger_control_2 routines be used instead so<br />

as to maintain compatibility with future versions of the drivers.<br />

Return Value<br />

A one is returned if successful and a zero is returned when the routine fails, and gage_error_code contains<br />

the error code.<br />

See also<br />

gage_trigger_control<br />

Examples<br />

C:<br />

gage_set_trigger_depth (512);<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 82


gage_set_trigger_view_offset<br />

Syntax<br />

C:<br />

void GAGEAPI gage_set_trigger_view_offset (int32 offset);<br />

Visual BASIC:<br />

Sub gage_set_trigger_view_offset (ByVal offset As Long)<br />

Remarks<br />

The gage_set_trigger_view_offset routine allows the application program to change where data transfer<br />

begins when using gage_trigger_view_transfer, gage_trigger_view_transfer_2 or<br />

gage_trigger_view_transfer_3 by offsetting the trigger address. Once the offset has changed, it keeps its<br />

new value until the program is restarted or it is changed again.<br />

The default value for the offset is 0, which denotes the trigger address. A negative offset can be used to<br />

capture pre-trigger data. A positive offset can be used to start transfer from after the trigger address.<br />

Care should be taken when using a negative number so that you don’t get data from before the start<br />

address. The valid start, trigger and ending addresses can be obtained from a call to<br />

gage_calculate_addresses.<br />

Return Value<br />

None.<br />

See also<br />

gage_get_trigger_view_offset and gage_calculate_addresses<br />

Examples<br />

C:<br />

gage_set_trigger_view_offset (offset);<br />

Visual BASIC:<br />

Call gage_set_trigger_view_offset (offset)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

83


gage_support_to_text<br />

Syntax<br />

C:<br />

LPSTR GAGEAPI gage_support_to_text (LPSTR string, uInt32 string_size, uInt32 board_support);<br />

Remarks<br />

The gage_support_to_text routine is used to get the names of the <strong>CompuScope</strong> boards supported by the<br />

current version of the installed drivers.<br />

The parameter string is a pointer to the string.<br />

string_size is the size of the string pointed to by string.<br />

board_support returns the <strong>CompuScope</strong> boards that are supported by the driver. This will be a<br />

combination of predefined constants GAGE_ASSUME_XXXXX, where XXXXX is a board type. Board<br />

type constants are defined in GAGE_DRV.H file.<br />

Return Value<br />

Returns the pointer to the string with above-mentioned parameters.<br />

See Also<br />

gage_board_type_size_to_text<br />

Examples<br />

C:<br />

gage_support_to_text (str, sizeof(str), board_support);<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 84


gage_transfer_buffer_2<br />

Syntax<br />

C:<br />

void far* GAGEAPI gage_transfer_buffer_2 (int32 ta, int16 channel, void far *buffer, int32 nsamples);<br />

Visual BASIC:<br />

This routine is currently not supported under Visual BASIC.<br />

Remarks<br />

gage_transfer_buffer_2 is used to copy nsamples points from the specified channel to the supplied<br />

buffer beginning from address ta. The channel can be either GAGE_CHAN_A or GAGE_CHAN_B. The<br />

relevant addresses can be obtained by calling gage_calculate_addresses routine. The buffer should be<br />

typecast to the appropriate size before accessing it. The <strong>CompuScope</strong> PCI boards will use bus-mastering if<br />

available, otherwise this routine is the same as gage_transfer_buffer.<br />

Because bus-mastering requires the buffer to be dword-aligned, the driver may have to change its starting<br />

address. The return value is a pointer that points to where the actual data begins. The difference between<br />

the buffer address passed to the routine and the one returned will be 0, 1, 2 or 3 addresses.<br />

Note: The buffer that the calling program allocates should be 4 samples larger than the requested size.<br />

For all <strong>CompuScope</strong> boards with two channels, single channel mode uses both of the channels. The<br />

captured data must be transferred one channel at a time. The even addresses will be from channel A and the<br />

odd addresses will be from channel B. The data must then be interleaved by the application when using<br />

gage_transfer_buffer, gage_trigger_view_transfer, gage_transfer_buffer_2 and<br />

gage_trigger_view_transfer_2 routines.<br />

Please see the Sample Programs section in the <strong>CompuScope</strong> <strong>SDK</strong> <strong>Manua</strong>l for further details.<br />

Return Value<br />

Returns a pointer that points to where the actual data begins.<br />

See also<br />

gage_transfer_buffer, gage_transfer_buffer_3 and Appendix B: Comparison of Various Data Transfer<br />

Routines.<br />

Examples<br />

C:<br />

ptr = gage_transfer_buffer_2(current_address, GAGE_CHAN_A, (uInt8 far *)(buffer), 512);<br />

first_value = ptr[0];<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

85


gage_trigger_address<br />

Syntax<br />

C:<br />

int32 GAGEAPI gage_trigger_address (void);<br />

Visual BASIC:<br />

Function gage_trigger_address () As Long<br />

Remarks<br />

gage_trigger_address finds the address in <strong>CompuScope</strong> memory where the trigger event occurred.<br />

Once a trigger event is detected, the address into which the data was being written is tagged as the trigger<br />

address.<br />

This routine will only access the hardware once per acquisition. The trigger address is then stored in the<br />

driver structure for future or repeated use. The gage_get_trigger_address routine accesses the<br />

<strong>CompuScope</strong> hardware every time it is called. In Multiple Record operation, gage_get_trigger_address<br />

should be used, if it is necessary to monitor the trigger addresses while capturing the data.<br />

Return Value<br />

The long integer returned is the trigger address.<br />

See also<br />

gage_get_trigger_address and gage_calculate_addresses<br />

Examples<br />

C:<br />

address = gage_trigger_address ();<br />

Visual BASIC:<br />

address = gage_trigger_address<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 86


gage_trigger_control<br />

Syntax<br />

C:<br />

int16 GAGEAPI gage_trigger_control (int16 source, int16 ext_coupling, int16 ext_gain, int16 slope,<br />

int16 level, int32 depth);<br />

Visual BASIC:<br />

Function gage_trigger_control (ByVal source As Integer, ByVal ext_coupling As Integer,<br />

ByVal ext_gain As Integer, ByVal slope As Integer,<br />

ByVal level As Integer, ByVal depth As Long) As Integer<br />

Remarks<br />

gage_trigger_control is used to set up the trigger parameters of the <strong>CompuScope</strong>.<br />

source can be either channel A, EXTERNAL or SOFTWARE and the constants GAGE_CHAN_A,<br />

GAGE_EXTERNAL and GAGE_SOFTWARE should be used to indicate their respective sources.<br />

ext_coupling can be either DC or AC for the external trigger input as indicated by the constants<br />

GAGE_DC and GAGE_AC respectively. The CS512 and CS512/PCI have TTL external trigger input,<br />

therefore this parameter has no effect.<br />

ext_gain can be either of the constants GAGE_PM_5_V or GAGE_PM_1_V for the external trigger input.<br />

The CS512 and CS512/PCI have TTL external trigger input therefore this parameter has no effect.<br />

slope is the trigger slope and can be either positive or negative. The constants GAGE_POSITIVE or<br />

GAGE_NEGATIVE should be used.<br />

level can be any value between 0 and 255. The values are scaled internally to match the trigger input range<br />

selected. The minimum input level is 0 while the maximum trigger level is 255 (these correspond to -1V<br />

and +1V respectively for the x1 input gain). The CS512 and CS512/PCI have TTL external trigger input,<br />

therefore this parameter has no effect.<br />

The depth parameter sets the trigger depth, that is, the number of samples captured after the trigger event.<br />

The minimum value is 0. This can help reduce the capturing overhead when only a few points of data are<br />

required. Several defined constants are available to the application programmer to illustrate the use of this<br />

parameter. The constants GAGE_POST_0K, GAGE_POST_1K, GAGE_POST_2K, GAGE_POST_4K,<br />

GAGE_POST_8K, GAGE_POST_16K, GAGE_POST_32K, GAGE_POST_64K and<br />

GAGE_POST_128K, GAGE_POST_256K, GAGE_POST_512K, GAGE_POST_1M, GAGE_POST_2M,<br />

GAGE_POST_4M and GAGE_POST_8M are for the trigger depths of 0, 1024, 2048, 4096, 8192, 16384,<br />

32768, 65536, 131072, 262144, 524288, 1048576, 2097152, 4194304 and 8388608 bytes respectively.<br />

Other values besides these constants can be used. The depth parameter should be a multiple of the trigger<br />

resolution. If the depth is not a multiple of the trigger resolution, it is rounded up to the nearest multiple.<br />

Note: If external trigger is not used, some parameters such as ext_gain and ext_coupling have no effect.<br />

All the parameters, however, should be set to the valid values for the <strong>CompuScope</strong> board in use.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

87


Return Value<br />

A one is returned if successful and a zero is returned when the routine fails, and gage_get_error_code may<br />

be called to obtain the error code. The application program should always check the return values.<br />

See also<br />

gage_capture_mode, gage_input_control, gage_trigger_control_2 and see the Appendix: Data Structures<br />

Used by Gage Drivers in the <strong>CompuScope</strong> <strong>SDK</strong> <strong>Manua</strong>l.<br />

Examples<br />

C:<br />

gage_trigger_control (GAGE_CHAN_A, GAGE_DC, GAGE_PM_1_V, GAGE_POSITIVE, 160,<br />

GAGE_POST_16K);<br />

Visual BASIC:<br />

dummy = gage_trigger_control (GAGE_CHAN_A, GAGE_DC, GAGE_PM_1_V, GAGE_POSITIVE,<br />

160, GAGE_POST_16K)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 88


gage_trigger_view_transfer<br />

Syntax<br />

C:<br />

void GAGEAPI gage_trigger_view_transfer (int16 channel, uInt8 far *buffer, int16 nsamples);<br />

Visual BASIC:<br />

Sub gage_trigger_view_transfer (ByVal channel As Integer, buffer(0) As Integer,<br />

ByVal nsamples As Integer)<br />

Remarks<br />

gage_trigger_view_transfer is used to copy nsample points of the <strong>CompuScope</strong> memory space, from the<br />

channel specified in the parameter channel to the supplied buffer array buffer starting with the trigger<br />

address of the most recent data capture. The starting point of the transferred data can be changed, by using<br />

gage_set_trigger_view_offset. The default starting point is the trigger address.<br />

For PCI (CP500) <strong>CompuScope</strong>s, there is no intrinsic limitation on the amount of data that can be<br />

transferred at a time by gage_trigger_view_transfer. Please note, however, that for ISA <strong>CompuScope</strong>s, a<br />

maximum of 4K samples may be transferred at a time. For 8-bit ISA <strong>CompuScope</strong>s, the sample size is 1<br />

byte, so 4K samples equals 4K bytes. The 12 bit and 16 bit ISA <strong>CompuScope</strong>s use integer samples,<br />

therefore 4K samples equals 4K integers.<br />

For all <strong>CompuScope</strong> boards with two channels, single channel mode uses both of the channels. The<br />

captured data must be transferred one channel at a time and put together by the application program. The<br />

even addresses will be from channel A and the odd addresses will be from channel B. Please see the<br />

Sample Programs section in the <strong>CompuScope</strong> <strong>SDK</strong> <strong>Manua</strong>l for further details.<br />

Return Value<br />

None.<br />

See also<br />

Appendix: Comparison of Various Data Transfer Routines<br />

Examples<br />

C:<br />

gage_trigger_view_transfer (GAGE_CHAN_A, (uInt8 far *)(buffer), 512);<br />

Visual BASIC:<br />

Call gage_trigger_view_transfer (GAGE_CHAN_A, buffer(0), 512)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

89


gage_trigger_view_transfer_2<br />

Syntax<br />

C:<br />

void far* GAGEAPI gage_trigger_view_transfer_2 (int16 channel, void far *buffer, int32 nsamples);<br />

Visual BASIC:<br />

This routine is currently not supported under Visual BASIC.<br />

Remarks<br />

gage_trigger_view_transfer_2 is used to copy nsample points of the <strong>CompuScope</strong> memory space, from<br />

the channel specified in the parameter channel to the supplied buffer array buffer starting with the trigger<br />

address of the most recent data capture.<br />

The <strong>CompuScope</strong> PCI boards will use bus-mastering if available; otherwise this routine is the same as<br />

gage_trigger_view_transfer.<br />

The calling program should typecast this buffer to the appropriate type before accessing the data.<br />

Because bus-mastering requires the buffer to be dword-aligned, the driver may have to change its starting<br />

address. The return value is a pointer to where the actual data begins. The difference between the buffer<br />

address passed to the routine and the one returned will be 0, 1, 2 or 3 addresses.<br />

Note: The buffer that the calling program allocates should be 4 samples larger than the requested size.<br />

For all <strong>CompuScope</strong> boards with two channels, single channel mode uses both of the channels. The<br />

captured data must be transferred one channel at a time and put together by the application program. The<br />

even addresses will be from channel A and the odd addresses will be from channel B. Please see the<br />

Sample Program section in the <strong>CompuScope</strong> <strong>SDK</strong> <strong>Manua</strong>l for further details.<br />

Return Value<br />

Returns a pointer that points to where the actual data begins.<br />

See also<br />

gage_trigger_view_transfer and Appendix B: Comparison of Various Data Transfer Routines.<br />

Examples<br />

C:<br />

ptr = gage_trigger_view_transfer_2 (GAGE_CHAN_A, (uInt8 far *)(buffer), 512);<br />

first_value = ptr[0];<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 90


gage_trigger_view_transfer_3<br />

Syntax<br />

C:<br />

uInt32 GAGEAPI gage_trigger_view_transfer_3 (int16 channel, void far *buffer, int32 nsamples);<br />

Visual BASIC:<br />

This routine is currently not supported under Visual BASIC.<br />

Remarks<br />

gage_trigger_view_transfer_3 is used to copy nsample points of the <strong>CompuScope</strong> memory space, from<br />

the channel specified in the parameter channel, to the supplied buffer array buffer starting with the trigger<br />

address of the most recent data capture.<br />

The <strong>CompuScope</strong> PCI boards will use bus-mastering if available; otherwise this routine is the same as<br />

gage_trigger_view_transfer.<br />

The buffer must be at least two dwords longer than the required size to store nsample samples. The<br />

calling program should typecast this buffer to the appropriate type before accessing the data.<br />

The application does not need to interleave the data when the acquisition has been performed in single<br />

channel mode, as is the case with gage_transfer_buffer, gage_trigger_view_transfer,<br />

gage_transfer_buffer_2 and gage_trigger_view_transfer_2. These routines should be used for new<br />

development when they are available.<br />

Return Value<br />

Returns an offset to the beginning of the dword-aligned buffer that the driver uses. The offset is the<br />

difference between the buffer passed to the driver and the buffer the driver uses.<br />

See also<br />

gage_trigger_view_transfer and Appendix B: Comparison of Various Data Transfer Routines.<br />

Examples<br />

C:<br />

offset = gage_trigger_view_transfer_3 (GAGE_CHAN_A, (uInt8 far *)(buffer), 512);<br />

new_ptr = (uInt8 *)(buffer+offset);<br />

first_value = new_ptr[0];<br />

Examples<br />

C:<br />

gage_trigger_view_transfer_3 (GAGE_CHAN_A, (uInt8 far *)(buffer), 512);<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

91


gage_use_cal_table<br />

Syntax<br />

C:<br />

int16 gage_use_cal_table (int16 action);<br />

Visual BASIC:<br />

Function gage_use_cal_table (ByVal action As Integer) As Integer<br />

Remarks<br />

This routine sets an internal driver variable that controls whether or not a <strong>CompuScope</strong> 12 bit board will be<br />

autocalibrated when the gain is changed.<br />

If action is 1, the driver variable is set and the board will use the internal DAC table rather than<br />

autocalibrate. The new value of the driver variable is returned.<br />

If action is 0, the variable is cleared and autocalibration is performed. This is the default value.<br />

If action is not 1 or 0, the current value is returned but nothing is changed. Also note that the DAC table<br />

should be set, by reading in a calibration file containing the proper values with gage_read_cal_table.<br />

Return Value<br />

The return value is the current state of the driver variable.<br />

See also<br />

gage_read_cal_table<br />

Examples<br />

C:<br />

gage_use_cal_table (1);<br />

Visual BASIC:<br />

gage_use_cal_table (1)<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 92


IV<br />

Appendices<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

93


Appendix A<br />

Comparison of Various<br />

Data Transfer Routines<br />

Buffered Access Routines<br />

All buffered routines read a block of data from <strong>CompuScope</strong> on-board memory; achieving high data<br />

transfer rates and thus allowing significant optimization of application performance. However, most<br />

buffered routines have access to only one <strong>CompuScope</strong> A/D converter's memory at a time. Therefore, in<br />

single channel mode, these routines will read only the odd or the even samples. The two buffers must be<br />

interleaved later by the user applications. In dual channel mode no interleaving is necessary, since each<br />

A/D converter's memory holds the data from a separate input channel. The only exception is the<br />

gage_transfer_buffer_3 routine which, when called in single channel mode, automatically downloads the<br />

data from both A/D converters' memories and does the interleaving within the drivers.<br />

The gage_transfer_buffer and gage_trigger_view_transfer routines provide a CPU mediated data<br />

transfer (i.e., a transfer where the CPU acts as mediator between host memory and the <strong>CompuScope</strong><br />

board). The only difference between the two routines is in how the addresses for data to be downloaded<br />

are specified. gage_transfer_buffer transfers data starting from the absolute address given as one of the<br />

parameters. By contrast, gage_trigger_view_transfer transfers data starting from a reference address<br />

position. This reference address is available in the trigger_view_offset global driver variable, which is set<br />

by the function set_trigger_view_offset. For both the gage_transfer_buffer and<br />

gage_trigger_view_transfer routines, the user application must allocate and provide a host buffer of<br />

sufficient size to hold the requested data.<br />

For PCI (CP500) <strong>CompuScope</strong>s, there is no intrinsic limitation on the amount of data that can be<br />

transferred at a time by gage_trigger_view_transfer. However, the gage_trigger_view_transfer routine<br />

can only transfer 4 KSamples at a time on ISA bus <strong>CompuScope</strong>s. Several of these transfers can be<br />

chained together using the gage_set_trigger_view_offset routine to form one larger transfer, as shown<br />

below:<br />

offet = 0;<br />

position = 0;<br />

while (depth > 0)<br />

{<br />

if (depth > 4096)<br />

transfer_depth = 4096;<br />

else<br />

transfer_depth = depth;<br />

gage_set_trigger_view_offset (offset);<br />

gage_trigger_view_transfer (GAGE_CHAN_A, (int16*) (buffer+position), transfer_depth);<br />

depth -= transfer_depth;<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 94


}<br />

offset += transfer_depth;<br />

position += transfer_depth;<br />

Note: At the end of this routine buffer will hold all the data. The 4 Kilosample transfer size limitation only<br />

applies for the gage_trigger_view_transfer routine using ISA bus <strong>CompuScope</strong>s.<br />

For PCI <strong>CompuScope</strong>s that support PCI busmastering, the gage_transfer_buffer_2 and<br />

gage_trigger_view_transfer_2 routines execute a PCI bus-mastering data transfer from on-board<br />

<strong>CompuScope</strong> memory to host memory (PC RAM). In bus-mastering mode, data are transferred directly<br />

from <strong>CompuScope</strong> memory to host memory with no CPU mediation required. PCI bus-mastering is the<br />

fastest available PCI data transfer method and can achieve sustained data transfer rates of 100<br />

MegaBytes/second.<br />

The difference between the gage_transfer_buffer_2 and gage_trigger_view_transfer_2 routines is<br />

exactly the same as the difference between gage_transfer_buffer and gage_trigger_view_transfer. That<br />

is, gage_transfer_buffer accepts absolute <strong>CompuScope</strong> on-board memory addresses, while<br />

gage_trigger_view_transfer downloads data starting at the address specified by the trigger_view_offset<br />

global driver variable.<br />

Internally using PCI bus-mastering, PCI, PCI <strong>CompuScope</strong> hardware can only transfer data from a d-word<br />

(4 byte) boundary in <strong>CompuScope</strong> on-board memory. For instance, data can be downloaded starting from<br />

hexadecimal addresses 0x3000 or 3004, but not starting from hexadecimal addresses 0x3001. Because the<br />

gage_transfer_buffer and gage_trigger_view_transfer routines use CPU mediated data transfer, these<br />

details are handled by the drivers and the user need be concerned with data alignment issues. Since<br />

gage_transfer_buffer_2 and gage_trigger_view_transfer_2 do PCI bus-mastering with no CPU<br />

mediation, however, the user must deal with these data alignment issues.<br />

Both gage_transfer_buffer_2 and gage_trigger_view_transfer_2 return a pointer that gives the byte<br />

address location in host memory of the start of the data requested by the call. For instance, let us assume<br />

that the user requested transfer of data starting from <strong>CompuScope</strong> on-board memory address hex 0x3002.<br />

Let us suppose also that the user allocated a buffer whose starting address is hex 0x10000. Due to its<br />

hardware architecture, the <strong>CompuScope</strong> would be forced to download data from hexadecimal addresses<br />

0x3000. gage_transfer_buffer_2 and gage_trigger_view_transfer_2 would then return a pointer with<br />

the value of 0x3002 – 0x3000 + 0x10000= 0x10002. So the user application should start looking at the<br />

data starting at pointer value 0x10002 and not at 0x10000.<br />

Because the <strong>CompuScope</strong> is forced to download data from a d-word boundary, the drivers may need to<br />

download more data than is requested by the users. Consequently, the target host memory buffer must be<br />

slightly larger than the requested amount of data to be transferred. The required amount of padding is<br />

different for different <strong>CompuScope</strong> models. The best padding method is to use the variable<br />

user_buffer_padding, which is returned by the drivers and is the amount of target buffer padding in Bytes<br />

required for the current <strong>CompuScope</strong> model. Simply add user_buffer_padding to the amount of memory<br />

to be allocated for the target host memory buffer.<br />

gage_transfer_buffer_3 and gage_trigger_view_transfer_3 are two routines that are similar to<br />

gage_transfer_buffer_2 and gage_trigger_view_transfer_2 routines, except for two very important<br />

differences:<br />

1. Both gage_transfer_buffer_2 and gage_trigger_view_transfer_2 return a pointer that gives the<br />

byte address location in host memory of the start of the data requested by the call. By contrast,<br />

the return value of gage_transfer_buffer_3 is an offset in bytes that specifies the location within<br />

the user allocated buffer to the start of the requested data. For gage_trigger_view_transfer_3,<br />

the return value is an offset in Bytes that specifies the location within the user allocated buffer to<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

95


the data whose address was specified by the trigger_view_offset global driver variable. For<br />

instance, let us assume that the user requested transfer of data starting from <strong>CompuScope</strong> onboard<br />

memory address hex 0x3002. This is done by passing 0x3002 as the first argument to<br />

gage_transfer_buffer_3 or by setting the value of the trigger_view_offset global driver variable to<br />

0x3002 before calling gage_trigger_view_transfer_3 Due to its hardware architecture, the<br />

<strong>CompuScope</strong> would be forced to download data from hexadecimal addresses 0x3000.<br />

gage_transfer_buffer_3 and gage_trigger_view_transfer_3 would then return an offset with the<br />

value of 0x3002 – 0x3000 = 2. This returned offset of 2 indicates that the start of the requested<br />

data is in the 3 rd byte of the host memory buffer (0 means 1 st Byte, 1 means 2nd Byte, etc).<br />

2. The second feature is that the data from both A/D converter memories are automatically<br />

interleaved in single channel mode. Behind the scenes in single channel mode, both<br />

gage_transfer_buffer_3 and gage_trigger_view_transfer_3 download the data from both A/D<br />

converter memories and interleaves them within the driver. The user is then presented with the<br />

complete single channel mode data record. Therefore, the application does not need to interleave<br />

the data when the acquisition has been performed in single channel mode. By contrast, in the<br />

case of gage_transfer_buffer, gage_trigger_view_transfer, gage_transfer_buffer_2 and<br />

gage_trigger_view_transfer_2, it is the application’s responsibility to interleave the transferred<br />

data in single channel mode. Since they are easier to use, therefore, gage_transfer_buffer_3 or<br />

gage_trigger_view_transfer_3 should be used for new software development.<br />

Single Sample Access Routines<br />

gage_mem_read_chan_a and gage_mem_read_chan_b<br />

These functions read one sample (which is 1 byte for 8 bit <strong>CompuScope</strong> boards and 2 bytes for 12, 14 and<br />

16 bit <strong>CompuScope</strong> boards) from <strong>CompuScope</strong> on-board memory for channel A or channel B respectively<br />

in dual channel mode. The functions are usually used to read relatively small amounts of data or to read<br />

non-sequential data from a <strong>CompuScope</strong> board regardless of the operating mode.<br />

gage_mem_read_dual is very similar to gage_mem_read_chan_a and gage_mem_read_chan_b. It<br />

reads one sample from <strong>CompuScope</strong> memory in dual channel mode, having the channel number as one of<br />

the parameters. This function is best suited for an application where there is prior knowledge that the data<br />

acquisition will be occurring in dual channel mode and both channels should be read.<br />

gage_mem_read_single is the counterpart of gage_mem_read_chan_a and gage_mem_read_chan_b for<br />

single channel mode. All three of these routines maintain the same parameters and return values<br />

gage_mem_read_master reads one sample from <strong>CompuScope</strong> memory for channel A of the Master<br />

<strong>CompuScope</strong> board. The Gage drivers detect the mode of operation, single or dual channel. This function<br />

is mostly used in conjunction with gage_calculate_mra_addresses to read embedded enhanced trigger bits<br />

from <strong>CompuScope</strong> memory. Embedded ETB information must always be read from the Master<br />

<strong>CompuScope</strong>.<br />

All Single Sample Access or gage_mem_read routines provide a “read ahead” caching mechanism, which<br />

reads a larger block of data from the <strong>CompuScope</strong> memory behind the scenes. This allows faster response<br />

of multiple calls to a gage_mem_read routine in order to download sequential data points. The size of the<br />

cache buffer, however, varies among the <strong>CompuScope</strong> boards. When call to a gage_mem_read routine is<br />

made, behind the scenes the driver downloads a multi-point block of data from <strong>CompuScope</strong> memory.<br />

This block is then stored in the driver and is used as long as address locations for subsequent<br />

gage_mem_read calls fall within it.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 96


Appendix B<br />

Frequently Asked<br />

Questions<br />

Q: When I run the sample programs provided on the <strong>SDK</strong> diskette, why do I get the message<br />

"No <strong>CompuScope</strong> boards found"?<br />

A: <strong>CompuScope</strong> boards need to be configured before acquiring data. Once Gage cards are properly<br />

configured, a configuration file, GAGESCOP.INC, is created and saved in the Windows system<br />

directory. Please see your Driver Installation Guide on use of the Windows board configuration<br />

utility. When an application, such as an <strong>SDK</strong> sample program, is executed, the Windows drivers<br />

look for this configuration file. If the configuration file is not found at the expected location, “No<br />

<strong>CompuScope</strong> boards found” message will be displayed on the Windows desktop.<br />

Q: Why did my program compile and run with a previous version of the driver, but not with the<br />

new version of the driver?<br />

A: You may have updated your driver to a newer version in which either the Major or Minor version<br />

numbers. This indicates that the common files, which contain important data structure<br />

declarations, have changed. For instance, if you updated from <strong>CompuScope</strong> driver version<br />

3.48.02 to 3.50.00, then since the Minor number 48 has been updated to 50, the common files<br />

must have been changed. Common files between an application and the drivers can lead to<br />

incompatibility that causes linking errors or incorrect operation. The solution is simply to update<br />

your common files. The new common files are included with the new drivers. You simply need<br />

to copy these new common files to your application folder, overwriting the old ones and<br />

recompile. This will make you application compatible with the new drivers.<br />

Q: My program calls gage_start_capture with the auto_trigger parameter set to TRUE. Why<br />

doesn’t the data capture occur immediately?<br />

A: The trigger source must be set to GAGE_SOFTWARE, through a call to gage_trigger_control,<br />

for this parameter to have a predictable effect of immediately triggering the <strong>CompuScope</strong><br />

hardware.<br />

Q: I’m using the gage_trigger_ view_ transfer routine in single channel mode. When I examine<br />

the captured data, every other point is missing. Why?<br />

A: In single channel mode on two channel <strong>CompuScope</strong>s, the data is divided between the memories<br />

of the two on-board A/D converters on the <strong>CompuScope</strong>. Accordingly, gage_trigger_<br />

view_transfer must be called once with each channel to transfer all the data. The two data sets<br />

must then be interleaved by the user application. This is also true of gage_transfer_buffer,<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

97


gage_trigger_view_transfer, gage_transfer_buffer_2 and gage_trigger_view_transfer_2. The<br />

recommended routine, gage_transfer_buffer_3, automatically does the interleaving in the driver<br />

and so is the preferred data transfer routine.<br />

Q: Why can’t I compile sample programs under a Borland C compiler?<br />

A: If you are using a Borland C compiler, you will have to recreate the GAGE_DRV.LIB file, using<br />

the IMPLIB.EXE utility supplied by Borland. This is because of an incompatibility between<br />

Microsoft-generated LIB files and Borland compilers.<br />

The syntax is: implib gage_drv.lib gage_drv.dll.<br />

This will create a Borland compatible LIB file. You can then recompile the sample programs with<br />

this LIB file.<br />

Q: Why can’t I install the C/C++ <strong>CompuScope</strong> <strong>SDK</strong> on Windows NT or 2000?<br />

A: You have to be logged on as the Administrator to install the C/C++ <strong>SDK</strong> in Windows NT or 2000.<br />

This built-in security ensures that not anyone can install software on your PC. You don't need,<br />

however, to be the Administrator to run the <strong>SDK</strong> programs.<br />

Q: Why am I getting a trigger without a trigger signal connected?<br />

A: You have probably made a common mistake in the gage_start_capture routine. The parameter<br />

should be either a 1 or a 0. If you are using software trigger it should be 1, otherwise it should be<br />

0. Our sample programs use gage_start_capture (board->source == GAGE_SOFTWARE), which<br />

is an evaluation not an assignment, and so requires the double "=" symbol.. The argument<br />

becomes 1 if the source is software and 0 otherwise. If you write gage_start_capture (board-<br />

>source = GAGE_SOFTWARE), this assigns GAGE_SOFTWARE to board->source, making the<br />

parameter non-zero. A non-zero parameter will cause a software trigger. Change the single "=" to<br />

a double "=" and the problem will be resolved.<br />

Q: Why I am getting the data from the wrong part of the signal?<br />

A: Most of our sample programs have a timeout for both busy and trigger. The trigger timeout is<br />

used to ensure that if the user runs the program without a signal connected, the program won't<br />

appear to hang while it is waiting for a trigger. After a pre-set time, the sample program will call<br />

gage_force_capture(), which will force the <strong>CompuScope</strong> hardware to trigger immediately. The<br />

busy timeout is similar and causes the capture to be aborted if it has taken too long. In the sample<br />

programs, the default values for the trigger and busy timeouts are unusually set to high values like<br />

100 seconds. If a trigger time-out does occur, then the <strong>CompuScope</strong> will trigger at a time that is<br />

unrelated to the nature of the signal. Depending on the speed of the computer and the trigger<br />

repeat rate, the trigger timeout value may have to be increased.<br />

Q: Why I am not getting a trigger?<br />

A: Check that the trigger level is correct. A common error is to use a TTL signal, which swings<br />

between 0 and 5 Volts as an external trigger source and set the trigger level to 0 volts. The actual<br />

0 level of the signal may actually be several tens of milliVolts above zero. The signal thus never<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 98


actually passes through zero and the <strong>CompuScope</strong> is never triggered. To resolve this problem,<br />

simply raise the trigger level to one that corresponds to 1 Volt or so. Using the wrong external<br />

trigger input range can also cause this problem.<br />

Q: The program runs, but why is the data capture incorrect?<br />

A: The order in which <strong>CompuScope</strong> parameter setup routines are called for data capture is important.<br />

gage_trigger_control should be called after gage_input_control, which should be called after<br />

gage_capture_mode. It is recommended that the programmer use the SetBoard() routine to<br />

implement <strong>CompuScope</strong> settings, since this routine calls all setup routines in the correct order.<br />

The SetBoard () routine resides in app_supp.c , which is included with every C sample program.<br />

Q: Why is Multiple Record mode behaving erratically in my program?<br />

A: The order in which the driver routines are called is important. gage_multiple_record should be<br />

called before gage_capture_mode, gage_input_control or gage_trigger_control. Also, if you<br />

change the Multiple Record settings, gage_trigger_control must be called again. . It is<br />

recommended that the programmer use the SetBoard() routine to implement <strong>CompuScope</strong><br />

settings, since this routine calls all setup routines in the correct order. The SetBoard () routine<br />

resides in app_supp.c , which is included with every C sample program.<br />

Q: Why I am not able to properly capture the data with an external clock?<br />

A: There can be several reasons for this. The nature of the required external clock signal is different<br />

for each <strong>CompuScope</strong> model. The voltage levels, signal shape, duty cycle and allowed frequency<br />

range must also be respected. Please see your hardware manual for these details. Many<br />

<strong>CompuScope</strong>s terminate the external clock input with a 50 Ohm load for good signal propagation.<br />

The users signal must then be capable of driving a 50 Ohm load. Finally, the external clock<br />

function is optional on some models, so make sure that your <strong>CompuScope</strong> is actually equipped<br />

with the external clock option.<br />

Most <strong>CompuScope</strong>s have a minimum operating frequency. Consequently, the clock signal cannot<br />

be turned off while the <strong>CompuScope</strong> is operating. It is best to have a free-running clock source<br />

that is always active.<br />

Another important point is to correctly set the external clock frequency in your application<br />

program. The drivers have no other means of knowing this frequency. The drivers need to know<br />

the external clock frequency in order to internally set low level timing delays on the <strong>CompuScope</strong>.<br />

If you tell the drivers the incorrect external clock frequency, this may lead to incorrect<br />

<strong>CompuScope</strong> operation.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

99


Appendix C<br />

Multiple/Independent<br />

Mode Operation<br />

In cases where there is more than one <strong>CompuScope</strong> board installed in one host computer. This is called a<br />

Multi-card <strong>CompuScope</strong> system. There are two types of Multi-card <strong>CompuScope</strong> systems: a Master/Slave<br />

<strong>CompuScope</strong> system and a Multiple/Independent <strong>CompuScope</strong> system.<br />

A Master/Slave <strong>CompuScope</strong> system consists of identical <strong>CompuScope</strong>s working in a synchronous<br />

manner for true simultaneous sampling and triggering on all channels in the system. The Master/Slave<br />

configuration must be specified at the time of order. The <strong>CompuScope</strong>s are then prepared as a<br />

Master/Slave system at the factory. The <strong>CompuScope</strong>s can no longer then be operated as independent<br />

<strong>CompuScope</strong>s unless they are reconfigured at the factory. All <strong>CompuScope</strong>s in the system, Master and<br />

Slaves, share start and trigger signals, as well as the sampling clock. The Master <strong>CompuScope</strong> provides all<br />

these timing signals to the Slaves. All capture parameters, such as the post-trigger depth and sampling rate,<br />

are set to the same value for all <strong>CompuScope</strong>s in the system. Only the <strong>CompuScope</strong> channel parameters<br />

(i.e. input range, coupling and impedance) can be set independently for each <strong>CompuScope</strong>.<br />

]<br />

A Multiple/Independent <strong>CompuScope</strong> system consists of different single <strong>CompuScope</strong>s that can be<br />

operated independently, with completely different sampling rates and trigger conditions. This system<br />

allows, for example, capturing a signal with one <strong>CompuScope</strong> at a very high sampling rate to see high<br />

frequency signal components, and capturing the same signal at a lower sample rate with another<br />

<strong>CompuScope</strong> to see low frequency signal components.<br />

These are the only two types of systems that are currently supported by the <strong>CompuScope</strong> Windows drivers.<br />

So, while the drivers can operate a single Master/Slave system or a Multiple/Independent system consisting<br />

of many independent <strong>CompuScope</strong>s, the two types of systems cannot be combined. So, for instance, the<br />

drivers do not support operation of two Master/Slave systems in the same PC. Similarly, the drivers do not<br />

support a Master/Slave system installed in the same PC with a single independent <strong>CompuScope</strong>. The only<br />

way to make use of such a system is to use the CP500_ED.EXE utility. CP500_ED can be used to disable<br />

<strong>CompuScope</strong> models so that only one system is recognized and operated by the drivers.<br />

By default, the <strong>CompuScope</strong> drivers assume Master/Slave Multi-Card operation. In order to use the boards<br />

in the Multiple/Independent mode of operation, the routine gage_set_independant_operation must be<br />

called before initializing Multiple/Independent <strong>CompuScope</strong>s. The <strong>CompuScope</strong> board order can be<br />

determined using a <strong>CompuScope</strong> configuration utility, such as Gage Config or Instrument Manager.<br />

The application program is able to select to which <strong>CompuScope</strong> it communicates by calling the<br />

gage_select_board routine with the board number as a parameter. This routine is used to then configure<br />

each board separately using standard configuration routines.<br />

Gage drivers provide special routines for starting the capture, forcing a trigger and aborting the capture for<br />

the a system of Multiple Independent <strong>CompuScope</strong>s. These routines are called<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 100


gage_board_start_capture, gage_board_force_capture, and gage_board_abort_capture, respectively.<br />

Data retrieval is done in the same manner as in Master/Slave mode. That is, the <strong>CompuScope</strong> is first<br />

selected using the gage_select_board routine and its data are downloaded using any of the data transfer<br />

subroutines.<br />

For both types of Multi-card <strong>CompuScope</strong> systems, Master/Slave and Multiple/Independent, the<br />

gage_driver_initialize routine is called to initialize the entire system. In a Master/Slave system, starting<br />

and aborting a capture can be done with a single subroutine call that is automatically sent to the Master<br />

<strong>CompuScope</strong>. In a Multiple/Independent system, starting and aborting a capture must be down separately<br />

for each <strong>CompuScope</strong> in the system by sending the appropriate call separately to each board.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

101


Appendix D<br />

Multiple Record Mode<br />

Operation<br />

Hardware Perspective<br />

Multiple Record is a feature supported by most <strong>CompuScope</strong> boards. It allows the user to take advantage<br />

of the <strong>CompuScope</strong> card’s very deep on-board acquisition memory. Even though the PCI bus allows very<br />

fast data throughput to PC memory, there are applications in which data bursts cannot be downloaded in<br />

time to prepare for the next trigger. Examples of such applications are radar pulses, ultrasound pulses,<br />

lightening pulses and imaging signals.<br />

Multiple Record Mode allows the <strong>CompuScope</strong> board to acquire successive rapidly repeating triggers.<br />

Between acquisitions, the <strong>CompuScope</strong> is re-armed in hardware to prepare for the next acquisition with no<br />

CPU intervention required. This hardware re-arm is lightning fast and usually occurs within under a<br />

microsecond. Successive acquisitions are then stacked in <strong>CompuScope</strong> on board memory. These Multiple<br />

Records are then usually downloaded all at once after their acquisition. Since, in Multiple Record Mode,<br />

all <strong>CompuScope</strong> re-arming is down in hardware, no communication with the CPU is required throughout<br />

the Multiple Record sequence. This has the advantage of providing deterministic operation with no<br />

possibility of spurious performance degradation due to the multi-tasking, non-RealTime nature of the<br />

Windows operating system.<br />

Between Multiple Record acquisitions, the on-board counter that determines the current on-board memory<br />

address to which the next data point will be stored is stopped. This counter is only re-started once the next<br />

trigger event occurs. Consequently, unlike in Single Record Mode, there are no pre-trigger data<br />

available in Multiple Record Mode.<br />

The CP500-class PCI and cPCI <strong>CompuScope</strong> boards allow the user to specify the number of Multiple<br />

Records to acquire. Multiple Record acquisition is completed when the requested number of records has<br />

been acquired. Acquired data cannot be downloaded until the complete Multiple Record Mode acquisition<br />

is completed or aborted.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 102


Like in Single Record mode, there is a minimum post-trigger depth of each Multiple Record that can be<br />

specified for a given <strong>CompuScope</strong> model. The depth can then be increased from this minimum in specific<br />

increments. See your <strong>CompuScope</strong> hardware manual for minimum depth and depth increment values in<br />

Multiple Record Mode.<br />

The total number of Multiple Records that can be acquired is slightly less than the total acquisition memory<br />

available divided by the post trigger depth. For instance, for a <strong>CompuScope</strong> with 1 MegaSamples of onboard<br />

memory capturing 2048 point Multiple Records in single channel mode, almost 1 MegaSample /<br />

2048 = 512 Multiple Records can be acquired (Note. 1 MegaSample = 1024 ×1024 Samples). The<br />

<strong>CompuScope</strong> cannot capture exactly 512 records, since a few points of inter-Record padding is required<br />

between sequential records. So, slightly more than 2048 points are acquired for each record and ,<br />

consequently, less than 512 records can be acquired. The amount of padding is small (less than 10 points<br />

for most <strong>CompuScope</strong> models), but slightly reduces the number of records that can be captured<br />

As with Normal Single Record Acquisition, the GET DATA signal is strobed low to initiate a Multiple<br />

Record acquisition. This clears the TRIGGER and RAM FULL signals and their status bits and initializes<br />

the data acquisition counters to zero. The BUSY signal and status bit are now set to high. The data<br />

conversion process does not begin until a trigger event occurs.<br />

When a trigger event does occur, the sample depth counter begins to decrement. When this counter<br />

expires, it clears both the TRIGGER signal and its status bit, (instead of the BUSY signal as in Single<br />

record Mode). This allows another trigger event to again start the data capture process and acquired<br />

another record. A minimal number of sample clocks is required to reset the TRIGGER signal before<br />

another trigger event will be recognized. This number varies with <strong>CompuScope</strong> model number but is<br />

under 20 for all current models.<br />

The Multiple Record process continues until all of the requested records have been acquired. This event<br />

clears the BUSY signal, thus ending the Multiple Record acquisition. The following figure is a detailed<br />

timing diagram for a Multiple Record acquisition.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

103


Illustration of a Multiple Record acquisition for the capture of three groups. The top illustrates a timing<br />

diagram and <strong>CompuScope</strong> memory usage is illustrated below.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 104


Turning ON Multiple Record<br />

To determine if your <strong>CompuScope</strong> is capable of performing a Multiple Record acquisition, check your<br />

<strong>CompuScope</strong> hardware manual. To set up the currently selected <strong>CompuScope</strong> to perform a Multiple<br />

Record capture, you must call gage_multiple_record with a parameter of 1. A 0 parameter will turn off<br />

Multiple Recording if it was previously selected. If Multiple Record is chosen, the trigger depth set in the<br />

call to gage_trigger_control or gage_trigger_control_2 is used to set the size of each individual record.<br />

The minimum trigger depth and increment depend upon the <strong>CompuScope</strong> model. Because some driver<br />

parameters must be adjusted for Multiple Record operation, the sequence of calls is important.<br />

gage_multiple_record must be called before calling gage_capture_mode. The proper sequence of calls is<br />

as follows:<br />

gage_multiple_record (1);<br />

gage_multiple_record_acquisitions (number_of_acquisitions);<br />

gage_capture_mode (GAGE_DUAL_CHAN, GAGE_RATE_10, GAGE_MHZ);<br />

gage_input_control (GAGE_CHAN_A, GAGE_ENABLE, GAGE_DC, GAGE_PM_1_V);<br />

gage_input_control (GAGE_CHAN_B, GAGE_ENABLE, GAGE_DC, GAGE_PM_1_V);<br />

gage_trigger_control (GAGE_CHAN_A, GAGE_DC, GAGE_PM_1_V, GAGE_POSTIVE, 128,<br />

GAGE_POST_4K);<br />

If more than one <strong>CompuScope</strong> is to be used in Multiple Record mode, then the functions must be called for<br />

each individual <strong>CompuScope</strong>. gage_select_board can be used to select each <strong>CompuScope</strong> to be set.<br />

Downloading Multiple Record Data<br />

Multiple Record data is usually downloaded one record or group at a time. The function<br />

gage_calculate_mr_addresses is used to return the starting, trigger and ending addresses for each<br />

individual group. One of the parameters is the group number, whose valid range of values is 1 to the<br />

number of groups captured. If the group number is set to 0, the function will return the starting, trigger and<br />

ending address for the entire series of groups, treating them all as if they were one large capture. If the<br />

group number is -1, gage_calculate_mr_addresses will return the group number and the relevant<br />

addresses for the last group captured.<br />

If the channel parameter is -1, the captures are treated as a Software Multiple Record. Software Multiple<br />

Record is a format in which each record is arranged one after the other with no inter-record padding, unlike<br />

in <strong>CompuScope</strong> on-board memory where there is always some inter-record padding. This format is used to<br />

store data in Software Multiple Record SIG files. Setting the channel parameter to –1, therefore, is a useful<br />

method of calculating record addresses retrieved from a Software Multiple Record SIG file.<br />

As mentioned above, due to <strong>CompuScope</strong> hardware architecture, there is always some inter-Multiple<br />

Record padding in <strong>CompuScope</strong> on-board memory. This padding depends on the <strong>CompuScope</strong> model,<br />

mode and sampling rate but will be consistent for all the groups in a given Multiple Record capture. For<br />

this reason, application programs should use the driver function gage_calculate_mr_addresses to read<br />

back the captured data, rather than incorrectly assuming, for instance, that the third 1000-point record will<br />

start at address 2000 and end at address 3000.<br />

The prototype of gage_calculate_mr_addresses is:<br />

int32 gage_calculate_mr_addresses (int32 group, int16 board_type, int32 depth, int32 memory,<br />

int16 chan, int16 op_mode, float tbs, int32 far *trig, int32 far *start, int32 far *end);<br />

The trig, start and end variables are used to obtain the relevant addresses for each individual group. The<br />

valid range of group numbers is from 1 to the number of groups captured by the Multiple Record<br />

acquisition. The return value of gage_calculate_mr_addresses is equal to the group number passed to it<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

105


as long the group number is less than or equal to the number of acquired groups. When the passed group<br />

number is not equal to the return value, this indicates that the passed group number is outside the rage of<br />

valid captured groups.<br />

The recommended way of downloading all the groups in a Multiple Record capture is shown below:<br />

gage_get_driver_info (&gdi);<br />

tbs = 1000000000 / sample_rate; /* tbs is time between samples in nanoseconds. The correct value must<br />

be passed to address calculation routines for correct operation */<br />

group = 1;<br />

while (group == gage_calculate_mr_addresses (group, gdi.board_type, gdi.depth,<br />

gdi.max_available_memory, chan, gdi.mode, tbs, &trig, &start, &end) {<br />

}<br />

size = end - trig +1;<br />

offset = gage_transfer_buffer_3 (trig, GAGE_CHAN_A, buffer, size);<br />

display_data(offset); /*User-supplied routine that displays buffer, beginning at offset*/<br />

group++;<br />

The above sample code assumes that the buffer has already been allocated. The capture was in dual<br />

channel mode and only data from channel A is being transferred from the <strong>CompuScope</strong> acquisition<br />

memory to PC memory.<br />

Note that size was calculated to be end – trig +1. In Multiple Record mode there is no pre-trigger data, so<br />

the end address will always be greater than the trigger address.<br />

The above method is convenient if you don't know the total number of groups that have been captured<br />

because of the inter-record padding. If you've aborted the capture after a predetermined number of groups,<br />

or the driver routine gage_multiple_record_acquisitions is available for your <strong>CompuScope</strong> board, you<br />

can use a for loop to read only the number of groups of interest.<br />

Embedded Enhanced Trigger Bits<br />

A factory option available on most <strong>CompuScope</strong> boards with Multiple Record is Embedded Enhanced<br />

Trigger Bits. Due to the architecture of the <strong>CompuScope</strong> Multiple Record hardware, there is some<br />

uncertainty inherent in the trigger address because the least significant bits of this address are not<br />

maintained. The Embedded ETB option embeds the least significant bits of the trigger address (the ETBs)<br />

in an early sample of each Multiple Record group. After download, these embedded ETBs can be<br />

recovered and then used to resolve the trigger address uncertainty.<br />

On <strong>CompuScope</strong>s with the Embedded ETB functionality, the trigger address returned by<br />

gage_calculate_mr_addresses will point to the sample that that contains the enhanced trigger bits (ETBs).<br />

This sample must be downloaded using the gage_mem_read_master function as illustrated below:<br />

data = gage_mem_read_master(trig);<br />

In a Master/Slave <strong>CompuScope</strong> system, the ETBs for records from all <strong>CompuScope</strong>s in the system (Master<br />

and Slaves) must be downloaded from the Master <strong>CompuScope</strong>. Using the gage_mem_read_master<br />

function, as illustrated above, ensures that the ETBs are always downloaded from the Master <strong>CompuScope</strong>.<br />

The embedded ETBs are used to adjust the trigger address using the gage_calculate_mra_addresses<br />

function. The prototype of this function is shown below:<br />

int32 gage_calculate_mra_addresses (int16 board_type, uInt16 board_version, int16 chan, int16<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l 106


op_mode, float tbs, int32 far *trig, int32 far *start, int32 far *end, int16 data);<br />

Note that the chan parameter in this routine is 0-based. That is, channel A is specified by 0 and channel B<br />

is specified by 1. The data variable is the data located at the raw trigger address. This must have been<br />

previously downloaded as described above.<br />

The recommended way of calculating Multiple Record addresses using the embedded ETBs in order to<br />

correct the trigger address and then downloading the record data is shown below:<br />

gage_get_driver_info (&gdi);<br />

tbs = 1000000000 / sample_rate; /* tbs is time between samples in nanoseconds. The correct value must<br />

be passed to address calculation routines for correct operation */<br />

group = 1;<br />

while (group == gage_calculate_mr_addresses (group, gdi.board_type, gdi.depth,<br />

gdi.max_available_memory, chan, gdi.mode, tbs, &trig, &start, &end) {<br />

}<br />

data = gage_mem_read_master (trig);<br />

gage_calculate_mra_addresses (gdi.board_type, gdi.board_version, chan-1, gdi.mode, tbs, &trig,<br />

&start, &end, data);<br />

size = (end - trig) +1;<br />

offset=gage_transfer_buffer_3(trig, GAGE_CHAN_A, buffer, size);<br />

display_data(offset); /*User-supplied routine that displays buffer, beginning at offset*/<br />

group++;<br />

Due to varying amounts of inter-record padding throughout a Multiple Record Acquisition, the groups<br />

differ in size after embedded ETBs have been used to adjust the trigger addresses.<br />

An application program can check if Enhanced ETBs are available on the current <strong>CompuScope</strong> hardware<br />

by comparing the ee_options field of the gage_driver_info_type structure and comparing it against the<br />

EEPROM_OPTIONS_MULREC_ADJUST constant (defined in the EEPROM.H file). For example:<br />

gage_get_driver_info (&gdi);<br />

if (gdi.ee_options & EEPROM_OPTIONS_MULREC_ADJUST)<br />

printf ("embedded trigger bits available\n");<br />

Notes<br />

If you are using Multiple Record, you should generally not use a busy timeout. A busy timeout is usually<br />

used to abort a capture if it is not finished within a predefined amount of time. Because a Multiple Record<br />

capture is actually a series of captures, the Multiple Record acquisition can last a long and perhaps<br />

indeterminate amount if time. Consequently, an incorrect busy timeout value may prematurely abort<br />

Multiple Record acquisition before all the captures are complete. If you must use a busy timeout, make<br />

sure that the timeout value exceeds the longest possible total Multiple Record acquisition time.<br />

<strong>CompuScope</strong> API Reference <strong>Manua</strong>l<br />

107


Technical Support<br />

Gage Applied Technologies, Inc. offers technical support for all its Software Development Kits.<br />

In order to serve you better, we have created a web-based technical support system that is available to you<br />

24 hours a day.<br />

By utilizing the internet to the fullest, we are able to provide you better than ever technical support without<br />

increasing our costs, thereby allowing us to provide you the best possible product at the lowest possible<br />

price.<br />

To obtain technical support, simply visit:<br />

www.gage-applied.com/support.asp<br />

Please complete this form and submit it. Our form processing system will intelligently route your request<br />

to the Technical Support Specialist (TSS) most familiar with the intricacies of your product. This TSS will<br />

be in contact with you within 24 hours of form submittal.<br />

In the odd case that you have problems submitting the form on our web site, please e-mail us at<br />

support@gage-applied.com<br />

As opposed to automatic routing of technical support requests originating from the Gage web site, support<br />

requests received via e-mail or telephone calls are routed manually by our staff. Providing you with high<br />

quality support may take an average of 2 to 3 days if you do not use the web-based technical support<br />

system.<br />

Please note that Technical Support Requests received<br />

via e-mail or by telephone will take an average of 2 to 3 days to process.<br />

It is faster to use the web site!<br />

When calling for support we ask that you have the following information available:<br />

1. Version and type of your <strong>CompuScope</strong> <strong>SDK</strong> and drivers.<br />

(The version numbers are indicated on the distribution media. Version numbers can also be obtained<br />

by looking in the appropriate README.TXT files)<br />

2. Type, version and memory depth of your <strong>CompuScope</strong> card.<br />

3. Type and version of your operating system.<br />

4. Type and speed of your computer and bus.<br />

5. Any extra hardware peripherals (i.e. CD-ROM, joystick, network card, etc.)<br />

6. Were you able to reproduce the problem with standalone Gage Software (e.g. GageScope, GageBit,<br />

etc)?


Gage Products<br />

For ordering information, see Gage’s product catalog, or visit our web site at<br />

http://www.gage-applied.com<br />

CompactPCI Bus Products <strong>CompuScope</strong> 85GC 8 bit, 5 GS/s Analog Input Card<br />

<strong>CompuScope</strong> 82GC<br />

8 bit, 2 GS/s Analog Input Card<br />

<strong>CompuScope</strong> 14100C<br />

14 bit, 100 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 1610C<br />

16 bit, 10 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 3200C<br />

32 bit, 100 MHz Digital Input for CompactPCI Bus<br />

PCI Bus Products <strong>CompuScope</strong> 1610 16 bit, 10 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 1602<br />

16 bit, 2.5 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 14200<br />

14 bit, 200 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 14105<br />

14 bit, 105 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 14100<br />

14 bit, 100 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 1450<br />

14 bit, 50 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 12100<br />

12 bit, 100 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 1250<br />

12 bit, 50 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 1220<br />

12 bit, 20 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 85G<br />

8 bit, 5 GS/s Analog Input Card<br />

<strong>CompuScope</strong> 82G<br />

8 bit, 2 GS/s Analog Input Card<br />

<strong>CompuScope</strong> 8500<br />

8 bit, 500 MS/s Analog Input Card<br />

<strong>CompuScope</strong> 3200<br />

32 bit, 100 MHz Digital Input for PCI Bus<br />

CompuGen CompuGen 1100 12 bit, 80 MS/s Analog Output Card<br />

CompuGen 3250<br />

32 bit, 50 MHz Digital Output Card<br />

Application Software GageScope World's Most Powerful Oscilloscope Software<br />

GageBit<br />

Digital Input/Output Software<br />

CompuGen for Windows<br />

Arbitrary Waveform Generator Software for Windows<br />

Software Development Kits<br />

<strong>CompuScope</strong> <strong>SDK</strong> for C/C++ for Windows<br />

<strong>CompuScope</strong> LabVIEW <strong>SDK</strong> for Windows<br />

<strong>CompuScope</strong> MATLAB <strong>SDK</strong> for Windows<br />

<strong>CompuScope</strong> LabWindows/CVI <strong>SDK</strong><br />

(for CompactPCI/PXI bus <strong>CompuScope</strong> cards)<br />

CompuGen Analog <strong>SDK</strong> for C/C++ for Windows<br />

CompuGen Digital <strong>SDK</strong> for C/C++ for Windows<br />

CompuGen Analog LabVIEW <strong>SDK</strong> for Windows<br />

CompuGen Digital LabVIEW <strong>SDK</strong> for Windows<br />

CompuGen Analog MATLAB <strong>SDK</strong> for Windows<br />

CompuGen Digital MATLAB <strong>SDK</strong> for Windows<br />

Instrument Mainframes Instrument Mainframe 7000<br />

Instrument Mainframe 2000<br />

Instrument Mainframe 8000C<br />

Instrument Mainframes for Housing <strong>CompuScope</strong> and<br />

CompuGen Products.<br />

Instrument Mainframes for Housing CompactPCI/PXI<br />

<strong>CompuScope</strong> Products.

Hooray! Your file is uploaded and ready to be published.

Saved successfully!

Ooh no, something went wrong!