Tektronix RISCom-8 Windows Function Call Driver Users Guide
RISCom-8 Windows
Function Call Driv er
USER’S GUIDE
RISCom-8
Windows Function Call Driver
User’s Guide
Revision A - July 1994
Part Number: 77890
New Contact Information
Keithley Instruments, Inc.
28775 Aurora Road
Cleveland, OH 44139
Technical Support: 1-888-KEITHLEY
Monday – Friday 8:00 a.m. to 5:00 p.m (EST)
Fax: (440) 248-6168
Visit our website at http://www.keithley.com
The information contained in this manual is believed to be accurate and reliable. However, Keithley
Instruments, Inc., assumes no responsibility for its use or for any infringements of patents or other rights
of third parties that may result from its use. No license is granted by implication or otherwise under any
patent rights of Keithley Instruments, Inc.
KEITHLEY INSTRUMENTS, INC., SHALL NO T BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES RELATED TO THE USE OF THIS PRODUCT. THIS
PRODUCT IS NOT DESIGNED WITH COMPONENTS OF A LEVEL OF RELIABILITY
SUITABLE FOR USE IN LIFE SUPPORT OR CRITICAL APPLICATIONS.
Refer to your Keithley Instruments license agreement for specific warranty and liability information.
MetraByte is a trademark of Keithley Instruments, Inc. All other brand and product names are
trademarks or registered trademarks of their respective companies.
© Copyright Keithley Instruments, Inc., 1994.
All rights reserved. Reproduction or adaptation of any part of this documentation beyond that permitted
by Section 117 of the 1976 United States Copyright Act without permission of the Copyright owner is
unlawful.
Keithley MetraByte Division
Keithley Instruments, Inc.
440 Myles Standish Blvd. Taunton, MA 02780
FAX: (508) 880-0179
Telephone: (508) 880-3000
●
Preface
The RISCom-8 Windows Function Call Driver User’s Guide describes
how to write application programs for the RISCom-8 board using
Windows DLL function calls. The RISCom-8 Function Call Driver
supports the following Windows-based languages:
●
Microsoft QuickC
for Windows (Version 1.0)
Microsoft Visual C++ (Version 1.0)
●
Borland
●
Borland Turbo Pascal for Windows (Version 1.0 and higher)
●
●
Microsoft Visual Basic for Windows (Version 2.0 and higher)
C/C++ (Version 3.1 and higher)
The manual is intended for application programmers using a RISCom-8
board in an IBM
PC/XT
, PC AT
, or compatible computer. It is
assumed that users have read the RISCom-8 User’s Guide to familiarize
themselves with the board’s features, and that they have completed the
appropriate hardware setup and installation.
It is also assumed that users are experienced in programming in their
selected language and that they are familiar with serial communication
principles.
v
The RISCom-8 Windows Function Call Driver User’s Guide is organized
as follows:
●
Chapter 1 contains the information needed to install the RISCom-8
Windows Function Call Driver, use the configuration program, and
get help, if required.
●
Chapter 2 provides background information about the functions
included in the RISCom-8 Windows Function Call Driver.
Chapter 3 describes how to create application programs in the
●
supported languages.
●
Chapter 4 contains detailed descriptions of the functions, arranged in
alphabetical order.
An index completes this manual.
vi
Table of Contents
Preface
1
Getting Started
Quick Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2
Running the Configuration Program . . . . . . . . . . . . . . . . . . . . . .1-3
Getting Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
Available Operations
2
Initialization Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1
Initializing the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2
Initializing a Communication Port . . . . . . . . . . . . . . . . . . . . .2-2
Resetting all Communication Ports. . . . . . . . . . . . . . . . . . . . .2-3
Setting the Communication Protocol . . . . . . . . . . . . . . . . . . .2-3
Data Movement Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4
Reading Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4
Writing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4
Port Control Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
Controlling the Receiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
Controlling the Transmitter. . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
Controlling the Modem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
Buffer Management Operations. . . . . . . . . . . . . . . . . . . . . . . . . .2-6
Managing the Receive Buffer . . . . . . . . . . . . . . . . . . . . . . . . .2-6
Managing the Transmission Buffer . . . . . . . . . . . . . . . . . . . . .2-6
3
Programming with the Function Call Driver
Programming in Microsoft QuickC for Windows . . . . . . . . . . . .3-1
Programming in Microsoft Visual C++ for Windows . . . . . . . . .3-2
Programming in Borland C++ for Windows . . . . . . . . . . . . . . . .3-3
Programming in Borland Turbo Pascal for Windows . . . . . . . . .3-4
Programming in Microsoft Visual Basic for Windows . . . . . . . .3-4
iii
iv
Function Call Reference
4
K_R8ClearRecBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-3
K_R8ClearTransBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4
K_R8DevOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5
K_R8GetModSignals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-7
K_R8GetNumRecChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-9
K_R8GetStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11
K_R8HandShakeProt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13
K_R8Init. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-15
K_R8ReadString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18
K_R8ReceiveChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20
K_R8Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21
K_R8RXDisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22
K_R8RXEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-23
K_R8SendChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24
K_R8SetBaudRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-26
K_R8SetModSignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-28
K_R8SetParity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-30
K_R8SetStopBits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32
K_R8SetWordLen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-34
K_R8TransBufAvail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-36
K_R8TXDisable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38
K_R8TXEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39
K_R8WriteString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40
K_R8XOFFChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-42
K_R8XONChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44
K_R8XONProt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-46
Index
List of Figures
Figure 2-1. Status of the Communication Port. . . . . . . . . . . . .2-2
Figure 4-1. Value Returned by K_R8GetStatus. . . . . . . . . . .4-11
Figure 4-2. Value Returned by K_R8Init. . . . . . . . . . . . . . . .4-16
Figure 4-3. Value Returned by K_R8SendChar. . . . . . . . . . .4-24
List of Tables
Table 2-1. Supported Operations . . . . . . . . . . . . . . . . . . . . . .2-1
Table 4-1. RISCom-8 DLL Functions. . . . . . . . . . . . . . . . . . .4-1
1
Getting Started
The RISCom-8 W indows Function Call Dri ver is a Dynamic Link Library
(DLL) of communication functions. This Function Call Driver allo ws you
to access the RISCom-8 board from the following Windows-based
languages:
●
Microsoft QuickC
●
Microsoft Visual C++
Borland C++
●
●
Turbo Pascal for Windows
●
Microsoft Visual Basic for Windows.
Included in this software package are the following:
●
Support files, containing program elements, such as function
prototypes and definitions of variable types, that are required by the
functions.
●
Configuration program.
Language-specific example programs that loop back data on the first
●
port of the RISCom-8. Note that you must attach a loopback
connector on the communication port of the RISCom-8 or use a
standard RISCom-8 Octal cable with a loopback plug to read the
characters.
The following sections describe how to install the Function Call Driver,
how to use the configuration program, and how to get additional
assistance, if required.
1-1
Quick Setup
To install the RISCom-8 Windows Function Call Driver, perform the
following steps:
1. Install the RISCom-8 boards as described in the RISCom-8 User’s
Guide , making sure that all boards have a unique base address and
interrupt setting.
2. Insert the RISCom-8 software diskette into a floppy disk driv e of your
computer.
3. Run Windo ws.
4. From the Program Manager File menu, select Run.
5. In the Command Line text box, type the letter of the drive containing
your RISCom-8 diskette, then type SETUP.EXE. For example, if you
diskette is in drive A, type the following:
A:SETUP.EXE
6. Select OK.
7. Respond to the installation prompts, as necessary.
8. Run the CFGR8W.EXE configuration program, described in the next
section, and answer the prompts as they appear to configure the driver
from the Windows program group.
Once you complete this procedure, you can write Windows application
programs that use the functions described in Chapters 2 and 4 to
communicate with the RISCom-8 boards. Refer to Chapter 3 for
language-specific programming information.
1-2 Getting Started
Running the Configuration Program
You can use multiple RISCom-8 boards in one computer. If you use four
boards, the ports are accessed as ports 0 to 31.
Run the configuration program, CFGR8W.EXE, every time you add a
new RISCom-8 board to your system. The program creates and/or edits a
configuration file you specify. You can name the configuration file any
name you like, such as RISCOM8.CFG.
Specify the following parameters in the configuration file:
●
Number of RISCom-8 boards used
●
Base address of each RISCom-8 board
Getting Help
Interrupt (IRQ) setting of each RISCom-8 board
●
Interface type (such as, RS-232, RS-422/485) of each RISCom-8
●
board
The following is an example of a configuration file:
[RISCOM8]
BOARD1=P 544, I 11, R RS232
BOARD2=P 576, I 10, R RS232
In this example, two RISCom-8, RS-232 boards are configured in the
system. One board is set up with a base address of 220h (544 decimal)
and an IRQ of 11; the other board is set up with a base address of 240h
(576 decimal) and an IRQ of 10.
If you need help installing or using the RISCom-8 Windows Function
Call Driver, call your local sales office or the Keithley MetraByte
Applications Engineering Department at:
(508) 880-3000
Monday - Friday, 8:00
A.M.
- 6:00
P.M.
, Eastern Time
1-3
An applications engineer will help you diagnose and resolve your
problem over the telephone. Please make sure that you hav e the follo wing
information available before you call:
RISCom-8 board
configuration
Computer
Operating system
Software package
Model
Serial #
Revision code
Base address setting
Interrupt level setting
Manufacturer
CPU type
Clock speed (MHz)
KB of RAM
Video system
BIOS type
Windows version
Windows mode
Name
Serial #
Version
Invoice/Order #
___________________
___________________
___________________
___________________
___________________
_____
___________________
___________________
___________________
___________________
___________________
___________________
______
___________________
___________________
___________________
___
___________________
___________________
___________________
___________________
____
Compiler
(if applicable)
Accessories
1-4 Getting Started
Language
Manufacturer
Version
Type
Type
Type
Type
Type
Type
Type
Type
___________________
___________________
___________________
___
___________________
___________________
___________________
___________________
___________________
___________________
___________________
___________________
________
2
Available Operations
This chapter provides the background information you need to use the
functions to perform communication operations on the RISCom-8 board.
The supported operations are listed in Table 2-1.
Table 2-1. Supported Operations
Operation Page Reference
Initialization page 2-1
Data Movement page 2-4
Port Control page 2-5
Buffer Management page 2-6
Initialization Operations
This section describes the functions provided in the RISCom-8 Windows
Function Call Driver to perform the following initialization operations:
●
Initializing the driver
●
Initializing a communication port
●
Resetting all communication ports
Setting the communication protocol
●
2-1
Initializing the Driver
Before you can use any of the functions included in the RISCom-8
Windows Function Call Driver, you must initialize the driver using the
K_R8DevOpen function.
K_R8DevOpen initializes the driver according to a configuration file you
specify and returns an error/status code indicating whether the driver was
initialized successfully. Refer to page 1-3 for more information about
creating a configuration file for RISCom-8 boards; refer to page 4-5 for
information on the error/status codes.
Initializing a Communication Port
If you use four RISCom-8 boards, the communication ports are accessed
as ports 0 to 31. To initialize a specified communication port, you can use
the following functions:
Bit 7 = 1;
Timed
Out
Bit 7 = 1;
RCD
On
Bit 6 = 1;
TxSR
Empty
Bit 6 = 1;
RI
On
●
K_R8Init - Initializes the specified communication port with a
specified parity (none, even, or odd), number of stop bits (one or
two), number of bits in the word to transfer (five to eight bits), and
baud rate (110 to 76800). This function also returns the status of the
communication port. The status consists of two bytes, as shown in
Figure 2-1.
Low Byte, Port Status
Bit 5 = 1;
TxHR
Empty
Bit 5 = 1;
DSR
On
Bit 4 = 1;
Break
On
High Byte, Modem Status
Bit 4 = 1;
CTS
On
Bit 3 = 1;
Frame
Error
Bit 3 = 1;
DCD
Changed
Bit 2 = 1;
Parity
Error
Bit 2 = 1;
RI
Changed
Figure 2-1. Status of the Communication Por t
Bit 1 = 1;
Overrun
Error
Bit 1 = 1;
DSR
Changed
Bit 0 = 1;
Data
Ready
Bit 0 = 1;
CTS
Changed
2-2 Available Operations
K_R8SetParity - Sets the parity for a specified communication port
●
to either none, even, or odd. This function also returns the previously
programmed parity value.
K_R8SetStopBits - Sets the number of stop bits for a specified
●
communication port to either one or two. This function also returns
the previously programmed stop bits value.
K_R8SetWordLen - Sets the number of bits in the word to transfer
●
(the word length) for the specified communication port to either five,
six, seven, or eight bits. This function also returns the previously
programmed word length.
●
K_R8SetBaudRate - Sets the baud rate for the specified
communication port to either 110, 150, 300, 600, 1200, 2400, 4800,
9600, 19200, 38400, 57600, or 76800. This function also returns the
previously programmed baud rate.
Resetting all Communication Ports
To reset all communication ports on the RISCom-8 boards, use the
K_R8Reset function. This function returns the number of RISCom-8
boards present.
Setting the Communication Protocol
T o set a communication protocol for a specified communication port, you
can use the following functions:
K_R8HandShakeProt - Specifies whether CTS and RTS (hardware
●
handshaking signals) are enabled or disabled for transmit operations.
K_R8XONProt - Specifies whether XON is enabled or disabled for
●
receive operations.
K_R8XONChar - Specifies the ASCII character that enables the
●
XON operation.
K_R8XOFFChar - Specifies the ASCII character that enables the
●
XOFF operation.
2-3
Data Movement Operations
This section describes the functions provided in the RISCom-8 Windows
Function Call Driver to perform the following data movement operations:
●
Reading data
Writing data
●
Reading Data
To read data from a specified communication port, you can use the
following functions:
●
K_R8ReceiveChar - Returns one character. This function also
returns the status of the communication port, shown in Figure 2-1.
Writing Data
●
K_R8ReadString - Reads a specified number of characters from a
string. This function also returns the number of characters read from
the receive buffer..
●
K_R8GetStatus - Returns the status of the communication port and
the modem as two bytes, shown in Figure 2-1.
To write data to a specified communication port, you can use the
following functions:
K_R8SendChar - Writes one character. This function also returns
●
the status of the communication port. Refer to Figure 2-1 for the
format of the value returned.
●
K_R8WriteString - Writes a specified number of characters in a
string. This function also returns the actual number of characters
written to the transmission buffer.
2-4 Available Operations
Port Control Operations
This section describes the functions provided in the RISCom-8 Windows
Function Call Driver to perform the following operations:
●
Controlling the receiver
Controlling the transmitter
●
Controlling the modem
●
Controlling the Receiver
T o control the recei ver of a specified communication port, you can use the
following functions:
●
K_R8RXEnable - Enables the receiver.
K_R8RXDisable - Disables the receiver.
●
Controlling the Transmitter
To control the transmitter of a specified communication port, you can use
the following functions:
●
K_R8TXEnable - Enables the transmitter.
K_R8TXDisable - Disables the transmitter.
●
Controlling the Modem
T o control the modem on a specified communication port, you can use the
following functions:
●
K_R8SetModSignals - Sets the RTS and DTR signals on or off.
●
K_R8GetModSignals - Returns the state of the RTS and DTR
signals.
2-5
Buffer Management Operations
This section describes the functions provided in the RISCom-8 Windows
Function Call Driver to perform the following buffer management
functions:
●
Managing the receive buffer
●
Managing the transmission buffer
Managing the Receive Buffer
To manage the receive buffer of a specified communication port, you can
use the following functions:
K_R8ClearRecBuf - Clears the receive buffer.
●
●
K_R8GetNumRecChar - Returns the number of characters in the
receive buffer.
Managing the Transmission Buffer
To manage the transmission buffer of a specified communication port,
you can use the following functions:
K_R8ClearTransBuf - Clears the transmission buffer.
●
K_R8TransBufAvail - Returns the space available in terms of the
●
number of characters that can be sent to the transmission buffer
before an overflow error occurs.
2-6 Available Operations
3
Programming with the
Function Call Driver
This chapter describes how to create an application program in each of
the supported languages using the RISCom-8 Windows Function Call
Driver.
Programming in Microsoft QuickC for Windows
To program in Microsoft QuickC for Windows, you need the following
files:
File Description
RISCOM8.DLL Dynamic Link Library.
RISCOM8.H Include file.
To create an executable file in Microsoft QuickC for Windows, perform
the following steps:
1. Load filename .c into the QuickC for Windows environment, where
filename indicates the name of your application program.
2. Create a project file. The project file should contain all necessary
files, including filename .c, filename .rc, filename .def, filename .h, and
RISC8IMP.LIB, where filename indicates the name of your
application program.
3-1
3. From the Project menu, choose Build to create a stand-alone
executable file (.EXE) that you can execute from within Windows.
3-2 Programming with the Function Call Driver
Programming in Microsoft Visual C++ for Windows
To program in Microsoft Visual C++, you need the following files:
File Description
RISCOM8.DLL Dynamic Link Library.
RISCOM8.H Include file for C.
RISCOM8.HPP Include file for C++.
To create an executable file in Visual C++, perform the following steps:
1. Create a project file by choosing New from the Project menu. The
project file should contain all necessary files, including filename .c,
filename .rc, filename .def, and RISC8IMP.LIB, where filename
indicates the name of your application program.
2. From the Project menu, choose Rebuild All FILENAME.EXE to
create a stand-alone executable file (.EXE) that you can execute from
within Windo ws.
3-3
Programming in Borland C++ for Windows
To program in Borland C++, you need the following files:
File Description
RISCOM8.DLL Dynamic Link Library.
RISCOM8.H Include file for C.
RISCOM8.HPP Include file for C++.
To create an executable file in Borland C++, perform the following steps:
1. Create a project file by choosing Open from the Project menu and
entering a project name. The project file should contain all necessary
files, including filename .c, filename .rc, filename .def, and
RISC8IMP.LIB, where filename indicates the name of your
application program.
2. From the Compile menu, choose Build All FILENAME.EXE to
create a stand-alone executable file (.EXE) that you can execute from
within Windo ws.
3-4 Programming with the Function Call Driver
Programming in Borland Turbo Pascal for Windows
To program in Borland Turbo Pascal for Windows, you need the
following files:
File Description
RISCOM8.DLL Dynamic Link Library.
RISCOM8.INC Include file.
To create an executable file in Borland Turbo Pascal for Windows,
perform the following steps:
1. Load filename .pas into the Borland Turbo Pascal for Windows
environment, where filename indicates the name of your application
program.
2. From the Compile menu, choose Make.
Programming in Microsoft Visual Basic for Windows
To program in Microsoft Visual Basic for Windows, you need the
following files:
File Description
RISCOM8.DLL Dynamic Link Library.
VBWDECL.BAS Include file.
To create an executable file from the Microsoft Visual Basic for Windows
environment, choose Make EXE File from the Run menu.
3-5