Legacy Document

Inside Macintosh: Devices /

Chapter 7 - Serial Driver / Serial Driver Reference

Serial Driver Routines /

SerStatus

You can use the SerStatus function to obtain status information from the Serial Driver.

FUNCTION SerStatus (refNum: Integer; VAR serSta: SerStaRec):OSErr;

refNum

The driver reference number of the serial input or output driver.

serSta

A pointer to a serial status record.

DESCRIPTION

The SerStatus function returns status information for the specified input or output driver. This information includes error conditions, flow control status, and whether there are read or write operations pending. Because the serial status record is shared, the SerStatus function returns the same information whether you reference the input or output driver. The serial status record is defined by the SerStaRec data type:

TYPE SerStaRec =
PACKED RECORD
   cumErrs:    Byte;       {cumulative errors}
   xOffSent:   Byte;       {XOFF sent as input flow control}
   rdPend:     Byte;       {read pending flag}
   wrPend:     Byte;       {write pending flag}
   ctsHold:    Byte;       {CTS flow control hold flag}
   xOffHold:   Byte;       {XOFF flow control hold flag}
END;

Field Description

cumErrs

A bit field that indicates what errors have occurred since the last time the SerStatus function was called. You can use the bit mask constants shown below to test for particular errors. Errors detected include software overrun, break asserted, parity error, hardware overrun, and framing error.

xOffSent

A bit field that indicates if the driver has initiated input flow control by sending an XOFF character or negating the DTR signal. You can use the bit mask constants shown below to test for these conditions.

rdPend

This field contains a non-zero value if the driver has a read operation pending.

wrPend

This field contains a non-zero value if the driver has a write operation pending.

ctsHold

This field contains a non-zero value if the driver has suspended output due to the CTS handshake signal.

xOffHold

This field contains a non-zero value if the driver has suspended output due to receiving an XOFF character.

You can use the following constants as bit mask values for the cumErrs field, to detect which errors have occurred since the last time the SerStatus function was called. Because these are bit mask values, you can sum them to specify more than one error condition. The remaining bit values in the cumErrs field are reserved.

CONST
   swOverrunErr   = 1;     {software overrun error}
   breakErr       = 8;     {break signal asserted}
   parityErr      = 16;    {parity error}
   hwOverrunErr   = 32;    {hardware overrun error}
   framingErr     = 64;    {framing error}

You can use the following constants as bit mask values to test the xOffSent field for the specified conditions. The remaining bit values in the xOffSent field are reserved.

CONST 
   dtrNegated     = 64;    {DTR signal was negated}
   xOffWasSent    = 128;   {XOFF character was sent}

IMPORTANT

Calling SerStatus resets cumErrs and other fields of the serial status record, so repeated calls to SerStatus may not return identical results.

ASSEMBLY-LANGUAGE INFORMATION

The SerStatus function is equivalent to a Device Manager status request with a csCode value of 8; the serial status record is returned in the first 6 bytes of the csParam field (csParam[0] = SerStaRec).

You can execute the status request immediately, bypassing the I/O queue, by setting bit 9 of the trap word. You can set this bit by appending the word IMMED as the second argument to the trap macro. For example:

_Status, IMMED

This technique is recommended when you need to determine the current status of a port before issuing a subsequent I/O request.

RESULT CODES

noErr

0

No error