ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / PASCAL / PCL4P30.ZIP / PCL4P.REF < prev next >

Wrap

Text File | 1992-01-24 | 39.4 KB | 1,981 lines

Personal Communications Library For Turbo Pascal 4.0 & up ( PCL4P ) REFERENCE MANUAL Version 3.0 Jan 15, 1992 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1992 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Phone (205) 881-4630 PCL4P Reference Manual Page 1 Table of Contents Chapter Page Table of Contents.............................2 Introduction..................................3 SioBaud.......................................4 SioBrkKey.....................................5 SioBrkSig.....................................6 SioCTS........................................7 SioDCD........................................8 SioDelay......................................9 SioDone......................................10 SioDSR.......................................11 SioDTR.......................................12 SioError.....................................13 SioGetc......................................14 SioLine......................................15 SioLoopBack..................................16 SioModem.....................................17 SioParms.....................................18 SioPutc......................................19 SioReset.....................................20 SioRI........................................21 SioRTS.......................................22 SioRxBuf.....................................23 SioRxFlush...................................24 SioRxQue.....................................25 SioTimer.....................................26 SioUART......................................27 SioUnGetc....................................28 Function Summary................................29 Error Code Summary..............................30 PCL4P Reference Manual Page 2 Introduction This manual list all the PCL4P 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 +--------------------------------------------------------+ | RetCode := SioFunction(); (* any PCL4P function *) | | if RetCode < 0 then begin | | RetCode := SioError(RetCode); | | (* ...do some stuff... *) | | end; | +--------------------------------------------------------+ For more examples, examine each of the example programs provided. Also look at the examples associated with each library function described in the following section. PCL4P Reference Manual Page 3 SioBaud Function Sets the baud rate of the selected port. Syntax function SioBaud(Port,BaudCode:Integer) : Integer; Remarks The SioBaud function sets the baud rate without resetting the port. It is used to change the baud rate after calling SioReset. Baud Code Baud Rate PCL4P.H Name 0 300 Baud300 1 600 Baud600 2 1200 Baud1200 3 2400 Baud2400 4 4800 Baud4800 5 9600 Baud9600 6 19200 Baud19200 7 38400 Baud38400 8 57600 Baud57600 9 115200 Baud115200 Returns -4 : Port out of range. Expecting 0 to 3. -11 : Bad baud rate code. See above code values. Example /* do auto baud detect */ for Code = 0 to 9 do begin RetCode := SioBaud(Port,Code); RetCode := SioPutc(Port,'A'); if SioGetc(Port,18) = Ord('A') then begin writeln('Baud rate detected'); (*...do something here...*) end end; See Also SioReset PCL4P Reference Manual Page 4 SioBrkKey Function Return non-zero if the Control-BREAK key was pressed. Syntax function SioBrkKey : Integer; 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. Example if SioBrkKey then begin writeln('User typed Contrl-BREAK'); RetCode := SioDone(Port); halt; end; See Also SioBrkSig PCL4P Reference Manual Page 5 SioBrkSig Function Asserts, cancels, or detects BREAK signal. Syntax function SioBrkSig(Port:Integer;Cmd:Char) : Boolean; Remarks The SioBrkSig function controls the BREAK bit in the line status register. The legal commands are: ASSERT ('A') to assert BREAK CANCEL ('C') to cancel BREAK DETECT ('D') to detect BREAK ASSERT, CANCEL, and DETECT are defined in PCL4P.H. See TERM.C for an example of the use of SioBrkSig. Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. -6 : Illegal command. Expected 'A', 'C', or 'D'. >0 : BREAK signal detected ( DETECT command only ) Example (* Assert BREAK for 1 second *) RetCode := SioBrkSig(Port,ASSERT); RetCode := SioDelay(18); RetCode := SioBrkSig(Port,CANCEL); (* Detect BREAK *) if SioBrkSig(Port,DETECT) then begin writeln('BREAK signal detected'); (* ...do some more stuff... *) end See Also SioBrkKey PCL4P Reference Manual Page 6 SioCTS Function Reads the Clear to Send ( CTS ) modem status bit. Syntax function SioCTS(Port:Integer) : Integer; Remarks The SioCTS function is used to read the Clear to Send ( CTS ) modem status bit. Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. 0 : CTS is clear. >0 : CTS is set. Example RetCode := SioCTS(Port); if RetCode > 0 then write('CTS is set'); else write('CTS is clear'); See Also SioDSR, SioRI, SioDCD, and SioModem. PCL4P Reference Manual Page 7 SioDCD Function Reads the Data Carrier Detect ( DCD ) modem status bit. Syntax function SioDCD(Port:Integer) : Integer; 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 : Port out of range. Expecting 0 to 3. 0 : DCD is clear. >0 : DCD is set. Example RetCode := SioDCD(Port); if RetCode > 0 then write('DCD is set'); else write('DCD is clear'); See Also SioDSR, SioCTS, SioRI, and SioModem. PCL4P Reference Manual Page 8 SioDelay Function Delays one or more tics. Syntax function SioDelay(Tics:Integer) : Integer; Remarks The SioDelay function is used to delay one or more timer tics, where each timer tic is approximately 55 milliseconds ( 18 to the second ). Returns zero Example (* delay 5 seconds *) RetCode := SioDelay(5*18); See Also SioTimer PCL4P Reference Manual Page 9 SioDone Function Terminates further serial processing. Syntax function SioDone(Port:Integer) : Integer 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. Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. Example (* terminate processing for COM3 *) RetCode := SioDone(COM3); See Also SioReset. PCL4P Reference Manual Page 10 SioDSR Function Reads the Data Set Ready ( DSR ) modem status bit. Syntax function SioDSR(Port:Integer) : Integer; 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 : Port out of range. Expecting 0 to 3. 0 : DSR is clear. >0 : DSR is set Example RetCode := SioDSR(Port); if RetCode > 0 then write('DSR is set'); else write('DSR is clear'); See Also SioCTS, SioRI, SioDCD, and SioModem PCL4P Reference Manual Page 11 SioDTR Function Set, clear, or read the Data Terminal Ready ( DTR ) bit. Syntax function SioDTR(Port,Cmd:Integer) : Integer; Remarks The SioDTR function controls the Data Terminal Ready ( DTR ) bit in the modem control register. Commands ( defined in PCL4P.H ) are: SET ('S') to set DTR ( ON ) CLEAR ('C') to clear DTR ( OFF ) READ ('R') to read DTR Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. -5 : Not one of 'S', 'C', or 'R'. 0 : DTR is OFF (READ Command). >0 : DTR is ON (READ Command). Example (* turn DTR on for modem connected to COM4 *) RetCode := SioDTR(COM4,SET); See Also SioRTS. PCL4P Reference Manual Page 12 SioError Function Displays error in text. Syntax function SioError(Code:Integer) : Integer; Remarks The SioError function displays the error in text corresponding to the error code. 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 Example RetCode := SioReset(Port,Baud4800); if RetCode < 0 then RetCode := SioError(RetCode); PCL4P Reference Manual Page 13 SioGetc Function Reads the next character from the serial line. Syntax function SioGetc(Port,Tics:Integer) : Integer; Remarks The SioGetc function reads 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 tics to the second. To specify no waiting, call SioGetc with Tics = 0. Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. -1 : If timed out. >0 : Character read. Example RetCode := SioGetc(COM1,1); if RetCode <> -1 then writeln('Character is ', chr(RetCode) ); else writeln('Timed out'); See Also SioUnGetc and SioPutc. PCL4P Reference Manual Page 14 SioLine Function Reads the line status register. Syntax function SioLine(Port:Integer) : Integer; Remarks The SioLine function reads the line status register. The individual bit masks are as follows: 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 PCL4P.H. Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. >0 : Line status ( rightmost byte of word ). Example RetCode := SioLine(Port); if(RetCode and (FramingError or ParityError or OverrunError)) <> 0 then begin if (RetCode and FramingError) <> 0 then writeln('Framing Error'); if (RetCode and ParityError) <> 0 then writeln('Parity Error'); if (RetCode and OverrunError) <> 0 then writeln('Overrun Error') end else writeln('No error'); See Also SioModem. PCL4P Reference Manual Page 15 SioLoopBack Function Does a UART loopback test. Syntax function SioLoopBack(Port:Integer) : Integer; Remarks SioLoopBack makes use of the built in loopback test capability of the INS8250 UART. Normally SioLoopBack will never need to be called except if you suspect that your UART is bad. See the LOOPBACK.C program. Returns 0 : Loopback test is successfull. -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. -12 : Loopback test fails. Example RetCode := SioLoopBack(Port); if RetCode = 0 then write('Loopback test has succeeded'); else write('Loopback test has failed'); PCL4P Reference Manual Page 16 SioModem Function Reads the modem status register. Syntax function SioModem(Port:Integer; Mask:Char) ; Integer; Remarks The SioModem function reads the modem register. The bit definitions for the function mask are as follows: Bit PCL4P.H Name Function 7 DCD Data Carrier Detect 6 RI Ring Indicator 5 DSR Data Set Ready 4 CTS Clear To Send 3 DeltaDCD Delta DCD ( DCD has changed ) 2 DeltaRI Delta RI ( RI has changed ) 1 DeltaDSR Delta DSR ( DSR has changed ) 0 DeltaCTS Delta CTS ( CTS has changed ) Bits 4 through 7 represent the absolute state of their respective RS-232 inputs. Bits 0 through 3 repesent a change in the state of their respective RS-232 inputs since last read. The above definitions are also in the PCL4P.H file for use by your application program. Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. >0 : Modem status ( rightmost byte of word ). Example (* any change in DCD ? *) Status := SioModem(Port,DeltaDCD); if Status < 0 then begin RetCode := SioError(Status); Halt; end; else writeln('DCD status = ', SioModem(Port,DCD) ); See Also SioCTS, SioDCD, SioDSR and SioRI. PCL4P Reference Manual Page 17 SioParms Function Sets parity, stop bits, and word length. Syntax function SioParms(Port,ParityCode,StopBitsCode, WordLengthCode:Integer) : Integer; 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 PCL4P.H. Value Description PCL4P.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 * = Default Returns -4 : Port out of range. Expecting 0 to 3. -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. Example RetCode := SioParms(COM1,NoParity,OneStopBit,WordLength8); See Also SioReset. PCL4P Reference Manual Page 18 SioPutc Function Transmit a character over a serial line. Syntax function SioPutc(Port:Integer; Ch:Char) : Integer; Remarks The SioPutc function transmits one character over the selected serial line. Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. Example crc := 0; for i = 0 to 127 do begin crc := crcupdate( buffer[i], crc); RetCode := SioPutc(Port, buffer[i]); end; RetCode := SioPutc(crc); See Also SioGetc. PCL4P Reference Manual Page 19 SioReset Function Initialize a serial port for processing. Syntax function SioReset(Port,BaudCode:Integer) : Integer; 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 PCL4P. 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 "PCL4P.H". Returns -3 : No buffer available. Call SioRxBuf first. -4 : Port out of range. Expecting 0 to 3. -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 : Cannot enable both COM1 & COM3 or COM2 & COM4. Example RetCode := SioRxBuf(COM1,Ofs(Buffer),Seg(Buffer),Size128); RetCode := SioReset(Com1,Baud38400); if RetCode = 0 then writeln('RESET ok'); else begin RetCode := SioError(rc); if (RetCode and OverrunError) <> 0 then writeln('Overrun Error'); if (RetCode and ParityError) <> 0 then writeln('Parity Error'); if (RetCode and FramingError) <> 0 then writeln('Framing Error'); if (RetCode and BreakDetected) <> 0 then writeln('Break Detected'); end; See Also SioBaud, SioParms, SioRxBuf, SioDone, and SioUART. PCL4P Reference Manual Page 20 SioRI Function Reads the Ring Indicator ( RI ) modem status bit. Syntax function SioRI(Port:Integer) : Integer; 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 : Port out of range. Expecting 0 to 3. 0 : RI is clear. >0 : RI is set ( RING has occurred ). Example RetCode := SioRI(Port); if RetCode > 0 then write('RING'); See Also SioDSR, SioCTS, SioDCD, and SioModem. PCL4P Reference Manual Page 21 SioRTS Function Sets, clears, or reads the Request to Send ( RTS ) line. Syntax function SioRTS(Port:Integer; Cmd:Char) : Integer; Remarks The SioRTS function controls the Request to Send ( RTS ) bit in the modem control register. Commands ( defined in PCL4P.H ) are: SET ('S') -- set RTS ( ON ) CLEAR ('C') -- clear RTS ( OFF ) READ ('R') -- read RTS Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. -5 : Command is not one of 'S', 'C', or 'R'. 0 : RTS is OFF (READ Command). >0 : RTS is ON (READ Command). Example (* turn off RTS for modem *) RetCode := SioRTS(Port,CLEAR); See Also SioDTR. PCL4P Reference Manual Page 22 SioRxBuf Function Sets up receive buffers. Syntax function SioRxBuf(Port,BufferOfs,BufferSeg, SizeCode:Integer) : Integer; Remarks The SioRxBuf function passes the address and size of the receive buffer to PCL4P. Recall that PCL4P requires a receive buffer for each port in simultaneous operation since the receive function is interrupt driven. SioRxBuf passes the receive buffer to PCL4P for both the primary ( COM1/COM3 ) and secondary ( COM2/COM4 ) ports. It must be called before any incoming characters can be received. SioRxBuf must be called before SioReset. Buffer size codes are listed in "PCL4P.H". Size Code Buffer Size PCL4P.H Name 0 8 bytes Size8 1 16 bytes Size16 2 32 bytes Size32 3 64 bytes Size64 4 128 bytes Size128 5 256 bytes Size256 6 512 bytes Size512 7 1024 bytes Size1024 8 2048 bytes Size2048 9 4096 bytes Size4096 10 8192 bytes Size8192 11 16384 bytes Size16384 Returns -4 : Port out of range. Expecting 0 to 3. -10 : Bad buffer size code. Expecting 0 to 11. Example RetCode := SioRxBuf( COM1, Ofs(RxBuf),Seg(RxBuf), 128); See Also SioReset. PCL4P Reference Manual Page 23 SioRxFlush Function To flush the receive buffer associated with the specified port. Syntax function SioRxFlush(Port:Integer) : Integer; 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 : Port out of range. Expecting 0 to 3. Example (* setup receive buffer and reset port *) RetCode := SioRxBuf(COM1,Ofs(Buffer),Seg(Buffer),Size1024); RetCode := SioReset(COM1,Baud115200); (* flush any spurious character *) RetCode := SioRxFlush(COM1); (* ready for serial processing ! *) See Also SioRxQue. PCL4P Reference Manual Page 24 SioRxQue Function Returns the number of characters in the receive queue. Syntax function SioRxQue(Port:Integer) : Integer; Remarks The SioRxQue function will return the number of characters in the receive queue. It can be used to implement XON/XOFF flow control. Returns -2 : Port not enabled. Call SioReset first. -4 : Port out of range. Expecting 0 to 3. Example RetCode := SioRxBuf(COM1,Ofs(Buffer),Seg(Buffer),Size128); (* implement XON / XOFF *) count := SioRxQue(COM1); if (last=XON) and (count>120) then begin RetCode := SioPutc(COM1,char(XOFF)); last := XOFF; end if (last=XOFF) and (count<8) then begin RetCode := SioPutc(COM1,char(XON)); last := XON; end See Also SioRxFlush. PCL4P Reference Manual Page 25 SioTimer Function Returns the number of system clock tics since midnight. Syntax function SioTimer : LongInt; 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. Also see SioDelay. Returns timer tics. Example Var Time : LongInt; ... Time := SioTimer(); (* do some stuff *) Writeln('Elasped time ', SioTimer - Time ); See Also SioDelay. PCL4P Reference Manual Page 26 SioUART Function Sets the UART base address. Syntax function SioUART(Port,Address:Integer) : Integer; 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 PCL4P 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 : Port out of range. Expecting 0 to 3. Example (* Record fact that you don't have COM4 *) RetCode := SioUART(COM4, 0); See Also SioReset. PCL4P Reference Manual Page 27 SioUnGetc Function "Un-gets" the last character read with SioGetc(). Syntax function SioUnGetc(Port:Integer; Ch:Char) : Integer; 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 : Port out of range. Expecting 0 to 3. Example (* push back c so next SioGetc will get it *) RetCode := SioUnGetc(Port,c); See Also SioReset. PCL4P Reference Manual Page 28 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 | | | | | SioGetc | Port | Tics | | | | SioLine | Port | | | | | SioLoopBack | Port | | | | | SioParms | Port | Parity | StopBits |WordLength| | SioPutc | Port | Ch | | | | SioReset | Port | BaudCode | | | | SioRI | Port | | | | | SioRTS | Port | Cmd | | | | SioRxBuf | Port | Ofs(Buff)| Seg(Buff)| SizeCode | | SioRxFlush | Port | | | | | SioRxQue | Port | | | | | SioTimer | | | | | | SioUART | Port | Address | | | | SioUnGetc | Port | Ch | | | +-------------+----------+----------+----------+----------+ ( 26 functions ) PCL4P Reference Manual Page 29 Error Code Summary Code Description 0 No error. -1 Timeout waiting for input. (Only returned by SioGetc). -2 Port not enabled. Call SioReset first. -3 No buffer available. Call SioRxBuf before calling SioReset. -4 Port out of range. Expecting 0 to 3. Recall that COM1 is port 0, COM2 is port 1, etc. -5 Expected 'S', 'C', or 'R' as second argument. -6 Expected 'A', 'C', or 'D' as second argument. -7 Bad parity code specified. Must be 0 to 7. -8 Bad stop bits code specified. Must be 0 or 1. -9 Bad wordlength code specified. Must be 0 to 3. -10 Bad buffer size code specified. Must be 0 to 11. -11 Bad baud rate code. Must be 0 to 9. -12 Loopback test fails. -13 UART undefined. -14 Missing or bad UART. -15 Port already enabled. -16 Cannot enable both COM1 and COM3 or COM2 and COM4. PCL4P Reference Manual Page 30