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

Unite 3 3.1 - Turn websites into full-fe...
Unite 3 lets you turn websites into apps on your Mac and change the way you use your computer forever Creating your app It all starts with the new Unite creation tool. Simply enter a name for your... Read more
App Tamer 2.5.2 - Efficiently manage you...
App Tamer tames your processor-monopolizing apps and keeps them from chewing up excessive CPU time and battery life. Powered by a unique AutoStop feature, App Tamer stops each application when you... Read more
Sid Meier's Civilization IV 1.74 -...
Note: Sid Meier's Civilization IV is no longer under development and the developer provides no support for it. With Civilization IV, history as you know it, is history. Rule throughout time and... Read more
Day One 4.15.3 - Maintain a daily journa...
Day One is an easy, great-looking way to use a journal / diary / text-logging application. Day One is well designed and extremely focused to encourage you to write more through quick Menu Bar entry,... Read more
Backblaze 7.0.1.450 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac. With unlimited storage available for $6 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
Visual Studio Code 1.47.0 - Cross-platfo...
Visual Studio Code provides developers with a new choice of developer tool that combines the simplicity and streamlined experience of a code editor with the best of what developers need for their... Read more
Apple Pages 10.1 - Apple's word pro...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more
Shimo 5.0.2 - VPN client for everyone.
Shimo is the most versatile VPN client for OS X and it enables really everybody to master secure network. It supports more protocols than any other VPN application out there! CiscoVPN, AnyConnect,... Read more
Yasu 6.0.1 - System maintenance app.
Note: Yasu is not being sold anymore and is listed only for people who had purchased it in the past. Yasu was created with system administrators who service large groups of workstations in mind, Yasu... Read more
Keynote 10.1 - Apple's presentation...
Easily create gorgeous presentations with the all-new Keynote, featuring powerful yet easy-to-use tools and dazzling effects that will make you a very hard act to follow. The Theme Chooser lets you... Read more

Latest Forum Discussions

See All

Puzzle & Dragons welcomes the cast o...
Puzzle & Dragons has a history of wild crossovers, and its latest is no exception. The gates of hell are now open, and the cast of Devil May Cry have made their grand entrance into the world Puzzle & Dragons. The collaboration is set to... | Read more »
Meteorfall: Krumit's Tale is launch...
Meteorfall: Krumit's Tale is getting an iOS & Android beta test this Thursday, and you can sign up now to get involved. [Read more] | Read more »
Marvel Duel, NetEase's promising ca...
Marvel Duel, NetEase's collectable card battler, has now opened for pre-registration in Thailand, Indonesia, Malaysia, and the Philippines. [Read more] | Read more »
PUBG Mobile teams up with Yamaha for a l...
PUBG Mobile has had various collaborations with various companies since it first burst onto the scene. The latest sees the popular battle royale title teaming up with vehicle and marine products company Yamaha, meaning players can take one of... | Read more »
Marvel Super War launches its third seas...
Marvel Super War, NetEase's popular MOBA, has kicked off its third season today, introducing its Zone Invasion beta and an all-new playable superhero. [Read more] | Read more »
Brave Dungeon, Unlock Games' idle-R...
Brave Dungeon, Unlock Games' idle-RPG and auto chess title, has been downloaded over 1 million times since it launched last week. To commemorate reaching this milestone the developers have decided to host a series of in-game events. [Read more] | Read more »
Clash Royale: The Road to Legendary Aren...
Supercell recently celebrated its 10th anniversary and their best title, Clash Royale, is as good as it's ever been. Even for lapsed players, returning to the game is as easy as can be. If you want to join us in picking the game back up, we've put... | Read more »
Steam Link Spotlight - Disco Elysium
Steam Link Spotlight is a feature where we look at PC games that play exceptionally well using the Steam Link app. Our last entry was Signs of the Sojourner Read about how it plays using Steam Link over here. | Read more »
Distract Yourself With These Great Mobil...
There’s a lot going on right now, and I don’t really feel like trying to write some kind of pithy intro for it. All I’ll say is lots of people have been coming together and helping each other in small ways, and I’m choosing to focus on that as I... | Read more »
Pokemon Go's July Community Day wil...
Pokemon Go developers have announced the details concerning the upcoming Gastly Community Day. This particular event was selected by the players of the game after the Gas Pokemon came in second place after a poll that decided which Pokemon would... | Read more »

Price Scanner via MacPrices.net

Apple has 2020 13″ 4-Core MacBook Airs availa...
Apple has a full line of Certified Refurbished 2020 13″ 4-Core MacBook Airs available for $200 off the cost of new models. Each MacBook features a new outer case, comes with a standard Apple one-year... Read more
Apple restocks clearance 2019 13″ MacBook Pro...
Apple has restocked Certified Refurbished 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros starting at $979 and up to $440 off original MSRP. Apple’s one-year warranty is included, shipping is free, and... Read more
US Cellular offers $300 off any new Cellular...
US Cellular is offering a $300 discount on any new Cellular Apple iPad, iPad Air, iPad Pro, or iPad mini with a new line of service. According to US Cellular, “Promotional pricing requires purchase... Read more
Sale! 16″ MacBook Pros for $400 off Apple’s M...
Amazon has 16″ MacBook Pros on sale for $400 off Apple’s MSRP today with prices starting at $1999. Shipping is free: – 2019 16″ 2.6GHz 6-Core MacBook Pro Space Gray: $1999.99 $400 off MSRP – 2019 16... Read more
Lowest price ever: Apple AirPods Pro for $214...
Amazon-owned Woot has new Apple AirPods Pro on sale for today only (Monday, July 13th) for $214.99 including free shipping for Prime members. Their price is $35 off Apple’s MSRP, and it’s the lowest... Read more
Woot is selling refurbished Apple iPhones tod...
Amazon-owned Woot is selling refurbished unlocked Apple iPhones today for as low as $99. Shipping is free for prime members. The following models are available, and note that many will sell out... Read more
Take $50 off the 64GB Apple iPhone SE at Simp...
Use coupon code SUMMER2020 at Simple Mobile through July 31, 2020, and take 20% off the 64GB Apple iPhone SE + service plan. This is in addition to their standard $50 discount on the iPhone SE.... Read more
Weekend Sale: Woot offers clearance MacBook,...
Amazon-owned Woot is blowing out a wide range of MacBooks, MacBook Airs, and MacBook Pros starting at only $389. All models are open-box returns, and according to Woot, “these MacBooks are in New-... Read more
Apple’s 2020 Mac minis on sale for up to $100...
B&H Photo has Apple’s 2020 Mac minis on sale today for $40-$100 off MSRP, each including free expedited delivery for many US addresses. These are the same Mac minis sold by Apple in their retail... Read more
Apple restocks refurbished 10.5″ iPad Airs fo...
Apple has restocked 10.5″ WiFI iPad Airs models for up to $100 off MSRP, Certified Refurbished. Each iPad comes with Apple’s standard one-year warranty and includes a new outer case. Shipping is free... Read more

Jobs Board

Blue *Apple* Cafe Student Worker - Fall - P...
…to enhance your work experience. Student positions are available at the Blue Apple Cafe. Employee meal discount during working hours is provided. Duties include food Read more
Geek Squad Advanced Repair *Apple* Professi...
**769390BR** **Job Title:** Geek Squad Advanced Repair Apple Professional **Job Category:** Store Associates **Store Number or Department:** 000580-Reading-Store Read more
Executive Team Leader GM Sales (Assistant Man...
…(Assistant Manager General Merchandise and Operations) - Apple Valley, CaliforniaApply NowJob ID:R0000082364job family:Store Managementschedule:Full Read more
Executive Team Leader Assets Protection (Assi...
…Assets Protection (Assistant Manager Loss Prevention) - Apple Valley, CaliforniaApply NowJob ID:R0000082365job family:Store Managementschedule:Full Read more
*Apple* Computing Sales Professional - Best...
**768543BR** **Job Title:** Apple Computing Sales Professional **Job Category:** Store Associates **Store Number or Department:** 002509-Riverdale-Store **Job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.