Using the SerialPort XObject

==========================================

You can use the SerialPort XObject to send and receive data over the MacintoshÕs two standard serial ports (commonly called the modem and printer ports). This XObject is built into MacroMind Director (and the Player), so you donÕt have to open an XLibrary to use it.

The following methods are supported by this XObject. Some of them return a result code. A result code of 0 indicates success, while a negative result code indicates an error condition.

------------------------------------------

mNew, portNumber -> object (or errorCode)

The mNew method creates and returns an instance of the SerialPort XObject.

The portNumber argument can be 0 to access the modem port or 1 to access the printer port.

Example:

     put SerialPort(mNew, 0) into port

------------------------------------------

mDispose 

The mDispose method closes the serial port and disposes of the XObject instance.

Example:

     port(mDispose)

------------------------------------------

mGetPortNum -> portNumber

The mGetPortNum method returns the portNumber for the XObject (0 for the modem port, 1 for the printer port).

Example:

     if port(mGetPortNum) = 0 then doModem
     else doPrinter

------------------------------------------

mWriteString, string -> resultCode 

The mWriteString method writes the specified string of characters to the port.

Example:

     port(mWriteString, "Here we go")

------------------------------------------

mWriteChar, characterNumber -> resultCode 

The mWriteChar method writes a single character, specified by its ACSII code number, to the port.

Example:

     port(mWriteChar, charToNum("$"))

------------------------------------------

mReadString -> string

The mReadString method reads the contents of the portÕs input buffer and returns it as a string.

Example:

     put port(mReadString) into input

------------------------------------------

mReadChar -> characterNumber

The mReadChar method reads a single character from the portÕs input buffer and returns its ASCII code number.

Example:

     if port(mReadChar) = charToNum(RETURN) then doIt

------------------------------------------

mReadCount -> number

The mReadCount method returns the number of characters in the portÕs input buffer.

Example:

     if port(mReadCount) < 10 then waitAWhile

------------------------------------------

mReadFlush 

The mReadFlush method clears the portÕs input buffer.

Example:

     if finished then port(mReadFlush)

------------------------------------------

mConfigChan, driverNumber, configuration -> resultCode

The mConfigChan method performs low-level configuration of the port. It allows the input and output sides of the port to be independently configured. 

The driverNumber argument can be 0 for the output driver or 1 for the input driver.

The configuration argument is the sum of four values: one for the baud rate, one for the number of stop bits, one for the parity, and one for the number of data bits. The values are shown below:

Baud Rate
			300 baud:								380
			600 baud:								189
			1200 baud:								94
			1800 baud:								62
			2400 baud:								46
			3600 baud:								30
			4800 baud:								22
			7200 baud:								14
			9600 baud:								10
		19200 baud:									4
		38400 baud:									1
		57600 baud:									0

Stop Bits
		1 stop bit:						16384
		1.5 stop bits:			-32768
		2 stop bits:				 -16384

Parity
			no parity:										0
			odd parity:						4096
			even parity:				12288

Data Bits
			5 data bits:								0
			6 data bits:					2048
			7 data bits:					1024
			8 data bits:					3072

Example: The statements

     put 22 + 16384 + 0 + 3072 into config
     port(mConfigChan, 0, config)
     port(mConfigChan, 1, config)

configure both the input and the output sides of the port for 4800 baud, 1 stop bit, no parity, and 8 data bits.

------------------------------------------

mHShakeChan, driverNumber, setFlags, xOnChar -> resultCode 

The mHShakeChan method determines the handshaking methods used by the port. It allows the input and output sides of the port to be independently configured. 

The driverNumber argument can be 0 for the output driver or 1 for the input driver.

The setFlags argument determines the handshaking methods to be used. Add the following values together for the desired methods:

		XOn/XOff output flow control:					1
		CTS hardware handshaking:							2
		XOn/XOff input flow control:						4
		DTR input flow control:										8

The xOnChar argument is the ASCII code number of the XOn character for XOn flow control.

Example: The statement

     port(mHShakeChan, 0, 2 + 4 + 8, 17)

enables CTS hardware handshaking, XOn/XOff input flow control (using Control-Q, ASCII code 17, for the XOn character), and DTR input flow control for the input driver.

------------------------------------------

mSetUp, baudRate, stopBit, parityBit -> resultCode

The mSetup method resets and configures both the input and the output drivers of the port.

The baudRate argument can be 1200, 2400, 4800, 4800, 9600, 19200, or 38400.

The stopBit argument can be 10 for 1 stop bit, 15 for 1.5 stop bit, or 20 for 2 stop bits.

The parityBit argument can be 0 for noParity, 1 for oddParity, or 2 for evenParity.

This method also configures the port for 8 data bits during asynchronous communication.  No handshaking options are assigned.

Example: The statement

   	port(mSetUp, 4800, 10 , 0)

configures the port for 4800 baud, 1 stop bit, no parity bit, 8 data bits, and no handshaking.

Note: The mSetup method is the recommended way to configure a serial port. For finer control, use mConfigChan and mHShakeChan.