Be Newsletter

Volume III, Issue 15; April 14, 1999

Table of Contents

• New Resource "abuzz" with BeOS Audio Product Info
• BE ENGINEERING INSIGHTS: Driver Settings, By Arve Hjønnevàg
• DEVELOPERS' WORKSHOP: All Hail the Mother Node!, By Stephen Beaulieu
• Technical Support and Your Bottom Line, By Dave Brown
• After the BeDC, By Jean-Louis Gassée

A comprehensive new resource will make it easier for buyers and sellers of BeOS audio products to come together. "Product Buzz!," (http://www.lebuzz.com/productbuzz.html) hosted by the "le BUZZ" web site (http://www.lebuzz.com/), is an all-in-one listing of commercial hardware and software vendors and their products, including links to the companies, descriptions of the products, and anticipated release dates for those items not yet ready to purchase.

le BUZZ "Buzzmaster" Dane Udenberg says the new resource is primarily targeted toward audio professionals, musicians, MIDI studios, and other high-end audio users. A link from the page points seekers of shareware and freeware to Be.com's BeWare site.

In addition to the obvious benefit companies and end-users will get from the new resource, an added side benefit is its usefulness to value-added resellers. "We've already gotten several inquiries from several resellers who are interested in working with the companies on the list to create all-in-one PC audio workstation solutions, complete with audio hardware, and software components including editing, composition, and multi-tracking," Udenberg said.

Visitors to the new site page are encouraged to alert Dane to any additional products not already listed, or updated information on the products already on the list.

BeOS drivers are allowed to open files, but there are a few reasons why you don't want to do this to read settings. For one thing, if your driver is loaded before the file system, you can't open your settings file. If the boot volume's disk driver needs information from the settings file before it can access the disk, just opening a file won't work. Also, parsing settings files can be complicated by corrupt files, and a crash in driver code is fatal.

The next BeOS release will have an API for drivers and kernel modules to get settings. The API includes easy access to Boolean and string settings, and is available for all drivers and modules. For complex settings, a call is provided that returns the settings as a tree of parameters and values. The boot loader reads the settings files from the selected boot volume and passes them to the kernel for use by drivers. The boot loader also lets the user append settings at boot time. A line of the form "filename:parameters" in the advanced savemode menu will add "parameters" to the end of the specified settings file. This can be used to change debugging information, and to test different options on hardware where the driver doesn't work. For beta testers, all this should already work in 4.1b3.

The functions are defined as follows:

void *load driver settings(const char *drivername);


status t unload driver settings(void *handle);


const char *get driver parameter(void *handle,
                                 const char *keyname,
                                 const char *unknownvalue,
                                 const char *noargvalue);


bool get driver boolean parameter(void *handle,
                                  const char *keyname,
                                  bool unknownvalue,
                                  bool noargvalue);


const driver settings *get driver settings(void *handle);

• "drivername" is the name of the settings file and should match the name of the driver.
• "handle" is the handle returned from load driver settings.
• "keyname" is the parameter name to search for in the file.
• "unknownvalue" is the value to return if the key is not found.
• "noargvalue" is the value to return if the key is found but no value is specified.

A driver calls load driver settings with the name of the settings file as the argument (settingshandle = load driver settings(drivername);). This returns a handle that is passed to the other driver settings functions. The driver can look for specific parameters by calling get driver parameter and get driver boolean parameter, or it can get a pointer to the parsed settings from get driver settings. When the settings have been processed, unload driver settings will free the resources.

Let's look a simple example first. A driver "sample1" has one setting, "foo", that can be true or false. To specify the value of "foo", a line of form "foo value" is placed in the settings file. If there is no entry for "foo" in the file, the default is false; if there is an entry "foo" but no value is specified, we assume the value is true. The code for our example looks like this:

void *settingshandle;
bool foo;
settingshandle = load driver settings("sample1");
foo = get driver boolean parameter(settingshandle, "foo",
                                   false, true);
unload driver settings(settingshandle);

Now let's look at how this works. If there is no settings file named "sample1" in ~/config/settings/kernel/drivers/, load driver settings will return NULL. Since we pass NULL to get driver boolean parameter it will return the value we specified for no entry: false. "foo" will therefore be false.

If the file exists, but doesn't contain an entry "foo", the result is the same. In this case, we get a valid handle and get driver boolean parameter will look for a "foo" parameter in the file. Since the file doesn't contain "foo", it returns false as requested.

If the file contains one line starting with "foo", the second word in this line is used as the value. If no value is specified, get driver boolean parameter will return the last argument passed. If a value is specified and is one of the strings "1", "true", "yes", "on", "enable", or "enabled", true will be returned. If the value is "0", "false", "no", "off", "disable", or "disabled", false is returned. If the value doesn't match any of these strings it is treated the same as if no entry was found; in this case, false.

If more than one line in the file starts with "foo", the last one is used. This allows the user to override settings from the boot loader.

Another simple case is when a driver has a string setting.

void *settingshandle;
const char *string;
settingshandle = load driver settings("sample1");
string = get driver parameter(settingshandle, "string",
                              NULL, "default");
unload driver settings(settingshandle);

This works the same way as get driver boolean parameter, except that the string value of string is returned instead of the logical value. If the file doesn't exist, or exists but has no line starting with "string", string will be NULL. If the last line starting with "string" has no values, string will be "default". If string has a value, it is returned as a string. Note that only one value is returned. If more than one value is needed for a key, use get driver settings and search for your key.

For drivers that need complex settings, the get driver settings will return the settings file as a tree. This tree allows a parameter to have multiple values and subparameters.

The following structure holds the root of the tree.

typedef struct driver settings {
    int parameter count;
    struct driver parameter *parameters;
} driver settings;

Each parameter is of the form:

typedef struct driver parameter {
    char *name;
    int value count;
    char **values;
    int parameter count;
    struct driver parameter *parameters;
} driver parameter;

The settings file follows these rules:

• The file consists of parameters and comments.
• When a word starting with a '#' character is found, the rest of the line is treated as a comment.
• A parameter can have values and subparameters. A parameter has the following form in the settings file:

    name [value]* [{
    [parameter]*
    }] ['\n',',']
  

  ( [] optional part, []* optional repeated part )

• Names and values may not contain spaces unless they are preceded by a '\' or enclosed in quotes.

Here's an example that clarifies these points. For the file:

device 0 {
	attribute1 value
	attribute2 value
}
device 1 {
	attribute1 value
}

get driver settings will return a pointer to the following tree:

driver settings = {
  parameter count = 2
  parameters = {
    {
      name = "device"
      value count = 1
      values = { "0" }
      parameter count = 2
      parameters = {
        {
          name = "attribute1"
          value count = 1
          values = "value"
          parameter count = 0
          parameters = NULL
        },
        {
          name = "attribute2"
          value count = 1
          values = "value"
          parameter count = 0
          parameters = NULL
        }
      }
    },
    {
      name = "device"
      value count = 1
      values = { "1" }
      parameter count = 1
      parameters = {
        {
          name = "attribute1"
          value count = 1
          values = "value"
          parameter count = 0
          parameters = NULL
        }
      }
    }
  }
}

"Developers' Workshop" is a weekly feature that provides answers to our developers' questions, or topic requests. To submit a question, visit

http://www.be.com/developers/suggestion_box.html.

Our thanks to the developers who attended last weekend's BeDC. It was great to meet you and to pass on our Media Kit knowledge to you. We promised you some sample code RealSoonNow(tm) at the conference, so here's the first delivery.

In the Node Track session, we presented a new class -- the MotherNode -- as a work in progress for the next release. This class helps manage the events your node needs to handle. It's another virtual BMediaNode subclass, so you can mix it with all the other classes: BBufferConsumer, BBufferProducer, BControllable, BFileInterface, and BTimeSource. Unlike these other classes, however, the MotherNode doesn't define any new services that your node must provide. Instead, it implements some basic node necessities for you.

In a nutshell, the MotherNode services the node's control port with its own thread. When BMediaNode messages come in, the MotherNode pushes events on to its BTimedEventQueue. In the main loop the MotherNode waits for new messages until it's time to handle a new event. Then it pops the event off the event queue and calls HandleEvent() with it.

Subclasses of the MotherNode will implement MessageReceived and other time-related BMediaNode subclass hook functions (like BBufferConsumer::ProducerDataStatus) to push events onto the event queue. The subclass will also implement HandleEvent() to do the actual work required to make sure the event is handled properly (i.e., the real work of the node).

You'll find the MotherNode class at

<ftp://ftp.be.com/pub/samples/media_kit/MotherNode.zip>

This code is only of use to people with access to the current beta CD.

Finally, it is certain that the MotherNode's functionality will find its way into the final release under another name. However, the API should stay pretty similar, so only minor code changes will be needed.

"I can't print."

These are words that strike fear in the hearts of many good men and women in call centers all over the world, including some who are reading this article right now. We are the knowledgeable and somewhat strained voices on the far end of "the help line." We need a vacation and a fresh look at humanity. We are tech support. Let's look at how the user got to us.

Some time in the past, your company -- which consists of three developers respectively titled VP of Development 1, VP of Development 2, and King -- encountered a situation they were not entirely prepared for. The company just released Product, the coolest thing on the block, and made its first sales. Finally! There is great rejoicing.

Then, John Q. Pedestrian, famous for not knowing the difference between WALK and DON'T WALK, decides to buy your product. He pays his money, takes home your software, and installs it. OK, so far. But then something fails to happen exactly how, when, where, or why John expected. He sends e-mail to your company:

From:John Q. Pedestrian
To:King@Product.com

I can't print.

The person who read the mail thinks, "What do you MEAN you can't print? I spent weeks, months on this! It works fine here! We proved it! All our testing works fine! What could possibly be wrong?"

Let me stop here and say that it's easy to blame the user. But remember, John is a real person with family, friends, loved ones, a mortgage, a driver's license *shudder*, and a job. John can balance a checkbook. Sometimes he does his own taxes. He's had some college education. He's not stupid. He may or may not know the available resources. He may not speak your language. He may or may not have good communication skills. He's stuck.

Your development team has suddenly become its own tech support. This is a problem. It has to figure out what the company's users need, as well as what they expect -- and what the company expects of them. It must determine what resources are available to meet users' needs and how to deploy those resources.

As Be's Customer Technical Support (CTS) manager, figuring these things out is my job. I make sure you can find the answers you need, and that someone is there to supply the answers you can't find. And if other support people can't help you, I'm the answer guy of last resort. My experience for that role comes from having worked for the world's largest supplier of outsourced technical support, on a variety of subcontracts ranging from hardware and software to operating systems and appliances. I know my share and have all the funny stories to prove it.

If you're interested in some background on technical support, one of the best articles I've read was written for "MacWorld" magazine, by David Pogue. He spent a day with Apple's support group just after it had changed from free to fee-based support. Based on the kind of service people were getting for the fee charged, he concluded that "... [Apple] should charge twice that [amount]." (See <http://macworld.zdnet.com/pages/october.98/Column.4493.html>.

So, why is support a problem?

Needs, Wants and, Expectations

What the user wants from a product is often unrealistic. For example, that the product should work immediately and unconditionally, right out of the box, without having to *gasp* read the manuals and instructions. And should something fail, the guy on the other end of the phone should be the one who wrote it, and can wave his magic wand and make it work while releasing daily free updates. He wants unlimited free support on a toll-free call. The developer wants people to buy the product and register it, so they can be solicited to buy Product updates, and leave the developer alone so he can write Product 2.0.

User expectations are a more realistic versions of wants: competent, bug-free software; a warm, skilled body at the other end of the support line; bug fixes as necessary; a route to request new features; and so on. These can be tuned up or down depending on the cost of the product and the size of the company.

Needs are an acceptable compromise between user wants and expectations, and developer resources.

Determining the Needs of Your Users

The easiest way to measure a company's support staffing needs is to see how long it takes to respond to each contact. If a company is a week behind on the support e-mail, or if it knows that users are getting busy signals or 20-minute hold times, it's time to get some help. To decide how to handles users' needs, let's look at common BeOS developer-sized situations.

Joe Developer runs the Small Shareware Group Co. Your company is you, or maybe you and a couple of friends. People want support for freeware; they don't generally expect it, and they're happy to get it. If you have a shareware or commercial product, you need at least one person responsible for responding to users. Here are some tips:

• Set a target turnaround time for your responses, like 1-2 days.
• Send an auto reply to let users know you got their mail and you'll get back to them within this time. The most damaging thing to your company is to have an e-mail disappear into the void unanswered. It happens, but do all you can to eliminate the possibility.
• Notify users that you have an auto reply; if they don't get it, that means you didn't receive their mail.
• Set up a separate e-mail account or alias for the support mail, so when someone goes on vacation or gets sick, another person can step in.
• If you provide phone support, specify the hours.
• Accustom people to contacting the support address rather than a specific person, since a specific person may change jobs within the company, or leave.

Customers expect little when no money is involved, and are generally forgiving. Once you charge however, expectations shift. Customers expect support, updates, and other commercial software services, including daytime phone support, e-mail support, and FAQs on a web site. People want the ability to document requested features and report bugs. They want updates to cure bugs and possibly add features, but they don't usually expect them to come instantly.

Mid-sized CommercialSoft

This situation postulates a loosely defined group of developers, support, and operations people. Support technicians generally aren't the best paid group; they'll often take the next best thing on short notice, and burn out regularly, costing you time to find and train a new technician, time away from other work, etc. You should consider getting quotes from outsource support companies to see if it will better accommodate growth, both in your support team and in your development team. If Product 3.0 takes off as you think it will, having a flexible support team in place can make all the difference. Ask for some estimates on outsourced support, so you can look at your current costs and make an informed choice.

Supplying Users' Needs

Once you've looked at where your needs and your customers' needs meet, you have the options of indirect and direct support to supply them.

Indirect support includes FAQs, tips, manuals, faxback lines, etc. These are directly available to the user, with no human contact required. This is cheap, takes little time to put together, and any number of people can use it at no additional cost to you. The more you spend here, the less your other costs will be. Some general tips:

• A good, responsive manual and FAQ will attract people who want answers, and they'll look here before contacting a support person, which is expensive. Build and regularly update your FAQs based on the problems or questions you're most often contacted about.
• Interactive troubleshooters or help files and symptom- to-problem charts can be very useful.
• Track all your customer contacts. By looking at the reasons users call, you can use indirect support that will decrease the things you hear about most, cutting your biggest support costs.

Direct support can be by e-mail or phone. Consider that an average 20 minute phone call can cost about US $10-30; e-mail costs between 25% and 50% of that amount. On average, a technician can respond to three times as much e-mail as phone calls. However, some people insist on using phones, or are too impatient for e-mail. Depending on your needs, you can decide what combination is best for your company. Miscommunications and slow interaction times in e-mail can be a problem, but questions that call for the same reply are much easier and cheaper for both the developer and the user via e-mail than on the phone.

Who does the support also affects costs. There are generally three possibilities here:

• Development team. Currently most BeOS developers do this. It is the most costly -- not in dollars but in resource consumption. Time spent dealing with customers takes away from time spent on development. It's a necessary cost, however, since the alternative ultimately costs the company more in public opinion.
• In-house support. This is when a person/group inside the company is dedicated to handling customers. Many companies do this because it gives them tight control of information, quality, and staffing. This is a lot of work and is generally expensive. It's important that in-house support staff be both competent and dedicated, so that it's unnecessary to replace and train people often. The technicians are generally well paid and have quick access to the information they need. They stay with the company a long time and are generally happy, which is apparent to users. It's expensive if you have to constantly pay to train, hire, and fire technicians to accommodate the swings of more and less user contact, like updates versus the holidays.
• Outsource support. In this case person/group outside the compan, handles tech support. This is convenient and can be inexpensive, especially when used in mass. For example, an in-house employee costs the company a given amount of money per day no matter how many people contact support. An outsource company that shares many resources with other companies (phone lines, Internet connections, etc.) can offer support at a discount, sometimes as much as 33% off. An outsource service can provide many types of staffing, including dedicated technicians, shared technicians (techs that answer many types of calls each day), and dedicated groups of flexible size.

The most common is a dedicated group on a pay-per-contact price. In this situation, if there are a lot of questions in one month, the outsourcer moves more people in (and trains them) as needed. If the calls drop by 50% the next month, the outsourcer moves people to other responsibilities, until they're needed again. This cuts costs considerably, though quality control and employee retention can still be problem areas.

Making a Choice

The best way to decide what you should do is by assessing your needs and their potential costs. Tech support providers will be glad to write a quote for you. If you're looking at in-house support, remember to include computers, benefits, training time, phone lines and charges, office space, etc. in the costs. If you have other questions, contact me and I'll try to answer them.

But to get back to John Q. Pedestrian, his printing problem was a proprietary software driven printer switchbox without BeOS equivalent software, and he can now print. He got his answer within two days, and he's happy as a clam. He disconnects the old 386 he stopped using and buys future updates of your product and mentions how cool your company is to his friends. Meanwhile, the technician sighs wearily and opens the next e-mail...

I always feel nervous going to a developer conference, because we're going to meet the people who literally make us. It may be obvious but nonetheless bears repeating that an operating system has little or no value by itself. Applications determine its value -- hence the vital role of software developers -- and of events such as the BeDC. A developer conference is an opportunity to give a progress report on our work. We get vigorous feedback from people who are committed to the platform and, in return, we offer them information and suggestions on how they can make the best use of the APIs and development tools. And, of course, there are the T-shirts.

That's more or less the script we followed at last weekend's event. By all accounts, our opening act was a little flat -- I know, I was part of it -- but the main part, the Media Kit sessions, got the good reviews, much to our grateful delight. For this conference, we did some things differently: we charged admission; and we focused on the Media Kit, instead of addressing all aspects of the BeOS. We highlighted the Media Kit because it is the key to the most important application space -- digital media -- and it provides the tools to produce "tangible" (I should probably say visible and audible) proofs of BeOS advantages.

The result was a happy, productive conference. Several attendees made unsolicited comments about the usefulness of the session and the productive use of their time. I even got the same feedback from a Be engineer who's been immersed in other parts of our work. This is not to say that we won't have general purpose conferences in the future, but for the introduction of the Media Kit -- the keystone of the BeOS edifice -- we wanted to ensure that its concepts and facilities were treated with the attention its role in the BeOS architecture warrants.

At the beginning, I stated I was always nervous going to a developer's conference, but I should have added I always enjoy these events and come away more motivated than ever after meeting people who take our future in their own hands. My thanks to them and to the Be team for making this conference a success -- and a great time for yours truly.