Consultor Eletrônico

Why is a code example needed for my language or ADE issue ?

Progress Technical Support often asks customers to provide code
examples for questions concerning language and development tools
such as the User Interface Builder (UIB). Sometimes customers wish
to understand the reasons for such a request before undertaking the
work involved.


WHY SHOULD A CODE EXAMPLE BE NECESSARY?
=======================================

Customers will find that the Technical Support Engineer (TSE) working
with them will ask for a code example in the following situations:


o THE ISSUE IS COMPLEX.

The key to resolving any customer issue concerning language is for
the TSE to recreate the questioned behavior in-house and,
through analysis and consultation with other TSEs and Progress
developers, either explain the behavior or verify that it
represents a bug. In many cases, the only way to recreate an
issue with any degree of accuracy is to obtain code directly from
the source: the customer.

When an issue involves a specific question on a specific
structure in the language, a code example from the customer may not
be necessary: it may be enough just to talk about the problem.
For example, if a customer asks how to initialize a selection
list widget with records from a database, the question is
limited enough in scope to be easily understood outside the context
of an application. A code example is not necessary because in
discussing the answer, any selection list will do.

Once an issue begins to involve interaction between data structures
such as widgets, frames, variables, procedures, or database fields,
it is far more likely that a verbal description of the problem
will not be sufficient. In order for a TSE to research the issue
properly, a precise code example will be necessary.

It is important to remember that in any software language of even
modest complexity, there can be a hundred ways to implement a
particular feature, even in a comparatively simple design.
The primary reason that a TSE will ask for customer code is
to determine which of these hundred ways the customer has taken
in approaching a goal.


o THE ISSUE INVOLVES NON-STANDARD BEHAVIOR IN WHAT APPEARS TO BE A
SOUND IMPLEMENTATION OF THE LANGUAGE.

Sometimes a customer will report strange behavior which, upon
review of the general design approach, appears to be contrary to
what a language specialist would expect. The type of code involved
can seem extraordinarily simple, yet the code behavior is
completely wrong.

With issues that fall into this category, it is not what is
painfully obvious that is causing the problem -- otherwise, there
would be no need to obtain technical support in the first place.
Rather, it is the tiny, seemingly inconsequential details that
are most important. These details may reveal a subtle bug or
nuance of expected behavior, but because of their apparent
simplicity the customer does not know to mention them, nor the TSE
to ask about them.

One example is a subtle browse bug that was discovered early in
Version 7. A customer contacted Technical Support to report a
problem where the bottom row of the browse was always hidden by
the browse's horizontal scrollbar. The frame in question consisted
only of a browse and a "cancel" button, yet Tech Support was not
able to reproduce the problem. It was only after obtaining
code from the customer that the bug was traced to the way the SIZE
phrase for the browse had been written. Rather than use WIDTH and
HEIGHT, the customer had used WIDTH and DOWN. Once this difference
had been spotted, the problem was readily reproduceable and a bug
could be logged.


WHY DOES THE EXAMPLE NEED TO BE "SHORT"?
========================================

Asking that a code example be as short as possible (preferably less
than one type-written page) assures that (1) it can be sent to a TSE
easily by fax, email, or by placing it on the bulletin board; (2)
that code details not related to the problem have been eliminated;
and (3) that the TSE can quickly type it in or load it to reproduce
the problem.

Eliminating extraneous code details is of primary importance. An
application that has been under development for months will typically
consist of several hundred lines of code -- perhaps thousands. An
application of such complexity is best understood by the programmer
who works with it from day to day. For this reason, Technical
Support expects that customers themselves are best equipped to
systematically remove extraneous code from their applications. Very
often, too, in doing so, customers become aware of other factors
that affect the issue.

Where a possible bug is involved, the customer's code example usually
is attached to the actual bug report logged with Development. This
allows better confirmation that a fix to the bug is also a fix to the
customer's precise problem.

In instances where no potential bug is involved and customers ask
for design ideas, "how-to's", etc., the requirement for a short code
example is even greater. Technical Support is not equipped to
offer extensive advice about application design to customers,
although it is reasonable for customers to ask implementation
questions which are specific and focused in nature.


WHY DOES THE CODE EXAMPLE HAVE TO USE THE "SPORTS" OR "DEMO" DB?
================================================================

The main reason for asking customers to use the Sports database when
submitting code is to assure that their database itself is not
affecting the issue. If a problem can be reproduced using Sports,
then there can be little question that the issue is one of language
and not database internals.

Furthermore, code that runs against the Sports database is readily
set up by the TSE in testing. The fast turnaround benefits the
customer and ensures faster service for other customers as well.

In certain issues where potential bugs are involved, Technical Support
may allow a customer to submit code that runs only with the
application database. Customers should understand that in these
instances, it is not sufficient to merely fax data definition
information to the TSE; the files necessary to recreate the database
will need to be given to the TSE via email or the bulletin board,
or by shipping a tape or diskette. This may introduce unavoidable
delays in resolving the problem.


FREQUENTLY ASKED QUESTIONS
==========================

"Why should I have to provide a code example? Shouldn't a TSE be
trained to reproduce my problem straightaway?"

The complexity of language issues makes it very difficult to
reproduce a customer issue based on a verbal description except in
very limited cases. If your issue concerns behavior within your
custom application and cannot be readily narrowed down to a
very specific language question, then a code example will be
necessary to research it.


"What if a bug I'm seeing involves an interaction between parts of
my application which are completely separate? How can I be expected
to narrow that down?"

In cases where a potential bug exists, a TSE may request
that the customer provide a larger portion of code.
Keep in mind, however, that this will introduce delays,
since it will require you to package up a runnable portion of
your application, get it to the TSE, and assist the TSE in setting
up the environment.


"I'm not seeing a bug, but the question I have involves an interaction
between separate parts of my application that cannot be narrowed down.
What happens then?"

Where no potential bug is involved, customer questions about how
to implement their applications must be focused to the point that
a code example can be easily provided. It is outside the scope of
Progress's Technical Support offering to provide consultation
on issues where intensive study of a customer's application is
required. The best source of help in such cases is Progress
Consulting Services.


"I'm unable to make the same behavior happen when I use the Sports
database. What do I do?"

As long as you're willing to narrow down the code that uses your
custom database, it is possible that the TSE will be able to work
with you. However, you will need to package up your .df, and in
some cases your .d files, in order for the TSE to create a copy of
your environment.

Progress Software Technical Support Note # 15220