home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
DP Tool Club 19
/
CD_ASCQ_19_010295.iso
/
dos
/
prg
/
bas
/
pcl4b42
/
pcl4bref.doc
< prev
next >
Wrap
Text File
|
1994-10-19
|
67KB
|
1,633 lines
Personal Communications Library
For BASIC
(PCL4B)
REFERENCE MANUAL
Version 4.2
Sept 1, 1994
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1994
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice 205-881-4630
FAX 205|881|4630
BBS 205-880-9748
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
PCL4B 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
SioCrtWrite................................5
SioCTS.....................................6
SioDCD.....................................6
SioDelay...................................7
SioDone....................................7
SioDSR.....................................8
SioDTR.....................................8
SioError...................................9
SioFIFO....................................9
SioFlow...................................10
SioGetc...................................10
SioGetDiv.................................11
SioKeyPress...............................11
SioKeyRead................................12
SioInfo...................................12
SioIRQ....................................13
SioLine...................................13
SioLoopBack...............................14
SioModem..................................14
SioParms..................................15
SioPorts..................................15
SioPutc...................................16
SioRead...................................16
SioReset..................................17
SioRI.....................................17
SioRTS....................................18
SioRxBuf..................................18
SioRxFlush................................19
SioRxQue..................................19
SioTimer..................................20
SioTxBuf..................................20
SioTxFlush................................21
SioTxQue..................................21
SioUART...................................22
SioUnGetc.................................22
Function Summary.............................23
Error Code Summary...........................24
Code Examples................................24
PCL4B Reference Manual Page 2
Introduction
This manual lists all of the PCL4B 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
The following code is the complete MINIMAL.BAS program. It talks on COM1 at
2400 baud. The code is as follows:
+--------------------------------------------------------+
| |
| ' |
| ' MINIMAL.BAS: Talk on COM1 @ 2400 baud |
| ' |
| '$INCLUDE: 'PCL4B.INC' |
| 'Reset port |
| S$ = STRING$(256,0) |
| BufSeg = SSEG(S$) + (SADD(S$)\16) + 1 |
| CODE = SioRxBuf(COM1, BufSeg, Size256) |
| CODE = SioReset(COM1, Baud2400) |
| DO |
| 'Anything incoming ? |
| CODE = SioGetc(COM1, 1) |
| IF CODE > -1 THEN CODE = SioCrtWrite(CODE) |
| 'Anything to send ? |
| IF SioKeyPress() <> 0 THEN |
| ANYKEY = SioKeyRead() |
| 'Exit if user types Escape (ESC=27) |
| IF ANYKEY = 27 THEN EXIT DO |
| CODE = SioPutc(COM1,ANYKEY) |
| END IF |
| LOOP |
| CODE = SioDone(COM1) |
| END |
| |
+--------------------------------------------------------+
For more examples, examine each of the example programs provided (SIMPLE.BAS
and TERM.BAS). Also look at the examples associated with each library
function described in the following section.
Also note that there are two versions of the library for each memory model.
One version is with transmitter interrupts disabled and one with them
enabled.
Refer to the User's Manual (PCL4B.USR) for addition information.
PCL4B Reference Manual Page 3
+-------------+------------------------------------------------------------+
| SioBaud | Sets the baud rate of the selected port. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioBaud(Port,BaudCode)
REM Port: Port selected (COM1 - COM16)
REM 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 FUNCTION SioBrkKey()
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. Don't mix this
function up with SioBrkSig.
Returns -1 : Control-BREAK was pressed.
0 : Control-BREAK was NOT pressed.
See Also SioBrkSig
PCL4B Reference Manual Page 4
+-------------+------------------------------------------------------------+
| SioBrkSig | Asserts, cancels, or detects BREAK signal. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioBrkSig(Port,Cmd)
REM Port: Port selected (COM1 thru COM16)
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
PCL4B.BI. 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
+-------------+------------------------------------------------------------+
| SioCrtWrite | Write character to the screen. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioCrtWrite(Ch)
REM char Ch: Character to write
Remarks The SioCrtWrite function uses the BIOS to write a single
character to the screen at the current cursor location.
Returns zero.
See Also SioKeyPress and SioKeyRead.
PCL4B Reference Manual Page 5
+-------------+------------------------------------------------------------+
| SioCTS | Reads the Clear to Send (CTS) modem status bit. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioCTS(Port)
REM Port: Port selected (COM1 thru COM16)
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(Port)
REM Port: Port selected (COM1 thru COM16)
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.
PCL4B Reference Manual Page 6
+-------------+------------------------------------------------------------+
| SioDelay | Delays one or more timer tics. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioDelay(Tics)
REM 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).
Returns zero.
See Also SioTimer
+-------------+------------------------------------------------------------+
| SioDone | Terminates further serial processing. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioDone(Port)
REM Port: Port selected (COM1 thru COM16)
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.
PCL4B Reference Manual Page 7
+-------------+------------------------------------------------------------+
| SioDSR | Reads the Data Set Ready (DSR) modem status bit. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioDSR(Port)
REM Port: Port selected (COM1 thru COM16)
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
+-------------+------------------------------------------------------------+
| SioDTR | Set, clear, or read Data Terminal Ready (DTR) status bit. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioDTR(Port,Cmd)
REM Port: Port selected (COM1 thru COM16)
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 PCL4B.BI) 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.
PCL4B Reference Manual Page 8
+-------------+------------------------------------------------------------+
| SioError | Displays error in text. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioError(Code)
REM Code: PCL4B error code
Remarks The SioError function displays the error in text corresponding
to the error code returned from a PCL4B 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.
+-------------+------------------------------------------------------------+
| SioFIFO | Sets the FIFO trigger level (16550 UART only). |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioFIFO(Port,LevelCode)
REM Port: Port selected (COM1 thru COM16)
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 or when running
simultaneous ports.
In order to take advantage of the TX FIFO, use the PCL4B library
with TX interrupts enabled.
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 PCL4B.BI 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).
PCL4B Reference Manual Page 9
+------------+-------------------------------------------------------------+
| SioFlow | Sets hardware (RTS/CTS) flow control. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioFlow(Port,Tics)
REM Port: Port selected (COM1 thru COM16)
REM 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 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 Flag=FALSE.
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
+------------+-------------------------------------------------------------+
| SioGetc | Reads the next character from the serial line. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioGetc(Port,Tics)
REM Port: Port selected (COM1 thru COM16)
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.
PCL4B Reference Manual Page 10
+---------------+----------------------------------------------------------+
| SioGetDiv | Reads the baud rate divisor. |
+---------------+----------------------------------------------------------+
Syntax FUNCTION SioGetDiv(Port)
REM Port: Port selected (COM1 thru COM16)
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.
+-------------+------------------------------------------------------------+
| SioKeyPress | Detects if keyboard key has been pressed. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioKeyPress()
Remarks The SioKeyPress function uses the BIOS to test the keyboard for
a key press (including control characters).
SioKeyPress calls the BIOS directly without any intermediate
buffering or processing. It is usually faster than using the C
library.
Returns zero.
See Also SioCrtWrite and SioKeyRead.
PCL4B Reference Manual Page 11
+--------------+-----------------------------------------------------------+
| SioKeyRead | Reads the keyboard. |
+--------------+-----------------------------------------------------------+
Syntax FUNCTION SioKeyRead()
Remarks The SioKeyRead function uses the BIOS to read the keyboard. It
will wait until a character is typed.
SioKeyRead calls the BIOS directly without any intermediate
buffering or processing. It is usually faster than using the C
library.
Returns zero.
See Also SioCrtWrite and SioKeyRead.
+-------------+------------------------------------------------------------+
| SioInfo | Returns PCL4B library information. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioInfo(Cmd)
REM Cmd: Command ('V' or 'I')
Remarks The SioInfo function returns an integer code corresponding to
either the (1) library version number or (2) whether or not
transmitter interrupts are enabled.
Returns Version ('V')
hex byte XY where version is denoted as X.Y
TX Interrupts ('I')
TRUE if transmitter interrupts are enabled in the library,
otherwise FALSE.
PCL4B Reference Manual Page 12
+-------------+------------------------------------------------------------+
| SioIRQ | Assigns an IRQ line to a port. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioIRQ(Port,IRQcode)
REM Port: Port selected (COM1 thru COM16)
REM IRQcode: IRQ number [IRQ2..IRQ7]
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 PCL4B
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(Port)
REM Port: Port selected (COM1 thru COM16)
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 PCL4B.BI.
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.
PCL4B Reference Manual Page 13
+-------------+------------------------------------------------------------+
| SioLoopBack | Does a UART loopback test. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioLoopBack(Port)
REM Port: Port selected (COM1 thru COM16)
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(Port, Mask)
REM Port: Port selected (COM1 thru COM16)
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.
PCL4B Reference Manual Page 14
+-------------+------------------------------------------------------------+
| SioParms | Sets parity, stop bits, and word length. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioParms(Port,Parity,StopBits,DataBits)
REM Port: Port selected (COM1 - COM16)
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 PCL4B.BI. (8 = default)
Value Description PCL4B.BI 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(NbrPorts,FirstPort,StatusReg,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 ther PCL4B 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.
PCL4B Reference Manual Page 15
+-------------+------------------------------------------------------------+
| SioPutc | Transmit a character over a serial line. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioPutc(Port,Ch)
REM Port: Port selected (COM1 thru COM16)
REM 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 (there are separate
versions of the library for transmitter interrupts enabled),
then the byte is placed in the transmit buffer, awaiting
transmission by the PCL4B 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(Port,Reg)
REM Port: Port selected (COM1 thru COM16)
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 PCL4B 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 PCL4B 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.
PCL4B Reference Manual Page 16
+-------------+------------------------------------------------------------+
| SioReset | Initialize a serial port for processing. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioReset(Port,BaudCode)
REM Port: Port selected (COM1 thru COM16)
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 PCL4B. 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 "PCL4B.BI".
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, SioDone, and SioUART.
+-------------+------------------------------------------------------------+
| SioRI | Reads the Ring Indicator (RI) modem status bit. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioRI(Port)
REM Port: Port selected (COM1 thru COM16)
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.
PCL4B Reference Manual Page 17
+-------------+------------------------------------------------------------+
| SioRTS | Sets, clears, or reads the Request to Send (RTS) line. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioRTS(Port, Cmd)
REM Port: Port selected (COM1 thru COM16)
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 PCL4B.BI) 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.
+------------+-------------------------------------------------------------+
| SioRxBuf | Sets up receive buffers. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioRxBuf(Port,Segment,SizeCode)
REM Port: Port selected (COM1 thru COM16)
REM Segment: Receive buffer segment
REM SizeCode: Buffer size code
Remarks The SioRxBuf function passes the address segment and size of
the receive buffer to PCL4B. Recall that PCL4B 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 "PCL4B.BI".
Size Code Buffer Size PCL4B.BI 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.
PCL4B Reference Manual Page 18
+------------+-------------------------------------------------------------+
| SioRxFlush | Flushes (clears) the receive buffer. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioRxFlush(Port)
REM Port: Port selected (COM1 thru COM16)
Remarks The SioRxFlush 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.
+-------------+------------------------------------------------------------+
| SioRxQue | Returns the number of bytes in the receive queue. |
+-------------+------------------------------------------------------------+
Syntax FUNCTION SioRxQue(Port)
REM Port: Port selected (COM1 thru COM16)
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.
PCL4B Reference Manual Page 19
+------------+-------------------------------------------------------------+
| SioTimer | Returns the number of system clock tics since midnight. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioTimer()
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
+------------+-------------------------------------------------------------+
| SioTxBuf | Sets up transmitter buffer. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioTxBuf(Port,Segment,SizeCode)
REM Port: Port selected (COM1 thru COM16)
REM Segment: Receive buffer segment
REM SizeCode: Buffer size code
Remarks The SioTxBuf function passes the address segment and size of
the transmit buffer to PCL4B, provided that you will link with a
PCL4B library with transmitter interrupts enabled. PCL4B
requires a transmit buffer for each port in simultaneous
operation if you are using the version of the library with
transmitter interrupts enabled (PCL4B2.LIB). SioTxBuf() must be
called before SioReset.
Size Code Buffer Size PCL4B.BI 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 (PCL4B2.LIB). Refer to the PCL4B 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.
PCL4B Reference Manual Page 20
+------------+-------------------------------------------------------------+
| SioTxFlush | Flushes (clears) the transmitter buffer. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioTxFlush(Port)
REM Port: Port selected (COM1 thru COM16)
Remarks The SioTxFlush function will delete any characters in the
transmit buffer for the specified port, provided that you will
link with a PCL4B 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 PCL4B 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.
+------------+-------------------------------------------------------------+
| SioTxQue | Returns the number of bytes in the transmit queue. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioTxQue(Port)
REM Port: Port selected (COM1 thru COM16)
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 PCL4B library with transmitter interrupts
enabled.
This function is not used unless the transmitter interrupts are
enabled. Refer to the PCL4B 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.
PCL4B Reference Manual Page 21
+------------+-------------------------------------------------------------+
| SioUART | Sets the UART base address. |
+------------+-------------------------------------------------------------+
Syntax FUNCTION SioUART(Port,Address)
REM Port: Port selected (COM1 thru COM16)
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 PCL4B 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(Port,Ch)
REM Port: Port selected (COM1 thru COM16)
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.
PCL4B Reference Manual Page 22
Function Sumary
+-------------+----------+----------+----------+----------+
| Function | Arg1 | Arg2 | Arg3 | Arg4 |
+-------------+----------+----------+----------+----------+
| SioBaud | Port | BaudCode | | |
| SioBrkSig | Port | Cmd | | |
| SioCTS | Port | | | |
| SioDCD | Port | | | |
| SioDone | Port | | | |
| SioDSR | Port | | | |
| SioDTR | Port | Cmd | | |
| SioError | Code | | | |
| SioFIFO | Port | FIFOcode | | |
| SioFlow | Port | | | |
| SioGetc | Port | Tics | | |
| SioGetDiv | Port | | | |
| SioInfo | Cmd | | | |
| SioIRQ | Port | IRQcode | ISRcode | |
| SioLine | Port | | | |
| SioLoopBack | Port | | | |
| SioModem | Port | Mask | | |
| SioParms | Port | Parity | StopBits |WordLength|
| SioPorts | NbrPorts | FirstDBP |StatusReg | Code |
| SioPutc | Port | Ch | | |
| SioRead | Port | Register | | |
| SioReset | Port | BaudCode | | |
| SioRI | Port | | | |
| SioRTS | Port | Cmd | | |
| SioRxBuf | Port | Buffer | SizeCode | |
| SioRxFlush | Port | | | |
| SioRxQue | Port | | | |
| SioTxBuf | Port | Buffer | SizeCode | |
| SioTxFlush | Port | | | |
| SioTxQue | Port | | | |
| SioUART | Port | Address | | |
| SioUnGetc | Port | Ch | | |
+-------------+----------+----------+----------+----------+
PCL4B 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. |
+------+--------------------------------------------------------+
Code Examples
SioRxBuf() Example
S$ = STRING(1024,0)
BufSeg = SSEG(S$) + (SADD(S$)\16) + 1
'BufSeg:0 is SEG:OFS address of 1024 contiguous bytes
RC = SioRxBuf(Port,BufSeg,SizeCode);
DigiBoard Example
'use 0x140 for odd IRQs & 0x141 for even IRQs
RC = SioPorts(8,COM1,0x140,DIGIBOARD);
FOR I = COM1 TO COM16
'set DigiBoard UART addresses
RC = SioUART(i,0x100+8*i);
'set DigiBoard for IRQ5
RC = SioIRQ(I,IRQ5);
NEXT I
BOCA Board Example
'use base port + 7
RC = SioPorts(16,COM1,0x100+7,BOCABOARD);
FOR I = COM1 TO COM16
'set BOCA UART addresses
RC = SioUART(i,0x100+8*i);
'set BOCA for IRQ5
RC = SioIRQ(I,IRQ5);
NEXT I
PCL4B Reference Manual Page 24
