# Overview of Serial Port I/O Routines (Windows*)

The serial port I/O (SPORT_xxx) routines help you perform basic input and output to serial ports. These routines are available only on Windows* systems.

The programming model is much the same as a normal file except the user does a connect (SPORT_CONNECT, SPORT_CONNECT_EX) and release (SPORT_RELEASE) to the port instead of an open and close of a file.

Two types of read and write operations (as determined in a mode on the connect call) are provided:

- Read and write arbitrary data from/to the port using SPORT_READ_DATA and SPORT_WRITE_DATA.

- Read and writes line-terminated data using SPORT_READ_LINE and SPORT_WRITE_LINE.

Once any I/O operation has been requested on the port, an additional thread is started that keeps a read outstanding on the port so that data will not be missed.

The SPORT_SET_STATE, SPORT_SET_STATE_EX, and SPORT_SET_TIMEOUTS (W*32 W*64) routines allow you to set basic port parameters such as baud rate, stop bits, timeouts, and so on. Additionally, you can call SPORT_GET_HANDLE to return the Windows* handle to the port so that you can call Windows* Communication Functions to implement additional needs.

## Calling the Serial Port I/O Routines

The SPORT_xxx routines are functions that return an error status:

- An error status of 0 (zero) indicates success

- Other values are Windows* error values that indicate an error

As described in the calling syntax, these routines require the following USE statement:

    USE IFPORT

The `USE IFPORT` statement includes the routine definitions in the compilation. You may also need to add a `USE IFWINTY` statement to your program because some Windows* constants may be required that are typically defined in the IFWINTY module.

Many arguments are optional. If a constant is used where an argument is both input and output, a probe for writeability is done before the output. Thus, in many cases, a constant may be used without creating a temporary variable. It should be noted, however, that doing so may not be compatible with all Fortran implementations.

## Run-Time Behavior of the Serial Port I/O Routines

To help ensure that data overruns do not occur, the SPORT_xxx run-time support creates a separate thread that maintains an outstanding read to the connected port. This thread is started when any read or write operation is performed to the port using the affiliated read/write routine. As such, port parameters must not be changed after you have started reading or writing to the port. Instead, you should set up the port parameters after connecting to the port and then leave them unchanged until after the port has been released.

If the parameters of the port must be changed more dynamically, use the SPORT_CANCEL_IO routine to ensure that no I/O is in progress. Additionally, that call will kill the helper thread so that it will automatically pick up the new, correct, parameters when it restarts during the next I/O operation.

## Serial Port Usage

Depending upon the application, serial port programming can be very simple or very complex . The SPORT_xxx routines are intended to provide a level of support that will help the user implement simple applications as well as providing a foundation that can be used for more complex applications. Users needing to implement full serial port protocols (such as a PPP/SLIP implementation or some other complex protocol) should use the Windows* Communication Functions directly to achieve the detailed level of control needed in those cases. Simple tasks, such as communicating with a terminal or some other data collection device are well suited for implementations using the SPORT_xxx routines.

You should first familiarize yourself with the hardware connection to the serial device. Typical connections used today involve either a 9 pin/wire connector or a 25 pin/wire connector. Many cables do not implement all 9 or 25 connections in order to save on costs. For certain applications these subset cables may work just fine but others may require the full 9 or 25 connections. All cables will implement the Receive/SendData signals as well as the SignalGround. Without these signals, there can be no data transfer. There are two other categories of important signals:

- Signals used for flow control

  Flow control signals tell the device/computer on the other end of the cable that data may be sent or that they should wait. Typically, the RequestToSend/ClearToSend signals are used for this purpose. Other signals such as DataSetReady or DataTerminalReady may also be used. Make sure that the cable used implements all the signals required by your hardware/software solution. Special characters (normally as XON/XOFF) may also be used to control the flow of data instead of or in addition to the hardware signals. Check your specific application to see what cabling is needed.

- Signals that indicate status or state of a modem or phone connection.

  These signals may not be required if the connection between the computer and the device is direct and not through a modem. This signals typically convey information such as the state of the carrier (CarrierDetect) or if the phone line is ringing (Ring). Again, make sure the cable used implements all the signals required for your application.

After the correct physical connection has been set up the programmer must become familiar with the data protocol used to communicate with the remote device/system.

Many simple devices terminate parcels of data with a "record terminator" (often a carriage return or line feed character). Other devices may simply send data in fixed length packets or packets containing some sort of count information. The two types of I/O routines provided by the SPORT_xxx support (line oriented using SPORT_READ_LINE and SPORT_WRITE_LINE or transfer raw data using SPORT_READ_DATA and SPORT_WRITE_DATA) can handle these two types of data transfer. The programmer must become familiar with the particular application to determine which type of I/O is more appropriate to use.

The SPORT_xxx routines call Windows* routines. For example, the SPORT_SET_STATE routine calls the routine SetCommState, which uses the DCB Communications Structure.

Parent topic: Run-Time Library Routines

## See Also

Portability Routines for a list of the SPORT routines