home *** CD-ROM | disk | FTP | other *** search
Text File | 1996-11-20 | 49.5 KB | 1,429 lines |
-
-
- Personal Communications Library
-
- For Visual BASIC / Windows
-
-
- (PCLVBW)
-
-
-
- REFERENCE MANUAL
-
-
-
-
-
- Version 1.1
-
- July 1, 1996
-
-
-
-
- This software is provided as-is.
- There are no warranties, expressed or implied.
-
-
-
-
- Copyright (C) 1996
- 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 : info@marshallsoft.com
- web : www.marshallsoft.com
-
-
- _______
- ____|__ | (R)
- --+ | +-------------------
- | ____|__ | Association of
- | | |_| Shareware
- |__| o | Professionals
- --+--+ | +---------------------
- |___|___| MEMBER
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 1
- C O N T E N T S
-
-
-
- Chapter Page
-
- Table of Contents.............................2
- Introduction..................................3
- SioBaud....................................4
- SioBrkSig..................................4
- SioCTS.....................................5
- SioDCD.....................................5
- SioDone....................................6
- SioDSR.....................................6
- SioDTR.....................................7
- SioFIFO....................................7
- SioFlow....................................8
- SioGetc....................................8
- SioGetDiv..................................9
- SioInfo....................................9
- SioIRQ....................................10
- SioLine...................................10
- SioLoopBack...............................11
- SioModem..................................11
- SioParms..................................12
- SioPorts..................................12
- SioPutc...................................13
- SioRead...................................13
- SioReset..................................14
- SioRI.....................................14
- SioRTS....................................15
- SioRxBuf..................................15
- SioRxClear................................16
- SioRxQue..................................16
- SioTxBuf..................................17
- SioTxClear................................17
- SioTxFlush................................18
- SioTxQue..................................18
- SioUART...................................19
- SioUnGetc.................................19
- Function Summary.............................20
- Error Code Summary...........................21
- Code Examples................................21
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 2
- Introduction
-
-
-
- This manual lists all of the PCLVBW functions in alphabetical order. Every
- library function returns a value as follows:
-
- 1. Negative values for error conditions. The last page of this manual lists
- all error values and their meanings.
-
- 2. Non-negative values when returning data (eg: SioLine).
-
- 3. Zero otherwise. Note that a zero or positive return value is never an
- error.
-
- When debugging an application, all return values should be tested. Refer to
- page 23 "Error Code Summary" for a textual description of the error codes.
-
- There are two versions of the library. One version is with transmitter
- interrupts disabled and one with them enabled (the default). The default
- library is normally chosen.
-
- Refer to the User's Manual (PCLVBW.USR) for additional information.
-
- It is also recommended that the two example programs SIMPLE and LOGIN be
- studied as examples of calling the library functions. Refer to the Users
- Manual for a description of the example programs.
-
- All data and function types are integer unless otherwise specified.
- ( DEFINT A-Z ).
-
- IMPORTANT
-
- Be sure to read the README.DOC file. It contains last release notes and
- other last minutes changes and/or additions.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 3
- +-------------+------------------------------------------------------------+
- | SioBaud | Sets the baud rate of the selected port. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioBaud(ByVal Port,ByVal BaudCode)
- REM Port: Port selected (COM1 - COM20)
- REM BaudCode: Baud code [not baud rate]
-
- 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
-
-
-
-
-
- +-------------+------------------------------------------------------------+
- | SioBrkSig | Asserts, cancels, or detects BREAK signal. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioBrkSig(ByVal Port,ByVal Cmd)
- REM Port: Port selected (COM1 thru COM20)
- REM char Cmd: ASSERT, CANCEL, or DETECT
-
- 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
- PCLVBW.BAS. See TERM.BAS for an example of the use of SioBrkSig.
-
- 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
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 4
- +-------------+------------------------------------------------------------+
- | SioCTS | Reads the Clear to Send (CTS) modem status bit. |
- +-------------+------------------------------------------------------------+
-
- Syntax FUNCTION SioCTS(ByVal Port)
- REM 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.
-
-
-
-
-
-
-
-
-
- +-------------+------------------------------------------------------------+
- | SioDCD | Reads the Data Carrier Detect (DCD) modem staus bit. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioDCD(ByVal Port)
- REM 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 5
- +-------------+------------------------------------------------------------+
- | SioDone | Terminates further serial processing. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioDone(ByVal Port)
- REM 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 dereferences the transmit and receive
- buffers set up by SioRxQue and SioTxQue.
-
- 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 FUNCTION SioDSR(ByVal Port)
- REM Port: Port selected (COM1 thru COM20)
-
- Remarks The SioDSR function is used to read the Data Set Ready (DSR)
- modem status bit.
-
- 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
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 6
- +-------------+------------------------------------------------------------+
- | SioDTR | Set, clear, or read Data Terminal Ready (DTR) status bit. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioDTR(ByVal Port,ByVal Cmd)
- REM Port: Port selected (COM1 thru COM20)
- REM Cmd: DTR command (SET, CLEAR, or READ)
-
- Remarks The SioDTR function controls the Data Terminal Ready (DTR) bit
- in the modem control register. DTR should always be set when
- communicating with a modem. Commands (defined in PCLVBW.BAS)
- 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.
-
-
-
-
- +-------------+------------------------------------------------------------+
- | SioFIFO | Sets the FIFO trigger level (16550 UART only). |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioFIFO(ByVal Port,ByVal LevelCode)
- REM Port: Port selected (COM1 thru COM20)
- REM LevelCode: FIFO level code (see below)
-
- Remarks The SioFIFO function is used to enable both transmit & 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.
-
- 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 PCLVBW.BAS Name Trigger Level
- -1 FIFO_OFF Disable FIFO
- 0 LEVEL_1 1 byte
- 1 LEVEL_4 4 bytes
- 2 LEVEL_8 8 bytes [Recommended]
- 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).
-
-
-
-
-
- PCL4VB Reference Manual Page 7
- +------------+-------------------------------------------------------------+
- | SioFlow | Sets hardware (RTS/CTS) flow control. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioFlow(ByVal Port,ByVal Tics)
- REM Port: Port selected (COM1 thru COM20)
- REM Tics: # tics before TX timeout [due to CTS=0]
-
- 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. To enable hardware
- flow control, call SioFlow with Tics > 0. "Tics" is the number
- of timer tics (18.2 per second) before a call to SioPutc will
- time out because CTS was not set.
-
- In order for hardware flow control to work correctly, your modem
- must also be configured to work with hardware flow control, and
- your computer to modem cable must have RTS and CTS wired
- straight through. 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.
- -1 : Flow control disabled.
- >0 : Flow control enabled.
-
- See Also SioPutc
-
-
- +------------+-------------------------------------------------------------+
- | SioGetc | Reads the next character from the serial line. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioGetc(ByVal Port,ByVal Tics)
- REM Port: Port selected (COM1 thru COM20)
-
- 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. Be careful not to pass too large a
- value for Tics.
-
-
- 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 8
- +---------------+----------------------------------------------------------+
- | SioGetDiv | Reads the baud rate divisor. |
- +---------------+----------------------------------------------------------+
-
-
- Syntax FUNCTION SioGetDiv(ByVal Port)
- REM Port: Port selected (COM1 thru COM20)
-
-
- Remarks The SioGetDiv function reads the baud rate divisor. The baud
- rate can then be determined by the divisor:
-
- 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.
-
-
-
- +-------------+------------------------------------------------------------+
- | SioInfo | Returns PCLVBW library information. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioInfo(ByVal Cmd)
- REM Cmd: Command (See below)
-
- Remarks The SioInfo function returns an integer code corresponding to
- the Cmd as follows
-
- Command SioInfo returns
- -1 Cannot recognize command.
- ASC("V") Library version number.
- ASC("I") TRUE (not 0) if transmitter interrupts are enabled.
- ASC("T") The accumulative total number of transmitter interrupts.
- ASC("R") The accumulative total number of receiver interrupts.
-
- Returns
- See remarks above.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 9
- +-------------+------------------------------------------------------------+
- | SioIRQ | Assigns an IRQ line to a port. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioIRQ(ByVal Port,ByVal IRQcode)
- REM Port: Port selected (COM1 thru COM20)
- REM 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 PCLVBW
- 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 FUNCTION SioLine(ByVal Port)
- REM Port: Port selected (COM1 thru COM20)
-
- Remarks The SioLine function reads the line status register. The
- individual bit masks are as follows:
-
- &H40 = Transmitter empty.
- &H20 = Transmitter buffer empty.
- &H10 = Break detected.
- &H08 = Framming error.
- &H04 = Parity error.
- &H02 = Overrun error.
- &H01 = Data ready.
-
- The above are documented in the file PCLVBW.BAS.
-
- 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.
-
-
-
-
-
-
- PCL4VB Reference Manual Page 10
- +-------------+------------------------------------------------------------+
- | SioLoopBack | Does a UART loopback test. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioLoopBack(ByVal Port)
- REM 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 FUNCTION SioModem(ByVal Port, ByVal Mask)
- REM Port: Port selected (COM1 thru COM20)
- REM 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 11
- +-------------+------------------------------------------------------------+
- | SioParms | Sets parity, stop bits, and word length. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioParms(ByVal Port,ByVal Parity,
- ByVal StopBits,ByVal DataBits)
- REM Port: Port selected (COM1 - COM20)
- REM Parity: Parity code [0,1,2]
- REM StopBits: Stop bits code [0,1]
- REM 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 PCLVBW.BAS. (8 = default)
-
- Value Description PCLVBW.BAS 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 FUNCTION SioPorts(ByVal NbrPorts,ByVal FirstPort,
- ByVal StatusReg,ByVal Code)
- REM NbrPorts: Total number of ports
- REM FirstPort: First DigiBoard port
- REM StatusReg: DigiBoard Status Register
- REM 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 the PCLVBW users maniual for more information on the
- DigiBoard and 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.
-
- PCL4VB Reference Manual Page 12
- +-------------+------------------------------------------------------------+
- | SioPutc | Transmit a character over a serial line. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioPutc(ByVal Port,ByVal Ch)
- REM Port: Port selected (COM1 thru COM20)
- REM Ch: Character to send [ASC(char)]
-
- 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 (there are separate
- versions of the library for transmitter interrupts enabled),
- then the byte is placed in the transmit buffer, awaiting
- transmission by the PCLVBW interrupt service routine.
-
- 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)
-
- See Also SioGetc and SioFlow.
-
-
- +-------------+------------------------------------------------------------+
- | SioRead | Reads any UART register. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioRead(ByVal Port,ByVal Reg)
- REM Port: Port selected (COM1 thru COM20)
- REM 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 PCLVBW 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 PCLVBW User's Manual for a
- discussion of the UART registers.
-
- Returns -3 : No buffer available. Call SioRxBuf and SioTxBuf first.
- -4 : No such port. Expect 0 to MaxPort.
-
- See Also SioLine and SioModem.
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 13
- +-------------+------------------------------------------------------------+
- | SioReset | Initialize a serial port for processing. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioReset(ByVal Port,ByVal BaudCode)
- REM Port: Port selected (COM1 thru COM20)
- REM 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 PCLVBW. 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 "PCLVBW.BAS".
-
- Returns -3 : No buffer available. Call SioRxBuf & SioTxBuf 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, SioDone, and SioUART.
-
-
-
- +-------------+------------------------------------------------------------+
- | SioRI | Reads the Ring Indicator (RI) modem status bit. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioRI(ByVal Port)
- REM 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.
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 14
- +-------------+------------------------------------------------------------+
- | SioRTS | Sets, clears, or reads the Request to Send (RTS) line. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioRTS(ByVal Port, ByVal Cmd)
- REM Port: Port selected (COM1 thru COM20)
- REM 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 some 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 PCLVBW.BAS) are:
-
- SET_LINE ASC("S") - set RTS (ON)
- CLEAR_LINE ASC("C") | clear RTS (OFF)
- READ_LINE ASC("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.
-
-
- +------------+-------------------------------------------------------------+
- | SioRxBuf | Sets up receive buffers. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioRxBuf(ByVal Port,ByVal Selector,ByVal SizeCode)
- REM Port: Port selected (COM1 thru COM20)
- REM Selector: Receive buffer selector
- REM SizeCode: Buffer size code
-
- Remarks The SioRxBuf function passes the address selector and size of
- the receive buffer to PCLVBW. Recall that PCLVBW 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 "PCLVBW.BAS".
-
- Size Code Buffer Size PCLVBW.BAS 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 and Code Examples.
-
- PCL4VB Reference Manual Page 15
- +------------+-------------------------------------------------------------+
- | SioRxClear | Clears the receive buffer. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioRxClear(ByVal Port)
- REM 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 SioRxClear 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.
-
-
-
-
-
-
- +-------------+------------------------------------------------------------+
- | SioRxQue | Returns the number of bytes in the receive queue. |
- +-------------+------------------------------------------------------------+
-
-
- Syntax FUNCTION SioRxQue(ByVal Port)
- REM 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 SioRxFlush.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 16
- +------------+-------------------------------------------------------------+
- | SioTxBuf | Sets up transmitter buffer. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioTxBuf(ByVal Port,ByVal Selector,ByVal SizeCode)
- REM Port: Port selected (COM1 thru COM20)
- REM Selector: Receive buffer selector
- REM SizeCode: Buffer size code
-
- Remarks The SioTxBuf function passes the address selector and size of
- the transmit buffer to PCLVBW, provided that you will link with
- a PCLVBW library with transmitter interrupts enabled. PCLVBW
- requires a transmit buffer for each port in simultaneous
- operation if you are using the version of the library with
- transmitter interrupts enabled (PCLVBW2.LIB). SioTxBuf() must
- be called before SioReset.
-
- Size Code Buffer Size PCLVBW.BAS 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
-
- This function is not used unless the transmitter interrupts are
- enabled (the default library). Refer to the PCLVBW Users
- Manual for information on transmitter (TX) interrupts.
-
- 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 | Clears the transmitter buffer. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioTxClear(ByVal Port)
- REM 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 PCLVBW 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 PCLVBW 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 SioTxQue & SioTxFlush.
-
-
-
-
-
- PCL4VB Reference Manual Page 17
- +------------+-------------------------------------------------------------+
- | SioTxFlush | Flushes the transmitter buffer characters. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioTxFlush(ByVal Port)
- REM Port: Port selected (COM1 thru COM20)
-
- Remarks The SioTxFlush function will transmit any characters in the
- transmit buffer before returning. In order to clear the buffer,
- call SioTxClear instead.
-
- Returns -2 : Port not enabled. Call SioReset first.
- -4 : No such port. Expect 0 to MaxPort.
-
- See Also SioTxQue & SioTxClear.
-
-
-
-
-
-
- +------------+-------------------------------------------------------------+
- | SioTxQue | Returns the number of bytes in the transmit queue. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioTxQue(ByVal Port)
- REM 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 PCLVBW library with transmitter interrupts
- enabled.
-
- This function is not used unless the transmitter interrupts are
- enabled. Refer to the PCLVBW 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 18
- +------------+-------------------------------------------------------------+
- | SioUART | Sets the UART base address. |
- +------------+-------------------------------------------------------------+
-
-
- Syntax FUNCTION SioUART(ByVal Port,ByVal Address)
- REM Port: Port selected (COM1 thru COM20)
- REM 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 PCLVBW 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 FUNCTION SioUnGetc(ByVal Port,ByVal Ch)
- REM Port: Port selected (COM1 thru COM20)
- REM 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 19
- Function Sumary
-
-
-
- +-------------+----------+----------+----------+----------+
- | Function | Arg1 | Arg2 | Arg3 | Arg4 |
- +-------------+----------+----------+----------+----------+
- | SioBaud | Port | BaudCode | | |
- | SioBrkSig | Port | Cmd | | |
- | SioCTS | Port | | | |
- | SioDCD | Port | | | |
- | SioDone | Port | | | |
- | SioDSR | Port | | | |
- | SioDTR | Port | Cmd | | |
- | SioFIFO | Port | LevelCode| | |
- | SioFlow | Port | | | |
- | SioGetc | Port | Tics | | |
- | SioGetDiv | Port | | | |
- | SioInfo | Cmd | | | |
- | SioIRQ | Port | IRQcode | | |
- | SioLine | Port | | | |
- | SioLoopBack | Port | | | |
- | SioModem | Port | Mask | | |
- | SioParms | Port | Parity | StopBits | DataBits |
- | SioPorts | NbrPorts | FirstDBP |StatusReg | Code |
- | SioPutc | Port | Ch | | |
- | SioRead | Port | Register | | |
- | SioReset | Port | BaudCode | | |
- | SioRI | Port | | | |
- | SioRTS | Port | Cmd | | |
- | SioRxBuf | Port | BufSeg | SizeCode | |
- | SioRxClear | Port | | | |
- | SioRxQue | Port | | | |
- | SioTxBuf | Port | BufSeg | SizeCode | |
- | SioTxClear | Port | | | |
- | SioTxFlush | Port | | | |
- | SioTxQue | Port | | | |
- | SioUART | Port | Address | | |
- | SioUnGetc | Port | Ch | | |
- +-------------+----------+----------+----------+----------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 20
- 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 and SioTxBuf first |
- | |4 | No such port. Expect COM1 to COM20. |
- | |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. Expected 0 to 3. |
- | -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 15) |
- | |18 | ISR limit (maximum of 4 PC IRQs) exceeded. |
- +-+----+--------------------------------------------------------+
-
-
- Code Examples
-
-
- DigiBoard Example
-
- 'status reg uses &H140 for odd IRQs & &H141 for even IRQs
- RC = SioPorts(8,COM1,&H140,DIGIBOARD)
- FOR I = COM1 TO COM20
- 'set DigiBoard UART addresses
- RC = SioUART(i,&H100+8*i)
- 'set DigiBoard for IRQ5
- RC = SioIRQ(I,IRQ5)
- NEXT I
-
- BOCA Board Example
-
- 'status reg uses base port + 7
- RC = SioPorts(16,COM1,&H100+7,BOCABOARD)
- FOR I = COM1 TO COM16
- 'set BOCA UART addresses
- RC = SioUART(i,&H100+8*i)
- 'set BOCA for IRQ5
- RC = SioIRQ(I,IRQ5)
- NEXT I
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PCL4VB Reference Manual Page 21
-