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. 

         ?/span>