Legacy Document

Inside Macintosh: Networking With Open Transport / Part 2 - Open Transport Reference

Chapter 31 - Serial Endpoint Reference / Options

Serial Options

You can use these options with a protocol level of COM_SERIAL. The SERIAL_OPT_STATUS option is read only; none of these are association-related options.

enum {
   SERIAL_OPT_BAUDRATE        0x0100,
   SERIAL_OPT_DATABITS        0x0101,
   SERIAL_OPT_STOPBITS        0x0102,
   SERIAL_OPT_PARITY          0x0103,
   SERIAL_OPT_STATUS          0x0104,
   SERIAL_OPT_HANDSHAKE       0x0105,
   SERIAL_OPT_RCVTIMEOUT      0x0106,
   SERIAL_OPT_ERRORCHARACTER  0x0107,
   SERIAL_OPT_EXTCLOCK        0x0108,
   SERIAL_OPT_BURSTMODE       0x0109
};

Option descriptions

SERIAL_OPT_BAUDRATE

Sets the baud rate. Values can be 300 to 56700. (The default is 19200.)

SERIAL_OPT_DATABITS

Sets the data bits. Values can be 5, 6, 7, and 8. (The default is 8.)

SERIAL_OPT_STOPBITS

Sets the stop bits. Values can be 10, 15, or 20. These reflect a number that is 10 times the bit time value: 1, 1.5, and 2. (The default is 10.)

SERIAL_OPT_PARITY

Sets the parity.

	Parity	Value	Description
	kOTSerialNoParity	0	No parity. ( default)
	kOTSerialOddParity	1	Odd parity.
	kOTSerialEvenParity	2	Even parity.

SERIAL_OPT_STATUS

Returns the current status in this read-only option. One or more bits can be set.

	Status	Value	Description
	kOTSerialSwOverRunErr	0x01	Software overrun.
	kOTSerialBreakOn	0x08	A break on the line.
	kOTSerialParityErr	0x10	Parity error.
	kOTSerialOverrunErr	0x20	Hardware overrun.
	kOTSerialFramingErr	0x40	Framing error.
	kOTSerialXOffSent	0x0010000	The XOFF character has been sent.
	kOTSerialDTRNegated	0x0020000	The DTR signal is negated.
	kOTSerialCTLHold	0x0040000	The CTS signal is negated, causing a hold.
	kOTSerialXOffHold	0x0080000	The XOFF character has been received, causing a hold.
	kOTSerialOutputBreakOn	0x1000000	A break has been initiated.

SERIAL_OPT_HANDSHAKE

Sets the handshake to be used by the serial line. (The default is no handshake.) The high word of the integer is a bitmap with 1 or more of the following bits set:

	Handshake	Value	Description
	kOTSerialXOnOffInputHandshake	1	XON/XOFF set for input.
	kOTSerialXOnOffOutputHandshake	2	XON/XOFF set for output.
	kOTSerialCTSInputHandshake	4	CTS set on input.
	kOTSerialDTROutputHandshake	8	DTR set on output.

The third byte in the option is the XON character. and the lowest byte is the XOFF character. If these two values are 0 and if XON/XOFF handshaking was requested, Open Transport uses the default values of Control-Q for XON and Control-S for XOFF. Use the SerialHandShakeData macro to construct this value.

SERIAL_OPT_RCVTIMEOUT

Sets the number of milliseconds the receiver should wait before delivering less than the RcvLoWat number of incoming serial characters. If RcvLoWat is 0, then the value is the number of milliseconds of quiet time (no characters being received) that must elapse before characters are delivered to the client. In all cases, this option is advisory and serial drivers are free to deliver data whenever they deem it convenient. For instance, many serial drivers deliver data whenever 64 bytes have been received because 64 bytes is the smallest "Streams" buffer size. Be sure to look at the return value of the option to determine what it was negotiated to. Here are some examples of its use:

	RcvTimeout	RcvLoWat	Action
	0	0	Data is delivered immediately after it arrives.
	x	0	Data is delivered after x milliseconds of no incoming characters on the line.
	x	y	Data is delivered after y characters are received, or x milliseconds after the first character is received, whichever comes first.

SERIAL_OPT_ERRORCHARACTER

Sets how characters with parity errors are handled. A 0 value disables their replacement--that is, error characters are discarded. A single character value in the low byte designates the replacement character. When characters are received with a parity error, they are replaced by this specified character. If a valid incoming character matches the replacement character, then the received character's most-significant-bit is cleared. For this situation, an alternate replacement character may be specified in bits 8 through 15 of the 32-bit value, with 0xff being placed in bits 16 through 23. You can use the macros OTSrlSetPEChar and OTSrlSetPECharWithAlternate to get the bit placement correct. In this case, whenever a valid character is received that matches the first replacement character, it is replaced with this alternate character (which may be 0).

SERIAL_OPT_EXTCLOCK

Requests an external clock. A 0 value turns off external clocking (the default). Any other value is a requested divisor for the external clock. Although Open Transport serial endpoint providers do not support synchronous communications protocols, you can use this option to select an external timing signal for synchronous clocking between the sender and receiver. Be aware that not all serial implementations support an external clock and that not all requested divisors will be supported if such an implementation does support an external clock.

SERIAL_OPT_BURSTMODE

Requests burst mode operation. A value of 0 turns off burst mode (the default) and a value of 1 requests burst mode to be turned on. In burst mode, the serial driver continues looping, reading incoming characters, rather than waiting for an interrupt for each character. This option may not be supported by all serial drivers.

WARNING

Note that burst mode may adversely impact performance of the Macintosh system, since interrupts may be held off for long periods of time.