Beijing Paradise BBS Backup

home *** CD-ROM | disk | FTP | other *** search

/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / PCL4C50.ZIP / PCL4CREF.DOC < prev next >

Wrap

Text File | 1995-11-20 | 55.6 KB | 1,701 lines

Personal Communications Library For the C Language (PCL4C) REFERENCE MANUAL Version 5.0 November 20, 1995 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1995 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 205-881-4630 FAX : 205|880|0925 BBS : 205-880-9748 email : msc@traveller.com Anon FTP : ftp.traveller.com /pub/users/msc web : www.traveller.com/~msc/ _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER PCL4C Reference Manual Page 1 C O N T E N T S Chapter Page Table of Contents.............................2 Introduction..................................3 SioBaud....................................4 SioBrkKey..................................4 SioBrkSig..................................5 SioCTS.....................................5 SioDCD.....................................6 SioDelay...................................6 SioDone....................................7 SioDSR.....................................7 SioDTR.....................................8 SioError...................................8 SioFIFO....................................9 SioFlow....................................9 SioGetc...................................10 SioGetDiv.................................10 SioGets...................................11 SioInfo...................................11 SioIRQ....................................12 SioLine...................................12 SioLoopBack...............................13 SioModem..................................13 SioParms..................................14 SioPorts..................................14 SioPutc...................................15 SioPuts...................................15 SioRead...................................16 SioReset..................................16 SioRI.....................................17 SioRTS....................................17 SioRxBuf..................................18 SioRxClear................................18 SioRxQue..................................19 SioTimer..................................19 SioTxBuf..................................20 SioTxClear................................20 SioTxFlush................................21 SioTxQue..................................21 SioUART...................................22 SioUnGetc.................................22 Function Summary.............................23 Error Code Summary...........................24 Code Examples................................25 PCL4C Reference Manual Page 2 Introduction This manual lists all of the PCL4C functions in alphabetical order. Every library function will return a value as follows: 1. Negative values for error conditions. See last page of this manual for a list of error values and their meanings. 2. Non-negative values when returning data (eg: SioLine). 3. Zero otherwise. When debugging an application, be sure to test all return values. Use SioError to print the associated text for errors. Example Code Segment +---------------------------------------------------------------+ | int Code; /* MUST be 'int', not 'char' */ | | | | Code = SioFunction( ); /* any PCL4C function */ | | if(Code<0) | | {/* error returned */ | | SioError(Code); /* SioError prints error text */ | | SioDone(Port); /* always call SioDone last */ | | exit(1); | | } | | /* no errors */ | | ...your application code... | | | +---------------------------------------------------------------+ For more examples, examine each of the example programs provided (MINIMAL.C, SIMPLE.C, LOGIN.C, DOOR.C, SPAWN.C, SELFTEST.C, etc.) in the distribution archive. You may also wish to examine the TERM.C example program in the protocol library (PPL4C). Refer to the User's Manual (PCL4C.USR) for additional information. PCL4C Reference Manual Page 3 +-------------+---------------------------------------------------------------+ | SioBaud | Sets the baud rate of the selected port. | +-------------+---------------------------------------------------------------+ Syntax int SioBaud(int Port,int BaudCode) /* Port: Port selected (COM1 - COM16) */ /* BaudCode: Baud code */ Remarks The SioBaud function sets the baud rate without resetting the port. It is used to change the baud rate after calling SioReset. Code Rate Name Code Rate Name 0 300 Baud300 5 9600 Baud9600 1 600 Baud600 6 19200 Baud19200 2 1200 Baud1200 7 38400 Baud38400 3 2400 Baud2400 8 57600 Baud57600 4 4800 Baud4800 9 115200 Baud115200 Returns -4 : No such port. Expect 0 to MaxPort. -11 : Bad baud rate code. See above code values. See Also SioReset +-------------+------------+-------------------+------------------------------+ | SioBrkKey | Return non|zero if the Control|Break key was pressed. | +-------------+------------+-------------------+------------------------------+ Syntax int SioBrkKey(void) Remarks The SioBrkKey function returns a TRUE value (non-zero) if the Control-BREAK key was pressed, else it returns a zero. Use SioBrkKey as a safety exit from a polling loop. Returns -1 : Control-BREAK was pressed. 0 : Control-BREAK was NOT pressed. See Also SioBrkSig PCL4C Reference Manual Page 4 +-------------+------------------------------------------------------------+ | SioBrkSig | Asserts, cancels, or detects BREAK signal. | +-------------+------------------------------------------------------------+ Syntax int SioBrkSig(int Port,char Cmd) /* Port: Port selected (COM1 thru COM20) */ /* Cmd: ASSERT ('A'), CANCEL ('C'), or DETECT ('D')*/ Remarks The SioBrkSig function controls the BREAK bit in the line status register. The legal commands are: ASSERT_BREAK ('A') : to assert BREAK CANCEL_BREAK ('C') : to cancel BREAK DETECT_BREAK ('D') : to detect BREAK ASSERT_BREAK, CANCEL_BREAK, and DETECT_BREAK are defined in PCL4C.H. SioBreak is often used by one side to signal the other than an error condition has occurred. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -6 : Illegal command. Expected 'A', 'C', or 'D'. >0 : BREAK signal detected (DETECT command only) See Also SioBrkKey +-------------+---------------------------------------------------------------+ | SioCTS | Reads the Clear to Send (CTS) modem status bit. | +-------------+---------------------------------------------------------------+ Syntax int SioCTS(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioCTS function is used to read the Clear to Send (CTS) modem status bit. The CTS line is used by some error correcting modems to implement hardware flow control. CTS is dropped by the modem to signal the computer not to send data and is raised to signal the computer to continue. Refer to the User's Manual for a discussion of flow control. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. 0 : CTS is clear. >0 : CTS is set. See Also SioFlow, SioDSR, SioRI, SioDCD, and SioModem. PCL4C Reference Manual Page 5 +-------------+---------------------------------------------------------------+ | SioDCD | Reads the Data Carrier Detect (DCD) modem staus bit. | +-------------+---------------------------------------------------------------+ Syntax int SioDCD(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioDCD function is used to read the Data Carrier Detect (DCD) modem status bit. Also see SioModem. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. 0 : DCD is clear. >0 : DCD is set. See Also SioDSR, SioCTS, SioRI, and SioModem. +-------------+---------------------------------------------------------------+ | SioDelay | Delays one or more timer tics. | +-------------+---------------------------------------------------------------+ Syntax int SioDelay(int Tics) /* Tics: # timer tics to delay */ Remarks The SioDelay function is used to delay one or more timer tics, where each timer tic is approximately 55 milliseconds (18.2 tics to the second). Be carefull calling SioDelay since it will not return until the specified delay has occurred. Returns zero. See Also SioTimer PCL4C Reference Manual Page 6 +-------------+---------------------------------------------------------------+ | SioDone | Terminates further serial processing. | +-------------+---------------------------------------------------------------+ Syntax int SioDone(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioDone function terminates further serial processing. SioDone MUST be called before exiting your application so that interrupts can be restored to their original state. Failure to do this can crash the operating system. If you forget to call SioDone before exiting, be sure to re-boot your computer. You can call SioDone even if SioReset has not been called, so it is good practice to always call SioDone before exiting your application. Also note that SioDone de-references the transmit and receive buffers set up by SioRxBuf and SioTxBuf. However, it does NOT free the transmit and receive buffers. It is good practice to free the transmit and receive buffers (after calling SioDone) if they were allocated by malloc (or fmalloc). Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioReset. +-------------+---------------------------------------------------------------+ | SioDSR | Reads the Data Set Ready (DSR) modem status bit. | +-------------+---------------------------------------------------------------+ Syntax int SioDSR(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioDSR function is used to read the Data Set Ready (DSR) modem status bit. The DSR line is typically used by the serial device (such as a modem) to indicate that it is connected. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. 0 : DSR is clear. >0 : DSR is set See Also SioCTS, SioRI, SioDCD, and SioModem PCL4C Reference Manual Page 7 +-------------+---------------------------------------------------------------+ | SioDTR | Set, clear, or read Data Terminal Ready (DTR) status bit. | +-------------+---------------------------------------------------------------+ Syntax int SioDTR(int Port,char Cmd) /* Port: Port selected (COM1 thru COM20) */ /* Cmd: DTR command (SET, CLEAR, or READ) */ Remarks The SioDTR function controls the Data Terminal Ready (DTR) bit in the modem control register. The DTR line is typically used by your program to tell the serial device that you are connected. DTR should always be set when communicating with a modem. Commands (defined in PCL4C.H) are: SET_LINE ('S') : to set DTR (ON) CLEAR_LINE ('C') : to clear DTR (OFF) READ_LINE ('R') : to read DTR Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -5 : Not one of 'S', 'C', or 'R'. 0 : DTR is OFF (READ_LINE Command). >0 : DTR is ON (READ_LINE Command). See Also SioRTS. +-------------+---------------------------------------------------------------+ | SioError | Displays error in text. | +-------------+---------------------------------------------------------------+ Syntax int SioError(int Code) /* Code: PCL4C error code */ Remarks The SioError function displays the error in text corresponding to the error code returned from a PCL4C function. During development of a communications application, it is a good idea to always test return codes, and print out their descriptions with SioError. Returns zero. PCL4C Reference Manual Page 8 +-------------+---------------------------------------------------------------+ | SioFIFO | Sets the FIFO trigger level (16550 UART only). | +-------------+---------------------------------------------------------------+ Syntax int SioFIFO(int Port,int LevelCode) /* Port: Port selected (COM1 thru COM20) */ /* LevelCode: FIFO level code (see below) */ Remarks The SioFIFO function is used to enable both transmit and receive FIFOs for 16550 UARTS, and to set the trigger level at which receive interrupts are generated. For example, if the FIFO level is set to 8, then the 16550 UART will not generate an interrupt until 8 bytes have been received. This reduces the number of interrupts generated and allows faster processing with slower machines or when running simultaneous ports. In order to test if your port is a 16550 UART, call SioFIFO with a LevelCode of other than FIFO_OFF. SioFIFO can be called for the 8250 and 16450 UART without ill effect. Code PCL4C.H Name Trigger Level -1 FIFO_OFF Disable FIFO 0 LEVEL_1 1 byte 1 LEVEL_4 4 bytes 2 LEVEL_8 8 bytes 3 LEVEL_14 14 bytes Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. >0 : FIFO level set. 0 : FIFO level not set (not 16550). +------------+----------------------------------------------------------------+ | SioFlow | Sets hardware (RTS/CTS) flow control. | +------------+----------------------------------------------------------------+ Syntax int SioFlow(int Port,int Tics) /* Port: Port selected (COM1 thru COM20) */ /* Tics: # tics before timeout */ Remarks The SioFlow function is used to enable or disable hardware flow control. Hardware flow control uses RTS and CTS to control data flow between the modem and the computer. Refer to the User's Manual for a discussion of flow control. To enable hardware flow control, call SioFlow with Flag >= 0. "Tics" is the number of timer tics (18.2 per second) before a call to SioPutc or SioPuts will time out because CTS was not set. If you enable hardware flow control, do not modify the RTS line (by calling SioRTS). Flow control is disabled after resetting a port. To explicitly disable hardware flow control, call SioFlow with Tics=-1. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. =0 : Flow control disabled. >0 : Flow control enabled. See Also SioPutc and SioPuts PCL4C Reference Manual Page 9 +------------+----------------------------------------------------------------+ | SioGetc | Reads the next character from the serial line. | +------------+----------------------------------------------------------------+ Syntax int SioGetc(int Port,int Tics) /* Port: Port selected (COM1 thru COM20) */ /* Tics: Timeout */ Remarks The SioGetc function reads a byte from the selected serial port. The function will wait for the number of system tics given by the 'Tics' argument before returning 'timed out'. There are 18.2 tics to the second. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -1 : If timed out. >0 : Character read. See Also SioUnGetc and SioPutc. +---------------+-------------------------------------------------------------+ | SioGetDiv | Reads the baud rate divisor. | +---------------+-------------------------------------------------------------+ Syntax int SioGetDiv(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioGetDiv function reads the baud rate divisor. The baud rate can then be determined from the divisor by using the following table: Baud Divisor Baud Divisor Baud Divisor 300 0180 4800 0018 38400 0003 1200 0060 9600 000C 57600 0002 2400 0030 19200 0006 115200 0001 Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. >0 : Baud rate divisor. See Also SioParms. PCL4C Reference Manual Page 10 +------------+----------------------------------------------------------------+ | SioGets | Receive a buffer from the serial line. | +------------+----------------------------------------------------------------+ Syntax int SioGets(int Port,char *Buffer,int Length) /* Port: Port selected (COM1 thru COM20) */ /* Buffer: Character buffer */ /* Length: Length of Buffer (# of requested bytes) */ Remarks The SioGets function reads bytes from the selected serial port. This function will read either the number of requested bytes or read fewer if no character is immediately available. SioGets cannot return more characters than are in the receive buffer at the time it is called. The number of characters actually read is returned. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -1 : If timed out. >0 : Number of characters read into Buffer. See Also SioUnGetc and SioGetc. +-------------+---------------------------------------------------------------+ | SioInfo | Returns PCL4C library information. | +-------------+---------------------------------------------------------------+ Syntax int SioInfo(char Cmd) /* Cmd: Command (see below) */ Remarks The SioInfo function returns a word value depending on the character argument in the table below. This function is usefull for understanding what the hardware is doing. Note that the command argument is case sensitive. Info Codes 'V' : Version [as hex byte XY means version X.Y] 'I' : TRUE if library compiled with TX interrupts enabled. 'M' : Memory model (0=small,1=compact,2=medium,3=large) 'P' : TRUE if compiled for protected mode. 'T' : Total (over all ports) transmitter interrupts. 'R' : Total (over all ports) receiver interrupts. 'd' : Total (over all ports) times RTS dropped. 'r' : Total (over all ports) times RTS raised. 'c' : Total (over all ports) times CTS drop detected. Returns -1 : Function argument not recognized. >=0 : Value as per above table. PCL4C Reference Manual Page 11 +-------------+---------------------------------------------------------------+ | SioIRQ | Assigns an IRQ line to a port. | +-------------+---------------------------------------------------------------+ Syntax int SioIRQ(int Port,intIRQcode) /* Port: Port selected (COM1 thru COM20) */ /* IRQcode: IRQ number [IRQ2..IRQ15] */ Remarks The SioIRQ function assigns an IRQ line to a port. That is, SioIRQ maps an IRQ to a port. SioIRQ (like SioUART) must be called before calling SioReset. Unless you have a non-standard (COM1 & COM3 use IRQ4 while COM2 & COM4 use IRQ3) serial port configuration (or don't want to run more than 2 ports concurrently), you will not need to call SioIRQ. Be EXTREMELY careful with SioIRQ as it can lock your machine up if given incorrect information. In particular, remember that your port hardware must generate the interrupt that you have specified. You should refer to your serial board hardware manual for specfic instructions in configuring your hardware. Be sure to call SioPorts first to setup DigiBoard ports if you have them. Refer to the PCL4C Users Manual for additional information. Returns -4 : No such port. Expect 0 to MaxPort. 15 : Port already enabled. SioReset has already been called. -17 : No such IRQ. -18 : ISR limit (maximum of 4 PC IRQs) exceeded. 0 : Otherwise See Also SioUART and SioPorts. +-------------+---------------------------------------------------------------+ | SioLine | Reads the line status register. | +-------------+---------------------------------------------------------------+ Syntax int SioLine(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioLine function reads the line status register. The individual bit masks are as follows: 0x40 = Transmitter empty. 0x20 = Transmitter buffer empty. 0x10 = Break detected. 0x08 = Framming error. 0x04 = Parity error. 0x02 = Overrun error. 0x01 = Data ready. The above are documented in the file PCL4C.H. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. >0 : Line status (rightmost byte of word). See Also SioModem. PCL4C Reference Manual Page 12 +-------------+---------------------------------------------------------------+ | SioLoopBack | Does a UART loopback test. | +-------------+---------------------------------------------------------------+ Syntax int SioLoopBack(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks SioLoopBack makes use of the built in loopback test capability of the INS8250 family UART. Normally SioLoopBack will never need to be called unless you suspect that your UART is bad. Many UARTs must be reset after running a loopback test. Returns 0 : Loopback test is successfull. -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -12 : Loopback test fails. +-------------+---------------------------------------------------------------+ | SioModem | Reads the modem status register. | +-------------+---------------------------------------------------------------+ Syntax int SioModem(int Port, int Mask) /* Port: Port selected (COM1 thru COM20) */ /* Mask: Modem function mask */ Remarks The SioModem function reads the modem register. The bit definitions for the function mask are as follows: Bit Name Function Bit Name Function 7 DCD Data Carrier Detect 3 DeltaDCD DCD has changed 6 RI Ring Indicator 2 DeltaRI RI has changed 5 DSR Data Set Ready 1 DeltaDSR DSR has changed 4 CTS Clear To Send 0 DeltaCTS CTS has changed Bits 4 through 7 represent the absolute state of their respective RS-232 inputs. Bits 0 through 3 represent a change in the state of their respective RS-232 inputs since last read. Once UART register 3 is read, the Delta bits are cleared. Thus, it is best not to depend on the Delta bits. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. >0 : Modem status (rightmost byte of word). See Also SioCTS, SioDCD, SioDSR and SioRI. PCL4C Reference Manual Page 13 +-------------+---------------------------------------------------------------+ | SioParms | Sets parity, stop bits, and word length. | +-------------+---------------------------------------------------------------+ Syntax int SioParms(int Port,int Parity,int StopBits, int DataBits) /* Port: Port selected (COM1 - COM16) */ /* Parity: Parity code [0,1,2] */ /* StopBits: Stop bits code [0,1] */ /* DataBits: Word length code [0,1,2,3] */ Remarks The SioParms function sets the parity, stop bits, and word length. If the default parity (none), stop bits (1), or word length (8) is not acceptable, then they can be changed by calling SioParms. SioParms can be called either before or after calling SioReset. See file PCL4C.H. (8 = default) Value Description PCL4C.H Name ParityCode: *0 no parity NoParity 1 odd parity OddParity 3 even parity EvenParity StopBitsCode: *0 1 stop bit OneStopBit 1 2 stop bits TwoStopBits WordLengthCode: 0 5 data bits WordLength5 1 6 data bits WordLength6 2 7 data bits WordLength7 *3 8 data bits WordLength8 Returns -4 : No such port. Expect 0 to MaxPort. -7 : Bad parity code selected. Expecting 0 to 2. |8 : Bad stop bits code. Expecting 0 or 1. -9 : Bad word length code. Expecting 0 to 3. See Also SioReset. +-------------+---------------------------------------------------------------+ | SioPorts | Sets number of PC & Digiboard / BOCA Board ports. | +-------------+---------------------------------------------------------------+ Syntax int SioPorts(int NbrPorts,int FirstPort,int StatusReg,int Code) /* NbrPorts: Total number of ports */ /* FirstPort: First DigiBoard port */ /* StatusReg: DigiBoard Status Register */ /* Code: PC_PORTS, DIGIBOARD, or BOCABOARD */ Remarks The SioPorts function must be called before ANY other serial functions. The purpose of the SioPorts function is to set the total number of ports, the first DigiBoard (or BOCA board) port and the DigiBoard (or BOCA board) status register address. Once SioPorts is called, all COM ports starting with "FirstPort" will be treated as DigiBoard (or BOCA board) ports. The default setup is 4 standard PC ports and no DigiBoard or BOCA ports [ SioPorts(4,4,0,PC_PORTS) ]. Refer to ther PCL4C users manual for more information on the DigiBoard and BOCA board. Many other multiport boards are functionally equivalent to either the DigiBoard or the BOCA board. Returns -4 : No such port. Expect 0 to 9. 0 : No error (sets MaxPort to NumberPorts-1). See Also SioUART, SioIRQ, and Code Examples. PCL4C Reference Manual Page 14 +-------------+---------------------------------------------------------------+ | SioPutc | Transmit a character over a serial line. | +-------------+---------------------------------------------------------------+ Syntax int SioPutc(int Port,char Ch) /* Port: Port selected (COM1 thru COM20) */ /* Ch: Character to send */ Remarks The SioPutc function transmits one character over the selected serial line. If flow control has been enabled, then SioPutc may return a -1 (time out) if the number of tics specified in the SioFlow function was exceeded waiting for the modem to raise CTS. Refer to the User's Manual for a discussion of flow control. If transmitter interrupts are enabled, SioPutc returns a -1 if the transmit buffer is already full. Otherewise the byte is placed in the transmit buffer, awaiting transmission by the PCL4C interrupt service routine. If transmitter interrupts are not enabled, the byte is loaded directly into the UART transmit buffer. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -1 : Timed out waiting for CTS (flow control enabled), or transmit buffer already full. See Also SioPuts, SioFlow, and SioTxFlush. +-------------+---------------------------------------------------------------+ | SioPuts | Transmit a buffer over a serial line. | +-------------+---------------------------------------------------------------+ Syntax int SioPuts(int Port,char *Buffer,int Length) /* Port: Port selected (COM1 thru COM20) */ /* Buffer: Character buffer */ /* Length: Length of Buffer */ Remarks The SioPuts function transmits each buffer character over the selected serial line. The number of characters actually transmitted is returned. This function can take a long time for large buffers if transmitter interrupts are not enabled! If flow control has been enabled, then SioPuts may transmit fewer characters than requested if the number of tics specified in the SioFlow function was exceeded waiting for the modem to raise CTS. Refer to the User's Manual for a discussion of flow control. If transmitter interrupts are enabled, SioPuts will transmit fewer than the number of characters requested if the transmit buffer would overflow. The actual number of characters transmitted is returned. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. >=0: Number of characters actually transmitted. See Also SioPutc, SioFlow, and SioTxFlush. PCL4C Reference Manual Page 15 +-------------+---------------------------------------------------------------+ | SioRead | Reads any UART register. | +-------------+---------------------------------------------------------------+ Syntax int SioRead(int Port,int Reg) /* Port: Port selected (COM1 thru COM20) */ /* Reg: UART register (0 to 7) */ Remarks The SioReset function directly reads the contents of any of the 7 UART registers. This function is useful when debugging application programs and as a method for verifying UART contents. Refer to the PCL4C Users Manual for a discussion of the 7 UART registers. The line status register (register 5) can also be read with SioLine while the modem status register (register 6) can also be read with SioModem. Refer to the PCL4C User's Manual for a discussion of the UART registers. Returns -3 : No buffer available. Call SioRxBuf first. -4 : No such port. Expect 0 to MaxPort. See Also SioLine and SioModem. +-------------+---------------------------------------------------------------+ | SioReset | Initialize a serial port for processing. | +-------------+---------------------------------------------------------------+ Syntax int SioReset(int Port,int BaudCode) /* Port: Port selected (COM1 thru COM20) */ /* BaudCode: Baud code or -1 */ Remarks The SioReset function initializes the selected serial port. SioReset should be called after calling SioParm and SioRxBuf but before making any other calls to PCL4C. SioReset uses the parity, stop bits, and word length value previously set if SioParm was called, otherwise the default values (see SioParm) are used. Recall that COM1 and COM3 share the same interrupt vector and therefore cannot operate simultaneously. Similiarly, COM2 and COM4 cannot operate simultaneously. Any other combination of two ports can be used. By specifing NORESET (-1) for the baud rate code, the port will NOT be reset. This is used to "take over" a port from a host communications program that allows a "DOS gateway". External protocols can be implemented this way. See SioBaud for a list of the baud rate codes, or see "PCL4C.H". Returns -3 : No buffer available. Call SioRxBuf first. -4 : No such port. Expect 0 to MaxPort. -11 : Bad baud rate code selected. Expecting 0 to 9. |13 : UART undefined. SioUART(Port,0) was called previously. |14 : Bad or missing UART. You may not have hardware present. |15 : Port already enabled. SioReset has already been called. -16 : Interrupt already in use. See Also SioBaud, SioParms, SioRxBuf, SioTxBuf, SioDone, and SioUART. PCL4C Reference Manual Page 16 +-------------+---------------------------------------------------------------+ | SioRI | Reads the Ring Indicator (RI) modem status bit. | +-------------+---------------------------------------------------------------+ Syntax int SioRI(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioRI function is used to read the Ring Indicator (RI) modem status bit. Also see SioModem. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. 0 : RI is clear. >0 : RI is set (RING has occurred). See Also SioDSR, SioCTS, SioDCD, and SioModem. +-------------+---------------------------------------------------------------+ | SioRTS | Sets, clears, or reads the Request to Send (RTS) line. | +-------------+---------------------------------------------------------------+ Syntax int SioRTS(Port, char Cmd) /* Port: Port selected (COM1 thru COM20) */ /* Cmd: RTS command (SET, CLEAR, or READ) */ Remarks The SioRTS function controls the Request to Send (RTS bit in the modem control register. The RTS line is used by most error correcting modems to implement hardware flow control. RTS is dropped by the computer to signal the modem not to send data, and is raised to signal the modem to continue. RTS should be set when communicating with a modem unless Flow Control is being used. Refer to the User's Manual for a discussion of flow control. Commands (defined in PCL4C.H) are: SET_LINE ('S') : set RTS (ON) CLEAR_LINE ('C') : clear RTS (OFF) READ_LINE ('R') : read RTS Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -5 : Command is not one of 'S', 'C', or 'R'. 0 : RTS is OFF (READ_LINE Command). >0 : RTS is ON (READ_LINE Command). See Also SioFlow and SioDTR. PCL4C Reference Manual Page 17 +------------+----------------------------------------------------------------+ | SioRxBuf | Sets up receive buffers. | +------------+----------------------------------------------------------------+ Syntax int SioRxBuf(int Port,int Selector,SizeCode) /* Port: Port selected (COM1 thru COM20) */ /* Selector: Receive buffer segment [selector for PM] */ /* SizeCode: Buffer size code */ Remarks The SioRxBuf function passes the address segment and size of the receive buffer to PCL4C. Recall that PCL4C requires a receive buffer for each port in simultaneous operation since the receive function is interrupt driven. It must be called before any incoming characters can be received. SioRxBuf must be called before SioReset. Buffer size codes are listed in "PCL4C.H". Size Code Buffer Size PCL4C.H Name 4 128 bytes Size128 5 256 bytes Size256 6 512 bytes Size512 7 1024 bytes Size1024 or Size1K 8 2048 bytes Size2048 or Size2K 9 4096 bytes Size4096 or Size4K 10 8192 bytes Size8192 or Size8K 11 16384 bytes Size16384 or Size16K 12 32768 bytes Size32768 or Size32K Returns -4 : No such port. Expect 0 to MaxPort. -10 : Bad buffer size code. Expecting 0 to 11. See Also SioReset, SioTxBuf and Code Examples. +------------+----------------------------------------------------------------+ | SioRxClear | Cleares (clears) the receive buffer. | +------------+----------------------------------------------------------------+ Syntax int SioRxClear(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioRxClear function will delete any characters in the receive buffer for the specified port. After execution, the receive buffer will be empty. Call SioRxBuf after resetting a port in order to delete any spurious characters. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioRxQue. PCL4C Reference Manual Page 18 +-------------+---------------------------------------------------------------+ | SioRxQue | Returns the number of bytes in the receive queue. | +-------------+---------------------------------------------------------------+ Syntax int SioRxQue(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioRxQue function will return the number of characters in the receive queue at the time of the call. It can be used to implement XON/XOFF flow control. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioRxClear. +------------+----------------------------------------------------------------+ | SioTimer | Returns the number of system clock tics since midnight. | +------------+----------------------------------------------------------------+ Syntax long SioTimer(void) Remarks The SioTimer function will return the number of system clock tics since midnight, at 18.2065 tics per second. This function is usefull for timing various functions. See Also SioDelay PCL4C Reference Manual Page 19 +------------+----------------------------------------------------------------+ | SioTxBuf | Sets up transmitter buffer. | +------------+----------------------------------------------------------------+ Syntax int SioTxBuf(int Port,int Selector,int SizeCode) /* Port: Port selected (COM1 thru COM20) */ /* Selector: Receive buffer segment [selector in PM] */ /* SizeCode: Buffer size code */ Remarks The SioTxBuf function passes the address segment and size of the transmit buffer to PCL4C, provided that you will link with a PCL4C library with transmitter interrupts enabled. SioTxBuf() must be called before SioReset. Size Code Buffer Size PCL4C.H Name 4 128 bytes Size128 5 256 bytes Size256 6 512 bytes Size512 7 1024 bytes Size1024 or Size1K 8 2048 bytes Size2048 or Size2K 9 4096 bytes Size4096 or Size4K 10 8192 bytes Size8192 or Size8K 11 16384 bytes Size16384 or Size16K 12 32768 bytes Size32768 or Size32K Returns -4 : No such port. Expect 0 to MaxPort. -10 : Bad buffer size code. Expecting 0 to 11. See Also SioRxBuf, SioReset and Code Examples. +------------+----------------------------------------------------------------+ | SioTxClear | Cleares (clears) the transmitter buffer. | +------------+----------------------------------------------------------------+ Syntax int SioTxClear(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioTxClear function will delete any characters in the transmit buffer for the specified port, provided that you will link with a PCL4C library with transmitter interrupts enabled. After execution, the transmit buffer will be empty. Once this function is called, any character in the transmit buffer (put there by SioPutc) will be lost and therefore not transmitted. This function is not used unless the transmitter interrupts are enabled Refer to the PCL4C Users Manual for information on transmitter (TX) interrupts. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioTxFlush and SioTxQue. PCL4C Reference Manual Page 20 +------------+----------------------------------------------------------------+ | SioTxFlush | Flushes the transmitter buffer. | +------------+----------------------------------------------------------------+ Syntax int SioTxFlush(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioTxFlush function will re-enable transmitter interrupts if they had been disabled by CTS dropping. This has the effect of forcing all data out of the transmitter queue unless stopped again by CTS going down. Once the transmitter interrupt has been disabled (by CTS going down), then the only way to restart it is by calling one of the serial I/O functions (SioPutc, SioPuts, SioGetc, or SioGets), SioTxQue, or SioTxFlush. The primary purpose of SioTxFlush is to provide an explicit means of restarting transmitter interrupts. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioTxQue. +------------+----------------------------------------------------------------+ | SioTxQue | Returns the number of bytes in the transmit queue. | +------------+----------------------------------------------------------------+ Syntax int SioTxQue(int Port) /* Port: Port selected (COM1 thru COM20) */ Remarks The SioTxQue function will return the number of characters in the transmit queue at the time of the call, provided that you will link with a PCL4C library with transmitter interrupts enabled. This function is not used unless the transmitter interrupts are enabled. Refer to the PCL4C Users Manual for information on transmitter (TX) interrupts. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioTxFlush. PCL4C Reference Manual Page 21 +------------+----------------------------------------------------------------+ | SioUART | Sets the UART base address. | +------------+----------------------------------------------------------------+ Syntax int SioUART(int Port,int Address) /* Port: Port selected (COM1 thru COM20) */ int Port; /* COM1 to COM4 */ /* Address: UART address */ Remarks The SioUART function sets the UART base address for the specified port. SioUART must be called before SioReset in order to have effect. Be extremely sure that you know what you are doing! Note that PCL4C uses the standard PC/XT/AT port addresses, interrupt request lines, and interrupt service vectors. Therefore, this function is only needed for non-standard ports. Returns >0 : The previous base address for this port. -4 : No such port. Expect 0 to MaxPort. -15 : Port already enabled. SioReset has already been called. See Also SioPorts, SioIRQ, and SioReset. +------------+-----+----------------------------------------------------------+ | SioUnGetc | "Un|gets" the last character read with SioGetc(). | +------------+-----+----------------------------------------------------------+ Syntax int SioUnGetc(int Port,char Ch) /* Port: Port selected (COM1 thru COM20) */ /* Ch: Character to unget */ Remarks The SioUnGetc function returns ("pushes") the character back into the serial input buffer. The character pushed will be the next character returned by SioGetc. Only one character can be pushed back. This function works just like the "ungetc" function in the C language. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioReset. PCL4C Reference Manual Page 22 Function Sumary +-------------+----------+----------+----------+----------+ | Function | Arg1 | Arg2 | Arg3 | Arg4 | +-------------+----------+----------+----------+----------+ | SioBaud | Port | BaudCode | | | | SioBrkKey | | | | | | SioBrkSig | Port | Cmd | | | | SioCTS | Port | | | | | SioDCD | Port | | | | | SioDelay | Tics | | | | | SioDone | Port | | | | | SioDSR | Port | | | | | SioDTR | Port | Cmd | | | | SioError | Code | | | | | SioFIFO | Port | LevelCode| | | | SioFlow | Port | Tics | | | | SioGetc | Port | Tics | | | | SioGetDiv | Port | | | | | SioGets | Port | Buffer | Length | | | SioInfo | Cmd | | | | | SioIRQ | Port | IRQcode | | | | SioLine | Port | | | | | SioLoopBack | Port | | | | | SioModem | Port | Mask | | | | SioParms | Port | Parity | StopBits | DataBits | | SioPorts | NbrPorts | FirstPort| StatusReg| Code | | SioPutc | Port | Ch | | | | SioPuts | Port | Buffer | Length | | | SioRead | Port | Reg | | | | SioReset | Port | BaudCode | | | | SioRI | Port | | | | | SioRTS | Port | Cmd | | | | SioRxBuf | Port | Segment | SizeCode | | | SioRxClear | Port | | | | | SioRxQue | Port | | | | | SioTimer | | | | | | SioTxBuf | Port | Segment | SizeCode | | | SioTxClear | Port | | | | | SioTxFlush | Port | | | | | SioTxQue | Port | | | | | SioUART | Port | Address | | | | SioUnGetc | Port | Ch | | | +-------------+----------+----------+----------+----------+ PCL4C Reference Manual Page 23 Error Code Summary +------+--------------------------------------------------------+ | Code | Description | +------+--------------------------------------------------------+ | 0 | No error. | | -1 | Timeout waiting for I/O. | | |2 | Port not enabled. Call SioReset first. | | |3 | No buffer available. Call SioRxBuf first. | | |4 | No such port. Expect 0 to MaxPort. (COM1 = 0) | | |5 | Expected 'S', 'C', or 'R' as 2nd argument. | | |6 | Expected 'A', 'C', or 'D' as 2nd argument. | | |7 | Bad parity code specified. Expected 0 to 7. | | |8 | Bad stop bits code specified. Expected 0 or 1. | | -9 | Bad wordlength code specified. Expect 0 to MaxPort. | | -10 | Bad buffer size code specified. Expected 0 to 11. | | |11 | Bad baud rate code. Expected 0 to 9. | | |12 | Loopback test fails. | | |13 | UART undefined. | | |14 | Missing or bad UART. (no UART hardware ?) | | |15 | Port already enabled. | | |16 | ISR (interrupt) already in use. | | |17 | No such IRQ. (Should be 2 to 7) | | |18 | ISR limit (maximum of 4 PC IRQs) exceeded. | | |19 | Shareware screen cannot be displayed. | +-+----+--------------------------------------------------------+ PCL4C Reference Manual Page 24 Code Examples SioRxBuf / SioTxBuf Example int BufSize = 1024; int SizeCode = Size1024; char far *Ptr; int BufSeg; ... /* allocate receive buffer + 16 bytes */ Ptr = (char far *) _fmalloc(BufSize+16); BufSeg = FP_SEG(Ptr) + ((FP_OFF(Ptr)+15)>>4); /* pass receive buffer segment to PCL4C */ SioRxBuf(Port,BufSeg,SizeCode); /* allocate transmit buffer + 16 bytes */ Ptr = (char far *) _fmalloc(BufSize+16); BufSeg = FP_SEG(Ptr) + ((FP_OFF(Ptr)+15)>>4); /* pass transmit buffer segment to PCL4C */ SioTxBuf(Port,BufSeg,SizeCode) DigiBoard Example /* use 0x140 for odd IRQs & 0x141 for even IRQs */ SioPorts(8,COM1,0x140,DIGIBOARD); for(i=COM1;i<=COM8;i++) {/* set DigiBoard UART addresses */ SioUART(i,0x100+8*i); /* set DigiBoard for IRQ5 */ SioIRQ(i,IRQ5); } BOCA Board Example /* use base port + 7 */ SioPorts(16,COM1,0x100+7,BOCABOARD); for(i=COM1;i<=COM16;i++) {/* set BOCA Board UART addresses */ SioUART(i,0x100+8*i); /* set DigiBoard for IRQ5 */ SioIRQ(i,IRQ5); } PCL4C Reference Manual Page 25