INITPORT

Initialize a serial port

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX

 

xcall INITPORT(port, [baud], [parity], [stop_bits], [length], [rts_cts], [xon_xoff], [dtr], 
&     [rts][, modem])

Arguments

port

An expression that contains a channel number from a Synergy DBL OPEN statement. (n)

baud

(optional) An expression that contains the desired baud rate (bps) setting. Possible values are 50, 75, 110, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, 9600, 19200, and 38400. The default is 9600. (n)

parity

(optional) An expression that indicates the desired parity: (n)

1 = No parity (default)

2 = Even parity

3 = Odd parity

stop_bits

(optional) An expression that indicates the number of stop bits: (n)

1 = One stop bit (default)

2 = Two stop bits

length

(optional) An expression that contains the desired word length (number of data bits). Possible values are 5, 6, 7, and 8. The default is 8. (n)

rts_cts

(optional) On Windows only, an expression that enables or disables the Request to Send/Clear to Send software flow control: (n)

1 = Disable RTS/CTS protocol. (default)

2 = Enable RTS/CTS protocol.

xon_xoff

(optional) An expression that enables or disables the XON/XOFF software flow control: (n)

1 = Disable XON/XOFF protocol. (default)

2 = Enable XON/XOFF protocol.

3 = Enable receive XON/XOFF only.

4 = Enable transmit XON/XOFF only.

dtr

(optional) On Windows only, an expression that asserts a Data Terminal Ready signal (RS232 pin 20): (n)

1 = Assert the signal. (default)

2 = Retract the signal.

rts

(optional) An expression that asserts a Request to Send signal (RS232 pin 4): (n)

1 = Assert the signal. (default)

2 = Retract the signal.

modem

(optional) An expression that specifies modem control: (n)

1 = Modem control (default)

2 = No modem control

Discussion

The INITPORT subroutine initializes a serial (asynchronous) port for subsequent I/O. It gives you more control over communication parameters for your serial port or channel because you can establish these settings from your Synergy program.

INITPORT can only be used after an OPEN statement.

On Windows, Data Terminal Ready (DTR) is usually asserted by the Data Terminal Equipment (DTE) to indicate a powered-up and ready condition to the attached Data Communications Equipment (DCE). The DTE asserts Request to Send (RTS) to indicate that it is ready to send data. The rts argument differs from the rts_cts argument, which lets you control the RTS/CTS hardware flow on Windows. This flow is a protocol in which the RTS modem control signal is turned on or off automatically by the amount of data in the receiving buffer, and in which the CTS modem status signal can be directed to control the transmitter. The rts argument simply enables you to assert or retract the signal.

On Windows, use of XON/XOFF disables RTS/CTS flow control.

On UNIX, INITPORT sets up the port as if an stty -raw had been performed.

The rts_cts and dtr arguments serve no function on UNIX. RTS/CTS flow control is not implemented because it is not available on most UNIX systems. The DTR signal control is not available because it is automatically raised when a channel is opened to a port and lowered when a channel is closed to a port.

Using the sleep command in INITTAB with an stty implies that DTR is always high. To control DTR, use off in INITTAB, open a channel with a Synergy DBL OPEN statement, and then use INITPORT to set the speed, and so forth. When the channel is closed, DTR drops, and the port resets to UNIX default speed settings.

There are two ways to access a serial port on UNIX systems—one with uppercase letters (such as
/dev/tty1A) and one with lowercase letters (such as /dev/tty1a). The uppercase form indicates use of CCITT modem control signal checking and time-outs.

To open a port using the uppercase letter form on UNIX, use the /NODELAY OPEN OPTIONS qualifier. If you do not specify this qualifier, the OPEN fails after a time-out period. You must also use the INITPORT subroutine to set the optional modem argument to 1 (modem control, which is the default) so that the “hupcl” and “clocal” stty flags are correctly set. When using the lowercase form to access a serial port, set the INITPORT modem argument to 2 (no modem control). This implies “-hupcl clocal” stty settings for correct operation.

Note

The serial communications set up by INITPORT fully support hardware and software flow control. Most machines reliably receive data at rates up to 19,200 bauds per second. In some cases, a hardware upgrade to a 16550x UART or faster machine may be necessary.

However, you must use a GETS statement, not an ACCEPT statement, with a multicharacter buffer to receive the data at higher rates.

For correct operation of a serial line, including acceptance of all possible character codes, you must use the INITPORT subroutine to set up the terminal characteristics. When using the INITPORT subroutine, make sure it follows the OPEN statement as soon as possible in case data arrives on the serial port before the port speed is set up in the UART by INITPORT. After a CLOSE, you must once again use the INITPORT subroutine (after a subsequent OPEN).

Synergy DBL uses the default settings if you don’t call INITPORT when doing serial port I/O. If you call INITPORT but omit an argument, the default setting for that argument is used.

In all cases, avoid doing single-character GETS/ACCEPT sequences with the TTSTS subroutine (which slows down the system). A computer may be slowed noticeably by trying to accept characters at 9600 baud. You should always use GETS with the WAIT and MASK qualifiers for timed I/O to a serial port. In this mode, several devices at 9600 baud can be handled simultaneously.

See also

OPEN statement

Examples

The following program is a terminal emulation program that uses the serial port interface and the INITPORT subroutine.

.define TTCHN           ,1
.define SRVCHN          ,2
.align
record
    ch          ,a10
    mask        ,[8]i4
    len         ,i4
    stat        ,i4
    data        ,a80
proc
    xcall flags(54020)                          ;No echo, lowercase
    open(TTCHN, i, "tt:")                       ;Channel 1 is console chan
    open(SRVCHN, i, "com1:")                    ;Channel 2 is serial chan
    xcall initport(SRVCHN, 9600, 1, 1, 8, 1, 2)
    xcall fill(%char(0), ^a(mask[]))
    repeat
      begin
        xcall ttsts(stat, TTCHN)                ;See if operator pressed key
        while (stat)
          begin
            accept(TTCHN, ch, exit)
            display(SRVCHN, ch)                 ;Send it to serial line
            xcall ttsts(stat, TTCHN)            ;See if more operator input
          end
        xcall ttsts(stat, SRVCHN)               ;If data is available from
        if (stat)
          begin
            gets(SRVCHN, data, WAIT:Q_NOWAIT, MASK:mask)
            len = %rdlen
            if (len)                            ;If data was received
              display(TTCHN, data(1:len))
          end
      end
exit,
    close TTCHN
    close SRVCHN
end