PROGRAMMING TECHNIQUES UNDER MS DOS

There are three methods to write application programs to control serial communication.

1. Use device driver name to perform I/O.

2. Use PCCOM library through DOS interrupt routines.

3. Use low-level BIOS interrupt routines.

6.1 How to Use Device Driver

After device driver is installed, you may use device name (such as COM5, COM6, ... etc.) as a file to perform I/O operations. Since many high level languages provide several kinds of I/O operations, e.g. in C language, the write statement for low level I/O and fprintf for high level I/O. You must care which I/O routine is used by yourself to prevent the lose of I/O data, if you use high level I/O, you must use flush to dump buffer contents to serial device when necessary.

In the distribution disk, we provide BASIC, C, PASCAL, and FoxPro examples, all of these programs use device driver.

LOOPBACK.BAS

Loopback test.

DTX.BAS

Transfer file.

DRX.BAS

Receive file.

LOOPBACK.C

Loopback test.

DTERM.C

ASCII terminal emulator.

DCLOCK.C

Receive clock message.

LOOPBACK.PAS

Loopback test.

DTERM.PAS

ASCII terminal emulator.

6.2 PCCOM Library

PCCOM provides C, PASCAL, BASIC, and FOXPRO library routines to let user to write application programs to control serial communication via device drivers.

To write an application program, you must link COMLI115.C or COMLI460.C (Borland C), COMLIBMS.C (MSC), PCCOM115.PAS or PCCOM460.PAS (PASCAL), COMLIBGW.BAS (GWBASIC), COMLIBQK.BAS (Quick BASIC) or COMLIBQ.BAS (Q BASIC) file according to your selection language. In the following, we describe the PCCOM library more details:

1. cominit(portno, baud, db, parity, sb)

int cominit

unsigned int baud

int portno, db, parity, sb

The cominit is used to setup several communication parameters.

portno (int)

port number that defined in configuration file.

baud (unsigned int)

baud rate. Either B38400, B19200, B9600, B4800, B2400, B1200, B600, B300.

db (int)

data bits. Either CS8, CS7, CS6, CS5.

parity (int)

parity bit. Either PNONE, PEVEN, PODD.

sb (int)

stop bits. Either ST1 or ST2.

return value (int)

0 : success.

1 : fail.

2. comtxch(portno, ch)

int comtxch

int portno

char ch

The comtxch is used to send a character to serial port.

ch (char)

transmitted character

return value (int)

3. comrxch(portno, ch)

int comrxch

int portno

char *ch

The comrxch is used to get a character.

ch (char*)

received character.

return value (int)

4. comstat(portno)

int comstat

int portno

The comstat is used to get serial port status, the status indicator is shown in the following.

return value (int)

You may check the parameters to detect which bit is set.

5. comactive(portno)

int comactive

int portno

Check if the port is active.

return value (int)

6. comsetDTR(portno,n)

void comsetDTR

int portno,n

Set DTR signal ON or OFF.

n (int)

7. compeek(portno)

int compeek

int portno

The compeek is used to perform nondestructively read a character. The read character remains in the receive buffer.

return value (int)

8. comsetflow(portno,n)

void comsetflow

int portno, n

To set communication protocol.

n (int)

9. comtxblk(portno, pointer, n)

int comtxblk

int portno,n

void *pointer

To transmit a block of data, it uses one BIOS call to transmit a block of data.

pointer (pointer)

pointer to start of block.

n (int)

block length.

return value (int)

number of characters be sent.

10. comrxblk(portno, pointer, n)

int comrxblk

int portno, n

void *pointer

To receive a block of data, it uses one BIOS call to receive a block of data.

pointer (pointer)

pointer to start of block.

n (int)

number of characters should be received.

return value (int)

number of characters actually received.

11. combreak(portno,brk)

void combreak

int portno, brk

Send the break signal to driver.

brk (int)

12. cominstalled(portno)

int cominstalled

int portno

Check if the driver is installed ?

return value (int)

13. comsetport(portno, addr)

void comsetport

int portno, addr

The comsetport is used to set serial port address.

addr (int)

serial port address.

14. comsetvector(portno, addr)

void comsetvector

int portno, addr

The comsetvector is used to set interrupt vector address. After interrupt vector is set, when interrupt is emerged then the device driver will detect interrupt vector to check which port emerges the interrupt.

addr (int)

interrupt vector address. The address is designed at hardware adapter.

15. comsetactive(portno, active)

void comsetactive

int portno

char active

The comsetactive is used to set interrupt vector is active low or high.

active (char)

16. comsetMCR(portno, mcr)

void comsetMCR

int portno, mcr

The comsetMCR is used to control the contents of modem control register. Please see APPENDIX B for more details.

mcr (int)

17. compurgerxbuf(portno)

void compurgerxbuf

int portno

Remove any received buffer data from specify port.

18. comtxs(portno, s)

int comtxs, portno

char *s

The comtxs is used to send one string to serial port by calling BIOS for each character.

s (char*)

one character string to be sent.

return value (int)

19. comrxs(portno, s)

int comrxs, portno

char *s

The comrxs is used to get one string from ring buffer by calling BIOS for each character. This routine gets characters from ring buffer until it find <CR> or ring buffer is empty.

s (char*)

received string.

return value (int)

20. comsettimeout(portno,timeout)

void comsettimeout

int portno

unsigned int timeout

Set time out value about tx; when transmitter buffer in the specified port is full, the driver will wait until buffer empty or the timeout value is expired.

timeout (unsigned int)

time out value, the unit is 1/18 sec.

21. comgettimeout(portno)

unsigned int comgettimeout

int portno

Get the tx timeout value.

return value (unsigned int)

The time out value, unit is 1/18 sec.

22. combufstat(portno)

int combufstat

int portno

The combufstat is used to count the received characters in buffer.

return value (int)

23. comgetMCR(portno)

char comgetMCR

int portno

Get the value of MCR.

return value (char)

modem control value (see comsetMCR).

24. comgetFC(portno)

char comgetFC

int portno

Get flow control value.

return value (int)

Flow control value (see comsetflow).

25. comgetsets()

int comgetsets

Get number of PCCOM set which are controlled by device driver.

return value (int)

Number of PCCOM set.

26. comgetsetinfo(portno)

BiosComSet_t *comgetsetinfo

int portno

To get PCCOM set information about specified port, which belongs to this set.

return value (BiosComSet_t*)

The set information, which is defined as

Where

27. comgetinfo(portno, baud, db, parity, sb)

void comgetinfo

unsigned int *baud

int portno, *db, *parity, *sb

The comgetinfo is used to get communication parameters of specified port.

baud (unsigned int*)

baud rate.

db (int*)

data bits. Either 5, 6, 7 or 8 data bits.

parity (int*)

parity bit. Either NONE, EVEN, ODD.

sb (int*)

stop bits. Either 1 or 2 stop bits.

28. comgetports()

int comgetports

Get the number of PCCOM ports controlled by the PCCOM driver.

return value (int)

The number of PCCOM ports.

29. comdetectport(portno)

int comdetectport

int portno

The comdetectport is used to detect the serial port is exist or not.

return value (int)

30. comgetportinfo(portno)

BiosComport_t *comgetportinfo

int portno

Retrieve all information about one specified PCCOM port.

Where

31. comrxoff(portno)

void comrxoff

int portno

Notify the peer to stop sending data.

32. comrxon(portno)

void comrxon

int portno

Notify the peer to restart sending data.

6.3 Examples

In the distribution disk, we provide file transfer and setup program, all of these programs use PCCOM library.

RSETUP.C

Setup communication parameters.

RTX.C

Transfer file.

RRX.C

Receive file.

6.4 I/O Control Via Software Interrupt

To communicate directly with device drivers, the PCCOM provides a set of sub-functions under extended BIOS INT 14H, and DOS IOCTL INT 21H. All these functions are included in the PCCOM library, however, if you want control I/O through BIOS interrupt by yourself, you need prepare CPU register contents and fork a system call. In the following, we will describe these I/O control functions and teach users to use it.

All BIOS functions are designed as a FOSSIL driver, the specification of FOSSIL driver is shown in the "FOSSIL.DOC" file. Our PCCOM BIOS functions specification are shown in the "PCCOM.SPC" file. The examples of DOS IOCTL function calls are shown in the

"COMDOS.C" file.

Before you perform system call, you must specify sub-function number in ah register.

1. set up communication parameters

ah register

always set to 0h.

al register

al is used to setup communication parameters.

bit 7, 6, 5 : setup baud rate.

bit 4, 3 : setup parity.

bit 2 : setup stop bits.

bit 1, 0 : setup data bits.

dx register

port number.

return value (ax register)

bit 15 to bit 8 : line status.

bit 7 to bit 0 : modem status.

2. send a character

ah register

always set to 1h.

al register

character.

dx register

port number.

return value (ax register)

line status and modem status.

3. receive a character

ah register

always set to 2h.

al register

received character.

dx register

port number.

return value

ah : line status.

al : receive character.

4. get port status

ah register

always set to 3h.

dx register

port number.

return value (ax register)

line status and modem status.

5. activate port

ah register

always set to 4h.

dx register

port number.

return value

ax : 1954h if successful.

bl : maximum function number supported.

bh : rev of FOSSIL specification.

6. set DTR

ah register

always set to 6h.

al register

dx register

port number.

7. nondestructive read ahead

ah register

always set to Ch.

dx register

port number.

return value

ah : 0, if character is available.

al : the read character.

ax : FFFF, if no character is available.

The character read by this operation is not removed from input queue. This means that the same character will be obtained in next read operation.

8. set flow control

ah register

always set to Fh.

al register

enable or disable flow control. When set to 1, means enable.

dx register

port number.

9. receive block from a port

ah register

always set to 18h.

dx register

port number.

cx register

length of block.

es:di register

starting address of block.

return value (ax register)

count of received bytes.

10. send block to a port

ah register

always set to 19h.

dx register

port number.

cx register

number of bytes to be sent.

es:di register

starting address for received block.

return value (cx register)

count of sent bytes.

11. send break signal

ah register

always set to 1Ah.

dx register

port number.

al register

12. return information about PCCOM driver

ah register

always set to 1Bh.

dx register

port number.

cx register

length of block.

es:di register

starting address of block.

This function will transfer information about PCCOM and its current status to the caller.

return value (ax register)

The data structure (assembly language style)currently returned by PCCOM is as follows:

13. get buffer status

ah register

always set to 30h.

dx register

port number.

return value (cx)

number of characters in buffer.

FFFh : overflow.

14. set port address

ah register

always set to 31h.

dx register

port number.

bx register

port address.

15. set vector address

ah register

always set to 32h.

dx register

port number.

bx register

vector address.

16. set active status in vector

ah register

always set to 33h.

dx register

port number.

al register

17. set modem control

ah register

always set to 34h.

dx register

port number.

al register

modem control value.

18. get port parameters

ah register

always set to 35h.

dx register

port number.

return value(al)

communication parameters. (see 00H)

19. get modem control value

ah register

always set to 36h.

dx register

port number.

al register

modem control value.

20. get flow control value

ah register

always set to 37h.

dx register

port number.

return value (al)

flow control value. see 0fH.

21. get the total number of PCCOM sets

ah register

always set to 38h.

return value (ax)

total number of PCCOM sets.

22. get information about each PCCOM set

ah register

always set to 39h.

dl register

set number.

es:di register

starting address of block.

return value (ax)

number of bytes returned in buffer point by es:di

register.

Data structure :

Represented in C:

23. get the total number of PCCOM ports

ah register

always set to 3Ah.

return value (ax)

total number of ports.

24. detect whether the the port is existent

ah register

always set to 3Bh.

dx register

port number.

return value (ax)

25. get information of one PCCOM port

ah register

always set to 3Ch.

dx register

port number.

es:di register

pointer to space containing port information.

turn value (ax)

Data structure :

Represented in C:

26. notify peer to stop sending data

ah register

always set to 3Dh.

dx register

port number.

27. notify peer to restart sending data

ah register

always set to 3Eh.

dx register

port number.

28. set time out value

ah register

always set to 3Fh.

dx register

port number.

cx register

time out value in unit of 1/18 sec.

29. get time out value

ah register

always set to 3Fh.

dx register

port number.

return value (cx)

time out value in unit of 1/18 sec.

6.5 PCCOM DOS IOCTL functions

Under the DOS interrupt 21H and its sub function 44H, user can use IOCTL to access PCCOM character device.

1. IOCTL input function

Input:

AH = 44H

AL = 02H

BX = handle number

CX = number of bytes to transfer

DS:DX = segment: offset of data buffer

(viewed as control block)

Output:

If function is successful:

Carry flag is clear.

AX = number of bytes to transfer.

Data buffer at DS:DX contains data

read from device driver.

If function is not successful:

Carry flag is set.

AX = error code:

The transfer address(DS:DX) points to a control block that is used to communicate with the device driver. The first byte of the control block determines the request that is being made.

·