TweetFollow Us on Twitter

Jun 98 Tips

Volume Number: 14 (1998)
Issue Number: 6
Column Tag: Tips & Tidbits

June 1998 Tips & Tidbits

by Steve Sisak

Over the past few months we've had a few tips submitted on how to open a serial port or detect if it is in use. Unfortunately, we haven't received one that was sufficiently correct or complete to publish as a winner. Since this seems like an interesting topic (and one that lots of people get wrong), I'm going to try a new format: a terse mini-article with enough information to get you started and pointers to more information.

If you like this format, have a good idea for a topic but don't know the answer, or have other ideas how to make this space more useful, please send mail to tips@mactech.com. I'll be glad to pay the standard reward and give you credit for a really good question (assuming I can find the answer and it's generally useful).

Serial Port TidBits

If you've ever tried to write an application which uses the serial port on a Macintosh, you've probably discovered that (1) it didn't work on the first try, (2) the information on what to do was scattered all over the place and (3) it still didn't work in all cases.

In case you haven't, the information for how to correctly open and use the serial drivers is scattered across Inside Macintosh, the Communication Toolbox documentation, the ARA SDK and various tech notes. There are also several misleading and obsolete descriptions in Inside Macintosh Vols. I-VI.

The most authoritative sources are Inside Macintosh: Devices and Tech note 1119, by Quinn (The Eskimo!) which pulls most of the relevant information together in one place.

Listing the Serial Ports

In the beginning, every Macintosh had exactly 2 serial ports named "Modem Port" and "Printer Port" and the names of their drivers were hard coded -- these days PowerBooks often have only one port and/or a built-in modem, NuBus and PCI cards make it possible for the user to add ports, and software creates "virtual" ports to make it possible for multiple programs to share the same physical port.

To determine how many ports a machine has and what their human-readable name are, you need to use the Communications Resource Manager (CRM), which is part of the Communications Toolbox (one of those managers that Apple has declared obsolete, but hasn't gotten around to replacing yet).

For each port, the CRM maintains a CRMSerialRecord containing the following information:

typedef struct CRMSerialRecord {
  short         version;
  StringHandle   inputDriverName;
  StringHandle   outputDriverName;
  StringHandle   name;
  CRMIconHandle  deviceIcon;
  long           ratedSpeed;
  long           maxSpeed;
  long           reserved;
} CRMSerialRecord, *CRMSerialPtr;

To iterate over the available ports, you use the function CRMSearch(). The following code fragment finds a port by name -- you can easily adapt it to build a menu, etc.:

CRMSerialPtr FindPortInfo(ConstStr255Param name)
{
  CRMRec      crmRec;
  CRMRecPtr    crm   = &crmRec;

  // Get the search started
  crmRec.crmDeviceType = crmSerialDevice;  crmRec.crmDeviceID   = 0;

  while ((crm = CRMSearch(crm)) != nil)
  {
    CRMSerialPtr portInfo = 
      (CRMSerialPtr) crm->crmAttributes;
    
    if (EqualString(*portInfo->name, name, false, true))
    {
      return portInfo;
    }
  }
  
  return nil;
}

Opening, Initializing and Closing a Serial port

There is a specific sequence of calls you must use to open, configure and close a serial port. It is listed in Inside Macintosh: Devices on page 7-11. If you do not make the calls in this order, strange things will happen.

The sequence is:

  1. Open the output driver, then the input driver; always open both.
  2. (optional) allocate a buffer larger than the default 64-byte buffer and call SerSetBuf.
  3. Set the handshaking mode.
  4. Set the baud rate and data format.
  5. Read and/or write the desired data.
  6. Call KillIO on both drivers to terminate any pending IO.
  7. Restore the default input buffers.
  8. Close the input driver, then the output driver.

Determining If a Serial Driver is Open

Determining if a serial driver is open in use is a little bit tricky and a lot of software gets it wrong. The problem is twofold: first, OpenDriver() doesn't bother to check if a driver is already open -- it just returns noErr and the reference number of the already-open driver. If you use it (or worse, close it when you're done) Bad Things(tm) will happen.

To get around this you must walk the device list in low memory to see if a driver is already open before trying to open it again.

The following routine finds the index of a driver in the unit table (or -1 if it doesn't exist):

short FindDriverIndex(ConstStr255Param name)
{
  StringPtr    driverName;
  short      index;
  AuxDCEHandle  entry;
  AuxDCEHandle*  table = (AuxDCEHandle*) LMGetUTableBase();
  short      count = LMGetUnitNtryCount();
  
  for (index = 0; index < count; index++)
  {
    if ((entry = table[index]) != nil)
    {
      if ((**entry).dCtlFlags & dRAMBasedMask)
      {
        driverName = (**((DRVRHeaderHandle)((**entry).dCtlDriver))).drvrName;
      }
      else
      {
        driverName = (*((DRVRHeaderPtr)((**entry).dCtlDriver))).drvrName;
      }
      
      if (EqualString(driverName, name, false, true))
      {
        return index;
      }
    }
  }
  
  return -1;
}

To check if a port is open, we can write:

Boolean  IsDriverOpen(ConstStr255Param name)
{
  short index = FindDriverIndex(name);
  
  if (index >= 0)
  {
    AuxDCEHandle dce = 
      ((AuxDCEHandle*) LMGetUTableBase())[index];
    
    if ((**dce).dCtlFlags & dOpenedMask)
    {
      return true;
    }
  }
  
  return false;
}

NOTE: LMGetUTableBase() is missing from some versions of the Universal Headers you may have to implement it yourself (or use newer headers).

Now for the second half of the problem -- the Serial Port Arbitrator, included with the Appletalk Remote Access server and other software allows a port to be opened "passively" meaning that a server may have a the port open to look for an incoming call, but will relinquish it if another application wants to use it.

In this case OpenDriver will return portInUse (-97) if the driver is open or noErr if it is not. (in either case, it will return a valid refNum). However, software which walks the device table will incorrectly think that the driver is open and report an error.

The correct procedure here is to use Gestalt to determine if the Serial Port Arbitrator is present and, if it is, then just call OpenDriver(), otherwise, walk the Unit Table:

Boolean  HaveSerialPortArbitration(void)
{
  long  result;
  OSErr  err;
  
  err = Gestalt(gestaltArbitorAttr, &result);
  
  return (err == noErr) && (result & (1 << gestaltSerialArbitrationExists));
}

OSErr OpenSerialDriver(ConstStr255Param name, short* refNum)
{
  if (!HaveSerialPortArbitration())
  {
    short index = FindDriverIndex(name);

    if (index >= 0)  // Driver is already open
    {
      *refNum = ~index;
      return portInUse;
    }
  }
  
  return OpenDriver(name, refNum);
}

Reading from a Serial Port

You can read from a serial port just like a file by using PBRead or FSRead, however you can't seek and if you try to read more bytes are actually available, you will hang the machine in SyncWait() until the number of bytes you requested is actually available.

To avoid this, you can make a status call to the input driver with csCode = 2 to find out how many bytes are available in the drivers buffer and then only request that many bytes.

Correction to May Tip -- Wrapper for ParamText

The tip "Wrapper for ParamText" incorrectly states that one cannot pass nil arguments to ParamText(). In fact, ParamText() has always accepted nil arguments, and leaves the corresponding parameters unchanged.

I use this feature frequently in order to conserve stack space. I can set all 4 parameters using only one Str255, as long as I do it one at a time.

Actually, this example only sets 3 params:

  void
ReportError( short doingIx, const char *what )
{
Str255          str;

  if( spareMem )
    DisposeHandle( spareMem );
  spareMem = NULL;

  CtoPstrcpy( str, (const unsigned char *)what, sizeof str );
  ParamText( str, NULL, NULL, NULL );

  GetErrString( doingIx, str );
  ParamText( NULL, str, NULL, NULL );

  /* Eww. But I don't have to ParamText menu item text every command,
    which might slow things down if we're being scripted.
  */

  if( doingIx == doingMenuCmd ) {
    str[0] = 0;
  if( tg.doingItem )
      GetID( tg.doingItem, str );
    ParamText( NULL, NULL, NULL, str );
  }

  else if( doingIx == doingMenuAct ) {
    str[0] = 0;
    if( tg.doingItem && tg.doingMenu )
    GetMenuItemText( GetMenu(tg.doingMenu), tg.doingItem, str );
    ParamText( NULL, NULL, NULL, str );
  }

  VerifyAlert( 144 );
  InitCursor();
  StopAlert( 144, DefaultFilter );
}

Tony Nelson
tonyn@tiac.net

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Affinity Designer 1.5.5 - Vector graphic...
Affinity Designer is an incredibly accurate vector illustrator that feels fast and at home in the hands of creative professionals. It intuitively combines rock solid and crisp vector art with... Read more
djay Pro 1.4.3 - Transform your Mac into...
djay Pro provides a complete toolkit for performing DJs. Its unique modern interface is built around a sophisticated integration with iTunes and Spotify, giving you instant access to millions of... Read more
Jamf Pro 9.98 - Powerful sysadmin/enterp...
Jamf Pro (formerly Casper Suite) is the EMM tool that delights IT pros and the users they support by delivering on the promise of unified endpoint management for Apple devices. At Jamf, connecting... Read more
Airmail 3.2.4 - Powerful, minimal email...
Airmail is an mail client with fast performance and intuitive interaction. Support for iCloud, MS Exchange, Gmail, Google Apps, IMAP, POP3, Yahoo!, AOL, Outlook.com, Live.com. Airmail was designed... Read more
RapidWeaver 7.3.1 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
PopChar 7.7 - $16.99 (51% off)
PopChar helps you get the most out of your font collection. With its crystal-clear interface, PopChar provides a frustration-free way to access any font's special characters. Features Expanded... Read more
Apple iTunes 12.6 - Play Apple Music and...
Apple iTunes lets you organize and stream Apple Music, download and watch video and listen to Podcasts. It can automatically download new music, app, and book purchases across all your devices and... Read more
MacPilot 9.0.6 - Enable over 1,200 hidde...
MacPilot gives you the power of UNIX and the simplicity of Macintosh, which means a phenomenal amount of untapped power in your hands! Use MacPilot to unlock over 1,200 features, and access them all... Read more
Sparkle Pro 2.1.4 - $79.99
Sparkle Pro will change your mind if you thought building websites wasn't for you. Sparkle is the intuitive site builder that lets you create sites for your online portfolio, team or band pages, or... Read more
TextSoap 8.3.3 - Automate tedious text d...
TextSoap can automatically remove unwanted characters, fix up messed up carriage returns, and do pretty much anything else that we can think of to text. Save time and effort. Be more productive. Stop... Read more

Splish, splash! The Pokémon GO Water Fes...
Niantic is back with a new festival for dedicated Pokémon GO collectors. The Water Festival officially kicks off today at 1 P.M. PDT and runs through March 29. Magikarp, Squirtle, Totodile, and their assorted evolved forms will be appearing at... | Read more »
Death Road to Canada (Games)
Death Road to Canada 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: Get it now at the low launch price! Price will go up a dollar every major update. Update news at the bottom of this... | Read more »
Bean's Quest Beginner's Guide:...
Bean's Quest is a new take on both the classic platformer and the endless runner, and it's free on the App Store for the time being. Instead of running constantly, you can't stop jumping. That adds a surprising new level of challenge to the game... | Read more »
How to rake in the cash in Bit City
Our last Bit City guide covered the basics. Now it's time to get into some of the more advanced techniques. In the later cities, cash flow becomes much more difficult, so you'll want to develop some strategies if you want to complete each level.... | Read more »
PixelTerra (Games)
PixelTerra 1.1.1 Device: iOS Universal Category: Games Price: $.99, Version: 1.1.1 (iTunes) Description: The world of PixelTerra is quite dangerous so you need to build a shelter, find some food supply and get ready to protect... | Read more »
Tokaido™ (Games)
Tokaido™ 1.0 Device: iOS Universal Category: Games Price: $6.99, Version: 1.0 (iTunes) Description: Discover the digital adaptation of Tokaido, the boardgame phenomenon that has already sold more than 250,000 copies worldwide, and... | Read more »
Card Thief (Games)
Card Thief 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Card Thief is a solitaire style stealth game played with a deck of cards. In Card Thief you move through a deck of cards as a... | Read more »
Smilegate’s crafting battler Super Tank...
Super Tank Rumbleputs you in the seat of your very own, handcrafted tank. You can choose from over 100 different parts to create your Super Tank before taking it out to wreak havoc on your opponents in glorious PVP combat. Now, Smilegate is upping... | Read more »
The best games to play while you wait fo...
Mass Effect: Andromeda arrives this coming Tuesday and people are getting understandably antsy. There's a whole weekend standing between us and a brand new Bioware adventure. What's a geek to do? Well, you could certainly give these fine mobile... | Read more »
Here are the best indie games that debut...
The App Store has been running a pretty spectacular promotion of indie games over the past few days, featuring a selection of indie games quite prominently on the storefront while releasing a brand new indie game each day. The promotion is running... | Read more »

Price Scanner via MacPrices.net

13-inch Touch Bar MacBook Pros on sale for up...
B&H Photo has the Apple 13″ Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.9GHz/512GB Touch Bar... Read more
Today only! 15-inch 2.7GHz Space Gray Touch B...
B&H Photo has the new 2016 15″ 2.7GHz Space Gray Apple Touch Bar MacBook Pro in stock today and on sale for $300 off MSRP for today only. Shipping is free, and B&H charges NY sales tax only... Read more
New $329 iPad A Fabulous Value; 10.5-Inch iPa...
Part of the iPad upgrade/new model puzzle is now in place. Yesterday, as KGI Securities financial services group analyst Ming-Chi Kuo last summer predicted they would, Apple released a new low-cost 9... Read more
New 9.7-Inch iPad Features All Of The Fun...
Apple today updated its most popular-sized iPad, featuring a brighter 9.7-inch Retina display and best-in-class performance at its most affordable price ever, starting at $329 (US) with 32GB of... Read more
Apple Introduces iPhone 7 and iPhone 7 Plus (...
Apple today announced iPhone 7 and iPhone 7 Plus (PRODUCT)RED Special Edition in a vibrant red matte aluminum finish, in recognition of more than 10 years of partnership between Apple and (RED). This... Read more
Apple now offering Certified Refurbished 15-i...
Apple is now offering Certified Refurbished 2016 15″ Touch Bar MacBook Pros for $360-$420 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2.6GHz... Read more
Apple Introduces Clips: A Free Innovative Way...
Apple today introduced Clips, a new app that makes it quick and fun for anyone to create expressive videos on iPhone and iPad. The app features a unique design for combining video clips, photos and... Read more
Urban Armor Gear Unveils Case For 4th Generat...
Orange County, California based Urban Armor Gear (UAG), designers of rugged, lightweight protective cases for phones, tablets and laptops, has released its latest drop-tested cases for Apple’s 4th... Read more
Most Users Continue To Prefer 5.0 to 5.3 Inch...
In the first half of 2016, US and UK smartphone users were most likely to be interested in purchasing a device with a 5.3″ or 5.0″ display. Findings in a new report from the User Experience... Read more
12-inch 1.2GHz Retina MacBooks on sale for up...
B&H has 12″ 1.2GHz Retina MacBooks on sale for up to $200 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 12″ 1.2GHz Space Gray Retina MacBook: $1439.99 $160 off MSRP - 12″ 1... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
Starte Dein Karriere-Abenteuer in den Hauptst...
…mehrsprachigen Teams betreust Du Kunden von bekannten globale Marken wie Apple , Mercedes, Facebook, Expedia, und vielen anderen! Funktion Du wolltest schon Read more
Starte Dein Karriere-Abenteuer in den Hauptst...
…mehrsprachigen Teams betreust Du Kunden von bekannten globale Marken wie Apple , Mercedes, Facebook, Expedia, und vielen anderen! Funktion Du wolltest schon Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.