Comtrol API 6508 User Manual

1

RocketPort/ISA

API (6508) for the MS-DOS

Operating System

First Edition, December 1993
Revised April 1994

Copyright © 1993, 1994, 1995, 1996. Comtrol Corporation.
All Rights Reserved.
Comtrol Corporation makes no representations or warranties with regard to

the contents of this guide or to the suitability of the Comtrol
controllers for any particular purpose.

RocketPort

Trademarks

The Comtrol logo is a registered trademark of Control Systems, Inc.
Comtrol is a trademark of Comtrol Corporation.
The RocketPort series is a registered trademark of Comtrol Corporation.
Borland is a registered trademark of Borland International, Inc.
Microsoft and
Product names mentioned herein may be trademarks and/or registered

trademarks of their respective companies.

MS-DOS are registered trademarks of Microsoft Corporation.

Document Number: 6508D1.

ELE

2

Before You Begin

Scope

This guide describes the following information about the DOS application
program interface (

• Installing the software and hardware

• Running the sample application

• Developing applications

Note: If you want to install the Interrupt 14 device driver, see the Reference

Card.

API) for RocketPort controllers:

Purpose

This guide explains installing and using the API functions.

Audience

This guide is for people who develop applications for the MS-DOS system.

Prerequisites

This guide assumes that you are running an ISA-based personal computer
with the following:

MS-DOS operating system (level 5.0 or higher)

•

• One of the following compilers:

®

- A Borland

- A Microsoft

C++ compiler (level 3.1 and higher)

®

C/C++ compiler (level 7.0 and higher)

Organization

Section 1. Installing RocketPort Systems

Provides you with the following information:

• Product introduction

• Software and hardware installation overview

• Installing the software and hardware

• Configuring controllers

• Running the sample application

Section 2. Developing Applications

Provides you with information about how to develop applications using the

Section 3. Troubleshooting and Technical Support

Provides you with troubleshooting and technical support information for your
RocketPort series controller.

Appendix A.

Contains the

Appendix B. Double Buffering Example

Illustrates the double buffering example on your diskette.

API Functions

API asynchronous functions available for writing the application.

API.

Software or Document Changes

For information that is not in this guide, see the README.API file on the
software diskette. If this file is empty, that means that this guide reflects the

API on the diskette.

Suggestions

Use Chapter 1 to install the API. Use Chapter 2 and AppendixA to develop
applications that run with the

API. If you have any problems, see Chapter 3.

3

Table of Contents

Before You Begin

Scope ...........................................................................................2

Purpose........................................................................................2

Audience......................................................................................2

Prerequisites...............................................................................2

Suggestions.................................................................................2

Organization...............................................................................2

Software or Document Changes ................................................2

Table of Contents

Examples.....................................................................................3

Flowchart....................................................................................4

Tables..........................................................................................4

Section 1. Installing RocketPort Systems

1.1. Product Introduction.........................................................5

1.2. Software and Hardware Installation Procedures............5

1.3. Installing the Software.....................................................5

1.4. Installing the Controller...................................................7

1.5. Running the Sample Application .....................................8

Section 2. Developing Applications

API Features......................................................................9

2.1.

API Functions ....................................................................9

2.2.

2.3. Writing the Configuration File.......................................10

2.4. Flowchart for Using the

2.5. Application Example.......................................................11

2.6. Include Files (Step 3)......................................................12

2.7. Configuring RocketPort Controllers (Step4).................12

2.8. Using

2.9. Writing Serial Data.........................................................15

2.10. Exiting the Application...................................................15

2.11. Reading Serial Data........................................................15

2.12. Installing and Detecting Events.....................................15

2.13. Double Buffering Transmit and Receive Data .............17

API Calls (Step 5)..................................................12

2.8.1. Understanding Device Numbers.........................13

2.8.2. Configuration Parameters for Serial Devices ....13

2.8.2.1. Open Type Parameter...........................13

2.8.2.2. Baud Parameter ....................................14

2.8.2.3. Parity Parameter...................................14

2.8.2.4. Data Bits Parameter .............................14

2.8.2.5. Stop Bits Parameter..............................14

2.8.2.6. Flow Control Parameter........................14

2.8.2.7. Detection Enable Parameter.................15

2.8.2.8. Modem Control Parameter ...................15

API...........................................11

2.14. Building Applications (Step 6).......................................17

Section 3. Troubleshooting and Technical Support

3.1. Resolving Installation Problems....................................18

3.2. Placing a Support Call....................................................19

3.3. Retrieving Future Software Updates ............................20

Appendix A.

Appendix B. Double Buffering Example

API Functions

aaChangeModemState....................................22

aaClose.............................................................22

aaEnPeriodicEvent..........................................23

aaExit...............................................................23

aaFlush ............................................................24

aaGetCtlStatus................................................24

aaGetModemStatus.........................................25

aaGetRxCount.................................................25

aaGetRxStatus ................................................26

aaGetTxCount .................................................26

aaInit................................................................27

aaInstallCtrlCHandler....................................27

aaInstallMdmChgEvent..................................28

aaInstallPeriodicEvent ...................................28

aaInstallRxEvent ............................................29

aaOpen.............................................................29

aaRead .............................................................30

aaReadWithStatus ..........................................31

aaReconfigure..................................................31

aaSendBreak ...................................................32

aaSetCloseDelay..............................................33

aaWrite ........................................................... 33

EvModemChange ............................................34

EvPeriodic........................................................35

EvRxData.........................................................35

Examples

Example 2-1. Sample Event Function....................................16

4

Flowcharts

Tables

Flowchart 1-1. Hardware and Software Installation

Overview ...........................................................5

Flowchart 2-1. How to Use the

API.........................................11

Table 1-1. Common Switch Settings.......................................6

Table 2-1.

API Functions..........................................................9

Table 2-2. Configuration File Parameters............................10

Table 2-3. Mapping Device Numbers....................................13

Table 2-4. Open Type Flags...................................................13

Table 2-5. Baud Flags............................................................13

Table 2-6. Parity Flags ..........................................................14

Table 2-7. Data Bits Flags.....................................................14

Table 2-8. Stop Bits Flags......................................................14

Table 2-9. Flow Control Flags ...............................................14

Table 2-10. Detection Enable Flags ........................................15

Table 2-11. Modem Control Output Flags..............................15

Table 3-1. System
Table 3-2. System

I/O Addresses – Up to 3FF ......................18

I/O Address Aliases – Above 3FF............18

Table 3-3. Support Call Information.....................................19

Table A-1.

API Function Reference........................................21

5 Installating RocketPort/ISA Systems

Section 1. Installating RocketPort/ISA Systems

This section contains a product overview and discusses installing the API for
your system. The

DOS API and Interrupt 14 device driver are delivered on one

diskette.

Note: See the Int 14 Reference Card for Interrupt 14 information.

1.1. Product Introduction

The RocketPort multiport serial controller series fits into a 16-bit ISA slot of a
personal computer. The RocketPort series uses a 36
designed to process asynchronous serial communications, thereby maximizing
performance and eliminating bottlenecks.

RocketPort series uses Application Specific Integrated Circuits (
technology to replace most hardware components, including:

• The processor

• Serial controller

• Bus interface logic and other miscellaneous logic
The RocketPort series is
The RocketPort series supports

I/O mapped eliminating memory mapping conflicts.

RS-232 or RS-422 mode and connects easily to

the interface box or your peripherals, depending on the type of RocketPort
controller you purchased.

The device driver supports up to four RocketPort controllers (128 ports) in one

PC. You can install any combination of the series, which includes the following:

Name

Number

of Ports

RocketPort 4* 4 Requires interface box
RocketPort 4J 4 RJ45 cables not included

RocketPort Quadcable* 4

Includes a fanout cable with standard DB25 or

DB9 connectors

RocketPort 8 8 Requires interface box
RocketPort 8J 8 RJ11 cables not included

RocketPort Octacable 8

RocketPort 16 16

RocketPort 32 32

Includes a fanout cable with standard DB25 or

DB9 connectors

Requires 16-port interface box (Standard DB25
or Rack Mount RJ45 available)

Requires two 16-port interface boxes (Standard

DB25 or Rack Mount RJ45 available)

The RocketPort series is easy to install using Subsection 1.2.

MHz processor specifically

ASICs)

Interface Type

1.2. Software and Hardware Installation Procedures

Use Flowchart1-1 for an overview of installing a RocketPort series system.

Install the API (see 1.3).

Set the switches on the controller and
install the controller (see 1.4).

Update the

Connect the interface box to the controller
your peripherals to the interface box (if you have not already
done so). For specific cabling information, see the appropriate
Hardware Reference Card.

Develop applications using Section 2 and Appendix A.

AUTOEXEC.BAT file.

(if applicable) and

Flowchart 1-1. Hardware and Software Installation Overview

Note: If you have an installation or operations problem, see Chapter 3.

1.3. Installing the Software

You may want to install the API in a directory named \ROCKET so that the
examples illustrated in this guide match your environment.

The following shows a sample installation onto your hard disk (assuming the
hard disk is drive C):

1. Insert the Comtrol
appropriate drive.

2. Change to the drive that you installed the diskette on.

3. Enter the following:

install

4. Select the API button by pressing <Enter> or <Click>. <Click> means that
you should move the cursor over the item and press the mouse button.

API and Device Driver for MS-DOS diskette into the

6 Installating RocketPort/ISA Systems

Installating RocketPort/ISA Systems

ON

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

Controller #3 Controller #4

ON

ON

ON

ON

Note: Press <F1> on any item for button-sensitive Help.

5. Select the
a. Use the<Tab> key and the <

<click> on the arrow next to the

I/O address range for each RocketPort series controller.

ALT> <Down Arrow> key combination or

I/O Address Range box to view the I/O

address ranges.

b. Use an <Arrow> key or the mouse cursor to highlight the

I/O range you

want to select.

c. Press <Enter> or <Click> to execute the selection.

I/O address identifies the location in the system’s I/O space used to pass

The
control information between the system and the controller.

For the first controller, you will select a 68-byte

I/O address range. For

subsequent controllers, you will select a 64-byte range.
Most peripherals use

I/O address ranges between 0 and 3FF hexadecimal.

If you have peripherals installed above 400h, you may experience an
conflict.

RocketPort controllers use

I/O address range. Make sure that other peripherals in the system do not

use these

I/O usage.

I/O address ranges. See Table3-1 for information about common

4. Enter a path name for the
default path,

5. Select an interrupt (

\ROCKET.

IRQ) for the controller that does not conflict with an

I/O address ranges at 400h intervals above the

API directory, if you do not want to use the

existing interrupt.

6. Select <Ok to Install>.

7. Select <

8. Set the

OK> at the confirmation screen.

DIP switches on the controller as directed in the summary screen.

You may want to fill in the blank switches provided for you or place a check
mark in Table 1-1, which illustrates common

Press <

ENTER> to view the DIP switch settings for additional controllers.

I/O ranges.

I/O

if you do not set them at this time.

9. Make sure that you note the line that you must add to the

AUTOEXEC.BAT

file. For example:

SET ROCKETCFG=C:\ROCKET\CONFIG.DAT

This path is the same path where the

API is installed.

Note: After you create your own applications, you may need to change the

configuration file (see Subsection 2.3).

10. When your cursor returns to the

DOS prompt, remove the diskette from the

drive.

11. Edit the

AUTOEXEC.BAT file as directed in Step 9.

Go to the next subsection to install the controller.

Table 1-1. Common Switch Settings

Controller #1

I/O Address

Range

100 - 143 hex

140 - 183 hex

1st ISA 2nd ISA

3rd ISA 4th ISA

1st ISA 2nd ISA

3rd ISA 4th ISA

DIP Switch Settings

Controller #1 determines other

controller settings

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

Controller #1 Controller #2

Notes:You may want to set the

DIP switches for the controllers while

180 - 1C3 hex
(Default)

1st ISA 2nd ISA

3rd ISA 4th ISA

ON

1 2 3 4 5 6 7 81 2 3 4 5 6 7 8

ON

looking at the summary screen.
You can also use the

\ROCKET\INSTALL.LOG file to set the switches,

Installating RocketPort/ISA Systems

O

ON

ON

ON

ON

ON

ON

3rd ISA

4th ISA

ON

ON

Table 1-1. Common Switch Settings (Continued)

Controller #1

I/O Address

Range

200 - 243 hex

240 - 283 hex

280 - 2C3 hex

300 - 343 hex

340 - 383 hex

1st ISA 2nd ISA

3rd ISA 4th ISA

1st ISA 2nd ISA

3rd ISA 4th ISA

1st ISA 2nd ISA

3rd ISA 4th ISA

1st ISA 2nd ISA

3rd ISA 4th ISA

1st ISA 2nd ISA

DIP Switch Settings

Controller #1 determines other

controller settings

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 81 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 81 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

N

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

Table 1-1. Common Switch Settings (Continued)

Controller #1

I/O Address

Range

380 - 3C3 hex

1st ISA 2nd ISA

3rd ISA 4th ISA

DIP Switch Settings

Controller #1 determines other

controller settings

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1 2 3 4 5 6 7 8

ON

1 2 3 4 5 6 7 8

1.4. Installing the Controller

To prepare your controller for installation, you may need to set the I/O address

DIP switch. The default I/O address range is 180 through 1C3. You must

change the
select the default address range.

If you did not set the
software installation, do so at this time. Make sure that you set each controller
as advised during the software installation or use the information in the

\ROCKET\INSTALL.LOG file.

After you set the
following steps to install the controller:

1. Turn the power switch for the system unit to the

2. Remove the system unit cover.

3. Select a slot to install the controller.

4. Remove the expansion slot cover.

5. Insert the controller in the expansion slot, make sure that it is properly
seated.

6. Attach the controller to the chassis with the expansion slot screw. Repeat
Steps3 through 5 for each controller.

7. Replace the cover on the system unit.

If connecting a system with an interface box:

a. Attach the male end of the RocketPort cable to the controller and the

Note: If you have a RocketPort 32, the connector labelled J1 corresponds to

b. Connect the peripherals to the interface box.

Note: The ports on the interface box are numbered from 0 to 3, 7, or 15 on the

I/O address settings on any additional controllers, even if you

DIP switch on the controller or controllers during the

I/O DIP switch, you are ready to install the controller. Use the

OFF position.

female end to the connector on the interface box labeled Host.

ports 0 through 15 on the interface box and the connector labeled J2
(closest to the bus) corresponds to ports 16 through 31.

standard

DB25 interface. The Rack Mount RJ45 interface is numbered

Installating RocketPort/ISA Systems 7

8 Installating RocketPort/ISA Systems

Installating RocketPort/ISA Systems

from 1 to 16.

c. If applicable, set each port to the appropriate communications mode

RS-232 or RS-422) for your peripheral using the slide switch.

(

If connecting a system with a Quad/Octacable:

a. Attach the male end of the Quad/Octacable to the controller.
b. Connect the Quad/Octacable to the peripherals.

If connecting a RocketPort

a. Connect your peripheral devices to the

4J or 8J controller:

RJ style connector on the

controller.

After installing and configuring the controller, you are ready to attach your
peripherals. Refer to the Hardware Reference Card if you need information
about the pinouts for the connectors.

After connecting the peripherals, you can go to the next subsection to run the
sample application. The sample application shows you how to use the

API.

Use Section 2 and Appendix A to develop applications.

1.5. Running the Sample Application

The sample program, TERM, is a simple terminal emulator program which
uses one RocketPort port at a time.
port 0 of the Comtrol interface box with an
for both transmit and receive. The terminal should be configured for 9,600
baud, 8 data bits, 1 stop bit, and no parity.

Optionally, if you do not have an available terminal to run the sample
application, you can use the loopback plug that came with your controller.

Note: If your configuration is different, you must change the parameters in the

aaOpen call to match your requirements. Make sure you recompile before
running the sample program.

Use the following procedure to run the sample program:
At the

12. Type

DOS prompt, change to the c:\ROCKET\SAMPLE directory.

TERM at the DOS prompt. The following displays:

Serial Device Number:

Optionally, insert the loopback plug in Port 0 of the interface box.

TERM uses an ASCII terminal connected to

RS-232 cable. This allows testing

13. Type 0 and then press <Enter>. The following displays:

Serial Device Number 0 Hit F10 to Quit

The

TERM application allows you to type any character on the PC keyboard

and have it appear on the terminal, and type any character on the terminal
and have it appear on the

PC screen.

Optionally, if you are using the loopback plug, any character that you type
on the keyboard appears on the screen.

14. Enter several characters using the
keystrokes appear on the

ASCII terminal.

15. Enter several characters using the
see these keystrokes appear on the

PC keyboard. You should see these

ASCII terminal keyboard. You should

PC screen.

If the sample fails, see Section 3.
Use Section 2 and Appendix A to develop applications.

9 Developing Applications

Section 2. Developing Applications

This section describes the following topics:

API features and functions

•

• Writing the configuration file

• Using the

• Include files

• Configuring the controllers

• Using

- Understanding device numbers

- Configuration parameters for serial devices

• Writing serial data

• Exiting the application

• Reading serial data

• Installing and detecting events

• Building applications

API (flowchart and example)

API calls to write the application

2.1. API Features

The API contains the following features:

• Supports up to 4 RocketPort controllers in a

• Supports up to 32 serial devices per controller.

• Provides baud rates from 50 to 230.4 K baud.

• Supports all modem control lines available on the controller.

• Provides detection of modem control line changes.

• Provides direct control of modem control outputs.

• Provides direct read of modem control inputs.

• Provides detection of receive errors:

- Parity

- Receiver overrun

- Framing

- Buffer overflow

• Supports
buffering.

• Supports hardware (

• Supports software (

• Provides read counts of buffered transmit and receive data.

1K bytes of receive data buffering and 256 bytes of transmit data

RTS/CTS) flow control.

XON/XOFF) flow control.

PC.

• Provides send break and receive break detection.

• Provides installable event functions for the following:

- Receive data available

- Modem control changes

- Periodic event

For information about event functions see Subsection 2.12.

2.2. API Functions

Table2-1 lists API functions that are available to a system application. For
detailed information about the functions, see AppendixA.

Table 2-1.

Function Name Description

aaChangeModemState Changes the state of modem

aaClose Closes a device.
aaEnPeriodicEvent Enables/disables dispatching of

aaExit Performs cleanup when exiting

aaFlush Flushes transmit or receive

aaGetCtlStatus Gets controller status.
aaGetModemStatus Gets modem status.
aaGetRxCount Gets count of data bytes available

aaGetRxStatus Gets status of receive buffer.
aaGetTxCount Gets count of data bytes in

aaInit Executes controller and

aaInstallCtrlCHandler Installs a handler for the

API Functions

output lines.

periodic event function.

application.

buffer, or both.

in receive buffer.

transmit buffer.

API

initialization.

CTRL+C

key interrupt.

10 Developing Applications

Table 2-1.

API Functions (Continued)

Function Name Description

aaInstallMdmChgEvent Installs an event function to

handle modem change events.

aaInstallPeriodicEvent Installs a periodic event function.
aaInstallRxEvent Installs an event function to

handle Rx data available events.

aaOpen Opens a device for reading or

writing, or both.

aaRead Reads serial data.
aaReadWithStatus Reads serial data and status.
aaReconfigure Reconfigures communication

parameters.

aaSendBreak Sends a break signal.
aaSetCloseDelay Sets the maximum aaClose()

transmit drain delay.

aaWrite Writes serial data.
EvModemChange* Modem control input change

event function.

EvPeriodic* Periodic event function.
EvRxData* Receive data available event

function.

* These are not part of the API, but are part of the application.

2.3. Writing the Configuration File

The configuration file is used by the aaInit() function to obtain information
about all the RocketPort controllers installed in the system. The aaInit()
function checks the
and path of this file.

When you installed the
were instructed to place the following line in your AUTOEXEC.BAT file:

SET ROCKETCFG=filepath

where filepath is the complete path to the configuration file. This path is the
same path where the

ROCKETCFG environment variable to determine the name

API, the configuration file was created for you, and you

API was installed.

The initial configuration file allows you to run the sample application program
(

TERM), but when you create and distribute your own application you may wish

to use a different configuration file.
The configuration file contains between two and five lines:

• The first line gives the

IRQ number that is used by all RocketPort

controllers.

• The second through fifth lines give the starting

I/O addresses for the first

through the fourth controllers

The first controller uses a 68-byte block of
controllers use 64-byte blocks.

I/O address lines should be placed in the file only

I/O address space, subsequent

for controllers that are actually installed in the system. Table2-2 summarizes
this information.

Table 2-2. Configuration File Parameters

Line

Number

1

Parameter Allowable Values

IRQ number 3, 4, 5, 9, 10, 11, 12,

Block

Size

NA

15

2 Ctrl 1 I/O 100, 140, 180, 1C0,

68 bytes
200, 240, 280, 2C0,
300, 340, 380

3 Ctrl 2

I/O 100, 140, 180, 1C0,

64 bytes
200, 240, 280, 2C0,
300, 340, 380

4 Ctrl 3

I/O 100, 140, 180, 1C0,

64 bytes
200, 240, 280, 2C0,
300, 340, 380

5 Ctrl 4

I/O 100, 140, 180, 1C0,

64 bytes
200, 240, 280, 2C0,
300, 340, 380

Each RocketPort controller uses up to three additional “alias”

I/O address

ranges located at 400h intervals above the address ranges described above.
For example, if the first controller is addressed at 100, the

I/O address ranges

used by that controller are:

• 100 - 143

• 500 - 543

• 900 - 943

• D00 - D43
This is normally of no concern because

I/O addressing, meaning they are limited to addresses below 400h.

ISA peripherals often use only 10 bits of

Note: In order for your application to locate the configuration file, the

ETCFG
SET

environment variable must point to it. This is done with the DOS

command, usually placed in the AUTOEXEC.BAT file.

ROCK-

Step 1

Step 2

Create a new subdirectory called

Copy the appropriate make file from the

\ROCKET\SAMPLE directory into the
\ROCKET\CUSTOM directory.

Developing Applications

\ROCKET\CUSTOM.

2.4. Flowchart for Using the API

This subsection contains the steps required to write and execute an
application program using the
in the following subsections.

The remainder of this chapter assumes that the
named
directory called

\ROCKET, and that you will place your application source code in a new

\ROCKET\CUSTOM.

You may wish to create your own directory structure for source code. In that
case, these instructions and the make files must be adjusted accordingly. A
complete application demonstrating the use of the

\ROCKET\SAMPLE directory.

API. Each of these steps are described in detail

API is installed in a directory

API is provided in the

Step 3

Step 4

Step 5

Step 6

Step 7

Write the application source files. Make sure that
you provide #include statements for the

The first action in the main() is to call the
aaInstallCtrlCHandler() and aaInit() functions.

Write the remainder of your application using API
calls to access the serial devices as needed:
* Open, reconfigure, and close
* Write and read serial data
* Modem control outputs
* Receive and modem change events
* Call aaExit() before leaving the application

Build the application.

Execute the application.

Flowchart 2-1. How to Use the

API.H file.

API

2.5. Application Example

The following application corresponds to the previous flowchart and the
following subsections explain specific steps in detail.

#include <stdio.h>
#include <dos.h>
#include <process.h>
#include <stdlib.h>
#include <conio.h>
#include "api.h" Step 3

main(void)
{
unsigned int InitReturn;
char Buf[80];
int i,Dev,Cnt,Err;

(2.6)

Developing Applications 11

12 Developing Applications

Developing Applications

/* Initialize API */
aaInstallCtrlCHandler();
if((InitReturn = aaInit()) !=
{ (2.7)
printf("Init fail: %x\n",InitReturn);
aaExit();
exit(1);
}

/* Get serial device and display terminal emulator screen */
printf("Serial Device Number (0-15): ");
gets(Buf); /* get serial device */ Step 5
sscanf(Buf,"%d",&Dev); (2.8­ system("cls"); /* clear screen */ 2.12)
printf("Serial Device Number %d\t\t\tHit F10 to Quit\n",Dev);

/* Open the device */
if((Err = aaOpen(Dev,

COM_TX | COM_RX,
COM_BAUD_9600,
COM_PAR_NONE,
COM_DATABIT_8,
COM_STOPBIT_1,
COM_FLOW_NONE,
COM_DEN_PARITY | COM_DEN_RXOVR | COM_DEN_FRAME,
COM_MDM_DTR)) != 0)

{
printf("Failure - Could not open device number %d, Error
%d\n",Dev,Err);
aaExit(); /* required
exit(1); (2.13)
}
/* Infinite loop to handle console
while(1)
{
/* Attempt to read char from serial device and write to screen */
if((Cnt = aaRead(Dev,80,(unsigned char *)Buf)) > 0)
{
for(i = 0;i < Cnt;i++)
putch(Buf[i]);
}

/* Attempt to read char from keyboard and write to serial device */
if((bdos(11,0,0) & 0xff) == 0xFF) /* if char waiting */
{
Buf[0] = bdos(8,0,0) & 0xff; /* read keybd char */
if((Buf[0] == '\0') && ((bdos(11,0,0)&0xff) == 0xff)) /* 2 char key */
{
Buf[1] = bdos(8,0,0) & 0xff; /* 2nd key */
if(Buf[1] == 0x44) /* F10 = quit */
break;
}
aaWrite(Dev,1,(unsigned char *)Buf); /* write char to serial device */
}
}

NO_ERR) Step 4

API call before exiting */ Step 6

I/O and serial I/O */

aaClose(Dev,
aaExit(); /* required
return(0);
}

COM_MDM_RTS | COM_MDM_DTR); /* close device */

API call before exiting */

2.6. Include Files (Step 3)

The API.H file must be included in the .C source code files.

2.7. Configuring RocketPort Controllers (Step4)

Configuration of the RocketPort controllers and the API is done using aaInit(),
as shown in the previous example. The aaInit() function must be called once
before any other

API function (except aaInstallCtrlCHandler()) can be called. It

performs the configuration using the information in the configuration file
given in the

ROCKETCFG environment variable. See Subsection 2.3 for

information about the format and placement of the configuration file.from the
system configuration. See Subsection 2.3 for information about the system
configuration.

Many applications also require that the

DOS default CTRL+C key handler be

replaced with a handler that calls aaExit() (see Subsection 2.10). This is done
using aaInstallCtrlCHandler(). Once installed, this handler calls aaExit() if the
user terminates the application by pressing the

CTRL+C or CTRL+BREAK keys.

If the application prevents program termination with these keys, the
aaIntallCtrlCHandler() function does not need to be called.

2.8. Using API Calls (Step 5)

The following subsections provide details about Step 5 of the API sample. The
topics include:

• Device numbers

• Configuration parameters for opening, closing, and reconfiguring serial
devices

- Open type

- Baud

- Parity

- Data bits

- Stop bits

- Flow control

- Detect enable

• Modem Control (output only)