The Developer Connection…ice Driver Kit for OS/2 3/DEV3-D1.ISO/docs/devcon1.inf

OS/2 Help File | 1993-10-12 | 209.5 KB | 2,998 lines

ΓòÉΓòÉΓòÉ 1. Cover ΓòÉΓòÉΓòÉ

The Developer Connection News

The Developer Connection for OS/2  Γûá  Volume 1

"The complete source of information for all of your OS/2 development efforts."


ΓòÉΓòÉΓòÉ 2. Publisher's Note ΓòÉΓòÉΓòÉ

The Developer Connection News
August 1993
Volume 1
Number 1

Publisher                                    Barbara Britt

Editor, The Developer Connection News        Stacey Miller

Editorial Advisor                            Suzanne Gagnon

Technical Advisors                           David Kenner, Jay Tunkel

Art Director                                 Brian Black

The Developer Connection News is published quarterly by the Personal Systems
Line of Business of International Business Machines Corp., Boca Raton, Florida,
U.S.A., Stacey Miller, Editor.  The terms OS/2, OS/2 2.0, and OS/2 2.1 are used
in this publicatio n as abbreviations for the full term OS/2 operating system.
OS/2 is a registered trademark of the IBM Corporation. Titles and abstracts,
but no other portions, of information may be copied and distributed by
computer-based and other information service systems. Permission to republish
information from this publication in any other publication of computer-based
information systems must be obtained from the Editor.

IBM believes the statements contained herein are accurate as of the date of
publication of this document.  All specifications are subject to change without
notice.  However, IBM, hereby disclaims all warranties, either expressed or
implied, including with out limitation any implied warranty of merchantability
or fitness for a particular purpose.  In no event will IBM be liable to you for
any damages, including any lost profits, lost savings, or other incidental or
consequential damage arising out of the u se or inability to use any
information provided through this publication even if IBM has been advised of
the possibility of such damages, or for any claim by any other party.

Some states do not allow the limitation or exclusion of liability for
incidental or consequential damages so the above limitation or exclusion may
not apply to you.

This publication may contain technical inaccuracies or typographical errors.
Also, illustrations contained here may show prototype equipment.  Your
configuration may differ slightly.

This publication may contain articles by non-IBM authors.  These articles
represent the views of their authors.  IBM does not endorse any non-IBM
products that may be mentioned.  Questions should be directed to the authors.

This information is not intended to be an assertion of future action.  IBM
expressly reserves the right to change or withdraw current products that may or
may not have the same characteristics or codes listed in this publication. It
is possible that this material may contain reference to, or information about,
IBM products (machines and programs), programming or services that are not to
be construed to mean that IBM intends to announce such products, programming,
or services in your country.

IBM takes no responsibility whatsoever with regard to the selection,
performance, or use of the products advertised herein.  All understanding,
agreements, or warranties must take place directly between the software vendors
and perspective users.

To correspond with the IBM Developer Connection News, please write to the
Editor at IBM Corp., PO Box 1328, Internal ZIP 1510, Boca Raton, Florida 33431.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation whatever.

IBM, OS/2, PS/2, Micro Channel, Presentation Manager, Workplace Shell, AS/400,
and ES/3090 are registered trademarks of IBM Corp.

AIX, C/2, CUA, SAA, WIN-OS/2, AS/400, ES/390, AS/400, C Set/2, WorkSet/2,
WorkFrame/2 , Pen for OS/2, MMPM/2, and Multimedia Presentation Manager/2,
Ultimotion, and M-Audio Capture are trademarks of IBM Corp.

MS-DOS and Code View are registered trademarks of Microsoft Corp.

CompuServe is a registered trademark of CompuServe Incorporated.

UNIX is a registered trademark of AT&T Bell Laboratories.

Apple and Macintosh are registered trademarks, and System 7 is a trademark of
Apple Computer, Inc.

Borland is a registered trademark of Borland International, Inc.

Intel, DVI, Indeo, and Pentium are registered trademarks of Intel Corporation.

SmallTalk is a trademark of the Digitalk Corporation.

HockWare and VisPro/REXX are trademarks of HockWare, Inc.

WATCOM and Vx_Rexx are trademarks of WATCOM.

Kurta is a trademark of Kurta Corporation.

Wacom is a trademark of Wacom Co., Ltd.

Hitachi is a trademark of Htachi Ltd.

NEC is a trademark of NEC Corporation.

Panasonic is a trademark of Matsushita Electric Industrial Co., Ltd.

Pioneer is a trademark of Sony Corporation.

Toshiba is a trademark of Toshiba Corporation.

Future Domain is a trademark of Future Domain Corporation.

Adaptec is a trademark of Adaptec, Inc.

Kodak is a trademark of Eastman Kodak Company.

Taligent is a trademark of Taligent, Inc.


ΓòÉΓòÉΓòÉ 3. IBM Ships Premiere Issue of The Developer Connection for OS/2 ΓòÉΓòÉΓòÉ

by David Kenner

Welcome to The Developer Connection for OS/2!  Your participation in this
program ensures that you'll receive the latest and the best in development
information from IBM's own OS/2 development team.  But not just information,
The Developer Connection for OS/2 is a real product.  On the CD-ROM,  look for
internal, pre-release tools, APIs, sample code, and pre-release versions of the
new operating system technologies.


ΓòÉΓòÉΓòÉ 3.1. So How Did It Begin? ΓòÉΓòÉΓòÉ

It all began about a year ago, as a group of OS/2 developers asked themselves,
"How can we make a difference?  What is needed?"  They asked those questions at
the technical conferences, and really listened to the responses.  You said you
needed tools, samples of code, APIs, and accurate information.  You said you
needed it delivered on a regular basis, so you could have access to the latest
and the best.  This team brainstormed and came up with a product called the
Professional Developer Kit (or the PDK).  They delivered it at multiple OS/2
technical conferences. The response was overwhelmingly positive. You liked what
you saw, and we liked answering your needs.

The  PDK has since matured into a new product, The Developer Connection for
OS/2.  And that small team has also grown.  Over 18 folks in Boca Raton
participated in this release of the Developer Connection (and that number keeps
growing).  Our colleagues at the IBM Labs in Vienna, Austria and Santa Teresa,
California also helped in the direct development.  So, the development of The
Developer Connection for OS/2 really was a worldwide team effort.


ΓòÉΓòÉΓòÉ 3.2. What Exactly Do You Get? ΓòÉΓòÉΓòÉ

Each CD-ROM contains a powerful search browser that lets you, with the click of
a mouse, locate any desired piece of information.  It's front-end is an
easy-to-use GUI.  Each item on the CD-ROM is catalogued into a specific
category.  When you want to see the contents of that category all you need to
do is select it. The category expands, allowing you to view its contents.

The premiere issue of the CD-ROM is particularly exciting as it contains a
limited-use demo copy of OS/2 2.1, a demo of IBM's GIK/2 (a toolkit for the
graphical representation and manipulation of data),  many internal IBM tools
that previously were unavaiable, plus many other tools and products.  As new
versions of OS/2 become available, we plan to include them on subsequent issues
of the CD-ROM.

But the CD-ROM doesn't stop there, it includes the complete reference library
for OS/2 2.1 Toolkit, as well as the technical documentation for the Multimedia
and Pen for OS/2 products.


ΓòÉΓòÉΓòÉ 3.3. The Developer Connection News ΓòÉΓòÉΓòÉ

The Developer Connection News is your source for fast-breaking,
up-to-the-minute information.  This month, we feature Future Directions and
Strategy columns by Sam Kahn and Paul Giangarra.  You might also want to browse
the articles from Borland, HockWare, and WATCOM to learn about some of the
latest OS/2 applications.


ΓòÉΓòÉΓòÉ 3.4. Summary ΓòÉΓòÉΓòÉ

So, turn on your  computer, insert the CD-ROM, and enjoy.  This is your
product, it was designed by developers for developers.  And, we believe it
really will give you The power of the future... delivered to your door.


About the Author

David Kenner has been with IBM since 1990 and is currently the Project Lead for
The  Developer Connection for OS/2.   David has had many different roles at
IBM, including working on the OS/2 Toolkit, Virtual Device Driver Design, and
OS/2 Install.  Before joining IBM, David was a computer consultant.


ΓòÉΓòÉΓòÉ 4. Workplace OSs: Doors to the Future ΓòÉΓòÉΓòÉ

by Paul Giangarra

The Workplace Operating Systems (Workplace OSs) will change the way you think
about your computer.  They're  a whole new concept in operating system
architecture.  By unifying the worlds of multiple operating systems, and
providing a new base for common services, scalable and flexible systems are
born. Workplace OSs protect your current investment, as well as bring you into
the future.  A key feature of Workplace OSs is their support for 32-bit
applications.

With the roll-out of OS/2 2.1, we have provided you with a true 32-bit
operating system that extends the features of OS/2 2.0 by providing significant
new features.  OS/2 2.1 truly takes advantage of the capabilities of the
increased power of the new generations of Intel-based processors, including
Pentium.

Having chosen OS/2, what exactly do you get?  You get the bestselling 32-bit
operating system.  This is because your operating system is designed to handle
the increased requirement of complex programs, such as multitasking and
object-oriented programming (OOP).  You are also working in a protected
environment, so if one application fails, the system continues to function.

Internally, OS/2 provides support for even more including, but not limited to,
the following:

o Preemptive multitasking so you can run several programs at one time.

o A protection model that isolates the operating system from errant
  applications, as well as applications from each other.

o A System Object Model (SOM) that provides a language-neutral mechanism for
  object management services.

o A Workplace Shell, implemented on SOM, that provides a powerful,
  object-oriented user interface.

o Dynamic link libraries (DLLs) that allow for interchangeable software
  components.

o A 32-bit presentation driver model that lets you add and install such items
  as printers and displays, as needed, and without a needing a complete
  reinstallation.

o Installable file systems that allow the addition of new types of file
  systems, such as CD-ROMs.

o Multimedia audio and video players.

In addition, OS/2 can support the enterprise-wide, LAN-based client/server
applications of the future, such as SQL databases, CICS, and REXX.  OS/2 2.1
continues to be IBM's mainstream desktop offering for Intel x386 and 80x86
processors and will continue to be enhanced and optimized for that platform.


ΓòÉΓòÉΓòÉ 4.1. What Lies Ahead? ΓòÉΓòÉΓòÉ

What lies ahead are exciting, new technologies that we are ready to exploit.
Some of these technologies include:

o New hardware architecture and platforms that will provide a significant
  increase in computing power

o Object-oriented programming that results in productivity gains making it
  possible to fully exploit the power and features of this new hardware

o New devices, such as speech, wireless, and enhanced video, that will provide
  exciting and new functions

So how do we get to this future?  We are developing a new operating system
foundation that will take advantage of all these emerging technologies. It will
include features, such as a higher security level and the use of multiple
processors (MP).

This operating system foundation will let you move forward to the future, while
preserving your current investment.

Figure 1.  Doors to the future


ΓòÉΓòÉΓòÉ 4.2. And What Is That New Operating System? ΓòÉΓòÉΓòÉ

Workplace OSs are the operating systems that will prepare you for the future.
Taking the  best, most elegant features of multiple operating systems,
Workplace OSs combine them with the flexibility to run on unlimited platforms.

Workplace OSs do not replace OS/2; rather, they compliment OS/2 by providing
for:

o More applications than any other operating system
o Increased and varied hardware support
o Open system architecture providing for increased potential in a scalable
  environment
o Increased quality and flexibility

The products that make up Workplace OSs are:

o The IBM Microkernel
o Common (cross-personality) services
o Multiple personalities


ΓòÉΓòÉΓòÉ 4.2.1. The IBM Microkernel ΓòÉΓòÉΓòÉ

The IBM Microkernel provides the base mechanisms required for building
operating systems.  It is not tied to any operating system-specific functions.

The Microkernel is pure, simple, and minimal.  It isolates all the critical,
machine-dependent services from the operating environments outside of it.
Operating environment policies are set by the operating environment
personality.

The Microkernel is based on Carnegie Mellon University's (CMU's) Mach
technology that provides for:

o Task management (tasks, threads, and dispatching)

o Interprocess communications (IPC)

o Memory management

o Interrupt management

The Microkernel does not enforce policy; rather, it executes whatever policy is
set externally.  Using Microkernel technology greatly enhances the value of
Workplace OSs.  The Microkernel embraces future technology by providing for the
current 32-bit technology, but allowing for 64-bit and beyond extensibility. It
provides for flexibility, integrity, and scalability. The design of the
Microkernel encourages modular client/server design; therefore, reducing
complexity.

Figure 2.  The Workplace look

Each point of control within the Microkernel is a thread having access to all
of the elements in the task that contains it.  A task is a container for the
system resources for the threads contained within it.  A task does not have a
life of its own...it is governed by the threads it contains.  Only threads can
execute instructions.  All threads contained in a specific task share all of
that task's resources.  Tasks exist as separate entities; for example, they
cannot share any resources without taking explicit action. Tasks resemble UNIX
processes and, in fact, are the mechanisms by which UNIX processes are created
by the UNIX personality.

Each task contains an associated memory map that is also known as an address
space.  As with most virtual memory systems, a mechanism must exist to use
physical memory as a cache for the virtual addresses of tasks. Because this is
a generic Microkernel, the operating system personalities must participate in
this mechanism.  The Microkernel's memory management provides the mechanisms of
memory objects and functions to manipulate all this. Mach IPC (ports) manage
client/server communication.  The requesting thread (client) accesses services
by sending messages to the owning task (servers).  These messages are sent over
communication channels, called ports.

Mach provides first level interrupt management services that rely on device
support to provide specific second level interrupt handlers.  The Microkernel
sees the device drivers as tasks and threads that are external to itself. The
device drivers can inject interrupt handlers into the Microkernel, where
necessary.


ΓòÉΓòÉΓòÉ 4.3. Common (Cross-Personality) Services ΓòÉΓòÉΓòÉ

Common services include default paging services, security, device driver
frameworks, and file servers.

The file server framework provides support for multiple, installable file
systems and conforms to the industry-standard VNODE interface.  The file server
also provides memory-mapped file support and allows for logical volume
management.  The device driver framework provides for hardware resource
management and a common framework to build base device drivers.  Interrupt
service routines (ISRs) get interrupts from first-level Microkernel interrupt
management and reflect interrupts to the device drivers that are executing in
user space.  The default pager handles page faults that are reflected by the
Microkernel.


ΓòÉΓòÉΓòÉ 4.4. Multiple Personalities ΓòÉΓòÉΓòÉ

External to the Microkernel and common services are personalities that provide
the specific services for the operating systems.  Personalities are actually
application loaders and launchers.  They let you run operating system-specific
applications on multiple operating systems.  Personality specific services work
with the personality server and personality neutral services to map application
requests to the correct services with the proper semantics.

Personalities reflect particular operating environments, such as UNIX, DOS,
OS/2, and more.  You can run one or more of these person alities on top of the
Microkernel and the common services.  You can choose which personality is
dominant and which personality is alternate.  The dominant personality provides
the look and feel of the system (that is, the user interface).  It provides the
default runtime semantics, as well as the runtime and execution environment.
The alternate personalities will respond to a set of requests from the dominant
personality. For example, the UNIX dominant personality looks to the other
personalities to recognize, load, and launch anything other then an UNIX
application. However, the UNIX personality will handle all UNIX applications
itself.

So, whatever your dominant personality is, your operating systems will look
just like your system does today.  Adding alternate personalities will grant
you the enhanced flexibility of running additional operating system
applications, such as UNIX.


ΓòÉΓòÉΓòÉ 4.5. So, What Does All This Mean to Me? ΓòÉΓòÉΓòÉ

What this means to you, as a developer, is that using multiple personalities,
you are going to have a flexible environment in which you can run not just one,
but multiple applications across system platforms.  It also means that you will
be able to develop and test different flavors of your application on one
machine in a uniform programming environment.

And, each personality will share a common look and feel...the Workplace Shell
look.  Workplace OSs are your key to a whole new level of computing. This
reason is why they are your door to the future.


About the Author

Paul Giangarra has been with IBM since 1977 and is currently a member of IBM's
Senior Technical Staff.  Paul has had many different roles at IBM, including
Chief Designer for OS/2 during OS/2 1.2, OS/2 1.3, and OS/2 2.0.  He is
currently Lead Architect for Workplace OS.  Paul is a member of the PSP Line of
Business Software Architecture board.


ΓòÉΓòÉΓòÉ 5. An Open Letter from the Publisher and Product Manager of The Developer Connection for OS/2 ΓòÉΓòÉΓòÉ

This CD-ROM and Newsletter  mark the  kick off of The Developer Connection for
OS/2 product.  My team and  I are dedicated to providing tools, information,
and the latest pre-release products to you.  As Product Manager for The
Developer Connection for OS/2, I am dedicated to providing you with the best
possible tools for developing applications, the latest information to help you
develop applications that exploit new functions on the operating system, and
pre-release products of new operating system functions.  We believe that being
a member of The Developer Connection will give you a tremendous edge in
creating your OS/2 applications.

In The Developer Connection News, you will find technical articles about the
latest strategic directions for Personal Software Products (PSP) Operating
Systems.  You will learn about the importance of Microkernel technology, and
how it will let you port your applications across multiple platforms.  You will
also hear directly from the developers of OS/2 and future technologies.  They
will be providing you with technical information about features in the
operating system, as well as programming tips and techniques.

Because this product is for you, your feedback is critical to our success. I
would like to hear your comments on our program.  Tell us the types of articles
you would like to see in the Newsletter and the types of tools and information
you need on the CD-ROM.  We promise to go out there and do what we can to
deliver them to you.  If we can do it, we will! Our goal is to make your job
easier.  So let us know what we're doing right; but maybe even more
importantly, let us know if we need to change.

I hope you enjoy using this product as much my team and I have had in
delivering it to you!

Sincerely,

Barbara  J. Britt

Barbara J. Britt

Product Manager

OS/2 Software Development Tools


About Barbara:

Brarbara Britt has been with IBM since 1984 and is currently the Product
Manager for OS/2 Software Development Tools, which includes the OS/2 Toolkit,
Device Driver Source Kit for OS/2, and The Developer Connection for OS/2.
Barbara has had many different roles at IBM, from Programming positions to
various Software Development Management positions.


ΓòÉΓòÉΓòÉ 6. A Snapshot of the IBM Personal Operating Systems Strategy ΓòÉΓòÉΓòÉ

by Sam Kahn

As OS/2 developers, you are likely to be rolling out your own applications that
exploit OS/2 2.1.  These applications might range from personal productivity
and vertical applications developed for resale, to internally developed
line-of-business applications for large enterprises.

At the same time, we are all making investment decisions on our next wave of
products.  This article is intended to be a brief description of the IBM
Personal Operating System (POS) decisions with respect to OS/2 2.x, the
microkernel-based Workplace Operating Systems (Workplace OSs), and Taligent.
IBM is keenly interested in how you're planning to invest in its platforms,
versus other current and emerging alternatives.

All of us are making these decisions in tight economic times and in an
environment of fierce competition; so we both need an investment strategy that
balances our immediate and long-term needs.

We are investing in enhancements to OS/2 2.x because that is where the largest
immediate opportunity is. At the same time, we recognize that RISC
price/performance will soon make it very attractive in the PC market, and that
Intel architecture products are becoming much more powerful and are driving
into the workstation market.  We need an operating system base that wil let our
customers take advantage of both RISC and CISC (Intel) architectures.  The
Microkernel-based Workplace OSs will be our solution.

However, Microkernel and related technologies provide much more than just
portability.  They enable a new level of modularity within the operating
systems that dramatically reduces the overall system complexity.  They will let
us be more responsive to our customers at an affordable development expense;
and allow other vendors to more easily add or enhance parts of the operating
system, such as device drivers, file systems, emulators, and much more.

We have featured OS/2 as The Integrating Platform, based on its ability to run
OS/2 2.x, OS/2 1.x, DOS, and Windows applications concurrently. At the same
time, we are recommending that all OS/2 applications be fully 32-bit to take
full native advantage of both RISC and Intel 32-bit architectures.  We also
encourage you to consider moving or creating functions as Personality Neutral
Servers. This lets your code run directly on the Microkernel, and be
independent of the operating system (personality).  One way to think of this
environment is the notion of client/server within a single system. This has
some obvious advantages for applications such as databases, which service users
in one or more application environments.  Other applications, such as key
functions of a spreadsheet package or word processor, can be separated as
servers that operate asynchronously and are independent of the user interface.
These portions of applications are good candidates for Personality Neutral
Servers, while the user interface itself runs in the personality and conforms
to its style.

As IBM concentrate on the internal structure of Workplace OSs, we also must
concentrate on user-visible functions.  IBM is investing heavily in object
technology, because it has reached a level of maturity where it can contribute
very significantly to both application development productivity and end-user
ease of use.  We are currently in Beta test with enhancements to our System
Object Model (SOM), frameworks, class libraries, and a visual builder.  We will
enhance our offerings in stages over the next 12 -18 months with technology
developed by Taligent.

We are focused on two complementary, but distinct, directions in exploiting
object technology.  We are expanding the object-oriented infrastructure by
extending SOM to be distributed (DSOM), to be CORBA compliant, and support more
languages.  We're working with major players in the industry to develop an
industrial-strength, full-function, interapplication communication vehicle.

At the same time, we will deliver frameworks and class libraries that provide a
dramatic increase in productivity for today's applications and the tools to
develop tomorrow's more sophisticated applications, such as
cooperative/collaborative computing and true client/server computing.

This high-function object layer and its prerequisite infrastructure will be
delivered on many, if not all, of the operating system platforms that can
effectively support it.  These will include, but not be limited to, OS/2 2.x,
Workplace OSs, AIX, and other flavors of UNIX.

In parallel, Taligent is developing a fully object-oriented system in contrast
to the layered approach just described.  We in POS are developing the
capability to run current and future OS/2 2.x 32-bit applications concurrently
with native Taligent applications.

We're also continuing to look at ways to help you port source code to or from
other platforms to reduce your overall development expense, while at the same
time allowing you to optimize your applications for the unique capabilities of
our products.

We're continuing to build on DOS for small systems and emerging form-factors or
devices, such as Personal Digital Assistants (PDAs).  We're investing in a
number of areas within Multimedia such as, compression and decompression
algorithms, authoring tools, servers for time-dependent media (such as, motion
video with synchronized audio), and much more.  We're also investing in Pen-
and Speech-Recognition technologies.  We're enhancing our support for various
forms of clients and native system management; and integrating them with
products developed by our colleagues in LAN systems, in order to provide a
complete foundation for the next generation of client/server applications.

Now, given what I've told you about our strategy, what are your key decisions?
The first is how much to continue to invest in our platforms.  We hope that the
combination of our success with OS/2 2.x and our strategy lead you to the
conclusion that continued investment is an excellent business decision.  You
also must decide on how quickly you want to shift your development emphasis
from procedural to object.  We believe that the benefits of object-oriented
development will be compelling, and that we can offer you the best technology
in the industry.  But, we recognize that developers will adopt object
technology at varying rates.  So we'll continue to offer and enhance the best
32-bit APIs in the industry.

We believe that this strategy will deliver the best combination of short- and
long-term value to our current and potential customers, investment partners
like yourselves, and us.  We hope that you agree and will continue to make the
appropriate complement ary investments to share in its success.


About the Author

Sam Kahn has been with IBM since 1967 and is currently the Manager of Strategy
and Technology, where he is responsible for strategy, Workplace OSs, and being
the Taligent interface.  Sam has had many different roles at IBM, including
project management in the DB2 and Callpath areas.  In the mid-1980's, Sam was a
member of the IBM Corporation Technical Committee that concentrated on future
directions.


ΓòÉΓòÉΓòÉ 7. Pen for OS/2 ΓòÉΓòÉΓòÉ

by Judy Schwait

Pen for OS/2 (Pen) is a system-software extension to the IBM OS/2 2.1 operating
system that provides support for the pen as an input device in the desktop and
portable computing arenas.  With a Workplace Shell interface, Pen uses
Presentation Manager (PM) for pen-based input and recognition

Pen currently supports pen digitizers from Kurta, Wacom, and Calcomp that are
designed for using the pen as the primary input device.  Pen for OS/2 has
complete mouse emulation for use with OS/2 and existing applications.

Pen for OS/2 offers the pen as the primary source of input; however, Pen will
support existing applications, without modification.  This is done through the
Pen C ompatibility Layer.  The Compatibility Layer maps the pen movement to an
event, such as a mouse or keyboard.  The set of applications that were not
designed for use with the pen are called pen-unaware.  Compatibility support is
provided for OS/2, DOS, and Windows sessions in a PM environment.

With the pen, you use gestures, which are sets of points that are translated
into specific commands or command sequences.  Pen contains predefined gestures
or lets you customize gestures.

Pen-aware and pencentric applications take advantage of the new controls, APIs,
and messages defined in the Pen for OS/2 Developer's Toolkit.  A developer can
use the Pen functions to various degrees.  Minimally, a developer can create a
pen-aware application, using Pen to detect gestures or pen proximity in their
application development.  For a full-blown pencentric application, a developer
can use all the features contained in the Toolkit to manipulate processing and
interpretation of the pen input for the application.  Programs can also be
selective in the context of character recognition in order to increase
accuracy.

The degree to which a program uses the capabilities of Pen determines its
pen-awareness.  Pen has a variety of components to enhance the pen, as follows:

o Gesture Practice lets you view and practice drawing predefined shapes.

o The Sketch Pad is an application that collects strokes and captures images
  that the user can manipulate through the clipboard.

o Telepen is a LAN-aware application that allows for communication through
  handwritten notes and graphics across the LAN.

o The Pen Tool Bar provides easy access to functions that you might want to
  perform, such as emulating the right mouse button, starting the Handwriting
  Pad, or displaying the Pop-Up Keyboard.

Pen's Workplace Shell interface lets you change system-wide values using either
the Customization or Device object.  In addition, the Customization object lets
you train the system for your particular style of handwriting and to change
system-wide ges ture assignments.

You can also configure gestures on a per object basis through the Gesture page
in the Settings notebook of Program object and Program File object.  Pen
settings also have been added to the Mouse object and Sound objects.

Pen for OS/2 provides device-independence that shields the programmer from the
differences in hardware devices.  During installation, the device driver
(furnished by the manufacturer) registers itself and defines all events and
device capabilities with the IBM Pen for OS/2 Device Services.  The Device
Services layer provides a consistent programming interface to software
developers.

Pen for OS/2 extends the functions of the existing PM input subsystem by
providing new APIs.

The Virtual Keyboard Playback APIs provide control over the Pop-Up Keyboard
tool.

New Window Control APIs provide an interface to the new controls supplied with
the Pen extensions, handwriting input control and the sketch control.  Use
these APIs to customize and manipulate data flows.  Two new tools that use
these contr ols are the Handwriting Input Pad and the Sketch Pad.

The Pen Writing Subsystem APIs encompass the arena of seeing and controling the
pen and stroke data and interfacing with the pen subsystem facilities.  New
OS/2 messages, such as WM_TOUCHDOWN, WM_LIFTOFF, WM_EXIT_PROXIMITY, and WM_RECO
report the various asynchronous events and state changes associated with Pen.
These messages are sent to applications with the standard mouse-event messages.

The Writing Subsystem APIs handle receiving stroke data from the input queue
and the internal cache, determining which window gets the data, and sending PM
messages to that window.  Pen maintains a stroke buffer that collects all
points in the movement of the pen between the touch-down point and the lift-off
point. On stroke completion, Pen sends a WM_STROKE message to the application.
At this point, the application can access the stroke data through an API.

The main function of the Compatibility Layer is to convert pen events to mouse
and keyboard events or to invoke special-purpose command handlers that can be
registered with the system.  This Layer provides the interface to the
pen-unaware applications that are designed to work with mouse and keyboard
input.  It allows programs to work in the pen environment without being altered
for use with the pen.

Some examples of mapping of pen operations to mouse events are:

Touch down and pause          Mouse button down

Touch down, pause, move       Begin drag or selection

Lift off                      Mouse button up

Tap                           Mouse button single click

Double-tap                    Mouse button double click

Move pen                      Mouse move

For these unaware applications, the Compatibility Layer will collect strokes
and build a doodle on behalf of the application.  When this doodle is complete,
the Layer tries to resolve the points as a gesture.  If a shape is matched, an
event is sent to the Recognition Event Delivery (RED) component.

The RED component assists developers in the interpretation of
command-recognition events, such as gestures.  Its purpose is deliver
recognition results to applications.  The RED component maps these recognition
results to assignments de fined by the system or user.  These assignments are
accessed through the Program or Program File objects settings and the Pen
Customization object settings.  Assignments can be predefined commands packaged
with Pen, such as Close Window, o r they can be the name of a program to be
started.  The predefined command, Send Keystrokes, lets you play back a set of
keystrokes when drawing a gesture.

Pen for OS/2 provides an open architecture with a number of well-defined socket
interfaces for device and recognition providers.  The pen opens up features in
the operating system and applications that were not previously available with
th e keyboard and the mouse.  It allows for freehand drawing, gives a more
natural input device, and interprets ink as handwriting and gestures.

We believe that Pen for OS/2 will launch the pen into becoming the primary
source of input for OS/2.


About the Author

Judy Schwait has been with IBM since 1989 and is currently a Senior Associate
Programmer with the Mobile, Voice, and Pen team.  Judy's previous position with
IBM was in the OS/2 Workplace Shell department.


ΓòÉΓòÉΓòÉ 8. Snap! Crack! Bang! With OS/2 2.1 Multimedia Support ΓòÉΓòÉΓòÉ

by Gary G. Allran

OS/2 2.1 provides the richest multimedia platform of any PC-based operating
system currently available.  With everything from built-in System Sound support
to Software Motion Video Playback, IBM has covered all the bases.

This article looks at the user interface aspect of the audio support features
of OS/2's multimedia support.  Look to the next issue of this Newsletter for
information about the Video interface of the multimedia platform.  More
detailed information for sof tware developers can be found in the OS/2 2.1
Toolkit product found on your CD-ROM.

After you install the multimedia support, a new folder appears on your desktop,
Multimedia.


ΓòÉΓòÉΓòÉ 8.1. Audio Support ΓòÉΓòÉΓòÉ

OS/2's audio support provides a variety of methods for including audio in your
applications.  Major features include System Sounds, Compact Disc, Digital
Audio, and MIDI support.  Let's take a closer look at each of these.


ΓòÉΓòÉΓòÉ 8.2. System Sounds ΓòÉΓòÉΓòÉ

The System Sound support lets you associate sounds with a variety of system
events, such as opening or closing a folder or shredding an object. Multimedia
currently defines 13 system sound events (.WAV files); however, a total of 23
sound files are included with the product.

The System Sound application, included in the OS/2 System Setup folder,
provides an easy method for associating a particular sound file with a system
event.  If you want to change one of the .WAV files associated with a system
event, you simply click on the system event, such as End Drag, and then click
on a new .WAV file.  In addition to selecting from the different .WAV files
that are shipped with OS/2, you also can create your own using the Digital
Audio application.  More about that later.

The System Sound application has a volume control that lets you adjust the
audio level for a particular system sound or for all of the system sounds. For
example, you might choose to soften the volume for things like opening and
closing folders (so they don't drive you crazy!).  You could also specify that
other events, such as errors and warnings, have a higher volume level to get
your attention.


ΓòÉΓòÉΓòÉ 8.3. Compact Disc ΓòÉΓòÉΓòÉ

Another very popular aspect of OS/2 multimedia support is the compact disc
player.  Most CD-ROM drives also play CD Digital Audio (CD-DA) discs.  The
Compact Disc application helps control a standard CD-ROM drive in much the same
way as a home or car CD player.  You will recognize some of the familiar
buttons, such as PLAY, FAST FORWARD, and EJECT.

This application also has a feature known as a track calendar display.  This
display presents a numbered button for each of the tracks on the disc, allowing
direct selection of any track.  At startup, the first fourteen tracks appear.
Step through the entire disc using the up and down buttons beside the calendar
display.

Click the right mouse button to access a variety of features, such as the
capability to edit the CD-ROM's title.  As you might know, a CD-ROM is actually
a digital storage device with a capacity of over 600MB.  Amazingly, with over
600MB of storage, the designers of the CD-DA format didn't include the title of
the disc!  If you choose Edit Title from the CD-ROM Player, you can type in any
title you like (up to 32 characters).  The CD-ROM Player associates that title
with the unique disc number in a very simple database. Now, every time you
insert that disc, its title appears in the title bar of the CD-ROM Player.

The CD-ROM Player also supports a track-shuffle feature.  Selecting this option
causes all the tracks in the music-calendar display to be shuffled. The disc
then plays in this random order, giving a whole new sound to a very familiar
disc.


ΓòÉΓòÉΓòÉ 8.4. Digital Audio ΓòÉΓòÉΓòÉ

OS/2 with MMPM/2 installed has very powerful Digital-Audio support.  With the
addition of a simple audio card, you now have the ability to record, playback,
and edit a wide variety of Digital-Audio sounds.

An interesting example of how you can use the OS/2 Digital-Audio subsystem is
in the Digital-Audio application.  This application is unusual in that it
provides two personalities or views.  One view is that of a Digital-Audio
player and recorder.  The other, slightly more complicated view, allows editing
of digital audio.

In the player/recorder view, this application displays simple features, such as
rewind, play, and record.  Also displayed are a volume-control and
media-position information.  To play an existing Digital-Audio file (typically
found with the .WAV extension), simply open the file and press PLAY.

If you choose to create a new audio file, simply make sure that your audio
source is connected to your system, and press the RECORD button.  The red
RECORD button blinks, and recording continues until you press the STOP button.
This action creates a temp orary file containing the audio data.  You, then,
can specify a name and save the file, or discard it and record again.

The Editor view of the Digital-Audio application is slightly more complicated.
In addition to the features described previously, a graphic representation of
the Digital-Audio file can now be seen.  The scale of this representation can
be changed using the Zoom slider, located to the right of the View window.
Moving this slider down lets you zoom in on a specific portion of the audio
file.

Sections of the Digital-Audio file can now be marked by holding down the right
mouse button and swiping across the view window.  After you mark an area, you
then can use a variety of editing functions, such as cut, copy, and paste.
Specialized features, such as fade in and out, echo, reverb, and reverse are
also availble.  And, if you don't like what you've done, discard the changes,
and start over!


ΓòÉΓòÉΓòÉ 8.5. MIDI ΓòÉΓòÉΓòÉ

Musical instrument digital interface (MIDI) is a lot like a simple local area
network (LAN) definition.  Various electronic musical devices, such as
keyboards, synthesizers, and drum machines use MIDI to communicate with one
another.

For example, when you press middle C on a keyboard, a 3-byte note-on MIDI
message is generated.  This message contains the ID of the key pressed, as well
as the velocity or speed at which the key was pressed.  When the key is
released, a note-off message is generated.  These messages can then be
interpreted by another device, such as a synthesizer to generate the actual
sound of a piano note.

Thanks to this message-based design, MIDI is a very compact method for storing
music content.  MIDI is very popular among game developers for this reason.
They can deliver a complete audio track for a game, without worrying about the
great deal of storage that would be required using standard digital-audio
recording.

The OS/2 support for MIDI currently is restricted to playback only.  It allows
use of certain digital-audio cards that can emulate MIDI synthesizers.  For
example, the M-Audio card from IBM, which is built around a Texas Instruments
C25 Digital Signal Proce ssor (DSP) can be used to emulate a four-voice
synthesizer.

The MIDI player application lets you select any of the included MIDI files for
playback.

Note:  It is important to understand that MIDI implementations vary quite a bit
       from one audio card to another, so files that sound great on one audio
       card might sound a little funny on others.


ΓòÉΓòÉΓòÉ 8.6. Summary ΓòÉΓòÉΓòÉ

This sums up the Audio Support for OS/2 Multimedia.  Look in the next issue of
The Developer Connection News for Video Support for OS/2 Multimedia.


About the Author

Gary G. Allran has been with IBM since 1982 and is currently the Manager of OS
Technical Marketing and Support.  Gary has held a variety of roles at IBM,
including OS/2 Multimedia Evangelist, Development Manager, Audio Subsystem
Architect, and IBM DOS Lead Architect.


ΓòÉΓòÉΓòÉ 9. Multithreading Presentation Manager Applications ΓòÉΓòÉΓòÉ

by Monte Copeland

Over the years, many different styles have emerged to multithread Presentation
Manager (PM) applications.

The approach presented in this article is the start-a-thread, keep-it-around,
and give-it-work  approach and is based on PM message queues.  It is a good
choice, because PM applications must have message queues already.
Additionally, this choice lets you achieve multithreading without using
semaphores.


ΓòÉΓòÉΓòÉ 9.1. Why Multithreaded PM Applications Are a Must ΓòÉΓòÉΓòÉ

PM applications, like all OS/2 applications, call into the operating system for
services using the OS/2 APIs.  However, PM applications must provide functions,
called window procedures, for PM to call.

PM delivers messages to a PM application by calling window procedures.  For
example, these messages include menu selections, mouse clicks, and
termination-notification messages.  In addition, PM sends a message to the
application when it is time to repaint the window or it can deliver
user-defined messages.

For PM to stay synchronized with all the applications on the desktop, it
delivers messages one at a time.  These are sent messages.  In other words,
when PM sends a message to your window procedure, it stops sending messages
elsewhere until your procedure returns.

Therefore, PM applications must respond to all sent messages in a timely
manner.  The often-cited response time is 1/10th second; hence, the
1/10th-second rule.  When an application takes too long to respond to messages,
unacceptable behavior can occur.

This article describes a robust, two-threaded PM application architecture.
Applications coded in this style obey the 1/10th second rule, and yet, can
perform long tasks.  A second thread in PM applications is created to bust the
1/10th-second rule, and perform long tasks, such as diskcopy, upload/download,
file input/output, or SQL queries.


ΓòÉΓòÉΓòÉ 9.2. Thread Responsibilities ΓòÉΓòÉΓòÉ

Thread 1 is responsible for presentation.  It operates the first message queue
that the application creates.  This message queue gets and dispatches messages
to one or more application windows on the desktop.

Thread 1 presents the client window, as well as the dialog and message boxes.
It reacts to command messages from menus and child controls.  It processes
messages that the frame-window controls generate.  In fact, thread 1 is devoted
to the operation of all the application's visible windows on the desktop.

Thread 2 operates a second message queue that is created by thread 2 of the
application.  This message queue delivers messages to an object window and its
window procedure.  Object windows are invisible, that is, they do not appear on
the desktop.  More importantly, they are not bound by the 1/10th-second rule.

When object-window procedures run on thread 2, they are perfect for doing any
time-consuming tasks required by the application.  While the object window is
busy working on a task, the main-window procedure continues to get and dispatch
messages in a time ly manner-as it must.


ΓòÉΓòÉΓòÉ 9.3. Post a Message, Do Some Work ΓòÉΓòÉΓòÉ

Thread 1 creates thread 2, and thread 2 creates its own message queue for its
object window.  Then it blocks in the call to the API, WinGetMsg, in the
message loop.  (See the OBJECT.C file in the sample code that follows this
article.)

The object window stays blocked until there is work to do.  For example, a user
selects a task from a pull-down menu.  PM sends a menu message to the client
window procedure on thread 1. Thread 1 calls the API, WinPostMsg, and posts a
user-defined messa ge to the object window on thread 2. Thread 2 performs the
task in the object-window procedure.  When the task is complete, thread two
posts an acknowledgement back to the originating window.

client/dialog                         object window
window on thread 1                    on thread 2
---------------                       ---------------      |
|             |                       | waiting in  |      |
| user        | WinPostMsg(           | WinGetMsg   |      |
| requests    |     hwndObject,       |             |      |
| a lengthy   |     WM_USER_WORKITEM, |             |      |
| workitem    |     hwndToAck,        |             |      |
|             |     null )            |             |      |
|             | --------------------> |             |
| window      |                       | perform     |     time
| disabled    |                       | lengthy     |      |
| while       |                       | task        |      |
| busy        |                       |             |      |
|             | WinPostMsg(           |             |      |
|             |    hwndToAck,         |             |      |
|             |    WM_USER_ACK,       |             |      |
|             |    WM_USER_WORKITEM,  | task        |      |
|             |    result code )      | complete    |      |
|             | <-------------------- |             |      |
| enable      |                       |             |      |
| again       |                       |             |      |
---------------                       ---------------      |
                                                           |
                                                          \ /
                                                           .

The following convention exists with the two message parameters of the API,
WinPostMsg, when posting a user-defined work message to the window:

Message parameter one is the window handle of the originating window.

By having the window handle of the originator, the object window knows which
window to acknowledge when the task completes.

The sample file, APP.C, only shows the client-window procedure originating
tasks; however, dialog boxes also can originate tasks.


ΓòÉΓòÉΓòÉ 9.4. Disable While Busy ΓòÉΓòÉΓòÉ

In the sample code, the application disables its client and selected menu item,
and then posts a message to the object window to perform the lengthy task.
These actions prevent the user from initiating another work item, while the
object window is busy.  (See the message WM_USER_DISABLE_CLIENT in the file,
APP.C, which is sent before the application posts the work request to the
object window.)

Note:  When the application disables the client window, its message queue does
       not stop working.

Click on the client window, while the object window is busy.  The beep you hear
is proof that the client window's message queue continues to process messages.

The frame window is not disabled; therefore, the user can minimize the frame
window or switch to another application while the application is busy.

The mouse pointer changes to an hourglass when it passes over the window of the
busy application.  When the mouse pointer leaves the application window, it
changes back to a normal pointer.  The application keeps a busy flag and
references it during proce ssing of WM_MOUSEMOVE in the client-window
procedure.

This approach is simplistic (if not rigid), but it is one that you can modify
by choosing which items are grayed on which menus.  If a given thread/object
window pair (there could be many) was responsible for tasks A and B, you would
gray items A and B, while the object window was busy working on either A or B.


ΓòÉΓòÉΓòÉ 9.5. Object Window Acknowledges Completion ΓòÉΓòÉΓòÉ

When the lengthy task completes, the object window posts a user-acknowledgment
message to the window that originated the task.  This message informs the
originating window that the task is complete, and that it can re-enable itself
and any menu items, as required.

Use the following convention with message parameters on the acknowledgment
message:

Message parameter one is the user-defined message posted to the object window.

With this parameter, the originating window can discern which activity is now
complete; the second message parameter is a result code.


ΓòÉΓòÉΓòÉ 9.6. Closing Considerations ΓòÉΓòÉΓòÉ

The act of closing the application is like a chain reaction between the two
threads.  Usually, client windows post a WM_QUIT message to themselves when
they receive a WM_CLOSE message-not in multithreaded PM applications.

When the client window receives a WM_CLOSE message, it posts a WM_QUIT message
to the object window, then it returns.  When the object window receives the
WM_QUIT message, it leaves its message loop, cleans up, posts a WM_QUIT message
to thread 1. Thread 1 leaves its message loop, waits for thread 2 to exit, and
then exits itself (and the process).

The object-window thread calls the API, WinCancelShutdown.  If the user shuts
down the system while the application is still running, this API tells PM not
to send a WM_CLOSE message to the object-window message queue. PM sends a
WM_CLOSE message to the client-window message queue, then the chain reaction
starts.


ΓòÉΓòÉΓòÉ 9.7. Common Data ΓòÉΓòÉΓòÉ

Both threads share a common data space.  This space is defined by the GLOBALS
structure in the app.h file.  WM_CREATE processing allocates this space and
passes the pointer to thread 2 on the call to _beginthread.  The client- and
object-window procedures keep a pointer to this memory in their window words.
The number of extra words for each window is set by the API, WinRegisterClass.
Both the client and object windows have 4 extra bytes of window words.

When dialog-box procedures initialize, they must obtain the pointer to shared
memory, and store it in their window words.  By default, dialog boxes have
enough window words to hold a 32-bits-long pointer.


ΓòÉΓòÉΓòÉ 9.8. pmassert ΓòÉΓòÉΓòÉ

The pmassert macro is a debugging tool.  It works much like the C-language
assert macro.  Anywhere in the source code, you can assert that a Boolean
expression is true.  At runtime, nothing happens if the expression is true. If
the expression is false, the macro displays the failed assertion in a message
box along with the line number and the C source file name where the assertion
failed.

Because pmassert is a macro, it is easy to redefine it to be a no operation,
after you debug the application.  In the C-language tradition, you accomplish
this by defining the symbol, NDEBUG.  This approach to program building
produces both debug and ret ail versions of your program.  See the pmassert.h
file in the sample code.


ΓòÉΓòÉΓòÉ 9.9. Acknowledgments ΓòÉΓòÉΓòÉ

By now you might have recognized this architecture from the OS/2 Toolkit Print
Sample (PRTSAMP.EXE) on the CD-ROM.  It is the same.


ΓòÉΓòÉΓòÉ 9.10. Sample Code ΓòÉΓòÉΓòÉ

Use the following sample code to create your own multithreaded PM applications.

// start of file app.h -------------------------------------------------------

// strings
#define APP_TITLE               "Object Window Application"
#define APP_CLASS_CLIENT        "APPClient"
#define APP_CLASS_OBJECT        "APPObject"

// identifiers
#define ID_APP             3
#define IDM_SLEEP         303
#define IDM_ACTIONS       304

// lengths
#define LEN_WORKSTRING              256
#define LEN_STACK                 18000

// structure to hold globals variables common to both threads
struct _globals {
  BOOL           fBusy;
  HAB            hab;
  HWND           hwndClient;
  HWND           hwndFrame;
  HWND           hwndTitlebar;
  HWND           hwndMenubar;
  HWND           hwndObject;
  TID            tidObject;
};
typedef struct _globals GLOBALS, *PGLOBALS;

// user-defined messages for work items and acknowlegements
#define WM_USER_ACK                      (WM_USER+0)
#define WM_USER_SLEEP                    (WM_USER+1)
#define WM_USER_ENABLE                   (WM_USER+2)
#define WM_USER_DISABLE                  (WM_USER+3)

// function prototypes -- _Optlink is a IBM C SET/2 modifier
void _Optlink threadmain( void *  );
PGLOBALS Create( HWND hwnd );
MRESULT EXPENTRY ObjectWinProc( HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2 );
MRESULT EXPENTRY ClientWinProc( HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2 );

// end of file app.h ----------------------------------------------------------

//-------------------------------------------------------------------
// pmassert.h
#ifndef NDEBUG
#define pmassert(hab,exp)\
{\
if(!(exp)) {\
  char ebuff[ 64 ]; unsigned long errorid; unsigned short shortrc;\
  errorid = WinGetLastError( hab ); \
  sprintf( ebuff, "Line %d\nFile %s\nLast Error %p\nExpression %s\n",\
                 __LINE__, __FILE__, errorid, #exp );\
  shortrc = WinMessageBox( HWND_DESKTOP, HWND_DESKTOP, ebuff,\
                 "Assertion failed. Continue?", 0, MB_YESNO  );\
  if( shortrc == MBID_NO ) exit( 1 );\
}\
}
#else
  #define pmassert(hab,exp)
#endif
// end of file pmassert.h

// start of file app.c -------------------------------------------------------
// A sample PM application showing use of an object window operated by
// thread 2 for time-consuming tasks.

// os2 includes
#define INCL_DOSPROCESS
#define INCL_WIN
#include <os2.h>
// c includes
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
// app includes
#include "app.h"
#include "pmassert.h"

// ----------------------------------------------------------------------
// main entry point for thread 1
int main ( void )
{
  APIRET   rc;
  BOOL     fSuccess;
  HAB      hab;
  HMQ      hmq;
  HWND     hwndClient;
  HWND     hwndFrame;
  QMSG     qmsg;
  ULONG    flCreate;
  PGLOBALS pg;

  // PM application init
  hab = WinInitialize( 0 );
  hmq = WinCreateMsgQueue( hab, 0 );
  assert( hmq );

  // register client window class
  // with 4 bytes of window words to hold a pointer to globals
  fSuccess = WinRegisterClass( hab, APP_CLASS_CLIENT, (PFNWP)ClientWinProc,
                      CS_SIZEREDRAW | CS_CLIPCHILDREN, sizeof( PGLOBALS ) );
  pmassert( hab, fSuccess );

  flCreate = FCF_SYSMENU | FCF_SIZEBORDER    | FCF_TITLEBAR |
             FCF_MINMAX  | FCF_SHELLPOSITION | FCF_TASKLIST |
             FCF_MENU    | FCF_ICON;

  // standard window create; returns after WM_CREATE processing finishes
  hwndFrame = WinCreateStdWindow( HWND_DESKTOP, WS_VISIBLE, &flCreate,
               APP_CLASS_CLIENT, APP_TITLE, 0, 0, ID_APP, &hwndClient );
  pmassert( hab, hwndFrame );
  pmassert( hab, hwndClient );
  pg = (PGLOBALS) WinQueryWindowULong( hwndClient, QWL_USER );

  // dispatch user input messages
  while( WinGetMsg( hab, &qmsg, 0, 0, 0 ))
  {
    WinDispatchMsg( hab, &qmsg );
  }

  // wrap up
  WinDestroyWindow ( hwndFrame );
  WinDestroyMsgQueue ( hmq );
  WinTerminate ( hab );

  rc = DosWaitThread( &pg->tidObject, DCWW_WAIT );
  assert( rc == 0 );

  // exit the process
  return 0;
}

// ----------------------------------------------------------------------
// client window procedure
MRESULT EXPENTRY ClientWinProc(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2 )
{
  HAB           hab;
  HPS           hps;
  PGLOBALS      pg;
  RECTL         rectl;
  ULONG         ulWork;

  switch( msg ) {
  case WM_CLOSE:
    // get pointer to globals from window words
    pg = (PGLOBALS) WinQueryWindowULong( hwnd, QWL_USER );
    // tell object window to quit, then exit its thread
    WinPostMsg( pg->hwndObject, WM_QUIT, 0, 0 );
    return (MRESULT) 0;

  case WM_COMMAND:
    // get pointer to globals from window words
    pg = (PGLOBALS) WinQueryWindowULong( hwnd, QWL_USER );
    switch( SHORT1FROMMP( mp1 )) {
    case IDM_SLEEP:
      // disable client for this lengthy task
      WinSendMsg( hwnd, WM_USER_DISABLE, 0L, 0L );
      // object window is busy now
      pg->fBusy = TRUE;
      // tell object window to perform lengthy task
      WinPostMsg( pg->hwndObject, WM_USER_SLEEP, (MPARAM)hwnd, 0 );
      // wait for ack
      break;
    }
    return (MRESULT) 0;

  case WM_CREATE:
    hab = WinQueryAnchorBlock( hwnd );
    // allocate memory for global variables; see GLOBALS struct in app.h
    pg = (PGLOBALS) malloc( sizeof( GLOBALS ));
    pmassert( hab, pg );
    // initialize globals to zero
    memset( pg, 0, sizeof( GLOBALS ));
    // store globals pointer into client window words; see WinRegisterClass
    WinSetWindowULong( hwnd, QWL_USER, (ULONG) pg );
    // disable until object window initializes
    WinSendMsg( hwnd, WM_USER_DISABLE, 0, 0 );
    // initialize globals with important data
    pg->hab          = hab;
    pg->hwndClient   = hwnd;
    pg->hwndFrame    = WinQueryWindow( hwnd, QW_PARENT );
    pg->hwndTitlebar = WinWindowFromID( pg->hwndFrame, FID_TITLEBAR );
    pg->hwndMenubar  = WinWindowFromID( pg->hwndFrame, FID_MENU );
    // create thread 2 for object window; pass pointer to globals
    pg->tidObject = _beginthread( threadmain, NULL, LEN_STACK, (void *)pg );
    pmassert( hab, pg->tidObject );
    return (MRESULT) 0;

  case WM_MOUSEMOVE:
    // if busy, display the wait pointer, else the arrow pointer
    pg = (PGLOBALS) WinQueryWindowULong( hwnd, QWL_USER );
    ulWork = pg->fBusy ? SPTR_WAIT : SPTR_ARROW;
    WinSetPointer(HWND_DESKTOP,WinQuerySysPointer(HWND_DESKTOP,ulWork,FALSE));
    return (MRESULT) TRUE;

  case WM_PAINT:
    hps = WinBeginPaint( hwnd, 0, &rectl );
    WinFillRect( hps, &rectl, SYSCLR_WINDOW );
    WinEndPaint( hps );
    return (MRESULT) 0;

  case WM_USER_ACK:
    // get pointer to globals from window words
    pg = (PGLOBALS) WinQueryWindowULong( hwnd, QWL_USER );
    // object window has completed which task?
    switch( (ULONG) mp1 ) {
    case WM_USER_SLEEP:
      WinMessageBox(HWND_DESKTOP,pg->hwndFrame,"Done.",APP_TITLE,0,MB_CANCEL);
      break;
    }
    WinSendMsg( hwnd, WM_USER_ENABLE, 0, 0 );
    // object window is not busy anymore
    pg->fBusy = FALSE;
    return (MRESULT) 0;

  case WM_USER_DISABLE:
    // get pointer to globals from window words
    pg = (PGLOBALS) WinQueryWindowULong( hwnd, QWL_USER );
    // this message sent by client
    WinEnableWindow( pg->hwndClient, FALSE );
    // this is a macro defined in pmwin.h
    WinEnableMenuItem( pg->hwndMenubar, IDM_SLEEP, FALSE );
    return (MRESULT) 0;

  case WM_USER_ENABLE:
    // get pointer to globals from window words
    pg = (PGLOBALS) WinQueryWindowULong( hwnd, QWL_USER );
    // this message sent by client
    WinEnableWindow( pg->hwndClient, TRUE );
    // this is a macro defined in pmwin.h
    WinEnableMenuItem( pg->hwndMenubar, IDM_SLEEP, TRUE  );
    return (MRESULT) 0;
  }
  // default
  return WinDefWindowProc( hwnd, msg, mp1, mp2 );
}
// end of file app.c ---------------------------------------------------------

// start of file object.c ---------------------------------------------------
// the object window thread and procedure on thread 2

// os2 includes
#define INCL_DOSPROCESS
#define INCL_WIN
#include <os2.h>
// crt includes
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
// app includes
#include "app.h"
#include "pmassert.h"

//----------------------------------------------------------------------
// thread 2 entry point: gets and dispatches object window messages
// _Optlink is an IBM C Set/2 function modifier
void _Optlink threadmain( void * pv  )
{
  BOOL       fSuccess;
  HAB        hab;
  HMQ        hmq;
  PGLOBALS   pg;
  QMSG       qmsg;

  // cast and set pointer to globals
  pg = (PGLOBALS) pv;

  // thread initialization
  hab = WinInitialize( 0 );
  hmq = WinCreateMsgQueue( hab, 0 );

  // prevent system from posting object window a WM_QUIT
  // I'll post WM_QUIT when it's time.
  fSuccess = WinCancelShutdown( hmq, TRUE );
  pmassert( hab, fSuccess );

  fSuccess = WinRegisterClass( hab, APP_CLASS_OBJECT,
                  (PFNWP)ObjectWinProc, 0, sizeof( PGLOBALS ));
  pmassert( hab, fSuccess );

  pg->hwndObject = WinCreateWindow( HWND_OBJECT, APP_CLASS_OBJECT, "",
             0, 0, 0, 0, 0, HWND_OBJECT, HWND_BOTTOM, 0, (PVOID)pg, NULL );
  pmassert( hab, pg->hwndObject );

  // created OK, ack client
  WinPostMsg( pg->hwndClient, WM_USER_ACK, 0, 0 );

  // get/dispatch messages; user messages, for the most part
  while( WinGetMsg ( hab, &qmsg, 0, 0, 0 ))
  {
    WinDispatchMsg ( hab, &qmsg );
  }

  // tell client window to quit
  WinPostMsg( pg->hwndClient, WM_QUIT, 0, 0 );

  // clean up
  WinDestroyWindow( pg->hwndObject );
  WinDestroyMsgQueue( hmq );
  WinTerminate( hab );
  return;
}

// --------------------------------------------------------------------------
// object window procedure; mp1 is the window to acknowledge upon completion
MRESULT EXPENTRY ObjectWinProc( HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2)
{
  PGLOBALS      pg;
  HWND          hwndToAck;

  // store the handle of the window to ack upon task completion;
  hwndToAck = (HWND)mp1;

  switch( msg ) {
  case WM_CREATE:
    // for the create case, mp1 is pointer to globals;
    // save it in object window words; dependency on WinRegisterClass
    pg = (PGLOBALS) mp1;
    WinSetWindowULong( hwnd, QWL_USER, (ULONG) pg  );
    return (MRESULT) 0;

  case WM_USER_SLEEP:
    // get pointer to globals from window words
    pg = (PGLOBALS) WinQueryWindowULong( hwnd, QWL_USER );
    // sleep as though this were a time-consuming task
    DosSleep( 20000 );
    DosBeep( 500, 150 );
    // tell originating window that the task is complete
    WinPostMsg( hwndToAck, WM_USER_ACK, (MPARAM) msg, 0 );
    return (MRESULT) 0;
  }

  // default:
  return WinDefWindowProc( hwnd, msg, mp1, mp2 );
}
// end of file object.c ------------------------------------------------------

/* start of file app.rc ----------------------------------------------*/

#include "os2.h"
#include "app.h"

POINTER ID_APP THREADS.ICO

MENU ID_APP
BEGIN
  SUBMENU    "Actions",                 IDM_ACTIONS,            MIS_TEXT
  BEGIN
    MENUITEM "Sleep & Beep",            IDM_SLEEP,              MIS_TEXT
  END
END

/* end of file app.rc -------------------------------------------------*/

; ---------------------------------------------------------------------
; app.def

NAME app WINDOWAPI

STUB    'OS2STUB.EXE'

DATA    MULTIPLE

STACKSIZE  12192
HEAPSIZE    8200

PROTMODE
EXPORTS
  OBJECTWINPROC
  CLIENTWINPROC

; end of file app.def -------------------------------------------------

#-------------------------------------------------------------------
# makefile for APP.EXE, the 2-threaded PM sample

CC   = icc /c /gd- /re /ss /ms /gm+ /ti+ /q+ /Sm /kb+
LINK = link386 /nod /cod /map
LIBS = dde4mbs + os2386
H    = app.h
OBJ  = app.obj object.obj

all: app.exe

app.exe: $(OBJ) app.res app.def
  $(LINK)  $(OBJ) ,,, $(LIBS) , $*
  rc app.res

app.res: $*.rc threads.ico app.h
  rc -r $*.rc

app.obj: $*.c $(H)
  $(CC) $*.c

object.obj: $*.c $(H)
  $(CC) $*.c


# end of file makefile ---------------------------------------------


About the Author

Monte Copeland has been with IBM since 1987 and is currently a staff Programmer
in OS/2 Print Driver development.  Monte has contributed to the OS/2 print
sample program in the OS/2 Toolkit.  He also occasionally speaks about OS/2
programming at IBM's OS/2 Technical Interchanges.


ΓòÉΓòÉΓòÉ 10. Tips 'N Techniques ΓòÉΓòÉΓòÉ

Tip:  Use the new command-line option, /RUNFROMVDM, in the LINK386 linker
provided in OS/2 2.1 to enable your OS/2 applications to run from either an
OS/2 or DOS prompt.

Technique:  Doesn't it seem unfair that DOS applications can be executed from
either an OS/2 or DOS command prompt, while OS/2 applications can be executed
from an OS/2 command prompt only.  In the past, the only way to give your OS/2
application the same advantage as DOS applications was to BIND your
application.  This binding lengthened and complicated the build process and
produced much larger programs.

OS/2 2.1 provides a way to level the playing field that makes starting your
OS/2 application just as easy as starting a DOS application.

Don't believe us?  Okay, try this exercise:  Start a DOS command prompt under
OS/2 2.1, and attempt to run an OS/2 application that was not built with the
/RUNFROMVDM option (like ICONEDIT.EXE).  The following message:  appears:

This program cannot be run in a DOS session.

Now run an application that was linked using the /RUNFROMVDM option (like
VIEW.EXE) . You guessed it--no error message!  OS/2 just launches the program
in protected mode, and better yet, the user no longer needs to remember whether
the application is a DOS or OS/2 program.

Why does this work?  An OS/2 application is actually two programs, a DOS
program and an OS/2 program.  Offset 3Ch within the DOS header contains a
pointer to the OS/2 header.

If the OS/2 application is executed from a DOS command line (either the real
DOS, a DOS session of OS/2 1.x, or a DOS session of OS/2 2.x), the DOS stub
program is executed.  This program is a fully-functional DOS program, whose
default is to display an e rror message and terminate in this circumstance. If,
however, the application is executed from an OS/2 command line, the OS/2 2.x
program is executed.

The /RUNFROMVDM option causes LINK386 to include an alternate DOS stub program.
When this DOS stub is executed (when the OS/2 application is executed from a
DOS command line), it starts an OS/2 protected-mode session and runs the
application.  The DOS command line of OS/2 2.1 contains this function; while
real DOS and earlier versions of OS/2 do not.

By linking an OS/2 application with the /RUNFROMVDM LINK386 option, you improve
usability without adding complexity, increasing size, or reducing performance.


ΓòÉΓòÉΓòÉ 10.1. Tip 2 ΓòÉΓòÉΓòÉ

Tip:  Keep a backup copy of the OS2.INI and OS2SYS.INI files.

Technique:  You can protect you INI files by having them automatically backed
up each time you start your system.  Add the following lines to your CONFIG.SYS
file to backup your current .INI files, as well as the .INI files as they
existed at the previou s system statup:

CALL=x:\OS2\XCOPY.EXE x:\OS2\*.INI x:\OS2\*.INY
CALL=x:\OS2\XCOPY.EXE x:\OS2\OS2*.INI x:\OS2\*.INX

where x is the drive on which you have OS/2 installed.

Copying .INI files this way allows you to always recover a recent version of
these files...just in case!


ΓòÉΓòÉΓòÉ 10.2. Tip 3 ΓòÉΓòÉΓòÉ

Tip:  Display your directories in alphabetical order; with the subdirectories
listed first.

Technique:  Add the following line to your CONFIG.SYS file:

SET DIRCMD=\O:GN

For this to take affect you must shudown, then, restart your system.

Note:  If you wish the same thing for your DOS sessions, add the same line to
       your AUTOEXEC.BAT file.


ΓòÉΓòÉΓòÉ 10.3. Tip 4 ΓòÉΓòÉΓòÉ

Tip:  Use the DosLoadModule API only when appropriate

Technique:  The DosLoadModule API is a very expensive API call to make, so take
care!

Appropriate uses of this API are:

o At Build time when you do not know the name of the DLL that you need to call.
  For example, if it is a user-configurable DLL.

o The system (not just your code or just your thread!)  will not use that DLL
  during normal operation.  An example DLL is hlpmgr.dll.

o The DLL might not be present, and you have to handle the case where it is not
  present.

Inappropriate uses of this API are:

o You need the module handle of your own DLL.  In this case, you should use the
  module handle that is pased to the DLL at INIT time.

o You need the module handle of another DLL that is already loaded by the
  system.  In this case, the module handle should have been saved by the first
  load, so you can just use the existing handle.


ΓòÉΓòÉΓòÉ 10.4. Tip 5 ΓòÉΓòÉΓòÉ

Tip:  Tweak OS/2 2.1 for maximum performance

Technique:  You can perform several basic functions to maximize your OS/2 2.1
performance:

 1. Tweak the MAXWAIT, TIMESLICE, PRIORITY, PRIORITY_DISK_IO, PROTECTONLY, and
    cache settings (DISKCACHE (for FAT); IFS (for IPFS)) in the CONFIG.SYS.  In
    addition, place the swap file on the most used partition on the least used
    disk.  Control the location of the swap file using the SWAPPATH line in the
    CONFIG.SYS file.  The online OS/2 Command Reference provides the details
    for setting these parameters.

 2. Drag shadows of most often-used items to the desktop or to folders close
    the the surface of the Workplace Shell.  Disable animation.  Use the faster
    Details View when opening drive and folder objects.

 3. Try reducing the number of on-screen colors or dropping down in screen
    resolution.  Close (not just minimize!)  unnecessary objects and
    applications. Use the Monochrome scheme from the Scheme palette.


ΓòÉΓòÉΓòÉ 11. Creating Multithreaded Applications with WATCOM VX Γûá REXX ΓòÉΓòÉΓòÉ

by Brian Vink

The integrated graphical user interface (GUI) and multithreading capability of
the OS/2 operating system are two of its key advantages.  The integrated GUI
provides the framework necessary for rich, graphical applications.
Multithreading enables simultaneous running of many applications.  WATCOM's VX
REXX provides an easy-to-use development environment for creating applications
that exploit both the GUI capabilities and multithreading of OS/2 2.x.  In this
article we focus on multithreading.  We briefly discuss threads and then show
how to create a simple multithreaded application using WATCOM VX Γûá REXX.


ΓòÉΓòÉΓòÉ 11.1. Why Threads? ΓòÉΓòÉΓòÉ

A thread is a unit of execution.  It has its own instructions, related CPU
register values, and a stack.  A thread does not own system resources, but it
shares the resources owned by the process that created it.  A program that uses
threads will appear to be able to do more than one thing at a time.

The IBM OS/2 Application Design Guide states "The most efficient use of your
system will be achieved if you structure your application so that one thread
remains responsive to user input while others continue processing work."  An
example of this occurs in any OS/2 application that uses the Presentation
Manager (PM) GUIs.  These applications, if properly designed, have a minimum of
two threads.  One thread handles the processing for your application, while the
other remains responsive to user input.  If this is not done, your application,
as well as all other PM applications, will be blocked. That is, they will be
unable to receive any user interface messages. VX Γûá  REXX  automatically
creates applications having two threads to properly handle PM.

Many applications require more than the minimum number of threads.  For
instance, a process might create a thread to perform a lengthy database query
or to write data to a disk or to display a movie in a multimedia presentation.
The creation of this thread frees the rest of the application so that it can
continue to do other things, like process user input.  The following example
shows how to develop this kind of multithreaded application in VX Γûá REXX.


ΓòÉΓòÉΓòÉ 11.2. A Multithreaded  Application ΓòÉΓòÉΓòÉ

The sample application has a main window running on a single thread.  By
pressing the Spawn New Thread button, you can start multiple child windows
(each running on a separate thread).  Once started, each child window can send
text messages to the main wi ndow.  Figure 1 shows the sample application begin
created in the WATCOM VX Γûá REXX visual-design environment.  This is the same
visual design environment used when creating any VX Γûá REXX application.

Figure 1.  Sample VX Γûá REXX application


ΓòÉΓòÉΓòÉ 11.3. Starting a New Thread ΓòÉΓòÉΓòÉ

Figure 2 shows the main window of the application running.  The main thread of
the application is called thread 1. From the main window we can create any
number of additional threads.

Figure 2. Main thread of the application

To spawn the new thread, we defined a procedure in the Main window to execute
the following set of instructions:

        call VRMethod "Application", "StartThread", "Window2", threadID
        if( result = 0 )then do
                        call VRMessage VRWindow(), "Could not spawn thread", "Spawn
                Error"
        end

This code tells VX Γûá REXX to start a new thread running the previously-defined
Window2 code.  The value of the variable thread ID is passed to the Window2
REXX code as an argument, just as if it had been started from the OS/2 command
line.  Figure 3 sho ws the result of running the previous code segment by
pressing the Spawn New Thread button shown on the application screen.

ce Figure 3. The result of pressing the Spawn New Thread button


ΓòÉΓòÉΓòÉ 11.4. Communication between Threads ΓòÉΓòÉΓòÉ

To synchronize the operation of the threads, we need a way for them to
communicate. Using a method called posting, messages can be sent to a
particular thread.  For example, if we would like Window2 to pass a message to
the main window, we post a message from Window2 as follows:

        text = VRGet( "input_window", "value" )
        // Concatenation of quotes forms the string to pass  //
        text = '"' || text || '"'
        call VRMethod "Application", "Post", mainThread, "call ShowMessage"
        text

The VRGet function retrieves the text from the input box in Window2.  The
function posts a message to the main window.  The message is a REXX command
that is executed in the main window.  In this case, the message is:

                call ShowMessage text
As in all PM applications, there is an event loop that receives and dispatches
messages.  The message posted to the Main window is queued so that the
procedure, ShowMessage, is automatically called the next time the event loop is
executed.

The ShowMessage procedure of Window1 is:

                ShowMessage:
                    text = Arg( 1 )
                    call VRMethod "message_list", "addstring", text
                    return
In this example, ShowMessage simply lists the message that has been passed to
it in its message box.  Figure 4 shows a message that was passed to the main
thread from thread 2. Figure  4.  Message passed to the main thread

The method described previously is not the only method of communicating between
threads.  Other methods, such as using process-wide global variables, are also
supported by WATCOM VX Γûá REXX.

In summary, an integrated GUI and support of multithreading are two of the many
benefits offered by OS/2 2.x.  WATCOM VX Γûá REXX exploits both of these key
features of OS/2 in one cost effective package.  VX Γûá REXX is ideal for both
simple development projects and the creation of advanced applications requiring
the advanced features of OS/2 2.x
Watcom History

Founded in 1974, WATCOM supplies high-performance programming and information
tools for a wide range of computing environments.  For more information on
WATCOM or VX Γûá REXX, contact WATCOM at:

WATCOM International
415 Phillip Street
Waterloo, Ontario
Canada N2L3X2
519-886-3700
519-747-4971

or

WATCOM Europe
PO Box 64
LIVINGSTON
West Lothian 5H547AE
44 506 460112 (phone)
44 506 460115 (fax)


ΓòÉΓòÉΓòÉ 12. Discovery Search Engine ΓòÉΓòÉΓòÉ

by Dale Torres

Have you ever wondered if something you needed was available?  Is a table of
contents or an index enough to figure out if what you need is in a document?
What questions do you ask to determine if that module is one you could use? If
you have ever asked these questions or others like them, read on.

This article describes some of the technology that was used in the Discovery
Search Engine developed by IBM Santa Theresa.  A subset of the Discovery Search
Engine is used in the Developer Connection CD-ROM.


ΓòÉΓòÉΓòÉ 12.1. Today ΓòÉΓòÉΓòÉ

Different types of search technologies are used for different types of work.

You can spend a lot of time is spent browsing source (text or otherwise) to
determine what information is available, how something works, or whether or not
you can reuse some or all of what you are looking at.  To find things, a simple
search mechanism pe rforms a pattern-match with what you are looking for by
scanning the source.  There might be a few optional features, but generally
browsers or editors are only good for a particular source with a particular
tool.

The rest of this article descrives some of the search technologies available
today to help you find words, source code, test cases, or other items.


ΓòÉΓòÉΓòÉ 12.2. Free Text Search ΓòÉΓòÉΓòÉ

Free text search engines let the user pick their own identifiers to look for,
as opposed to a sometimes arbitrary table of contents or index.  Most search
engines allow for a free text search, based on a technology that scans the
source file.  An index file is built that contains the primal elements found in
the source file, along with offsets when duplicates are found.  This file is
used by the search engine to locate items of interest.  An optional feature
might exist to allow the file creator to ignore such noise words as a, to, or
the.

When compiling such a index for multiple source files an additional piece of
information may be necessary.  This information consists of an indicator that
identifies what information is found in which source file.  An additional
header is appended.  The extra indicators would help the search engine identify
in which which source files the desired information might be found. The file a
bit larger now, perhaps up to 15%.  This type of search also might take longer.


ΓòÉΓòÉΓòÉ 12.3. Keyword Search ΓòÉΓòÉΓòÉ

Keyword search engines provide a different type of capability for the end user.
By associating source information with selected keywords, the user can obtain
information quickly and easily.  This association of keywords allows for
combinations not availa ble with free text searches andis very useful when
there are many source files to be examined for specific information.  The use
of boolean expressions is a valuable part of this search technique.  Verbs such
as AND, OR, and NOT help combine these keywords into extended search arguments.
Faceted arguments may also be used, as well as additional qualifiers.  Sounds
pretty good so far, doesn't it?

There are several areas that limits keyword search.  Many of these types of
keyword search engines are implemented in a relational database, with a great
number of tables that would need to be maintained.  It can also be terribly
slow.  As many of you prob ably already know, when you are looking for
something and you are distracted or annoyed (in this case with slow response
time), the tool isn't very valuable.


ΓòÉΓòÉΓòÉ 12.4. Artificial Intelligence ΓòÉΓòÉΓòÉ

Artificial Intelligence (AI) allows for new, additional opportunities.  It
allows for specialized searches, such as elements that meet a special category,
parameter values for example.  AI provides capabilities for not only free text
searches and keyword s earch arguments but also specific context searches
within facets.  Say you wanted to know of elements within a library that
contain length fields of less than 1,000 bytes, or an arrangement where when
this condition is satisfied, list all associated compon ents called by these
modules.  AI allows for wild-card searching as well.  AI is beginning to look
pretty good.

Of course, there is no free lunch with AI either.  Someone has to generate the
semantic nets and the rules.  Someone also has to decide a bunch of other stuff
as well.  It can be a bit of a maintenance nightmare.  Besides, such an AI
index may be as large as 75% of the original library, a real space hog.  It is
also questionable when it comes to response time.


ΓòÉΓòÉΓòÉ 12.5. Structured Search ΓòÉΓòÉΓòÉ

Structured searches let you navigate through the subdirectories and other
similar structures that make up libraries.  They present information that might
not be available with the other search technologies, such as when a file was
last updated, ownership, and security issues.

When combined with a keyword type of search the results can be of immense
benefit for maintenance programmer.  When a maintenance programmer wants to
make an enhancement to an existing application program this type of search may
be of great benefit.


ΓòÉΓòÉΓòÉ 12.6. Summary ΓòÉΓòÉΓòÉ

What would be the optimum search tool?  I propose combininng the best of all
those described.  A Keyword Search capability combined with a Structured
approach that included the ability to search for intelligent answers, such as
the ones sought with AI.  It would also be lightning fast, and build an index
smaller than 10% and provide automated method of accumulating the keywords, the
structure, the rules and the semantic nets, without the need for human
intervention.  It would have provisions for self-maintenance as well as the
capability of tailoring it to suit individual needs.

The prototype of such a tool is used in The Developer Connection Browser,
providing the ability to search through the volumes of technical documentation
on the CD-ROM.


ΓòÉΓòÉΓòÉ 13. VisPro/REXX Is Visual Programming with REXX ΓòÉΓòÉΓòÉ

by Dave Hock

HockWare Inc.'s VisPro/REX lets seasoned and novice PM programmers quickly
create powerful graphical applications using REXX.  VisPro/REXX uses the
features of OS/2 2.1 and the Workplace Shell, and demonstrates the power of the
OS/2 2.1 environment.

Many OS/2 programmers are using it to quickly construct applications that are
critical to their business.  Others are taking advantage of the OS/2 REXX
support for database manager, HLLAPI, and APPC in building their applications.

VisPro/REXX looks and feels just like the Workplace Shell, making it extremely
easy to learn.  It employs direct editing, pop-up menus, multiple views, and
settings notebooks.  In addition, VisPro/REXX supports the OS/2 font and color
palettes, making it easy to change the font or color of the application you are
creating.

The fact that VisPro/REXX conforms to CUA '91 standardshas another benefit:
because developers often design by example when creating an application,
programmers use design aspects of their favorite applications.  Therefore,
VisPro/REXX helps programmers design proper CUA '91 applications by acting as
an example.

VisPro/REXX provides drag and drop capabilities throughout the product.  The
most distinctive of these is drag and drop programming.  Using drag and drop,
VisPro/REXX users literally have the option of programming a window with very
little use of the keyb oard.  This capability is made possible by automatically
generating REXX code for all object interactions.

VisPro/REXX has defined a series of powerful REXX calls to interface with GUI
objects.  These calls free the programmer from having to deal with the
multitude of ways of accessing information on controls by using the object
oriented programming (OOP) concept, overloading.

For example, consider the chore of getting the value of an OS/2 control.  A
VisPro/REXX programmer can use the VpGetItemValue function.  In contrast, an
OS/2 programmer would have to deal with many different types of calls, which
vary from control to contr ol.  The following shows the programming constructs
that are replaced by a single call to the function, VpGetItemValue:

To get the text for a push button, radio button, entry field, or check box:

      WinQueryWindowText(hwnd,sizeof(value),value)

To get the text for a menu item:

      WinSendMsg(hwndMenu, MM_QUERYMENUTEXT,
           MPFROM2SHORT(item,sizeof(value), value)

To get the position of a slider arm:

      value=WinSendMsg(hwnd, SLM_QUERYSLIDERINFO,
              MPFROM2SHORT(SMA_SLIDERARMPOSITION,SMA_RANGEVALUE),0)

To get the text of the selected item in a list box or combo box:

      sTemp=SHORT1FROMMR(WinSendMsg(hwnd,LM_QUERYSELECTION,
                 MPFROMSHORT(LIT_FIRST), 0));
      if (sTemp!=LIT_NONE)
         WinSendMsg(hwnd,LM_QUERYITEMTEXT,
                 MPFROM2SHORT(sTemp,value),
                 MPFROMP(value));

To get the contents of a spin button:

      WinSendMsg(hwnd,SPBM_QUERYVALUE,
                 MPFROMP(value),
                 MPFROM2SHORT(sizeof(value),SPBQ_UPDATEIFVALID))

To get the contents of a selected value set cell:

      mr=WinSendMsg(hwnd,VM_QUERYSELECTEDITEM,0,0);
      usRow=SHORT1FROMMR(mr);
      usColumn=SHORT2FROMMR(mr);
      vsText.pszItemText=value;
      vsText.ulBufLen=sizeof(value);
      WinSendMsg(hwnd,VM_QUERYITEM,
                MPFROM2SHORT(usRow,usColumn),MPFROMP(&vsText))

To get the text for a selected container icon:

      pRecord=(PMINIRECORDCORE)PVOIDFROMMR(WinSendMsg(hwnd,CM_QUERYRECO
  RDEMPHASIS,
     MPFROMP(CMA_FIRST), MPFROMSHORT(CRA_SELECTED)));
     if (pRecord)
      if(WinSendMsg(hwnd,CM_QUERYRECORDINFO,
            MPFROMP(&pRecord), MPFROMSHORT(1)))
            strcpy(value,pRecord->pszIcon);

Who wants to do all this just to get the value of the object?  VisPro/REXX does
the equivalent operations with the single function, VpGetItemValue, and because
of the drag and drop programming interface, programmers don't even have to type
any code to achieve this.


ΓòÉΓòÉΓòÉ 13.1. Creating a Program using VisPro/REXX ΓòÉΓòÉΓòÉ

To start working on a program, the VisPro/REXX user drags a new project from
the Project template icon.  Once open, the project displays a Main icon that
represents the main window for the application being created.

From a pop-up menu, the VisPro/REXX user can open a Layout view of the Main
icon.  The WYSIWYG Layout view lets the user lay out the user-interface objects
for the window..  To add an object, drag the corresponding icons from the Tool
bar, and drop them at the desired location in the canvas within the Layout
view.

Figure 1.  Lyout view of VisPro/REXX

The objects you add behave just like Workplace Shell objects, including pop-up
menus, support direct editing, and have a Settings view to modify attributes of
the object.  All objects can be dragged to the Shredder or to a Workplace Shell
folder where they can be made into file objects.  Objects can also be copied by
holding down the Control key while dragging.

Add menus to the application using the Menu page of the Settings notebook.  To
add a menu, simply select Add menu from the Menu page.  An icon appears for the
menu; use direct editing to provide a name for it.  Menu items can be added
under the menu by selecting Add item; again, use direct editing to provide a
name.

To define what happens when an object is used (for example, a button is
clicked), you can either remain in the Layout view, or switch to the Event tree
view.  This view provides a split window, showing the objects the user added as
well as the events the user chose on the left.  On the right, the REXX
statements for the selected event appear.  If, for example, you want to specify
what happens when a push button is clicked, select the When Clicked/Selected
item from the push button's pop-up menu.  The code for the event appears on the
right side of the Event tree view.

The Event tree view is also handy for drag and drop programming.  For example,
to set the value of an entry field when the previously-described push button is
selected, use drag and drop programming to drag the entry field to the right
side (containing the code).  At this point, linking emphasis is shown by a
rubber-band line from the source of the drag to the current position of the
mouse pointer.  When the drag operation is ended, a window appears containing a
list, in plain English, of all the things that can be done to the entry field.
After the user selects the appropriate choice, the REXX statements used to set
the value of the entry field are generated.  See figure 2.

Figure 2.  Event tree view showing drag and drop capabilities

After programming an initial application, test it by selecting the Test
function.  This function immediately runs the application, and places the
programmer into an interactive debugger.  While this debugger runs, the
programmer can modify the code on the fly to correct any problems encountered.
After the application is complete, the programmer can select the Build function
to generate a small, stand-alone executable (.EXE) file.  This file can be
distributed to anyone free of charge.


HockWare History

HockWare, Inc.  was formerly UCANDU Software.  HockWare, Inc.  is a software
company specializing in OS/2 products.  Dave Hock is a former member of IBM's
CUA '91 Architecture group.  He was a member of the programming team that
developed the OS/2 2.0 Workplace Shell.  To find out more about Vispro/REXX or
HockWare, Inc, contact:

HockWare, Inc.
P.O. Box 336
Cary, NC 27512
[phone] (sales)
[phone] (technical support)
[phone] (fax)


ΓòÉΓòÉΓòÉ 14. Graphics Interface Kit/2 Brings Ease to Creating GUIs ΓòÉΓòÉΓòÉ

IBM (Vienna, Austria) recently announced the IBM Graphics Interface Kit/2
(GIK/2) product.  GIK/2 is a product that lets programmers focus on application
logic, rather than graphic programming.

With the advent of GUI-based integrated environments, such as IBM's OS/2
Presentation Manager (PM), market demand has increased for products providing
graphical front-ends.  Many tools on the market let you develop standard GUI
interfaces.  The GIK/2 product is different--it is a toolkit that assists you
in creating abstract graphical front-ends for applications.  An example of an
abstract front-end is shown in figure 1.

Figure 1. Abstract GUI front-end

Previously when a programming shop wanted to implement GUIs in their
applications, they had to make a substantial financial and personnel
commitment. Today, with the help of IBM GIK/2, you can rapidly develop
prototypes of your data objects and create skeleton C-language files.  GIK/2
also provides you with an interface to 300+ functions, which links the
prototype to your application code.  These functions consists of event and
action handlers, as well as API calls.

This article describes creating a GUI application using GIK/2.


ΓòÉΓòÉΓòÉ 14.1. Development Overview ΓòÉΓòÉΓòÉ

For most of your development, you will use GIK/2's easy-to-use, menu-driven
design tool.  The design tool lets you create a design program quickly, by
letting you define the parameters that characterize your GUI.  Then, GIK/2
generates a source-code skele ton for your customizing C code, based on these
parameters.  All of the parameters are saved in the .DF file; your custom C
program uses them during runtime.


ΓòÉΓòÉΓòÉ 14.1.1. Defining Symbol Types ΓòÉΓòÉΓòÉ

Symbols are the application building blocks.  GIK/2 defines two kinds of
symbols---nodes and links.  Nodes are the objects that the end-user can
manipulate; links are the relationship connecting either other links or nodes.
Symbols can consist of different parts, just as a car consists of an engine,
tires, and wheels.  The symbol part is the smallest unit that can be acted on.

In addition to defining multiple forms for each symbol, GIK/2 lets you define
multiple shapes for each form.  While you must specify a standard shape, you
also optionally can specify a palette or drag shape.

Whether you define one or many symbol parts and forms, GIK/2 uses the same
application code for each single symbol.

Symbols can take on many shapes.  Use the GIK/2 shape definition window to
develop the shape's graphical elements.  Associate one or more elements with
each symbol part.  The shape definition window is a WYSIWYG editor.  In
addition to drawing polylines, arcs, or boxes, GIK/2 lets you import icons, bit
maps, and pointers.


ΓòÉΓòÉΓòÉ 14.2. Defining the Rest of Your Interface ΓòÉΓòÉΓòÉ

Use the GIK/2 graphics editor to define the look of your windows.  For example:

o Define symbol palettes
o Customize menu bars
o Specify overview windows
o Specify colors
o Define context-sensitive help panels

After you specify how the windows look, specify the things you will let the
end-user to do to the object, called editing characteristics.  For example, you
might restrict the actions on some objects.

Finally, tell the GIK/2 design tool to generate skeleton files for customizing
code.  Customizing code consists of action and event handlers.  GIK/2 generates
the following files:

o Include files
o Action handlers
o Event handlers
o Definition files
o Make files


ΓòÉΓòÉΓòÉ 14.2.1. Runtime Overview ΓòÉΓòÉΓòÉ

The runtime component of GIK/2 contains a small starter program, as well as
DLLs having over 300 APIs, events, and actions.  Running GIK/2's starter
program gives you access to a powerful and generic graphics editor.  This
editor provides you with a set of windows, menus, and supporting features. The
characteristics of the graphics editor are dependent on the definitions in your
.DF file and can be customized using either the design tool or by writing
customizing code.  During runtime, the design file populates the interface with
symbols, the customizing code synchronizes the interface with the application,
and the help library provides context-sensitive help.

The runtime window is where the action takes place...it is where you check to
see whether or not your objects do what they're supposed to do.  Use the
runtime window to see if symbols can be moved, added, or deleted as planned.
Actions

The GIK/2 program comes with approximately 50 standard, generic actions.  Even
though they are functional, you must write customizing code to conform them to
your specific needs.

Explicit actions are actions that you invoke from the menu bar.  Implicit
actions are actions that you invoke using the mouse.  The association between a
menu choice and an explicit action must be defined in the design file.

If, however, you want to add your own actions invoked from the menu bar, you
must associate these menu choices with action handlers (a C function that is
called when the user selects one of these menu choices).  Each action handler
contains a switch st atement; while each menu choice associated with that
action handler consists of a case statement.
Events

Events are predefined points in GIK/2 processing where you can define user-exit
routines, called event handlers, which let you customize the behavior of the
graphic interface and link the graphics interface to the application code.

Event handler functions provide the key link between the graphic created with
the GIK/2 design tool and the application data.  When you register each event
handler in the design tool, GIK/2 creates code templates for each handler.
Graphics Library Functions

With the GIK/2 program, you get 300+ high-level graphics functions.  Call these
functions within your C-language program to change the default behavior of
GIK/2.  Functions are available to connect graphical symbols to the application
code that they repre sent, initialize and quit GIK/2 windows from the
application main code, and process events.

Again, the purpose of using a GUI programming tool remains clear.  Instead of
concentrating on graphic programming and associations, you are now free to
concentrate on your application logic.


ΓòÉΓòÉΓòÉ 14.2.2. Customizing with C Code ΓòÉΓòÉΓòÉ

After using the GIK/2 design tool to create your design and register your event
handlers, you are finally ready to work on the customizing code to build a
running application.  Your customizing code adds the application logic that
links the application da ta to your graphical interface.  The collection of
event and action handlers is your customized C code and will reside in an OS/2
DLL.


ΓòÉΓòÉΓòÉ 14.3. Summary ΓòÉΓòÉΓòÉ

So there you have it...  all the necessary components of the complete graphics
programming toolkit:

o A graphics editor with all the basic features needed by any graphics
  interface.

o A design tool that enables you to quickly adapt the graphics editor to
  specific application needs A powerful graphics library that allows you to
  link your graphics interface to your application code.

Now that you've read about it, use it!.  Your accompanying Developer Connection
CD-ROM contains a demo version of the GIK/2 product.  Use the demo to create
your own GUI applications, and find out how easy using the GIK/2 product really
is.


Related Information

This article was based on the paper Graphics Interface Kit/2 A toolkit for
graphical visualization and Manipulation of Data by Sylvia Hansjakob (Manager
of the GIK/2 Development Team) and Roland Hatschka (GIK/2 team programmer). It
was edited for this publication by Stacey Miller, the Editor of The Developer
Connection News.


ΓòÉΓòÉΓòÉ 15. Graphics Interface Kit/2 and The Developer Connection for OS/2 ΓòÉΓòÉΓòÉ

by Seth Eilbott

So, how does one go about choosing a product to develop a graphical user
interface for a new product?  We did it by accessing our needs and researching
our options.  Our tool of choice was the IBM Graphics Interface Kit/2 (GIK/2)
product.  This article gives some perspectives on a real-life use of GIK/2.

One of the great features of GIK/2 is its ability to separate the handling of
the graphics from the handling of the code.  Here are two examples:

o GIK/2 was able to handle all of the aspects of graphics manipulation, which
  freed up the User Interface team from worrying about the details of the
  graphics.  That meant we could concentrate on writing the code to implement
  features.  For example, a collapsed (closed) category is shown as a closed
  CD-ROM jewel case, while an expanded category is shown as an open jewel case.
  Both images first were created as standard OS/2 icons.  Then, GIK/2's design
  tool let us import these icons into separate parts of the category symbol.
  To change a category graphic from one state to the other, The Developer
  Connection user-interface code simply had to tell GIK/2 to hide one part and
  to show the other.  No PM calls were required of our code; GIK/2 magically
  handled the code details.

o GIK/2 was able to hide the details of the product icon manipulation in a
  similar manner to the graphics manipulation.  Even though different icons are
  shown for the different products, we actually used only a single symbol
  definition.  At runtime, we issue a single GIK/2 call that loads a different
  icon for each product and shows that icon in the window.

Another feature we liked was the ability to use our interface as an editor.
While this mode is not part of the distributed interface, we used this mode of
GIK/2 to create the catalog that you see.  In edit mode, we have incorporated
drag-and-drop support, so that we can place the categories and product in the
exact order we want.  We can also use edit mode to enter all the details for
each of the categories.

In a nutshell, IBM's GIK/2 drastically reduced our development time.  It
allowed us to concentrate on the internal processing of The Developer
Connection user interface, without worrying on the external processing.


About the Author

Seth Eilbott has been with IBM since 1982 and is currently an Advisor Program
responsible for The Developer Connection for OS/2's User Interface.  Seth has
had many differennt roles at IBM, including working on the Blockbuster and
ImagePlus/2 products.


ΓòÉΓòÉΓòÉ 16. Borland C++ for OS/2 Means Business ΓòÉΓòÉΓòÉ

by Michael Hyman

Object-oriented programming (OOP) has revolutionized the way people develop
software.  This technological breakthrough enables software developers to
quickly and easily develop more graphical, functional, and intuitive software,
as evidenced by Borland's own use of OOP technology to many of their own
products.

The acceptance of OOP is a growing industry trend, and Borland is one of the
leading suppliers of OOP languages and tools.  With the release of Borland C++
for OS/2, Borland brings its expertise to bear on a product that will become
the standard for dev elopment of OS/2 2.x applications.  Whether you are using
OS/2 to run DOS and Windows applications, or to take advantage of the 32-bit
multithreaded capabilities of native OS/2, Borland has a C++ compiler to meet
your needs.

Borland C++ for OS/2 provides users with a GUI-based integrated development
environment, global optimization, support for C++ 3.0, object-oriented
debugging, precompiled headers, and smart project management.  Borland C++ for
OS/2 takes advantage of the OS/2 operating system to provide integrated and
stand-alone GUI debugging, as well as support for multiple threads and
background compilation.


ΓòÉΓòÉΓòÉ 16.1. Fast 32-Bit Optimizing Compiler ΓòÉΓòÉΓòÉ

Borland C++ for OS/2 runs under OS/2 host systems and creates 32-bit
applications for OS/2 2.x.  The compiler produces 32-bit object code, supports
development of multithreaded applications and mixed-mode programming in OS/2
(16-bit calls from within 32-b it executables), and supports the OS/2 calling
convention.  This allows developers to create OS/2 2.x executables, libraries,
and DLLs, as well as text-mode programs and Presentation Manager (PM)
applications.

Borland C++ for OS/2 offers programmers state-of-the-art global optimizations
for 386 and 486 processors, such as dead-storage elimination, local-common
subexpression elimination, global-register allocation, and intrinsic expansion.
These optimizations h elp developers create fast, tight code.

Plus, Borland C++ for OS/2 is a 32-bit application that lets you deliver
solutions quickly.  It lets programmers develop in C++ (compatible with AT&T's
cfront C++ 3.0) or in 100% ANSI-compatible C. The combination of C++ and C lets
developers program in either or both languages, and eases the transition from C
to C++.  The included Turbo Assembler for OS/2 lets programmers easily include
assembly-language routines in their applications.


ΓòÉΓòÉΓòÉ 16.2. Easy-to-Use Development Environment ΓòÉΓòÉΓòÉ

Borland C++ for OS/2 features Borland's productivity enhancing integrated
development environment (IDE), which runs as a PM application.  The GUI
development environment integrates features, such as a SpeedBar that
graphically presents commonly-used comma nds, integrated debugging, pull-down
menus, color-syntax highlighting, multiple-edit windows, and dialog boxes that
greatly increase productivity by reducing the time necessary to edit, compile,
and debug a program.

The IDE takes advantage of the multithread capability of OS/2 2.x and permits
compilation of source files in the background, letting the developer perform
other activities, such as editing, without stopping to wait for the compilation
to finish.  This capability results in higher programmer productivity.

Help for all components of Borland C++ for OS/2 and for PM API is available
on-line.

Borland's IDE contains a powerful program editor.  In addition to providing
completely customizable color-syntax highlighting, and the normal editor
features, such as cut, paste, search, and replace, the editor includes column
blocking, variable indent an d outdent, case conversion, single keystroke
recording, and regular expression matching.  These features make creating and
editing code a pleasure.


ΓòÉΓòÉΓòÉ 16.3. Integrated GUI Debugging ΓòÉΓòÉΓòÉ

Borland C++ for OS/2 provides full-featured, integrated GUI debugging, allowing
developers to debug applications under PMwithout leaving the development
environment.  This provision makes it easy to catch and fix bugs.

Figure 1. The IDE is a high-productivity environment that lets you edit,
compile, debug, and run your applications.


ΓòÉΓòÉΓòÉ 16.4. Turbo Debugger GX ΓòÉΓòÉΓòÉ

Borland C++ for OS/2 includes a stand-alone debugger, in addition to the
integrated debugger.  Turbo Debugger GX offers users a graphical, source-level
solution for debugging applications running on OS/2 host systems.  Developers
can debug single and mult ithread OS/2 and PM applications.  The debugger
offers programmers the maximum flexibility to debug a wide range of
applications in a convenient environment.

The debugger provides full support for C and C++, as well as for debugging
optimized code.  Executable lines are graphically distinguished from comments,
declarations, and code removed by the optimizer, making it much easier to
understand code as you trace through it.

Turbo Debugger makes special use of screen real estate, intelligently showing
more information as you expand the size of the debugger windows.  Object
inspectors are used throughout.  You can simply click on any line of code to
inspect variables, set breakpoints, change values, or get more information
about a structure.  And glyphs in the source windows display additional
information about code properties.

Figure 2. Turbo Debugger GX offers developers a sophisticated, easy-to-use debugger.

You can view source code (Source, Modules), data (Watch, Variable, Evaluator),
hardware information (Disassembly, Register, Stack, Numeric Processor), memory
(Heap, Memory), and operating system details (Exceptionpoint).  All are
accessible with simple mouse clicks.

There is full support for traditional breakpoints, which perform an action
(such as a break, log, or expression evaluation) when a particular point is
encountered in code, as well as messagepoints (which act on encountering a PM
message or messages), datapoints (which act when the contents of a memory
address change), and exceptionpoints (which act when an exception is received
from the OS/2 kernel).

Turbo Debugger GX also supports hard- and soft-mode debugging.  With hard-mode
debugging, when the debugger has control, only the debugger receives messages
from PM.  In this situation, the debugger traps the messages to all other
processes.  Soft-mode debugging lets other processes receive PM messages, as
during normal operation.


Borland History

Borland International Incorporated is one of the leading developers and
marketers of business application software and programming products.  Borland
is one of the industry's largest personal computer companies, and a premeir
supplier of database software.  In addition to its prominence in the United
States, Borland is a global competitor with subsidiaries, sales offices, and
distributors worldwide.  Michael Hyman is a Senior Product Manager for Borland
International Incorporated.


ΓòÉΓòÉΓòÉ 17. IBM Device Driver Source Kit for OS/2 ΓòÉΓòÉΓòÉ

by Judith A. Courter

Does your hardware support the OS/2 operating system?  Are you writing device
drivers for your own or other company's hardware?  Now, writing device drivers
for OS/2 has been made easier with the release of the IBM Device Driver Source
Kit for OS/2 (DDK).

Imagine a kit containing over 80MB of complete, buildable source code of actual
OS/2 2.1 device drivers--not just samples!  Then imagine that this code comes
with great support directly from the OS/2 Driver Development Support Center.
Well, that's exactly what the DDK program provides for you.

This article describes the contents of Version 1.0.  The next update is planned
to be release within the next 2 months.


ΓòÉΓòÉΓòÉ 17.1. Device Driver Source Code Contained in the DDK ΓòÉΓòÉΓòÉ

The DDK contains the full source code for OS/2 2.1 drivers for the following
devices:

Displays                           Printers
CD-ROMs                            DASD
SCSI                               Diskettes
Keyboards                          Mouse
Serial Communications              8516 Touch Devices
Pen for OS/2                       MMPM/2


ΓòÉΓòÉΓòÉ 17.2. Verification Test Tools Contained in the DDK ΓòÉΓòÉΓòÉ

In addition to all the device driver source code, the DDK gives you the
following verification test tools:

PALDISP             Displays the hardware palette in a PM window.  Used to
                    debug palette manager enabled PM display drivers.

PALTEST             Performs general palette manager testing for PM display
                    drivers.

DTT                 Display test tool that performs tests for all mandatory
                    graphics rendering engine (GRE) functions for display
                    drivers.

PTT                 Printer test tool that performs tests for all mandatory GRE
                    functions for printer drivers.

PENTL               Pen for OS/2 test tool that is used to call and test the
                    Pen for OS/2 device driver.  It provides a means to control
                    and query all aspects of the Pen for OS/2 device driver.

ADDE                MMPM/2 audio device driver exerciser tool that allows
                    exercising the functions in MMPM/2 Audio Device Drivers at
                    the stream programming interface (SPI) API level.

P2STRING            MMPM/2 P2 string test tool that allows testing of the
                    MMPM/2 system at the media control interface (MCI) API
                    level.


ΓòÉΓòÉΓòÉ 17.3. Online Documentation Contained in the DDK ΓòÉΓòÉΓòÉ

Use the OS/2 VIEW command or open the IBM DDK folder to view the many books
that are available online.  Take a few moments to browse through all the
information that is shipped with the product.  We provide everything from
general information to references on all the supported device drivers.  If,
however, you would like a hardcopy of any of the books, simply order them
through the DDK order number.


ΓòÉΓòÉΓòÉ 17.4. Ease of Installation ΓòÉΓòÉΓòÉ

The IBM Device Driver Source Kit for OS/2 is available on a CD-ROM.  Install
the DDK directly from your CD-ROM root directory.  The installation allows for
selected installation or installation of the entire kit.  For example, you can
install just the prin ter drivers, the common files, build tools, or printer
documentation.  As components are selected from the Install directories  panel,
the bytes needed  appear by the installation program that identifies an
approximation of the number of bytes of free space, including Installation
program work files, that will be required to perform an installation on a drive
formatted FAT.  When installing on an HPFS formatted drive, significantly less
space is required.


ΓòÉΓòÉΓòÉ 17.5. OS/2 Driver Development Support ΓòÉΓòÉΓòÉ

Signing up for the IBM DDK entitles you to become a member of the OS/2 Driver
Development Support Center (DDSC).  Do this by connecting to the IBM DDSC Team.
This team provides worldwide support for all device driver developers. Send
your technical development questions using a PC and modem.

You can reach the DDSC computer system by dialing up [phone].  After
self-registration, you have limited access to the system.  Additional
information on DDSC operations and system operations are presented on the
system.  Within 24 hours, you are contacted and, following verification of the
registration information, are granted full access to the system.


ΓòÉΓòÉΓòÉ 17.6. Future Plans ΓòÉΓòÉΓòÉ

It doesn't end here!  This is not just a kit, it is a program.  As new OS/2
device drivers become available, and as enhancements and fixes to existing
drivers are made, they will be packaged and distributed to those who sign up
for the program.  The program entitles you to all updates made available within
one year from ordering the DDK.


ΓòÉΓòÉΓòÉ 17.7. Special Promo Offer ΓòÉΓòÉΓòÉ

Don't miss out!  For a limited time you can acquire the DDK CD-ROM for a
one-time charge of ony $149.00 as a program product or $59.00 as a single
issue.  (The $149.00 price includes all updates for one year.)  This is a
savings from the $499.00 regular price.  This offer ends September 22, 1993.
Call today to become a member of the DDK program:

1-800-6DEVCON


ΓòÉΓòÉΓòÉ 18. Conference Column ΓòÉΓòÉΓòÉ

Look to this column each issue for the most up-to-the-minute information on
OS/2 conferences.  Be sure to register for these conferences early, as you
don't want to be left out!


ΓòÉΓòÉΓòÉ 18.1. PSP OS/2 Technical Interchanges ΓòÉΓòÉΓòÉ

The wave of the future is coming to the next OS/2 Technnical Interchange! This
conference will be extremely valuable to the following groups:

o Software Designers
o Independent and Corporate Developers
o Technical Coordinators
o LAN Experts
o MIS Managers
o Consultants
o Training Executives
And, let's not forget all the premiums!  Registering for this conference brings
with it many extra that are actually worth more than the conference fee.  So
make your reservations today!

Where          Lake Buena Vista (Orlando), Florida at the Walt Disney World
               Dolphin Hotel

When           August 29  to September 2

Contact        US & Canada: 1-800-872-7109
                All other Countries: 1-508-443-4990


ΓòÉΓòÉΓòÉ 18.2. OS/2 Professional Interchange ΓòÉΓòÉΓòÉ

Sponsered by OS/2 Professional and IBM's Independent Vendor League, the annual
OS/2 Professional Interchange will bring you together with the people who are
shaping the future of OS/2 computing.

Where          Palm Desert, California at the Marriot's Desert Springs Resort
               and Spa

When           October 17 to October 20

Contact        US: 1-800-438-6700
               All other countries: 1-203-261-6227
               1-203-261-3884  (fax)


ΓòÉΓòÉΓòÉ 18.3. ColoradOS/2 Developer's Conference ΓòÉΓòÉΓòÉ

Wayne Kovsky is holding "the only conference put on by a software engineer for
software engineers."  So, expect topics to range from IBM C Set ++ to SOM to
object-oriented REXX.

Where          Colorado Springs, Colorado at the Cheyenne Mountain Resort

When           October 31 to  November 5

Contact        Wayne Kovsky at 1-719-481-3389 (phone)
               1-719-481-8069 (fax)


ΓòÉΓòÉΓòÉ 18.4. Trade Shows ΓòÉΓòÉΓòÉ

The following are some of the major trade shows for the remainder of the year.

What           CAMP
Where          Chicago, Illinois
When           September 9
Contact        1-708-291-1360

What           NetWorld
Where          Dallas, Texas
When           October 5 to October 8
Contact        1-800-829-3976

What           PC Expo
Where          Chicago, Illinois
When           October 19 to October 21
Contact        1-800-829-3976

What           Fall '93 /COMDEX
Where          Las Vegas, Nevada
When           November 15 to November 19
Contact        US: 1-617-449-6600 Ext. 4023
               1-617-444-0165  (fax)
               174273  (telex)


ΓòÉΓòÉΓòÉ 19. Question and Answers ΓòÉΓòÉΓòÉ

Q.  Which CD-ROM drives does OS/2 2.1 support?

A.  Although the list of OS/2 2.1-supported CD-ROM drives is constantly
growing, the following list is accurate as of press time:

o CD Technology (Model T3301)
o Hitachi (Models CDR-1650S, CDR-1750S, CDR-3650, and CDR-3750)
o IBM (All  models)
o NEC (Models CDR-25, CDR-36, CDR-37, CDR-38, CDR-72, CDR-73, CDR-74, CDR-82,
  CDR-83, CDR-84, Multispin 38, Multispin 74, and Multispin 84)
o Panasonic (Models CR-501, LK-MC501S, MC501B, and MC521)
o Pioneer (Models DRM-600 and DRM-604X)
o Sony (Models CDU-541, CDU-561, CDU-6111, CDU-6211, and CDU-7211)
o Texel (Models DM-3021, DM-3024, DM-5021, and DM-5024)
o Toshiba (Models XM-3201, XM-3301, and XM-3401)
These CD-ROM drives must be attached to IBM, Future Domain, Adaptec, DPT, or
other SCSI adapters with native OS/2 2.1 support.

Additionally, OS/2 2.1 CD-ROM support includes audio, ISO 9660/High Sierra,
CD-ROM/XA, and Kodak Photo CD-compatibility for those drives that support these
standards.

Note:  You also can obtain a list of the CD-ROM drives that are supported by
       your version of OS/2 by performing the following:

 1. Double-click on the OS/2 System folder.  The folder opens displaying a
    number of additional folders.

 2. Double-click on the System Setup folder. The folder opens displaying a
    number of objects.

 3. Double click on the Selective Install object.  The System Configuration
    pop-up window appears.

 4. Use your mouse to put a checkmark in the CD-ROM Device Support box.

 5. Click on OK.  A pop-up window appears showing the list of supported CD-ROM
    drives Use the scroll arrows to see if your CD-ROM drive is supported.

Q.  Why don't I receive any output when I send a print job to the printer over
the LAN, even though the job gets spooled?  This is a job that will print on a
local printer.

A.  To resolve the problem, change the CONFIG.SYS file on the server as
follows:

PRINT MONBUFSIZE=134,134,134

          to

PRINT MONBUFSIZE=2048,134,134

This change will set the parallel-port device driver buffersize.  Each number
corresponds to the buffer size for LPT1, LPT2, or LPT3, respectively.  The
minimum value that you can specify is 134 bytes; the maximum value is 2048
bytes.  Changing these valu es will increase the size of the parallel-port
device-driver buffers.  This, in turn, increases the performance of data
transfer to devices that are connected to the parallel ports.

Q.  Why does a 16-bit OS/2 application run in an OS/2 full-screen session, but
fail in an OS/2 window session?

A.  An OS/2 full-screen session is a native OS/2 environment, whereas the OS/2
window screen session is a PM environment.  That is, the OS/2 window session
actually has the application running as a child process under the OS/2
PresentationManager application (which is considered the parent process).

The failure is usually an access violation (TRAP 0005 or SYS3175) in the
DosCall.DLL, PMWin.DLL, or PMGRE.DLL module.  This can happen during the
conversion of 16-bit API requests into 32-bit API requests or vice-versa This
conversion process is known as thunking, or more specifically 16-to-32-bit
thunk or 32-to-16-bit thunk.  Because OS/2 2.0 and higher run in 32-bit
environments, thunking occurs, to some degree, for 32-bit applications.

Memory is overwritten at a point that is decimal 2608 bytes (0a30 hex) from the
top the applications stack.  Specifically, if the bottom of the stack is at hex
00b0 and the top of the stack is at hex 1060 then memory at the location of
10b0 hex minus 0a30 hex is overwritten (0a30 hex).  This can cause a problem if
the stacksize is smaller then decimal 4096 bytes, because the area that is
overwritten can fall into the data variable area of the application.

To avoid this, application developers should use a module.DEF file that
contains a minimum Stacksize of 4096 bytes or larger, along with a Heapsize of
4096 bytes.  This overrides the language compiler/linker default Stack and Heap
sizes.

With the OS/2 Toolki, you can use the following work-a-round.  Run the EXEHDR
utility to change the Stacksize and Heapsize of the application's exetable
module.  As an illustration:

 1. At the OS/2 command prompt, type:

        EXEHDR myapp.exe

    (where myapp.exe is the name of the application's exectable module.)

    The Stack size will appear; for example:

        Extra stack allocation:    0964 bytes

 2. Increase your Stacksize and Heapsize to a minimum of hex 2000 bytes larger
    than required by your application's executable module.  For example, use
    the following command to to set a Stacksize of decimal 6500 bytes and a
    Heapsize of decimal 4096 bytes:

        EXEHDR /STACK:6500 /HEAP:4096 myapp.exe

Q.  When I use the IBM C Set++ Compiler, does the appropriate event handling
function get called if my class contains a pointer to an IHandler? In other
words, if I have the following window class and a command handler:

    class MyWindow : public IDialogWindow {
              IHandler *p;
        public:
            MyWindow(IHandler *x) : p(x) {
        //...
       }
       //...
    };
    class MyCmdHandler  : public ICommandHandler  {
       //...
        Boolean command (ICmdEvents&);
     };

     void main() {
             MyCmdHandler mycmdhandler;
             MyWindow mywindow(mycmdhandler);
            //...
     }

will MyCmdHandler::command() get called for WM_COMMAND?

A.  Your handler will work just fine.  The message dispatching code calls the
handler's dispatch HandlerEvent function.  In your case, this will be the
implementation you inherit from ICommandHandler.  This function will call this
>command(), which you've reimplemented and this will invoke your command()
function.  This is the justification for C++ virtual functions.

Q.  When using the C Set ++ Compiler, I can't set any form of breakpoints in
source view.  I can set them in disassembly view.  Why?

A.  You must set the breakpoints by double-clicking in the PREFIX area of an
EXECUTABLE in the Program View windows.  If the statement is not executable
(usually it will be shown in a different color), you won't be able to set the
breakpoint there.

Note:  Be aware that most people who have this problem are not using the right
       linker.  This can cause the debugger to lose track of which lines of
       source code relate to the actual code that is running.


ΓòÉΓòÉΓòÉ 20. Directory ΓòÉΓòÉΓòÉ

Ever wonder where to call to order a product or to voice a particular problem
or concern.  Well, we believe it's our job to let you know how to contact IBM.
Watch this space; we'll continually update this information.

The Developer Connection for OS/2            1-800-6DEVCON (phone)
                                             1-800-494-3045 (fax)

Additional Order Numbers

To order in Europe:

England             45-3-252-6588
Germany             45-3-252-6711
France              45-3-252-7411
Spain               45-3-252-6311
Italy               45-3-252-7622
Netherlands         45-3-252-7088
FAX                 45-3-252-8203

To order in Canada:

1-800-465-7999 (phone)
1-416-946-5700 (fax)

To order in Asia/Pacific:

61-2-354-7684 (phone)
61-2-354-7766 (fax)

Stay in touch with The Developer Connection for OS/2 team by writing to:

The Developer Connection for OS/2
IBM Corporation
Internal ZIP 1599
PO Box 1328
Boca Raton, Florida  33429-1328
USA

Electronic Support

Electronic support is provided through CompuServe.  Obtain technical support or
use the forum to exchange messages, ideas, comments, or concerns with The
Developer Connection for OS/2 team or other members.  The dedicated Developer
Connection section is located in the IBM OS/2 Developer Forum 2. To obtain
access to this section, please send a note with your subscription number to the
Developer Connection Administrator at CompuServe user id 73423,2767.  You will
receive notification or access to the Developer Connection section within 2
business days.

To access the forum, type GO OS2DF2 at the ! prompt; then, select the Developer
Connection section.

For CompuServe membership information, call 1-800-524-3388, and ask for
Representative 239.  You will receive a special introductory membership for IBM
customers.

The Device Driver Source Kit for OS/2             1-800-6DEVCON (phone)
                                                  1-407-982-3217 (modem)
                                                  1-407-982-4239 (voice)

Obtain support for the IBM DDK kit by calling the Dynamic Upload/Download
Environment (DUDE) BBS.  After completing a self-registration, you will first
have limited access to the system; then, within one business day, you will be
notified that your access level has been upgraded to NORMAL.  Send your
questions using your PC and modem.

If you have problems connecting to the DUDE BBS, you can leave a voice message
on 1-407-982-4239.  A member of the DDSC team will return your call before the
end of the next business day.

OS/2 2.1 Technical Support                        1-800-992-4777

When you buy OS/2 2.1, you also receive 60 days of free technical support.  The
OS/2 technical support team will provide assistance with installing OS/2 2.1,
setting up printers and displays, partitioning disk drives, setting up to run
multiple operating systems, moving commercial programs to folders or to the
OS/2 desktop, and installing and using Multimedia.  You can also report
suspected product defects to the technical support team.

Electronic Support (U.S. and Puerto Rico only)

Electronic support enables you to access current OS/2 technical information,
exchange messages with other OS/2 users, and submit program defects to IBM.
Electronic support is available to users with a modem and a telephone line
through the OS/2 Bulletin Board System (BBS) or CompuServe.

For information about registration and access to the IBM OS/2 BBS, call
1-800-547-1283.

For CompuServe membership information, call 1-800-848-8199.

If you are already a CompuServe member, type GO OS2SUP at the ! prompt to
access the IBM OS/2 forum.

Electronic Support (Canada only)

Electronic Support enables you to access current OS/2 technical information and
exchange messages with other OS/2 users.  Electronic support is available to
users with a modem and a telephone line through an OS/2 BBS.

You can connect directly to the OS/2 BBS nearest you by dialing one of the
following numbers:

1-416-946-4255
1-514-938-3022
1-604-664-6466

Note:  Set your modem and communication software to the following:  no parity
       bit, 8 data bits, 1 stop bit.

The Developer Assistance Program

The Developer Assistance Program (DAP) is a worldwide porgram that offers
services to software developers.  Specific services vary by country and
development platform.  For more information about the DAP, call:

U.S.                1-407-982-6408 (phone)
                    1-407-998-7610 (fax)

Worldwide           1-407-982-4259 (phone)

Additional Phone Numbers

All 800 numbers are applicable in the USA only; for individual country numbers,
please check on your local BBS or your IBM Representative.

IBM Academic Information Systems Ordering Information 1-800-222-7257

IBM Direct Marketing               1-800-IBM-2YOU
Order IBM ValuePoint systems, IBM ThinkPad systems, IBM Communication and LAN
hardware and software, memory options, printer, and typerwriter supplies.
HOURS:  8:00 a.m.  - 10:00 p.m.  EST.

IBM FAX Information Service        1-800-IBM-4FAX
Retrieve information on IBM products with your fax machine.

IBM LAN Systems Service and Support 1-800-237-5511
Technical support for custumers who own LAN Systems products.

IBM PC Dealer Referral             1-800-237-4824
Locate an IBM dealer nearest you.

IBM Personal Systems Help Center   1-800-PS2-2227
Obtain general information and technical support on ValuePoint systems,
ThinkPad systems, PS/2, and OS/2 products.  HOURS:  24-hours a day.

IBM PS/2 Technical Support Line    1-800-237-5511
                                   1-800-992-4777
60-days of free technical support after purchase of OS/2.  Additional support
is available at US$129.95 per year.  HOURS:  24-hours a day.

Independant Vendor League
The Independant Vendor League was formed to meet the specific needs of
individuals and companies who develop and market products and services that
support OS/2.  It is an association of vendors whose common ground is the IBM
OS/2 marketplace.

   To join or to receive information         1-203-262-3769
                                             1-203-262-3776
   To order an IVL Catalog                   1-800-342-6672

Multimedia Help LIne               1-800-241-1620
Obtain technical support for the Multimedia Presentation Manager/2 product.

Multimedia Information Center      1-800-IBM-9402
Obtain informaiton on the Multimedia Presentation Manager/2 product.

OS/2 and IBM LAN Systems Sales     1-800-3-IBM-OS2
Purchase OS/2 and IBM LAN Systems products by phone.

Ultimedia Tool Series              1-800-228-ULTI
Obtain technical support on the Ultimedia tool series.