Legacy Document

Inside Macintosh: Devices /

Chapter 7 - Serial Driver / Serial Driver Reference

Serial Driver Routines /

SerHShake

You can use the SerHShake function to set software handshaking options and other control information.

FUNCTION SerHShake (refNum: Integer; flags: SerShk): OSErr;

refNum

The driver reference number of the serial output driver.

flags

A pointer to a serial handshake record.

DESCRIPTION

The SerHShake function enables flow control, sets flow control characters, and specifies which conditions will cause input requests to be aborted.

Note that the SerHShake function has been superseded by a newer function that allows control over DTR handshaking. There is no high-level interface to the new function, you access it using a Device Manager control request with a csCode value of 14. This function uses the same SerShk data structure, but adds an additional field for DTR hardware flow control. See the section "Low-Level Routines," beginning on page 7-27, for a description of control routine 14.

The serial handshake record is defined by the SerShk data type:

TYPE SerShk = 
PACKED RECORD
   fXOn:    Byte;    {XON/XOFF output flow control flag}
   fCTS:    Byte;    {CTS output flow control flag}
   xOn:     Char;    {XON character}
   xOff:    Char;    {XOFF character}
   errs:    Byte;    {mask for errors that will terminate input}
   evts:    Byte;    {mask for status changes that cause events}
   fInX:    Byte;    {XON/XOFF input flow control flag}
   fDTR:    Byte;    {DTR input flow control flag(csCode14only)}
END;

Field Description

fXOn

Set this byte to a non-zero value to enable XON/XOFF output flow control.

fCTS

Set this byte to a non-zero value to enable CTS output flow control.

xOn

If XON/OFF flow control is enabled, this field specifies the character to use for XON.

xOff

If XON/XOFF flow control is enabled, this field specifies the character to use for XOFF.

errs

Indicates which errors will cause input requests to be terminated, using the bit mask constants shown below.

evts

Indicates whether changes in the CTS signal or the break signal will cause the Serial Driver to post device driver events, using the bit mask constants shown below.

fInX

Set this byte to a non-zero value to enable XON/XOFF input flow control.

fDTR

Set this byte to a non-zero value to enable DTR input flow control. This field is only used by control function 14; it is ignored by the SerHShake function.

You can use the following constants as bit mask values for the errs field, to specify which errors will cause input requests to be aborted. Because these are bit mask values, you can sum them to specify more than one error condition.

CONST
   parityErr      = 16; {parity error}
   hwOverrunErr   = 32; {hardware overrun error}
   framingErr     = 64; {framing error}

You can use the following constants as bit mask values for the evts field, to specify which status changes will cause the Serial Driver to post device driver events. Because these are bit mask values, you can sum them to specify more than one event.

CONST
   ctsEvent    = 32;    {change in CTS signal}
   breakEvent  = 128;   {change in break signal}

WARNING

Using device driver events is discouraged because interrupts are disabled during the event posting process, which may cause serial data to be lost or other events to be missed. Instead, you should use the SerStatus function to check the value of the ctsHold or breakErr flags in the serial status record.

ASSEMBLY-LANGUAGE INFORMATION

The SerHShake function is equivalent to a Device Manager control request with a csCode value of 10. To specify DTR flow control, use a csCode value of 14 and set the fDTR flag to a non-zero value. You pass the flags parameter in the csParam field (csParam[0] = flags).

RESULT CODES

noErr

0

No error