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 RocketPort controllers for any particular purpose. Trademarks RocketPort/ISA API (6508) for the MS-DOS Operating System The Comtrol logo is a registered trademark of Control Systems, Inc. Comtrol is a trademark of Comtrol Corporation.
Before You Begin Scope Organization This guide describes the following information about the DOS application program interface (API) for RocketPort controllers: • 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. This guide is for people who develop applications for the MS-DOS system. Section 1.
Table of Contents Before You Begin Scope ...........................................................................................2 Purpose........................................................................................2 Audience......................................................................................2 Prerequisites...............................................................................2 Suggestions ..............................................................................
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 .........................
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. The RocketPort multiport serial controller series fits into a 16-bit ISA slot of a personal computer.
Installating RocketPort/ISA Systems DIP Switch Settings Controller #1 determines other controller settings 2nd ISA ON ON 1 2 3 4 5 6 7 8 ON 1st ISA 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 180 - 1C3 hex (Default) 4th ISA 1 2 3 4 5 6 7 8 ON 3rd ISA 2nd ISA 1 2 3 4 5 6 7 8 1 2 3 4 5 6 7 8 1st ISA ON ON 140 - 183 hex 4th ISA 1 2 3 4 5 6 7 8 1 2 3 4 5 6 7 8 3rd ISA 2nd ISA ON 1st ISA ON 100 - 143 hex 1 2 3 4 5 6 7 8 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
Installating RocketPort/ISA Systems ON ON 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 1 2 3 4 5 6 7 8 3rd ISA 2nd ISA 4th ISA ON 1 2 3 4 5 6 7 8 4th ISA 1st ISA ON 3rd ISA 380 - 3C3 hex 1 2 3 4 5 6 7 8 2nd ISA DIP Switch Settings Controller #1 determines other controller settings ON 1 2 3 4 5 6 7 8 1st ISA 1 2 3 4 5 6 7 8 200 - 243 hex Controller #1 I/O Address Range DIP Switch Settings Controller #1 determines other controller settings 1 2 3 4 5 6 7 8 Controller #1 I/O Ad
Installating RocketPort/ISA Systems from 1 to 16. 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 4J or 8J controller: a. Connect your peripheral devices to the RJ style connector on the controller.
Section 2. Developing Applications This section describes the following topics: • API features and functions • Writing the configuration file • Using the API (flowchart and example) • Include files • Configuring the controllers • Using API calls to write the application - Understanding device numbers - Configuration parameters for serial devices • Writing serial data • Exiting the application • Reading serial data • Installing and detecting events • Building applications 2.1.
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. Table 2-2.
Developing Applications • 900 - 943 • D00 - D43 This is normally of no concern because ISA peripherals often use only 10 bits of I/O addressing, meaning they are limited to addresses below 400h. Note: In order for your application to locate the configuration file, the ROCKETCFG environment variable must point to it. This is done with the DOS SET command, usually placed in the AUTOEXEC.BAT file. 2.4.
Developing Applications /* Initialize API */ aaInstallCtrlCHandler(); if((InitReturn = aaInit()) != NO_ERR) { 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 */ sscanf(Buf,"%d",&Dev); system("cls"); /* clear screen */ printf("Serial Device Number %d\t\t\tHit F10 to Quit\n",Dev); Step 4 (2.7) } 2.6. Include Files (Step 3) The API.H file must be included in the .
Developing Applications 2.8.1. Understanding Device Numbers 2.8.2.1. Open Type Parameter Each serial device is identified by a device number. Most API functions take the device number as a parameter. The number of ports that exist on each controller determines which device numbers map to which serial ports on which controllers. The device numbers always count sequentially from 0, with the first port on the first controller in the configuration file assigned device number 0.
Developing Applications Table 2-5. Baud Flags (Continued) Meaning When the Flag Flag is Set COM_BAUD_7200 7,200 baud COM_BAUD_9600 9,600 baud COM_BAUD_19200 19,200 baud COM_BAUD_38400 38,400 baud COM_BAUD_57600 57,600 baud COM_BAUD_76800 76,800 baud COM_BAUD_115200 115,200 baud COM_BAUD_230400 230,400 baud 2.8.2.3. Parity Parameter Table 2-7. Data Bits Flags Meaning When Flag is Set Flag COM_DATABIT_7 7 data bits COM_DATABIT_8 8 data bits 2.8.2.5.
Developing Applications Table 2-9. Flow Control Flags (Continued) Flag Meaning When Flag Set Table 2-11. Modem Control Output Flags Flag Modem Control Line COM_FLOW_OS Enable output software flow control COM_MDM_RTS Request to send COM_FLOW_OH Enable output hardware flow control using CTS COM_MDM_DTR Data terminal ready COM_FLOW_OXANY Enable restart output on any Rx character 2.8.2.7.
Developing Applications you can give the system software the name of an application program function that executes when a particular event occurs. The following aaInstallxxxEvent functions are available: • aaInstallMdmChangeEvent • aaInstallPeriodicEvent • aaInstallRxEvent Example 2-1 provides event function examples and shows how to install event functions. Notice that installing event functions is done shortly after the controller is initialized.
Developing Applications during event functions and any functions called by event functions. Stack checking can be turned off and on with: #pragma check_stack(off) #pragma check_stack(on) 2.13. Double Buffering Transmit and Receive Data Each serial device on the RocketPort controller internally provides 250 bytes of buffering for transmit data and 1K bytes of buffering for receive data. In some applications this may not be sufficient.
Section 3. Troubleshooting 3.1. Resolving Installation Problems If installation fails or you are trying to resolve a problem, you should try the following before calling the Comtrol technical support line: • Check the signals between your peripherals and the interface box to verify that they match (if applicable). See the appropriate Hardware Reference Card for information. • Check to make sure the serial and interface cables are connected properly.
Troubleshooting 5C0 – 5FF 9C0 – 9FF DC0 – DFF 200 – 23F 600 – 63F A00 – A3F E00 – E3F 240 – 27F 640 – 67F A40 – A7F E40 – E7F Table 3-3.
Troubleshooting Contact Comtrol using one of the following methods. Corporate Headquarters: • email: support@comtrol.com • FAX: (612) 631-8117 • Phone: (612) 631-7654 • BBS: (612) 631-8310 (for device driver updates) • FTP Site: ftp://ftp.comtrol.com Note: The BBS supports modem speeds up to 28.8 Kbps with 8 bits, and no parity. Comtrol Europe: • email: support@comtrol.co.uk • FAX: +44 (0) 1 869-323-211 • Phone: +44 (0) 1 869-323-220 • BBS: +44 (0) 1 869-243-687 3.3.
Appendix A. API Functions Table A-4. API Function Reference This appendix contains reference pages for the RocketPort API. Table A-4 lists all of the API functions. Function Table A-4. API Function Reference Function 21 Description aaInstallRxEvent Installs an application level event function to handle receive data available events. Description aaChangeModemState Changes the state of modem output lines. aaOpen Open a device for reading or writing, or both. aaClose Closes a device.
aaChangeModemState Function aaChangeModemState Function aaClose Purpose Changes the state of modem output lines. Purpose Closes a device.
aaEnPeriodicEvent Function aaEnPeriodicEvent Purpose Enables or disables dispatching of the periodic event function. Purpose Performs cleanup when exiting from an application program. Call aaEnPeriodicEvent(State) TRUE to enable dispatching of int State the periodic event function, FALSE to disable dispatching.
aaFlush Function aaFlush Function aaGetCtlStatus Purpose Flushes the transmit or receive buffer, or both for a device. Purpose Gets controller status, including the first device number on the controller and the number of devices on the controller. Call aaFlush(Dev,FlushFlags) int Dev unsigned char FlushFlags Call aaGetCtlStatus(CtlNum,FirstDevP,NumDevP) int CtlNum Controller number to get status on. int *FirstDevP Pointer to variable where first device number on this controller will be returned.
aaGetModemStatus Function aaGetModemStatus Function aaGetRxCount Purpose Gets a device’s modem status. Purpose Gets the count of data bytes available in the receive buffer. Call aaGetModemStatus(Dev) int Dev: Call aaGetRxCount(Dev) int Dev Return int: Receive byte count Return 25 unsigned char Device number State of the modem control inputs using the COM_MDM_CTS, COM_MDM_DSR, and COM_MDM_CD flags. If a flag is set that modem line is ON, if a flag is not set that modem line is OFF.
aaGetRxStatus Function aaGetRxStatus Function aaGetTxCount Purpose Gets the status of the device’s receive buffer. Purpose Gets the count of data bytes in the transmit buffer waiting to be transmitted.
aaInit Function aaInit Function aaInstallCtrlCHandler Purpose Executes controller and API initialization. Purpose Installs a handler for the CTRL+C key interrupt. Call aaInit() Call aaInstallCtrlCHandler() Return unsigned int Return void Comments This function replaces the existing CTRL+C (interrupt 23H) handler with a handler that performs the following actions: 1. Calls aaExit(). 2. Sets the carry flag to signal DOS to terminate the application. 3. Executes a far return.
aaInstallMdmChgEvent Function aaInstallMdmChgEvent Function aaInstallPeriodicEvent Purpose Installs an application level event function to handle modem change events. Purpose Installs a periodic application level event function. aaInstallMdmChgEvent(EvFuncP) void (*evFuncP)(Dev,unsigned char MdmChange, unsigned char MdmState) Ptr to the event function Call Call aaInstallPeriodicEvent(EvFuncP) void (*EvFuncP)(void) Ptr to the event function.
aaInstallRxEvent 29 Function aaInstallRxEvent Function aaOpen Purpose Installs an application level event function to handle receive data available events. Purpose Open a device for reading or writing, or both. aaInstallRxEvent(EvFuncP) void (*EvFuncP)(int Dev); function. Call Call Comments See the EvRxData() function for a description of the event function. Return void Warning The function installed here is called during an interrupt service routine (ISR).
aaRead COM_MDM_DTR, or both. If the flag is not set the line is OFF. If hardware flow control is in use for a modem line, it’s flag has no effect.
aaReadWithStatus Function aaReadWithStatus Function aaReconfigure Purpose Reads serial data and status from a device. Purpose Reconfigures a device’s communications parameters. Call aaReadWithStatus(Dev,Cnt,Buf) int Dev Device number int Cnt Max number of bytes that can be read unsigned int *Buf Buffer to store the data and status. The low byte of each array element in Buf contains the data byte, and the high byte contains the status for that data byte.
aaSendBreak ERR_PAR ERR_DATAB ERR_STOPB ERR_FLOW ERR_DETECT ERR_NOTOPEN Warning if invalid parity bits flag if invalid data bits flag if invalid stop bits flag if invalid flow control bits flag if invalid detect enable flag if device not open error flag Function aaSendBreak Purpose Sends a break signal. Call aaSendBreak(Dev,Time) int Dev Device number int Time Time in milliseconds to send the break Return int: NO_ERR This function disables and enables interrupts.
aaSetCloseDelay Function aaSetCloseDelay Function aaWrite Purpose Sets the maximum time aaClose() waits for a device’s transmit buffer to drain before flushing the transmit buffer and completing the close. Purpose Writes serial data out a device. Call aaWrite(Dev,Cnt,Buf) int Dev: int Cnt: Call Return aaSetCloseDelay(Dev,MaxDelay) int Dev Device number int MaxDelay Maximum time aaClose will wait for a device’s transmit buffer to drain in seconds. For no delay use 0.
EvModemChange Function EvModemChange Purpose Application modem input change event function Call EvModemChange(Dev,unsigned char MdmChange,unsigned char MdmState) int Dev Device number unsigned char MdmChange Modem input lines which changed. Can be any combination of the flags: COM_MDM_DSR, COM_MDM_CTS, or COM_MDM_CD. If a flag is set that modem line is changed, if a flag is not set that modem line did not change. unsigned char MdmState Current state of the modem inputs.
EvPeriodic Function EvPeriodic Function EvRxData Purpose Application periodic event function Purpose Application receive data available event function Call EvPeriodic() Call Return void EvRxData(Dev) int Dev: Warning This function is not part of the API, it must be written by the developer as part of the application program. The function name EvPeriodic is an example name only, this event function can be given any name desired. This function is not called directly by the application.
Appendix B. Double Buffering Example This appendix contains a copy of the \ROCKET\SAMPLE\DBUF.C file for your convenience. File: Project: Purpose: Comments: Operation: DBUF.C RocketPort DOS API Double buffering sample program This program shows how to use the periodic event function to double buffer Tx data, and how to use the receive event function to double buffer Rx data. The double buffering is done in a pair of queues for each device, these are defined in the Q_T structure.
Troubleshooting aaEnPeriodicEvent(TRUE); /* Test background transmit and receive on device 0. A loopback plug can be installed on device 0 so that all transmitted data is received on the same device. */ printf("To stop test press any key\n"); if((Err = aaOpen(0, COM_TX | COM_RX, COM_BAUD_38400, COM_PAR_NONE, COM_DATABIT_8, COM_STOPBIT_1, COM_FLOW_NONE, COM_DEN_RDA, COM_MDM_RTS | COM_MDM_DTR)) != 0) { printf("Open Failure - Device %d, Error %d\n","0",Err); aaExit(); exit(1); } q[0].
Troubleshooting /* Copy the rest of the buffer, if any left */ if (i != 0) { memcpy(&Buf[BCnt - i],q[Dev].RxBuf,i); Out = i; } /* Update Tx queue In index */ q[Dev].TxIn = In; asm sti; /* enable interrupts */ return(NumOpen); } /******************************************************** Function: DeqRxData Purpose: Remove data from a Rx queue. Call: DeqRxData(Dev,Buf,Cnt) int Dev; Device number unsigned char *Buf; Buffer takes data removed from Rx queue.
Troubleshooting /* Updata Out index, point to start of buffer if already at end of it */ Out = (Out + WCnt) % TXBUF_SIZE; /* Read more data if any room left at front of buffer and if device wasn't already emptied */ if((i != 0) && (Cnt == NumOpen - i)) { In = aaRead(Dev,i,q[Dev].RxBuf); /* read balance of data */ } /* Write more data if any left at front of buffer and if device wasn't already filled */ if((i != 0) && (WCnt == Cnt - i)) { Out = aaWrite(Dev,i,q[Dev].
