OS/2 Shareware BBS: 10 Tools/10-Tools.zip/odtlktv6.zip/ODTLKT/TOOLKIT/BOOK/USETLKT.INF

OS/2 Help File | 1995-12-14 | 377KB | 8,901 lines

ΓòÉΓòÉΓòÉ 1. How to Use This Book ΓòÉΓòÉΓòÉ

Before you start reading the information in this book, it might be helpful to
review the following topics, which explain how to use this book:

     Using the Contents
     Getting Additional Information
     Using the Menu Bar Choices
     Documentation Conventions


ΓòÉΓòÉΓòÉ 1.1. Using the Contents ΓòÉΓòÉΓòÉ

When the Contents window first appears, some topics have a plus (+) sign beside
them. The plus sign indicates that additional topics are available.

To expand the Contents if you are using a mouse, click on the plus sign. If you
are using the keyboard, use the Up or Down Arrow key to highlight the topic,
and press the plus (+) key. For example, Toolkit Roadmap has a plus sign beside
it. To see additional topics for that heading, click on the plus sign or
highlight that topic and press the plus (+) key.

To view a topic, double-click on the topic (or press the Up or Down Arrow key
to highlight the topic, and then press Enter).


ΓòÉΓòÉΓòÉ 1.2. Getting Additional Information ΓòÉΓòÉΓòÉ

After you select a topic, the information for that topic appears in a window.
Highlighted words or phrases indicate that additional information is available.
You will notice that certain words and phrases are highlighted in green
letters, or in white letters on a black background. These are called hypertext
terms. If you are using a mouse, double-click on the highlighted word. If you
are using a keyboard, press the Tab key to move to the highlighted word, and
then press Enter. Additional information then appears in a window.


ΓòÉΓòÉΓòÉ 1.3. Using Menu Bar Choices ΓòÉΓòÉΓòÉ

Several choices are available for managing information presented in this book.
There are three menus on the menu bar:

     Services menu
     Options menu
     Help menu


ΓòÉΓòÉΓòÉ 1.3.1. Services Menu ΓòÉΓòÉΓòÉ

The actions that are selectable from the Services menu operate on the active
window currently displayed on the screen. These actions include the following:

     Bookmark Option
     Copy Option
     Print Option
     Search Option


ΓòÉΓòÉΓòÉ 1.3.1.1. Bookmark Option ΓòÉΓòÉΓòÉ

The Bookmark option allows you to set a placeholder so you can retrieve
information of interest to you. When you place a bookmark on a topic, it is
added to a list of bookmarks you have previously set. You can view the list,
and you can remove one or all bookmarks from the list. If you have not set any
bookmarks, the list is empty. To set a bookmark, do the following:

   1. Select a topic from the Contents.

   2. When that topic appears, choose the Bookmark option from the Services
      menu.

   3. If you want to change the name used for the bookmark, type the new name
      in the field.

   4. Click on the Place radio button or press the Up or Down Arrow key to
      select it.

   5. Click on OK or select it and press Enter. The bookmark is then added to
      the bookmark list.


ΓòÉΓòÉΓòÉ 1.3.1.2. Copy Option ΓòÉΓòÉΓòÉ

The Copy option allows you to copy a topic that you are viewing to the System
Clipboard or to a file that you can edit. You will find this particularly
useful for copying syntax definitions and program samples into the application
that you are developing.

You can copy a topic that you are viewing in two ways:

     Copy copies the topic that you are viewing into the System Clipboard. If
      you are using a Presentation Manager editor (for example, the System
      Editor) that copies or cuts (or both) to the System Clipboard and pastes
      to the System Clipboard, you can easily add the copied information to
      your program source module.

     Copy to file copies the topic that you are viewing into a temporary file
      named TEXT.TMP. You can later edit that file by using any editor. You
      will find TEXT.TMP in the directory where your viewable document resides.

 To copy a topic, do the following:

   1. Expand the Contents list and select a topic.

   2. When the topic appears, choose Copy to file from the Services menu.

   3. The system puts the text pertaining to that topic into the temporary file
      named TEXT.TMP.

 For information on one of the other choices in the Services menu, highlight
 the choice and press the F1 key.


ΓòÉΓòÉΓòÉ 1.3.1.3. Print Option ΓòÉΓòÉΓòÉ

The Print option allows you to print one or more topics. You can also print a
set of topics by first marking the topics in the Contents list. To print the
document contents list do the following:

   1. Choose Print from the Services menu.

   2. Click on Contents (or press the Up or Down Arrow key to select it).

   3. Click on Print (or select it and press Enter).

   4. The Contents list is printed on your printer.


ΓòÉΓòÉΓòÉ 1.3.1.4. Search Option ΓòÉΓòÉΓòÉ

The Search option allows you to find occurrences of a word or phrase in the
current topic, selected topics, or all topics. You can specify a word or phrase
to be searched. You can also limit the search to a set of topics by first
marking the topics in the Contents list.

To search for a word or phrase in all topics, do the following:

   1. Choose the Search option from the Services menu. Type the word or words
      to be searched for.

   2. Click on All sections or press the Up or Down Arrow keys to select it.

   3. Click on Search or select it and press Enter to begin the search.

   4. The list of topics where the word or phrase appears is displayed.


ΓòÉΓòÉΓòÉ 1.3.2. Options Menu ΓòÉΓòÉΓòÉ

The actions that are selectable from the Options menu allow you to change the
way your Contents list is displayed. To expand the Contents and show all levels
for all topics, choose Expand all from the Options menu. You can also press
Ctrl+*. For information on one of the other choices in the Options menu,
highlight the choice and press the F1 key.


ΓòÉΓòÉΓòÉ 1.3.3. Help Menu ΓòÉΓòÉΓòÉ

The actions that are selectable from the Help menu allow you to select
different types of help information. You can also press the F1 key for help
information about the Information Presentation Facility (IPF).


ΓòÉΓòÉΓòÉ 1.4. Documentation Conventions ΓòÉΓòÉΓòÉ

Throughout the Using Your Toolkit, the following conventions distinguish the
different elements of text:

 plain text                    Function names, structure names, data type
                               names, message names, enumerated types, and
                               constant names.

 Initial capitalization        Key names, push buttons, check boxes, radio
                               buttons, group-box controls, drop-down list box,
                               dialog windows, spin buttons, combo-boxes,
                               single-line entry (SLE) and multiple-line entry
                               (MLE) fields.

 CAPITALS                      File names and error codes.

 monospace                     Programming examples and user input at the
                               command line prompt or into an entry field.

 bold                          Window sub-titles, menu bar choices and menu
                               items.

 italics                       Parameters, structure fields, titles of
                               documents, and first occurrences of words with
                               special meaning.


ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ

Welcome to the IBM Developer's Toolkit for OS/2 Warp (Warp Toolkit). This book
documents the following:

     Additions and updates made to the IBM Developer's Toolkit for OS/2 Warp
      as listed in the What's New section.

     Descriptions of hardcopy and online documentation, code samples, and
      tools

     Ordering information for hardcopy books and The Developer Connection for
      OS/2

     Programming considerations that have been changed or added

     System debug support which introduces you to the interface that installs
      the debug kernel, symbol files, and debug version of the PM

     Toolkit roadmap that covers the folder hierarchy and the contents and
      directory structure

     Toolkit support information that assists you in installing or using the
      Warp Toolkit, or reporting suspected system defects as a result of
      applying the Warp Toolkit

     Mechanisms for sending us your ideas and comments about the Warp Toolkit
      and its documentation


ΓòÉΓòÉΓòÉ 3. README ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 4. Installation ΓòÉΓòÉΓòÉ

The TK21DESK.CMD command, used to recreate the Toolkit's icons or objects on
the Desktop, is no longer necessary. The function, formerly part of TK21DESK,
is now a part of the installation program.

To restore your Toolkit Desktop objects, insert the CD or diskette that
contains the install program (TKINSTAL.EXE), start the program, and follow
these steps:

   1. Click on Options to open Installation options.

   2. Deselect Install selected files and Write CONFIG.SYS updates to: (only
      Register WPS classes and Create desktop objects should be selected).

   3. Click on OK to close Installation options.

   4. Highlight the root (top-most) component in the component tree, then fill
      in the Destination: field with the location of your Toolkit subdirectory.

   5. Click on Install.


ΓòÉΓòÉΓòÉ 5. What's New ΓòÉΓòÉΓòÉ

What's New provides information on the latest release of the Warp Toolkit
available on The Developer Connection for OS/2. See the following sections for
the latest updates and additions:

     Important Information
     IBM Developer API Extensions for OS/2
     OpenDoc for OS/2
     Sample Additions
     Tool Updates


ΓòÉΓòÉΓòÉ 5.1. Important Information ΓòÉΓòÉΓòÉ

Included in this section are important items that can affect your development
efforts when using the IBM Developer's Toolkit for OS/2 Warp.

     Compiling with IBM C/2
     Compiling with VisualAge (C Set ++)
     Replacing DLGEDIT - Dialog Editor
     Replacing IPFCBIDI - Bidirectional Information Presentation Facility
      Compiler


ΓòÉΓòÉΓòÉ 5.2. IBM Developer API Extensions for OS/2 ΓòÉΓòÉΓòÉ

The IBM Developer API Extensions for OS/2 extends the OS/2 Warp application
programming interface (API) set so that application developers can develop a
common source code base for OS/2 Warp and Windows platforms. The SMART and
Hyperwise tools assist in analyzing existing Windows applications and migrating
the source code, resources, and help files to code that will compile on both
OS/2 Warp and Windows platforms. Both SMART and Hyperwise are available on the
Developer Connection for OS/2.

See the following sections for more detailed information:

     IBM Developer API Extensions for OS/2 Samples
     Programming Considerations


ΓòÉΓòÉΓòÉ 5.3. OpenDoc for OS/2 ΓòÉΓòÉΓòÉ

The header files, libraries, and bindings along with samples, technical
documentation and tools specific to OpenDoc for OS/2 are included in this
release of the Warp Toolkit.

See the following sections for more detailed OpenDoc information:

     OpenDoc Overview
     OpenDoc for OS/2 Support
     Programming Considerations
     What's New in OpenDoc for OS/2


ΓòÉΓòÉΓòÉ 5.3.1. OpenDoc Overview ΓòÉΓòÉΓòÉ

OpenDoc is an architecture that provides a means for applications to support
compound documents. Compound documents are documents that are created and
edited by several cooperating applications working within the context of a
single document.

OpenDoc enables users to integrate and edit any kind of content, including
multimedia, in place, in any kind of document. An example of this type of
integration would be a chart from a graphics application embedded into a
word-processing document. The chart could still be edited by the graphics
application while it is in the word-processing document. In this case, the
chart from the graphics application and the word-processing document would both
be parts.

To a user, a part is a single set of information displayed and manipulated in
one or more frames or windows. OpenDoc delivers component-based software in an
industry-standard manner. For end users, OpenDoc will simplify and streamline
the computing experience, while ensuring a much higher level of flexibility and
customization.  Specifically, OpenDoc offers the following user benefits:

     Easy creation of compound documents.  OpenDoc is designed to handle
      current and future types of media.  Users can place any kind of media
      into an OpenDoc document using the familiar cut-and-paste or
      drag-and-drop manipulation.

     Editing in place.  With OpenDoc, users can edit any type of content
      within a single document, without having to cut and paste between
      different application windows.

     Powerful document management.  Rather than manually assembling the
      various pieces of a document, users can let an OpenDoc document hold all
      of them.  This reduces the task of managing files, and facilitates
      document exchange and updating. As documents are edited, changes are
      tracked through drafts, ensuring greater data integrity and allowing
      users to work on shared documents without content loss from version to
      version.

     Consistency of operation.  Because users can specify preferred part
      editors, they only need to learn one way to edit each type of data for
      example, using the same text editor for word processing, entering
      spreadsheet data, or labeling diagrams.

     Uniformity of interface.  OpenDoc defines a consistent user interface for
      embedding and manipulating all kinds of media in documents.

     Scalability.  The OpenDoc human interface addresses a wide range of
      users, from novices to experts.  No class of user has to understand the
      additional functionality typically used at the next level.  Novices can
      create compound documents easily, while experts can experience nearly
      unlimited potential.

     Plug-and-play solutions.  With OpenDoc, vendors will be able to assemble
      collections of parts into solution sets that target specific tasks or
      work styles, such as a legal publishing bundle, allowing users to choose
      the solutions most appropriate for their needs.

     Access to object services.  OpenDoc is based on the industry-standard
      CORBA (Common Object Request Broker Architecture) object technology. This
      will allow users to take advantage of a wide range of distributed
      services working consistently across many different CORBA-compliant
      desktop and server systems.

 To more clearly understand the benefits OpenDoc provides to the user, let's
 examine a usage scenario that most computer users can relate to, the use of
 text editors.

 Most applications today (whether word processors, spreadsheets, databases, or
 more specialized tools) include text editing capabilities.  Some rely heavily
 on text editing, such as WordPerfect or Ami Pro.  Some use text only
 incidentally, such as WordPerfect Office or Lotus 1-2-3/G.  Unfortunately, for
 the user, all differ in their details.  For example, some allow text styles,
 and some do not. Some offer tab stops, and some do not, and so on. In addition
 to such details, they also differ in functionality and mode of operation.  The
 result? If you use six different programs, you need to learn six different
 ways to do the same task:  edit text. With OpenDoc, a text paragraph becomes a
 software module, usable wherever text is needed.  You could take your favorite
 text editor and use it whenever you needed to work with text.  Applications
 built in this way would have an important characteristic: they would
 simultaneously be simpler and more powerful. They would be simpler because you
 would have to learn only one way to do something, and they would be more
 powerful because you always have the option of choosing a fully functional
 module replacing less capable ones.

 OpenDoc also offers developers a number of important advantages:

     Faster, more efficient development.  Software developers can reuse
      previously developed parts, eliminating the need to start from scratch
      with each development effort.  This ability to reuse existing parts also
      means that developers need to spend less time on parts that are
      peripheral to their main area of expertise.

     Reduction of application complexity.  Because OpenDoc parts are
      independent of one another, a collection of parts that is less complex
      than the large, monolithic applications of today can offer equivalent
      functionality.

     Diminished costs of software development.  The fact that parts are
      smaller than applications makes them both quicker and cheaper to write,
      which reduces the penalties for failure.

     Industry-standard object mechanism.  Because parts can use SOM, a
      CORBA-compliant object mechanism, they can be written in a wide range of
      programming languages and development will be supported by many tool
      vendors. This mechanism gives developers high performance coupled with
      great flexibility in the use of plug-and-play objects.

 Here is a developer usage scenario.  Today, a developer who wants to create
 even a highly specialized tool such as a three-dimensional modeling and
 rendering program has to spend time developing a text editor, so that users
 can enter specifications and label their diagrams.  But, as a developer of
 such a program, you would much rather concentrate on your specific area of
 expertise. In the OpenDoc world, you would have two choices for providing
 functions that fall outside the primary focus of your application: bundle
 existing parts with your product or rely on the user to provide parts to
 support those functions.  Either way, you are free to concentrate on the
 competitive value of your product, rather than on peripheral issues.  The
 result is a much more useful, powerful program developed in a fraction of the
 time it would have taken using the conventional, monolithic approach.


ΓòÉΓòÉΓòÉ 5.3.1.1. Planning for Component Software ΓòÉΓòÉΓòÉ

Here are some questions to investigate when determining how components fit with
your business and software directions:

     What parts make sense for your business?

      Some parts may be included by end users in compound documents.  These
      parts are manipulated or tweaked by users and are embedded within word
      processor, spreadsheet, drawing, or other kinds of horizontal application
      documents.

      Other parts do not have a visual incarnation but instead provide access
      to server data or facilitate sharing between related activities or users.
      Typically, such parts will be used by setting parameters in a dialog box
      and then displaying the resulting data with a more conventional visual
      part (for example, a database access part that provides tabular data
      targeted at a spreadsheet).  These "back-end" parts probably represent
      real business objects such as a customer, problem report, or invoice.

     How will existing applications be divided into parts?

      Where are the value fault-lines in your applications? What are the
      facilities and features of your applications that others would want to
      use if they could only pull them out separately?

      Consider your user-interface components--do they include look-and-feel
      features that can be reused in new kinds of reports and documents?

      Consider also the internal calculations and manipulations performed by
      your application.  Are these reusable in other places? Where are the
      places you have added information specific to your business or
      application?

      Finally, consider any connectivity between different machines or modules
      in your application.  Should this connectivity be made available in a
      general- purpose way?

      Remember, in most cases, componentized applications are still delivered
      as large complete applications--people still want solutions, not
      technology. Nonetheless, these complete applications will increasingly be
      made out of components.  This allows more flexible delivery, faster
      response to changing needs, and solutions better tailored to end users.

     What is scriptable in my components?

      The Open Scripting Architecture (OSA) in OpenDoc allows one part to
      direct or request information from another.  Parts publish "event suites"
      that define the available interfaces for such interactions.  Event suites
      are like an API but are intended for users of the part, not implementers.

      Suites consist of verbs--the actions that can be performed on the parts,
      and nouns--the kinds of data stored within a part.  For example, a Person
      part might define Name, Phone, and Address nouns. A typical action on
      Person might be "Tell me the home phone number."  There are core and
      standard suites that most parts should support.  There are OpenDoc
      standardized suites for parts that manipulate text, tables, etc.

      What suites should your parts support?  You can answer this question by
      considering the nouns and verbs that users of the part would need.  Your
      parts should support standard suites where possible.


ΓòÉΓòÉΓòÉ 5.3.2. What's New in OpenDoc for OS/2 ΓòÉΓòÉΓòÉ

The following sections outline what is new in OpenDoc support since the release
of the OpenDoc Developer's Kit 2 for OS/2 product that shipped on The Developer
Connection for OS/2, Volume 9.

     Standard ISO Prefix
     DTS HH Header Files
     ITEXT.H
     Settings Extension
     Registry
     Templates API Changes
     Menu IDs
     DR4 Merge
     Changes in ODDragandDrop and ODClipboard
     Miscellaneous
     Template Code
     Public Utilities
     Notes on Scripting Support in the Container Part


ΓòÉΓòÉΓòÉ 5.3.2.1. Standard ISO Prefix ΓòÉΓòÉΓòÉ

All standard types/properties now have a standardized ISO prefix of:

   +//ISO 9070/ANSI::113722::US::CI LABS::

Parts produced by vendors should also add this prefix where appropriate with
the addition of a vendor name as follows:

   +//ISO 9070/ANSI::113722::US::CI LABS::XXX:

where XXX is your company name.


ΓòÉΓòÉΓòÉ 5.3.2.2. DTS HH Header Files ΓòÉΓòÉΓòÉ

Removed *.HH files (including OSA.HH) and integrated DTS changes into existing
.H files. Changes were also made to the PUBUTILS so they can be built for both
regular C++ and VisualAge DTS C++. Include os2.h instead of os2.hh and define
the symbol INCL_ODDTS.


ΓòÉΓòÉΓòÉ 5.3.2.3. ITEXT.H ΓòÉΓòÉΓòÉ

Modified ITEXT.H to remove MAC-specific references:

             BEFORE                                  AFTER

  ODTradITextData                              ODPlainITextData
  ODTraditionalMacText                         kODOS2PlainText
  ODScriptCode                                 ODCodePage
  SetITextScriptCode(ODIText*, ODScriptCode)   SetITextCodePage(ODIText*, ODCodePage);
  GetITextScriptCode(ODIText*)                 GetITextCodePage(ODIText*);


ΓòÉΓòÉΓòÉ 5.3.2.4. Settings Extension ΓòÉΓòÉΓòÉ

The flPageFlag parameter will determine what pages are added to or removed from
the notebook.
Added two additional parameters to AddNotebookPages():  flPageFlag and
ulReserved. ulReserved should be set to 0.

  AddNotebookPages(ODSettingsExtension *somSelf,   Environment *ev,
                   HWND hwndNotebook, ODULong flPageFlag, ODULong ulReserved)

Predefined values for flPageFlag are as follows:

 const ODULong  kODGeneralPage  =     0X00000001;  // General notebook page
 const ODULong  kODTypePage     =     0X00000002;
 const ODULong  kODViewPage     =     0X00000004;
 const ODULong  kODFile1Page    =     0X00000008;
 const ODULong  kODFile2Page    =     0X00000010;
 const ODULong  kODStandardPages =    0X0000001F;
 const ODULong  kODIconViewPage   =   0X00000020;
 const ODULong  kODTreeViewPage   =   0X00000040;
 const ODULong  kODDetailsViewPage=   0X00000080;
 const ODULong  kODFolderViewPages=   0X000000E0;
 const ODULong  kODLinkSourcePage   = 0X00000200;
 const ODULong  kODLinkTargetPage   = 0X00000400;
 const ODULong  kODLinkPages        = 0X00000600;
 const ODULong  kODAllPages         = 0X000006FF;

Note:  Can not load Presentation Page by calling AddNotebookPages() because it
       requires an additional parameter.

 Added new method to class to remove unwanted pages

    RemoveNotebookPages(ODSettingsExtension *somSelf,   Environment *ev,
                        HWND hwndNotebook, ULONG flPageFlag)


ΓòÉΓòÉΓòÉ 5.3.2.5. Registry ΓòÉΓòÉΓòÉ

Modified Registry error codes to begin with errPR_ .


ΓòÉΓòÉΓòÉ 5.3.2.6. Templates API Changes ΓòÉΓòÉΓòÉ

The ODTemplates class has had a method name change that also affects the C and
REXX utility functions for templates. ODTemplates::RemoveTemplate has been
renamed to ODTemplates::DeleteTemplate. The corresponding parameters are still
the same.  However, the C interface has changed as follows:

LONG APIENTRY ODRemoveTemplate(PSZ ObjectID);

   is now:

ODBoolean APIENTRY ODDeleteTemplate(PSZ ObjectID);

returning kODTrue for success, and kODFalse for failure.

   and

LONG APIENTRY ODCreateTemplate(ODType partKindName,ODEditor partEditor);

   is now:

PSZ APIENTRY ODCreateTemplate(ODType partKindName,ODEditor partEditor);

returning a NULL PSZ for failure and the Object ID for success.

The REXX utility function for RxODRemoveTemplate was changed to
RxODDeleteTemplate also.


ΓòÉΓòÉΓòÉ 5.3.2.7. Menu IDs ΓòÉΓòÉΓòÉ

Menu IDs have been moved from odmenuid.h to cmddefs.idl.


ΓòÉΓòÉΓòÉ 5.3.2.8. DR4 Merge ΓòÉΓòÉΓòÉ

The following list describes what changed in each IDL.

     Clipbd.idl

      The following methods were added:

              void ActionUndone(in ODUpdateID update, in ODCloneKind originalCloneKind);
              void ActionRedone(in ODUpdateID update, in ODCloneKind originalCloneKind);
              void SetPlatformClipboard(in ODPlatformTypeList typeList);
              void DraftSaved(in ODDraft draft);

     ObjctItr.idl

      The following methods:

              void  First(inout ODISOStr key,
                          inout ODObject object,
                          inout ODULong objectLength);
              void  Next(inout ODISOStr key,
                         inout ODObject object,
                         inout ODULong objectLength);

       were changed to:

              void  First(out ODISOStr key,
                          out ODObject object,
                          out ODULong objectLength);
              void  Next(out ODISOStr key,
                         out ODObject object,
                         out ODULong objectLength);

     ODObject.idl

      The following method was removed:

                 ODBoolean IsInitialized();

     ODSessn.idl

      The following method:

                 ODIText* GetUserName();

       was changed to:

                 void  GetUserName(out ODIText name);

     ShPlugIn.idl

      File replaced by ShPlugIn.h

     FaceItr.idl

      The following method was made private:

                 void InitFacetIterator(in ODFacet facet,
                                        in ODTraversalType traversalType,
                                        in ODSiblingOrder siblingOrder);

     Frame.idl

      The following public methods were added:

                 ODBoolean  IsInLimbo();
                 void    SetInLimbo(in ODBoolean isInLimbo);

      The following method:

                 ODPoint GetContentExtent();

       was changed to:

                 void    GetContentExtent(out ODPoint contentExtent);

     FrFaItr.idl

      The following method was made private:

                 void InitFrameFacetIterator(in ODFrame frame);

     Draft.idl

      The following method:

                 ODFrame CreateFrame(
                     in ODType    frameType,
                     in ODFrame    containingFrame,
                     in ODShape    frameShape,
                     in ODCanvas    biasCanvas,
                     in ODPart    part,
                     in ODTypeToken  viewType,
                     in ODTypeToken  presentation,
                     in ODBoolean  isSubframe,
                     in ODBoolean  isOverlaid);

       was changed to:

                 ODFrame CreateFrame(
                     in ODObjectType frameType,
                     in ODFrame    containingFrame,
                     in ODShape    frameShape,
                     in ODCanvas    biasCanvas,
                     in ODPart    part,
                     in ODTypeToken  viewType,
                     in ODTypeToken  presentation,
                     in ODBoolean  isSubframe,
                     in ODBoolean  isOverlaid);

     LinkSpcB.idl

      The following methods were made private:

                 ODPart GetPart();
                 ODByteArray GetPartData();
                 ODBoolean FromThisDraft();

     LinkSrcB.idl

      The following method has been made MAC-specific:

                 ODBoolean ShowLinkSourceInfo(
                         in ODFacet facet,
                         in ODUpdateID change,
                         in ODBoolean changesAllowed,
                         out ODLinkInfoResult infoResult);

      The following method has been made private:

                 ODLink GetLink();

     Undo.idl

      The following method has been added:

                 void AbortCurrentTransaction();

     Window.idl

      The following method has been removed:

                 void SetShouldDispose(in ODBoolean shouldDispose);

      The following methods:

                 void InitWindow(in ODPlatformWindow platformWindow,
                           in ODType    frameType,
                           in ODBoolean  isRootWindow,
                           in ODBoolean  isResizable,
                           in ODBoolean  isFloating,
                           in ODBoolean  shouldSave,
                           in ODPart    rootPart,
                           in ODTypeToken  viewType,
                           in ODTypeToken  presentation,
                           in ODFrame    sourceFrame);
                   void InitWindowForFrame(in ODPlatformWindow platformWindow,
                           in ODFrame    frame,
                           in ODBoolean  isRootWindow,
                           in ODBoolean  isResizable,
                           in ODBoolean  isFloating,
                           in ODBoolean  shouldSave,
                           in ODFrame    sourceFrame);

       were changed to:

                   void InitWindow(in ODPlatformWindow platformWindow,
                           in ODType    frameType,
                           in ODBoolean  isRootWindow,
                           in ODBoolean  isResizable,
                           in ODBoolean  isFloating,
                           in ODBoolean  shouldSave,
                           in ODBoolean    shouldDispose,
                           in ODPart    rootPart,
                           in ODTypeToken  viewType,
                           in ODTypeToken  presentation,
                           in ODFrame    sourceFrame);
                   void InitWindowForFrame(in ODPlatformWindow platformWindow,
                           in ODFrame    frame,
                           in ODBoolean  isRootWindow,
                           in ODBoolean  isResizable,
                           in ODBoolean  isFloating,
                           in ODBoolean  shouldSave,
                           in ODBoolean   shouldDispose,
                           in ODFrame    sourceFrame);

     WinStat.idl

      The following methods:

                   ODWindow RegisterWindow(in ODPlatformWindow newWindow,
                               in ODType frameType,
                               in ODBoolean isRootWindow,
                               in ODBoolean isResizable,
                               in ODBoolean isFloating,
                               in ODBoolean shouldSave,
                               in ODPart rootPart,
                               in ODTypeToken viewType,
                               in ODTypeToken presentation,
                               in ODFrame sourceFrame);
                   ODWindow RegisterWindowForFrame(in ODPlatformWindow newWindow,
                               in ODFrame frame,
                               in ODBoolean isRootWindow,
                               in ODBoolean isResizable,
                               in ODBoolean isFloating,
                               in ODBoolean shouldSave,
                               in ODFrame sourceFrame);

      were changed to:

                   ODWindow RegisterWindow(in ODPlatformWindow newWindow,
                               in ODType frameType,
                               in ODBoolean isRootWindow,
                               in ODBoolean isResizable,
                               in ODBoolean isFloating,
                               in ODBoolean shouldSave,
                               in ODBoolean shouldDispose,
                               in ODPart rootPart,
                               in ODTypeToken viewType,
                               in ODTypeToken presentation,
                               in ODFrame sourceFrame);
                   ODWindow RegisterWindowForFrame(in ODPlatformWindow newWindow,
                               in ODFrame frame,
                               in ODBoolean isRootWindow,
                               in ODBoolean isResizable,
                               in ODBoolean isFloating,
                               in ODBoolean shouldSave,
                               in ODBoolean shouldDispose,
                               in ODFrame sourceFrame);


ΓòÉΓòÉΓòÉ 5.3.2.9. Changes in ODDragAndDrop and ODClipboard ΓòÉΓòÉΓòÉ

   

   

     Support for non-OpenDoc drag&drop and clipboard formats

      To improve OpenDoc support for OS/2 standard drag&drop RMFs and clipboard
      formats, a set of standard kinds has been defined in stddefs.xh:

               Kind:                   Display name:              Clipboard format and/or drag&drop RMF:

            kODKindOS2Bitmap        kOS2BitmapDisplayName        CF_BITMAP, <DRM_OS2FILE,DRF_BITMAP>
            kODKindOS2DspBitmap     kOS2DspBitmapDisplayName     CF_DSPBITMAP, <DRM_OS2FILE,DRF_DSPBITMAP>
            kODKindOS2Metafile      kOS2MetafileDisplayName      CF_METAFILE, <DRM_OS2FILE,DRF_METAFILE>
            kODKindOS2DspMetafile   kOS2DspMetafileDisplayName   CF_DSPMETAFILE
            kODKindOS2Text          kOS2TextDisplayName          CF_TEXT, <DRM_OS2FILE,DRF_TEXT>
            kODKindOS2DspText       kOS2DspTextDisplayName       CF_DSPTEXT
            kODKindOS2DIB           kOS2DIBDisplayName           <DRM_OS2FILE,DRF_DIB>
            kODKindOS2DIF           kOS2DIFDisplayName           <DRM_OS2FILE,DRF_DIF>
            kODKindOS2OEMText       kOS2OEMTextDisplayName       <DRM_OS2FILE,DRF_OEMTEXT>
            kODKindOS2OwnerDisplay  kOS2OwnerDisplayDisplayName  <DRM_OS2FILE,DRF_OWNERDISPLAY>
            kODKindOS2PtrPict       kOS2PtrPictDisplayName       <DRM_OS2FILE,DRF_PTRPICT>
            kODKindOS2RTF           kOS2RTFDisplayName           <DRM_OS2FILE,DRF_RTF>
            kODKindOS2SYLK          kOS2SYLKDisplayName          <DRM_OS2FILE,DRF_SYLK>
            kODKindOS2TIFF          kOS2TIFFDisplayName          <DRM_OS2FILE,DRF_TIFF>
            kODKindOS2Palette       kOS2PaletteDisplayName       CF_PALETTE

      Parts that support any of the above clipboard formats and RMFs should
      register the corresponding standard kind. Parts that support other
      clipboard formats and RMFs should register the corresponding strings as
      kinds. This will ensure that if non-OpenDoc content of a certain type is
      dropped or pasted in a container part, the appropriate part editor will
      be chosen to handle the operation.

     ODDragAndDrop::GetDataFromDragManager has changed as follows :

              ODBoolean GetDataFromDragManager( in ODStorageUnitView theSUView,
                                                in ODPtr             szSelectedRMF,
                                                out ODStorageUnit    renderedSU );

      to:

              ODBoolean GetDataFromDragManager( in ODStorageUnitView theSUView,
                                                out ODStorageUnit    renderedSU );

     The following public methods have been added:

        -  ODDragAndDrop::CanEmbed

           Syntax:

                      ODBoolean CanEmbed(in ODStorageUnit dropSU);

           Parameters:

           dropSU - reference to the content storage unit for the drag item

           This method will query the registration manager for a part editor
           capable of handling the content of the drag-and-drop storage unit.
           It returns TRUE if a match is found, FALSE otherwise. A container
           part should call this method in its DragEnter method to determine
           whether it can accept the drop.

        -  ODDragAndDrop::CanIncorporate

           Syntax:

                      ODBoolean CanIncorporate(in ODStorageUnit dropSU, in ODType kind);

           Parameters:

                      dropSU - reference to the content storage unit for the drag item
                      kind  - part kind

           This method will determine if the type of data in dropSU matches the
           supplied kind. It returns TRUE if a match is found, FALSE otherwise.
           A non-container part should call this method in its DragEnter method
           for the kinds that it supports to determine whether it can accept
           the drop.

        -  ODClipboard::CanEmbed

           Syntax:

                      ODBoolean CanEmbed();

           This method will query the registration manager for a part editor
           capable of handling the content of the clipboard storage unit. It
           returns TRUE if a match is found, FALSE otherwise. A container part
           should call this method to determine whether to enable the Paste
           menu item.

        -  ODClipboard::CanIncorporate

           Syntax:

                      ODBoolean CanIncorporate(in ODType kind);

           Parameters:

           kind  - part kind

           This method will determine if there is a format on the PM clipboard
           matching the supplied kind. It returns TRUE if a match is found,
           FALSE otherwise. A non-container part should call this method for
           the kinds that it supports to determine whether to enable the Paste
           menu item.

           For examples on using the new APIs, see Container Part and ClipDrag
           Part code (methods: DragEnter, DragWithin, Drop, AdjustMenus).


ΓòÉΓòÉΓòÉ 5.3.2.10. Miscellaneous ΓòÉΓòÉΓòÉ

ODFacet::AcquireWindow changed to ODFacet::GetWindow.

ODTransform::TransformPoints now takes a pointer to an ODByteArray instead of a
pointer to an array of ODPoints.

ODDraft::BeginClone added a destination frame parameter.

The following IText utilities have had their names changed to be consistent
with the Apple names:

        CreateITextPSZ->CreateITextCString
        CreateITextStringPtr->CreateITextPString
        CreateITextSize->CreateITextClear
        SetITextPSZ->SetITextCString
        SetITextStringPtr->SetITextPString
        GetITextPSZ->GetITextCString
        GetITextStringPtr->GetITextPString

The following Storage utility functions have had an environment pointer added
as the first parameter:

        ODSUAddPropValue
        ODSUForceFocus
        ODSUExistsThenFocus
        ODSURemoveProperty
        ODGetBooleanProp
        ODSetBooleanProp
        ODGetUShortProp
        ODSetUShortProp
        ODGetSShortProp
        ODSetSShortProp
        ODGetULongProp
        ODSetULongProp
        ODGetSLongProp
        ODSetSLongProp
        ODGetISOStrProp
        ODSetISOStrProp
        ODGetTypeListProp
        ODSetTypeListProp
        ODGetITextProp
        ODSetITextProp
        ODGetTime_TProp
        ODSetTime_TProp
        ODGetPointProp
        ODSetPointProp
        ODGetRectProp
        ODSetRectProp
        ODGetStrongSURefProp
        ODSetStrongSURefProp
        ODGetWeakSURefProp
        ODSetWeakSURefProp
        ODGetPolygonProp
        ODSetPolygonProp
        ODGetMatrixProp
        ODSetMatrixProp
        ODGetIconFamilyProp
        ODSetIconFamilyProp

AEDescChanged function is obsolete.

ODNameResolver::GetUserToken no longer takes an ODDesc* parameter.

ODNameResolver::SetUserToken is obsolete.

A part's InitPart and InitPartFromStorage methods should now call their
parent's methods rather than the PersistentObject methods. The reason for this
is that the creation time, date and name stamps have been moved from pstobj.cpp
to part.cpp.

        InitPart(
          before DR3
            somSelf->InitPersistentObject(ev, storageUnit);
         after
            parent_InitPart(somSelf, ev, storageUnit, partWrapper);
        InitPartFromStorage(
         before DR3
            somSelf->InitPersistentObjectFromStorage(ev, storageUnit);
        after
            parent_InitPartFromStorage(somSelf, ev, storageUnit, partWrapper);

Parts can no longer assume that the partinfo property/value pair exist in the
storage unit provided in the ReadPartInfo and WritePartInfo calls.  See
Container Part for example code.

Parts must override the new ClonePartInfo method.  See Container Part for
example code.

Any reference counted object that is obtained with an AcquireXXX method has had
the reference count incremented by that method and the part is responsible for
releasing that object when done with it.

The following methods have been changed as follows:

ODBaseShape

    ODPolygon CopyPolygon();

to:

    void CopyPolygon(out ODPolygon copy);

ODTransform

    ODPoint TransformPoint(in ODPoint point);

to:

    void TransformPoint(inout ODPoint point);
    ODPoint InvertPoint(in ODPoint point);

to:

    void InvertPoint(inout ODPoint point);

ODFrame

    ODPoint GetContentExtent();

to:

    void GetContentExtent(out ODPoint contentExtent);

The following data types have been changed as follows:

ODPurgePriority

 kInvisibleBlocks to kODInvisibleBlocks
 kAllBlocks to kODAllBlocks
 kVisibleBlocks to kODVisibleBlocks

ODDraftPermissions

 kDPNone to kODDPNone
 kDPTransient to kODPTransient
 kDPReadOnly to kODPReadOnly
 kDPSharedWrite to kODPSharedWrite
 kDPExclusiveWrite to kODPExclusiveWrite

ODTranslateResult

 removed kODNative

Renamed DragReference to ODPlatformDragReference.

Changed type of ODEditor from string to ODISOStr.

Changed type of ODContainerSuite from char* to ODISOStr.

Added new method to ODMenuBar

  ODBoolean IsValid();

IText formats

 removed kODMACIText - use kODOS2IText instead
 removed related kODTraditionalMacText - use kODOS2PlainText instead


ΓòÉΓòÉΓòÉ 5.3.2.11. Template Code ΓòÉΓòÉΓòÉ

A change was made to the template code.  The part editor creating the part is
set as the preferred editor. This editor will always be used when the the
template is dragged into the docshell.  The preferred editor for the kind which
is set in the OpenDoc Preferences object is used only when when the part editor
that created the part is not available.


ΓòÉΓòÉΓòÉ 5.3.2.12. Public Utilities ΓòÉΓòÉΓòÉ

The following files are provided as public utilities for which we ship source
code in the Warp Toolkit.

  altpoint.h
  altpoly.h
  except.h
  focuslib.h
  lineops.h
  oddebug.h
  odutils.h
  altpoly.cpp
  altpoint.cpp
  except.cpp
  focuslib.cpp
  lineops.cpp
  oddebug.cpp
  odutils.cpp
  pubutils.mak   - builds pubutils.lib

These files are located in the \TOOLKIT\BETA\SAMPLES\OPENDOC\PUBUTILS
subdirectory.


ΓòÉΓòÉΓòÉ 5.3.2.13. Notes on Scripting Support in the Container Part ΓòÉΓòÉΓòÉ

The Container Part has been updated to enable scripting.  It has been updated
to support the SetData event for the background color.

 The following is a list of changes that were made.  Please refer to the source
code for the details.

     Initialization:

        -  Create an instance of the Semantic Interface

                               _fSemtIntf = new ODSemanticInterface();
                               _fSemtIntf->InitSemanticInterface(ev, somSelf, _fSession);

        -  Install Object Accessor and Event Handler

                               ODObjectAccessorUPP theAccessorUPP;
                               theAccessorUPP = NewODObjectAccessorProc( GetPropertyFromNULL );
                               _fSemtIntf->InstallObjectAccessor(ev, cProperty, typeNull, theAccessorUPP,
                                              (ODSLong)somSelf);
                               ODEventHandlerUPP newHandler;
                               newHandler = NewODEventHandlerProc( HandleSetData ) ;
                               _fSemtIntf->InstallEventHandler(ev, kAECoreSuite, kAESetData,
                                              newHandler,
                                              (ODSLong)somSelf);

     Accessing SemanticInterface extension:

        -  Update HasExtension method for semantic interface

                               ContainerPartHasExtension(...)
                               {
                                if (!strcmp(extensionName, kODExtSemanticInterface) )
                                  return kODTrue;
                                else
                                  return ContainerPart_parent_ODPart_HasExtension(...);
                               }

        -  Update AcquireExtension method for semantic interface

                               ContainerPartAcquireExtension(...)
                               {
                                                   ...
                                 if(!strcmp(extensionName, kODExtSemanticInterface) )
                                   return _fSemtIntf;
                                 else
                                   return ContainerPart_parent_ODPart_AcquireExtension(...);
                               }

     New routines to create object specifiers and send event to change color

                     ContainerPartHandleColorMenu(...)
                     {
                       AEDesc    objspec, color;
                       RGBColor  newColor;
                       ODError   err = noErr;
                       // Convert menu id to rgb color
                       newColor = RGBColorFromMenuColor(command);
                       // Create a desc for the color
                       AECreateDesc(typeInteger, &newColor, sizeof(RGBColor), &color) );
                       // create objspec
                       CreatePropObjSpec(somSelf, ev, frame, formUniqueID,
                                         pBackgroundColor, objspec);
                       // Send the SetData event to change background color to "color"
                       SendSetDataEvent(somSelf, ev, objspec, color);
                     }
                     CreatePropObjSpec(...)
                     {
                       AEDesc          nullDesc = {typeNull, kODNULL};
                       AEDesc          id, pr;
                       ODPersistentObjectID  foo;
                       ODDraft* draft = somSelf->GetStorageUnit(ev)->GetDraft(ev);
                       foo = draft->GetPersistentObjectID( ev, frame, kODFrameObject);
                       AECreateDesc(typeInteger, (Ptr) &foo, sizeof(foo), &id);
                       AECreateDesc(typeType, (Ptr) &prop, sizeof(prop), &pr);
                       // Create object specifier for this part
                       AECreateObjSpecifier(cPart, &nullDesc, form, &id, kODTrue, &objSpec);
                       // Create object specifier for background color
                       AECreateObjSpecifier(cProperty, &objSpec, formPropertyID, &pr,
                                            kODTrue, &objSpec);
                     }

                     SendSetDataEvent(...)
                     {
                       ODSession*           session = somSelf->GetStorageUnit(ev)->GetSession(ev);
                       ODMessageInterface*  msg = session->GetMessageInterface(ev);
                       ODOSAEvent*   event;
                       AEDesc         tempReply;
                       ODOSAEvent*   reply = new ODOSAEvent;
                       OSAEvent      tempEvent;
                       ODAddressDesc*  address;
                       // Create an address descriptor for this document
                       msg->CreatePartAddrDesc(ev, &address, somSelf);
                       // Create the OSA event
                       msg->CreateEvent(ev, kAECoreSuite, kAESetData, address,
                                        kAnyTransactionID, &event);
                       ODDeleteObject(address);
                       // Add parms to event
                       ODDescToAEDesc(event, &tempEvent);
                       AEPutParamDesc(&tempEvent, keyDirectObject, &objSpec);
                       AEPutParamDesc(&tempEvent, keyAEData, &data);
                       AEDescChanged(&tempEvent, event);
                       // Reply must have an AEDesc even though were not using it
                       AEDescToODDesc(&tempReply, (ODDesc *) reply);
                       // Send the event
                       msg->Send(ev, somSelf, event, reply, kAENoReply,
                                 kAENormalPriority, kAEDefaultTimeout);
                     }

     Create ObjectAccessor routine to create a token for the background color

                     GetPropertyFromNULL(...)
                     {
                          ...
                      switch(propID)
                      {
                        case pBackgroundColor:
                        {
                         // create an instance of Container property accessor object to
                         // do the work
                         accessorObj = new ContainerPropAccessor(propID, (ContainerPart *)refCon);
                         // create a desc for the object pointer
                         AECreateDesc(cProperty, &accessorObj, sizeof(accessorObj), &tokenDesc);
                         // add desc to token
                         resolver->SetUserToken(ev, value, userODDesc);
                        }
                          ...
                     }

     Create an event handler routine for SetData

                     HandleSetData(...)
                     {
                                     ...
                       GetDirectParam( session, &realMessage, &evtDp);
                                     ...
                       resolver->GetUserToken(ev, tmpWrapper, &myTokenODDesc);
                       AEDesc theToken;
                       error = ODDescToAEDesc(myTokenODDesc, &theToken );
                       if (error == noErr)
                       {
                         switch (theToken.descriptorType)
                         {
                             case typeProperty:
                             {
                               DescType typeCode;
                               ContainerPropAccessor* embedPropAccessorObj;
                               Size     dataSize = sizeof(embedPropAccessorObj);
                               // get prop accessor obj ptr
                               AEGetDescData(&theToken, &typeCode, (Ptr) &embedPropAccessorObj,
                                             (Size)sizeof(embedPropAccessorObj), &dataSize);
                               // use prop accessor obj to set the data
                               embedPropAccessorObj->SetData(&theData);
                               delete embedPropAccessorObj;
                             }
                             break;
                         }
                       }
                                     ...
                     }


ΓòÉΓòÉΓòÉ 5.4. Sample Additions ΓòÉΓòÉΓòÉ

New samples have been added in several different areas of the Warp Toolkit to
assist you in your programming efforts.

     Entertainment Video Samples

        -  Beehive

     IBM Developer API Extensions for OS/2 Samples

        -  Browser

     OpenDoc Samples

        -  Cookbook
        -  Hello World
        -  Push Button
        -  Ticker Tape 1
        -  Ticker Tape 2

     SOM REXX Sample

        -  Animal SOM Class

     WPS REXX Samples

        -  Workplace Shell Class
        -  Workplace Shell Folder

     REXX Samples

        -  Complex Number
        -  Concurrency
        -  Directives
        -  Display Month Array
        -  Factorial
        -  Guard and Reply
        -  Pipe
        -  Query Date
        -  Query Time
        -  Semaphore Class
        -  Stack
        -  Start and Guard


ΓòÉΓòÉΓòÉ 5.5. Tool Updates ΓòÉΓòÉΓòÉ

This release of the Warp Toolkit contains the following tool updates:

     Resource Compiler Enhancements


ΓòÉΓòÉΓòÉ 5.5.1. Resource Compiler Enhancements ΓòÉΓòÉΓòÉ

As an enhancement for the IBM Developer API Extensions for OS/2, the OS/2
Resource Compiler (RC) now supports string IDs for resources in addition to
numbers. You can use either SMART or the Resource Compiler to convert
resources. If you use the Resource Compiler, you do not need to include the hhh
file with your code. OS/2 supports string IDs with double quotes. See the
discussion of the RESOURCE statement in the IBM Developer API Extensions for
OS/2 Programming Guide for more information.


ΓòÉΓòÉΓòÉ 6. Toolkit Contents ΓòÉΓòÉΓòÉ

This section represents the main body of the Warp Toolkit. It contains the
following topics:

     Toolkit Roadmap -- provides a "roadmap" of the Warp Toolkit presented as
      a directory hierarchy and a folder hierarchy.

     Header files -- describes special programming considerations for Control
      Program, Multimedia, OS/2, and Workplace Shell header files.

     Sample programs -- provides descriptions of the OS/2, BIDI, REXX, IBM
      Developer API Extensions for OS/2, Presentation Manager, Multimedia,
      OpenDoc, and Workplace Shell code samples that are included in the Warp
      Toolkit.

     Tools -- provides descriptions of the Presentation Manager, Multimedia,
      OpenDoc, SOM, and Workplace Shell tools. It also introduces you to the
      interface that installs the debug kernel, symbol files, and debug version
      of PM, OpenDoc, and Workplace Shell and describes tools that support your
      debugging efforts.

     Online documentation -- describes the online books of the Warp Toolkit.

     Try Me! -- New samples and tools provided on an "as is" basis for
      evaluation and demonstration.

     BETA -- Beta version of entertainment samples, tools, and online
      documentation.


ΓòÉΓòÉΓòÉ 6.1. Toolkit Roadmap ΓòÉΓòÉΓòÉ

The tools, samples, and technical documentation in the Warp Toolkit are
available in two ways.  You can access them through the Toolkit folder and its
subfolders on the Desktop, or you can access them using an OS/2 window or OS/2
full-screen session and changing into the \TOOLKIT subdirectory and its
subdirectories.


ΓòÉΓòÉΓòÉ 6.1.1. Directory Hierarchy ΓòÉΓòÉΓòÉ

The Warp Toolkit package has the following directory structure:

  \TOOLKIT        - Root subdirectory for the Toolkit.
    Γöé
    Γö£ΓöÇ\BETA       - Beta version of new samples, tools (EXE), and online books
    Γö£ΓöÇ\BIN        - Programming tools
    Γö£ΓöÇ\BITMAP     - Sample multimedia bit maps
    Γö£ΓöÇ\BOOK       - Online technical information
    Γö£ΓöÇ\DLL        - Toolkit dynamic link library (DLL) files
    Γö£ΓöÇ\H          - C, C++, and DTS header files
    Γö£ΓöÇ\HELP       - Toolkit help (HLP) files
    Γö£ΓöÇ\ICON       - Toolkit icon (ICO) files
    Γö£ΓöÇ\IDL        - Workplace Shell interface definition language (IDL) files
    Γö£ΓöÇ\INC        - Assembler header (INC) files
    Γö£ΓöÇ\IPFC       - Information Presentation Facility Compiler (IPFC) files
    Γö£ΓöÇ\LIB        - Import library (LIB) files
    Γö£ΓöÇ\SAMPLES    - Contains common information for all
    Γöé               samples, as well as SAMPLES.DOC
    ΓööΓöÇ\SOM        - SOM subdirectories

Note:  If you have not installed the Warp Toolkit on your system and you are
       reading from The Developer Connection for OS/2 CD, the \TOOLKIT
       subdirectory is located in the \DEVTOOLS\WARPTLKT directory.


ΓòÉΓòÉΓòÉ 6.1.2. Folder Hierarchy ΓòÉΓòÉΓòÉ

The Warp Toolkit package has the following Workplace Shell folder hierarchy:

 IBM Developer's Toolkit                - Root folder of the Toolkit.
 for OS/2 Warp                            Contains the README file and the
  Γöé                                       other Toolkit folders
  Γöé
  Γö£ΓöÇDevelopment Tools                   - Programming tools
  Γö£ΓöÇMultimedia Bitmaps                  - Sample multimedia bit maps
  Γö£ΓöÇDeveloper API Extensions Samples    - IBM Developer API Extensions for
  Γöé                                       OS/2 samples
  Γö£ΓöÇMultimedia Sample Programs          - Multimedia sample programs
  Γö£ΓöÇOS/2 Sample Programs                - Control Program sample programs
  Γö£ΓöÇPM Sample Programs                  - Presentation Manager (PM) sample programs
  Γö£ΓöÇREXX Sample Programs                - REXX sample programs
  Γö£ΓöÇToolkit Information                 - Online technical books
  Γö£ΓöÇWorkplace Shell Sample Programs     - Workplace Shell (WPS) sample programs
  Γö£ΓöÇTry Me!                             - New samples and tools provided on an
  Γöé                                       "as is" basis for evaluation and demonstration
  ΓööΓöÇBETA                                - Beta version of books, samples, and tools
     Γö£ΓöÇBRender                          - BRender components
     Γöé  ΓööΓöÇBRender Samples               - BRender samples
     Γö£ΓöÇBeta Entertainment Samples       - Entertainment samples
     Γöé  Γö£ΓöÇAudio Samples                 - Audio samples
     Γöé  Γö£ΓöÇInput Samples                 - Input samples
     Γöé  Γö£ΓöÇNetwork Samples               - Network samples
     Γöé  ΓööΓöÇVideo Samples                 - Video samples
     ΓööΓöÇBeta Toolkit Information         - Online technical books


ΓòÉΓòÉΓòÉ 6.2. Header Files ΓòÉΓòÉΓòÉ

You should be aware of special programming considerations in the following sets
of header files:

     Control Program
     Multimedia
     OS/2
     Workplace Shell

 Note:  For compatibility with the VisualAge C++, the #pragma checkout
        directives in all header files have been changed to #pragma info. The
        #pragma checkout directive is no longer supported by C Set ++.  Because
        the #pragma info directive provides similar function to #pragma
        checkout, the header file changes should not affect code that uses the
        header files. If you use the #pragma checkout directive with VisualAge
        C++, it generates an "unsupported pragma" error for both C and C++
        compilers. Refer to the VisualAge C++ Language Reference for more
        details.


ΓòÉΓòÉΓòÉ 6.2.1. Control Program Header Files ΓòÉΓòÉΓòÉ

DosSetDOSProperty() and DosQueryDOSProperty() in BSEDOS.H are not supported. Do
not use these functions.


ΓòÉΓòÉΓòÉ 6.2.2. Multimedia Header Files ΓòÉΓòÉΓòÉ

The multimedia header files listed below are delivered in two different
versions. One version uses conventions compatible with the standard OS/2
header-file format. The other version uses conventions compatible with
Microsoft Windows header files. The Windows-style headers are currently shipped
for compatibility with earlier multimedia applications, but will be removed
from the Toolkit in the future.

New applications should use the OS/2-style header files. Applications that use
the Windows-style headers will need to modify their source code when moving to
the new headers.

 Windows-Style       OS/2-Style
 CDAUDIO.H           CDAUDOS2.H
 MCIDRV.H            MMDRVOS2.H
 MIDI.H              MIDIOS2.H
 MMIO.H              MMIOOS2.H
 MMSYSTEM.H          MCIOS2.H

 Note:  There is a known problem with the AUDIO.H header file when compiling
        for C++. The typedef for the audio_update structure must be changed:

 from:

    typedef struct audio_update FAR *UPDATE;

 to:

    typedef audio_update FAR *UPDATE;


ΓòÉΓòÉΓòÉ 6.2.3. OS/2 Header Files ΓòÉΓòÉΓòÉ

Instead of using the SELECTOROF macro in the OS2DEF.H header file, use one of
the following two macros to obtain the selector of a 16:16 address:

  #define SELECTOROF(p)   (((PUSHORT)&(p))[1])
  OR
  #define SELECTOROF(p)   ((ULONG)(p)>>16)

If you use the selector returned from one of the above macros with the OFFSETOF
and MAKEP macros in the OS2DEF.H header file, you can successfully convert a
16:16 address to a 0:32 address.


ΓòÉΓòÉΓòÉ 6.2.4. Workplace Shell Header Files ΓòÉΓòÉΓòÉ

The following #defines are needed by wpQueryNameClashOptions but are not in the
Workplace Shell header files:

  #define NO_NAMECLASH_RENAME   0x10
  #define NO_NAMECLASH_APPEND   0x20
  #define NO_NAMECLASH_REPLACE  0x40
  #define NO_NAMECLASH_DIALOG   0x80

You should define them when using wpQueryNameClashOptions.


ΓòÉΓòÉΓòÉ 6.3. Sample Programs ΓòÉΓòÉΓòÉ

This section describes the sample programs available with the Warp Toolkit.

The sample programs are categorized as follows:

     BIDI (Bidirectional)
     DAPIE (IBM Developer API Extensions for OS/2)
     Multimedia
     OpenDoc
     OS/2
     Presentation Manager
     REXX
     Workplace Shell

 Most sample programs are written in C language and demonstrate the use of the
 functions of the control program (CP, base OS/2 operating system), the PM
 interface, the multimedia (MM) interface, and the Workplace Shell (WPS).

 Each sample program serves as a template that can be easily modified for your
 own purposes. These programs let you investigate the best way to implement
 your own application requirements.

 Some of the sample programs require specific hardware devices. When
 appropriate, the hardware is listed following the program descriptions.
 Without these devices, you can still compile and run the sample programs;
 however, you might not receive the full effect of the program. For example, if
 a multimedia sample program has audio, you will not hear it unless you have an
 audio adapter supported by OS/2 multimedia and speakers installed.

 Most samples also contain the overhead routines necessary to create a PM
 application, as well as stubs for the basic menu items that all applications
 should have.

 There are many comments within the source code that clarify technical
 information.

 Note:  Names of the sample programs, in most cases, correspond to their
        Toolkit subdirectory names.


ΓòÉΓòÉΓòÉ 6.3.1. Starting Sample Programs ΓòÉΓòÉΓòÉ

There are two ways to start a sample program:

     From the Desktop:

      When installed, all sample programs (with the exception of the
      bidirectional samples, some of the Multimedia samples, and some of the
      Workplace Shell samples) appear in the sample programs folders located
      within the Toolkit folder. To start a sample program, open the Toolkit
      folder, open the folder representing the type of samples you wish to
      execute, then select the appropriate sample program.

     From an OS/2 command prompt:

      Change to the subdirectory where the sample is located, type the name of
      the executable file and press Enter.

 Most samples include a description file (or makefile) you can use to build the
 sample yourself. The name of the makefile is either MAKEFILE or filename.MAK,
 where filename refers to the name of the sample. To build the sample,

   1. Go to an OS/2 command prompt and change to the subdirectory where the
      makefile is located.

      You must execute these commands from the subdirectory where the makefile
      is located in order to build the sample correctly.

   2. Enter one of the following, depending on the name of the makefile:

          When the name of the makefile is MAKEFILE, type:

                        NMAKE

          When the name of the makefile is filename.MAK, type:

                        NMAKE /f filename.MAK

 For information about the NMAKE tool, refer to the OS/2 Tools Reference.

 Note:  The makefile assumes that the IBM C Set ++ compiler is used for code
        compilation.


ΓòÉΓòÉΓòÉ 6.3.2. BIDI Sample Programs ΓòÉΓòÉΓòÉ

These samples demonstrate the use of the Bidirectional Language support
available in the Arabic and Hebrew versions of OS/2. There are two sets of
samples provided: one set for the Arabic language and the other set for the
Hebrew language. For both languages, there are two samples:

     STYLE
     TELDIR

 Note:  Programs that use the bidirectional support functions will run only on
        the Arabic and Hebrew versions of the OS/2 operating system, which are
        currently the only versions of the operating system that support these
        features.


ΓòÉΓòÉΓòÉ 6.3.2.1. STYLE Sample Program ΓòÉΓòÉΓòÉ

STYLE is a sample program that demonstrates the bidirectional language support
features of PM controls and other system components.

Note:  The Arabic versions of this sample (located in
       \TOOLKIT\SAMPLES\BIDI\ARABIC), require the Arabic version of OS/2 to
       run, and the Hebrew versions of this sample (located in
       \TOOLKIT\SAMPLES\BIDI\HEBREW), require the Hebrew version of OS/2 to
       run.


ΓòÉΓòÉΓòÉ 6.3.2.2. TELDIR Sample Program ΓòÉΓòÉΓòÉ

TELDIR is a simple bilingual telephone directory application that demonstrates
how language and orientation selections can be set dynamically by a
"BIDI-aware" application.

Note:  The Arabic versions of this sample require the Arabic version of OS/2 to
       run, and the Hebrew versions of this sample require the Hebrew version
       of OS/2 to run.


ΓòÉΓòÉΓòÉ 6.3.3. Device Driver Sample Programs ΓòÉΓòÉΓòÉ

Physical device driver (PDD) and virtual device driver (VDD) samples are not
included in the IBM Developer's Toolkit for OS/2 Warp. See the Developer
Connection Device Driver Kit (DDK) for device driver samples.


ΓòÉΓòÉΓòÉ 6.3.4. IBM Developer API Extensions for OS/2 Samples ΓòÉΓòÉΓòÉ

The following samples are included supporting the IBM Developer API Extensions
for OS/2:

     Browser
     HiWorld
     ToyBox
     WinMain Wrapper Function (MAIN.C)
     DLL Initialization Entry Point (DLLMAIN.C)


ΓòÉΓòÉΓòÉ 6.3.4.1. Browser ΓòÉΓòÉΓòÉ

The Browser sample allows you to view the lines of text files in a Multiple
Document Interface (MDI) environment. The sample provides files containing the
program source code. You may open one or more of them, scroll them, change
their display fonts, and arrange their windows or icons inside the sample
program window.

There are two versions of the Browser sample. The Win32 version, located in the
\TOOLKIT\SAMPLES\DAPIE\BROWSER subdirectory, will build without source changes
on a Win32 system with the appropriate development tools. (Win32 tools are not
provided with the Warp Toolkit.)

The OS/2 version of Browser is located in the \TOOLKIT\SAMPLES\DAPIE\BROWSER2
subdirectory.

The Browser sample, like all the other IBM Developer API Extensions for OS/2
samples in the Warp Toolkit, should be compiled with IBM C Set ++.  The sample
will not compile with the VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 6.3.4.2. DLL Initialization Entry Point ΓòÉΓòÉΓòÉ

The DLLMAIN.C file (located in the \TOOLKIT\SAMPLES\DAPIE\DLLENTRY
subdirectory) contains the DLL initialization/termination function, which is
called when a process gains or loses access to the DLL. The .DEF file used to
build the DLL needs to specify INITINSTANCE and TERMINSTANCE; otherwise, this
function will only be called for the first process to gain access and the last
process to free up the DLL.

This implementation is for IBM C Set ++ and assumes that the C runtime library
is being statically linked to the DLL and that the library uses C++ classes.


ΓòÉΓòÉΓòÉ 6.3.4.3. HiWorld ΓòÉΓòÉΓòÉ

HiWorld is a simple Windows 32-bit (Win32) application that displays the
following text, centered in the client area of the main window:

Hello, World

There are two versions of the HiWorld sample. The Win32 version, located in the
\TOOLKIT\SAMPLES\DAPIE\HIWORLD subdirectory, will build without source changes
on a Win32 system with the appropriate development tools. (Win32 tools are not
provided with the Warp Toolkit.)

The OS/2 version of HiWorld is located in the \TOOLKIT\SAMPLES\DAPIE\HIWORLD2
subdirectory along with a README that briefly describes the steps that were
taken to convert the Win32 version of HiWorld to this native OS/2 executable.

The HiWorld sample, like all the other IBM Developer API Extensions for OS/2
samples in the Warp Toolkit, should be compiled with IBM C Set ++.  The sample
will not compile with the VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 6.3.4.4. ToyBox ΓòÉΓòÉΓòÉ

ToyBox is a basic Win32 application that uses bit-block transfer (BitBlt) to
display a large number of simple bit maps on the display screen and give them
motion. It moves the objects around the client portion of the screen and makes
the objects appear to change shape and rotate.

There are two versions of the ToyBox sample. The Win32 version, located in the
\TOOLKIT\SAMPLES\DAPIE\TOYBOX subdirectory, will build without source changes
on a Win32 system with the appropriate development tools. (Win32 tools are not
provided with the Warp Toolkit.)

The OS/2 version of ToyBox is located in the \TOOLKIT\SAMPLES\DAPIE\TOYBOX2
subdirectory.

The ToxBox sample, like all the other IBM Developer API Extensions for OS/2
samples in the Warp Toolkit, should be compiled with IBM C Set ++.  The sample
will not compile with the VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 6.3.4.5. WinMain Wrapper Function ΓòÉΓòÉΓòÉ

The MAIN.C file (located in the \TOOLKIT\SAMPLES\DAPIE\WINMAIN subdirectory) is
provided as a helper (stub) to demonstrate how to invoke the Windows WinMain
function from OS/2.

This is the "main" wrapper for an application based on the IBM Developer API
Extensions for OS/2. It initializes the Alternative Windows Emulator (AWE)
environment, calls the WinMain function, and upon completion, calls the WinTerm
function to shut down the AWE environment.

Note:  To be able to use the Windows WinMain() function, use the OS/2 Warp
       main() function located in the MAIN.C file. MAIN.C gets compiled and
       linked with the module containing WinMain() and creates an OS/2 Warp
       executable. If you do not use the OS/2 Warp main() function, you will
       receive a link error stating that there is no starting address for your
       program.


ΓòÉΓòÉΓòÉ 6.3.5. Multimedia Sample Programs ΓòÉΓòÉΓòÉ

The Multimedia sample programs are as follows:

     ADMCT
     ASYMREC
     AVCINST
     CAPSAMP
     CAPTION
     CASECONV
     CDMCIDRV
     Control File Templates
     CLOCK
     CODEC
     DIVE
     DOUBPLAY
     DUET1
     DUET2
     FSSHT
     MCD Command Tables
     MCDTEMP
     MCISPY
     MCISTRNG
     MMBROWSE
     MMOTTK
     MOVIE
     RECORDER
     Short Control File Templates
     SHRC
     TUNER
     ULTIEYES
     ULIOT


ΓòÉΓòÉΓòÉ 6.3.5.1. ADMCT Sample Program ΓòÉΓòÉΓòÉ

ADMCT (located in \TOOLKIT\SAMPLES\MM\ADMCT), is an example of a media control
driver (MCD) that demonstrates how to control a streaming device. Streaming
devices use the services of the sync/stream manager (SSM) of OS/2 multimedia to
control the data stream from a source location to a target location.


ΓòÉΓòÉΓòÉ 6.3.5.2. ASYMREC Sample Program ΓòÉΓòÉΓòÉ

ASYMREC (located in \TOOLKIT\SAMPLES\MM\ASYMREC), illustrates how to include
asymmetric recording function in your multimedia application. Modules include
source code extracted from the Video IN recorder application, which enables
frame-step recording using Ultimotion compression techniques.


ΓòÉΓòÉΓòÉ 6.3.5.3. AVCINST I/O Procedure Sample ΓòÉΓòÉΓòÉ

AVCINST (located in \TOOLKIT\SAMPLES\MM\AVCINST), illustrates how an
application can install and remove an I/O procedure to use multimedia
input/output (MMIO) file services. The AVC I/O procedure installation sample is
a simple PM application that allows you to install or de-install the audio AVC
I/O procedure, AVCAPROC.DLL.

Hardware requirements:

     Computer capable of running OS/2 Warp

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.4. CAPSAMP Sample Program ΓòÉΓòÉΓòÉ

CAPSAMP (located in \TOOLKIT\SAMPLES\MM\CAPSAMP), and the caption utility
functions (located in \TOOLKIT\SAMPLES\MM\CAPDLL) are part of the sample
captioning system provided with the Warp Toolkit. CAPSAMP demonstrates how
captioning can be integrated into applications using caption files in
conjunction with the caption utility functions.

Hardware requirements:

     Computer capable of running OS/2 Warp
     Speaker or headphones
     Sound card

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.5. CAPTION Sample Program ΓòÉΓòÉΓòÉ

CAPTION (located in \TOOLKIT\SAMPLES\MM\CAPTION), is part of the sample
captioning system provided with the Warp Toolkit. The caption creation utility
program creates a "caption" file. It enables a user to synchronize an audio
file with a text file.

This concept can be extended beyond audio and text to apply to many
possibilities, such as synchronizing audio and video, or synchronizing video
and text.

Note:  In order for the Caption sample to work correctly, captioning must be
       enabled in the operating system. To enable captioning proceed as
       follows:

        -  Open the Multimedia Setup object in the Multimedia folder
        -  Go to the System page
        -  Indicate a checkmark in the Captioning check box.


ΓòÉΓòÉΓòÉ 6.3.5.6. CASECONV I/O Procedure Sample ΓòÉΓòÉΓòÉ

CASECONV (located in \TOOLKIT\SAMPLES\MM\CASECONV), provides a simple example
of how to write a file format I/O procedure (without illustrating the use of
data translation). This sample performs case conversion of text.


ΓòÉΓòÉΓòÉ 6.3.5.7. CDMCT Sample Program ΓòÉΓòÉΓòÉ

CDMCT (located in \TOOLKIT\SAMPLES\MM\CDMCIDRV), is an example of a media
control driver (MCD) that demonstrates how to control a non-streaming device.
Non-streaming devices stream data within the device.


ΓòÉΓòÉΓòÉ 6.3.5.8. Control File Templates ΓòÉΓòÉΓòÉ

The \TOOLKIT\SAMPLES\MM\CF subdirectory contains control file templates you can
utilize when installing a program using MINSTALL.


ΓòÉΓòÉΓòÉ 6.3.5.9. CLOCK Sample Program ΓòÉΓòÉΓòÉ

CLOCK (located in \TOOLKIT\SAMPLES\MM\CLOCK), illustrates the use of the memory
playlist feature of OS/2 multimedia. The memory playlist feature provides for
easy manipulation of multimedia in memory to create unique effects based on
user input or other dynamic events.

Hardware requirements:

     Computer capable of running OS/2 Warp
     Speaker or headphones
     Sound card

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.10. CODEC Sample Program ΓòÉΓòÉΓòÉ

CODEC (located in \TOOLKIT\SAMPLES\MM\CODEC), illustrates how to write a CODEC
procedure to include compression and decompression routines in your multimedia
applications. A CODEC procedure operates on data within a file or buffer.


ΓòÉΓòÉΓòÉ 6.3.5.11. DIVE Sample Program ΓòÉΓòÉΓòÉ

DIVE (located in \TOOLKIT\SAMPLES\MM\DIVE), illustrates the use of the direct
interface video extensions. DIVE provides optimized blitting performance for
motion video subsystems and applications that perform rapid screen updates in
the OS/2 PM and full-screen environments. Using DIVE interfaces, applications
can either write directly to video memory or use the DIVE blitter. The DIVE
blitter will take advantage of acceleration hardware when present and
applicable to the function being performed.

Note:  The DIVE sample requires OS/2 Warp Version 3 in order to execute
       properly. The files for the samples will be installed when the samples
       are selected, but Workplace Shell objects will not be created for them
       if the installed operating system is not OS/2 Warp Version 3.

The OS/2 Warp color support defaults to 16 colors. This means that your setup
needs to be updated, otherwise the DIVE sample will not run.

The maximum window size of this sample has been limited to 640x480 because
larger window sizes may cause excessive swapping on machines with less than
16MB.

The DIVE sample that comes with this release of The Developer Connection for
OS/2 will not work with the original DIVE.DLL file. For this release of the
Warp Toolkit, an updated .DLL file is shipped with the sample. A .DLL file with
equivalent function will be included in a future version of OS/2 Warp.

 Hardware requirements:

     Computer capable of running OS/2 Warp
     SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system)

 Software requirements:

     OS/2 Warp
     Multimedia support
     Software motion video


ΓòÉΓòÉΓòÉ 6.3.5.12. DOUBPLAY Sample Program ΓòÉΓòÉΓòÉ

DOUBPLAY (located in \TOOLKIT\SAMPLES\MM\DOUBPLAY), allows an application to
play audio files directly from application memory buffers. An array of multiple
playlist structures can be constructed that combines playlist commands with
data buffers to perform complex operations on multiple buffers.

This sample takes a single wave file, MYWAVE.WAV, and plays it using a memory
playlist. The playlist is constructed as a circular buffer composed of a series
of small buffers, the sum of which may or may not be larger than the size of
the .WAV file. This circular buffer is used to repeatedly play an audio file
when the PLAY button is selected. As each buffer in the playlist is expended,
the application refills the expended buffer with new data from the .WAV file.
When all the buffers in the playlist have been expended, the playlist branches
back to the first buffer to play the new data. This circular buffering process
continues until the STOP button is selected or the application is closed.

Hardware requirements:

     Computer capable of running OS/2 Warp
     Speakers or headphones
     Sound card

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.13. DUET1 Sample Program ΓòÉΓòÉΓòÉ

DUET1 (located in \TOOLKIT\SAMPLES\MM\DUET1), illustrates the OS/2 multimedia
concept of device grouping and integrating multimedia into an application's
help information. This sample demonstrates the concepts of grouping two
streaming devices.

Note:  The Streaming Device Duet sample (DUET1, located in
       \TOOLKIT\SAMPLES\MM\DUET1) requires that the IBM M-Audio Capture and
       Playback Adapter card be installed in order for the sample to execute
       properly.

 Hardware requirements:

     Computer capable of running OS/2 Warp
     Speaker or headphones
     Sound card (capable of playing two mono wave files simultaneously such as
      the IBM M-AUDIO card)

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.14. DUET2 Sample Program ΓòÉΓòÉΓòÉ

DUET2 (located in \TOOLKIT\SAMPLES\MM\DUET2), illustrates the OS/2 multimedia
concept of device grouping and integrating multimedia into an application's
help information. This sample demonstrates how one of the devices in the
multimedia device group can be a non-streaming device.

Hardware requirements:

     Computer capable of running OS/2 Warp
     Speaker or headphones
     Sound card
     CD ROM

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.15. FSSHT Sample Program ΓòÉΓòÉΓòÉ

FSSHT (located in \TOOLKIT\SAMPLES\MM\FSSHT), contains a sample file system
stream handler.


ΓòÉΓòÉΓòÉ 6.3.5.16. MCD Command Tables ΓòÉΓòÉΓòÉ

Before a media control driver (MCD) can interpret a string command, the media
device manager (MDM) must use a command table to change the string into an
equivalent procedural command. Represented as resources to the driver, command
tables are created using the RCDATA type of resource. The resource number of
the RCDATA block is the device type number. The \TOOLKIT\SAMPLES\MM\MCDTBL
subdirectory contains command tables for each of the following devices:

     Amp Mixer
     CD-ROM/XA
     CD Audio
     Digital Video
     Sequencer
     Videodisc
     Wave Audio

 If you want to support device-specific messages, you must create a device-
 specific command table.


ΓòÉΓòÉΓòÉ 6.3.5.17. MCDTEMP Template ΓòÉΓòÉΓòÉ

MCDTEMP (located in \TOOLKIT\SAMPLES\MM\MCDTEMP), provides a basic template to
write a media control driver (MCD). Refer to the \ADMCT and \CDMCIDRV
subdirectories for specific streaming or to the multimedia I/O (MMIO) samples.


ΓòÉΓòÉΓòÉ 6.3.5.18. MCISPY Sample Program ΓòÉΓòÉΓòÉ

MCISPY (located in \TOOLKIT\SAMPLES\MM\MCISPY), monitors media control
interface messages that are exchanged between applications and the OS/2
multimedia subsystem.

In addition to teaching you about multimedia messages, MCISPY also serves as a
powerful debugging aid.

The MCISpy sample must be manually set up. To do so, follow these steps:

   1. Copy the MDM.DLL file located in the \MMOS2\DLL subdirectory to the
      \TOOLKIT\DLL subdirectory.

   2. Use the DLLRNAME tool from C Set ++ for OS/2 to rename the copy to
      MCI.DLL (type DLLRNAME MDM.DLL MDM=MCI).

   3. Place the stub MDM.DLL provided with the Warp Toolkit in the LIBPATH so
      that it is recognized prior to the MDM.DLL file located in the \MMOS2\DLL
      subdirectory. The source code for the stub MDM.DLL is included in the
      MCISpy sample.

   4. Restart your system.

 Note:  Driver notifications may not be visible in releases prior to OS/2 Warp,
        Version 3. These notifications include all multimedia messages routed
        through mdmDriverNotify().

 Hardware requirements:

     Computer capable of running OS/2 Warp

 Software requirements:

     Multimedia support
     OS/2 Warp

      Note:  The files for the samples will be installed when the samples are
             selected, but Workplace Shell objects will not be created for them
             if the installed operating system is not OS/2 Warp Version 3.


ΓòÉΓòÉΓòÉ 6.3.5.19. MCISTRNG Sample Program ΓòÉΓòÉΓòÉ

MCISTRNG (located in \TOOLKIT\SAMPLES\MM\MCISTRNG), serves as a powerful
testing and debugging tool that enables developers writing media drivers to
control their devices at the application level. The string test sample
illustrates how an application uses the interpretive string interface provided
by the media control interface.

This sample also illustrates how notification messages are returned from the
media drivers to the application.

Hardware requirements:

     Computer capable of running OS/2 Warp

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.20. MMBROWSE Sample Program ΓòÉΓòÉΓòÉ

MMBROWSE (located in \TOOLKIT\SAMPLES\MM\MMBROWSE), illustrates how to use the
multimedia I/O (MMIO) subsystem to install I/O procedures for various image
formats and then convert these image formats to OS/2 bit maps.

Hardware requirements:

     Computer capable of running OS/2 Warp

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.21. MMOTTK I/O Procedure Sample ΓòÉΓòÉΓòÉ

MMOTTK (located in \TOOLKIT\SAMPLES\MM\MMIOPROC), provides an example of how to
write an I/O procedure for use with image file formats. This sample enables
file format transparency for M-Motion still video files and illustrates the use
of data translation.


ΓòÉΓòÉΓòÉ 6.3.5.22. MOVIE Sample Program ΓòÉΓòÉΓòÉ

MOVIE (located in \TOOLKIT\SAMPLES\MM\MOVIE), demonstrates device control of a
software motion video device.

This sample also illustrates how to cut, copy, paste, and delete movie data
from an application.

A movie can be played in an application-defined window or in the system default
window provided by the software motion video subsystem.

Note:  If you installed the Warp Toolkit from diskette, the Movie sample
       (located in \TOOLKIT\SAMPLES\MM\MOVIE) does not contain the MOVIE.AVI
       file necessary to execute the application. Copy any .AVI file from the
       \MMOS2\MOVIES subdirectory on the drive you have Multimedia installed.
       The .AVI file should be copied to the \TOOLKIT\SAMPLES\MM\MOVIE
       subdirectory on which you have the Warp Toolkit samples installed, and
       the target name of the file should be MOVIE.AVI.

 Hardware requirements:

     Computer capable of running OS/2 Warp
     Speakers or headphones
     Sound card
     SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system)

 Software requirements:

     OS/2 Warp
     Multimedia support
     Software motion video


ΓòÉΓòÉΓòÉ 6.3.5.23. RECORDER Sample Program ΓòÉΓòÉΓòÉ

RECORDER (located in \TOOLKIT\SAMPLES\MM\RECORDER), illustrates the concept of
recording audio through the media control interface and how to query a device
to find out the recording capabilities.

This sample also illustrates how to change the audio recording and audio device
properties, such as bits per sample, samples per second, input level, and input
source.

Hardware requirements:

     Computer capable of running OS/2 Warp
     Speaker or headphones
     Sound card

 Software requirements:

     OS/2 Warp
     Multimedia support


ΓòÉΓòÉΓòÉ 6.3.5.24. Short Control File Templates ΓòÉΓòÉΓòÉ

The \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory contains a simple example of
control file templates you can use when installing a program using MINSTALL.


ΓòÉΓòÉΓòÉ 6.3.5.25. SHRC Sample Program ΓòÉΓòÉΓòÉ

SHRC (located in \TOOLKIT\SAMPLES\MM\SHRC), provides a sample stream handler
resource file.


ΓòÉΓòÉΓòÉ 6.3.5.26. TUNER Sample Program ΓòÉΓòÉΓòÉ

TV tuner cards allow a desktop PC to receive and display broadcasted television
signals. TUNER (located in \TOOLKIT\SAMPLES\MM\TUNER), provides an example of
how to use the MCI string interface to control a tuner card.

Once the application is running, the display window can be sized and a TV
channel can be selected. The channel can be selected through up/down buttons or
a text entry field displayed both at the bottom of the window.

Hardware requirements:

     Computer capable of running OS/2 Warp
     TV tuner card (such as the WinTV Basic)

 Software requirements:

     OS/2 Warp
     Multimedia support
     Appropriate drivers for installed tuner card

 A TV tuner card is handled as a digital video device by the multimedia
 subsystem. A typical system has one or more digital video devices, with
 digital video 1 assigned to software motion video. By default this sample
 opens the digital video 2 device. If the tuner card is not assigned to digital
 video 2 an alternate device ordinal must be provided at the command line with
 the following format:

    /d=digitalvideoxx

 where:

 xx        Is a two digit number, padded on the left with zero.

 For example:

    /d=digitalvideo03

 Most TV tuner cards, such as the Hauppauge WinTV card, support several video
 sources. The connector number that corresponds to the tuner video source is
 dependent on the hardware and may not be the same for each tuner card. The
 connector number is not changed by this sample. Instead, it uses the default
 connector number that is set by the Multimedia Setup program.


ΓòÉΓòÉΓòÉ 6.3.5.27. ULTIEYES Sample Program ΓòÉΓòÉΓòÉ

ULTIEYES (located in \TOOLKIT\SAMPLES\MM\ULTIEYES), demonstrates the use of
non-linear video by displaying segments from a movie clip in response to input
from the mouse.

Hardware requirements:

     SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system)

 Software requirements:

     Multimedia support
     Software motion video
     OS/2 Warp

      Note:  The files for the samples will be installed when the samples are
             selected, but Workplace Shell objects will not be created for them
             if the installed operating system is not OS/2 Warp Version 3.


ΓòÉΓòÉΓòÉ 6.3.5.28. ULIOT I/O Procedure Sample ΓòÉΓòÉΓòÉ

ULIOT (located in \TOOLKIT\SAMPLES\MM\ULTIMOIO), provides a detailed example of
what you need to consider when writing I/O procedures for software motion video
file formats. This sample program includes CODEC support and illustrates how to
integrate common and file-format-specific code to support multiple I/O
procedures.


ΓòÉΓòÉΓòÉ 6.3.6. OpenDoc Sample Parts ΓòÉΓòÉΓòÉ

Source code is provided for the following OpenDoc parts.

Note that installation of OpenDoc for OS/2 is required for execution of these
OpenDoc sample parts.

     Cookbook
     Hello World
     Push Button
     Ticker Tape 1
     Ticker Tape 2


ΓòÉΓòÉΓòÉ 6.3.6.1. Cookbook Sample Part ΓòÉΓòÉΓòÉ

The \TOOLKIT\SAMPLES\OPENDOC\PARTS\COOKBOOK subdirectory contains the source
code for the Cookbook part. This part shows a developer how to create a fairly
simple part by subclassing the OpenDoc ODPart class.  All 66 of the ODPart
methods are overridden, and 32 of the ODPart methods are implemented.

The Cookbook part accomplishes the following:

     Part registration
     Instantiation of the part object
     Initialization
     Opening the part
     Drawing the part
     Handling basic events (such as menu, mouse, and activate)
     Using persistent storage
     Embedding (the part itself can be embedded, but does not handle
      embedding)
     Facet manipulation
     Frame manipulation
     Activation

 In general, the implementation of the Cookbook sample part follows the Apple
 recipes. There is, however, one exception. The ActivateFrame method
 incorrectly calls the FocusAcquired method to handle the acquiring of the
 part's focus by the activated frame.  Similarly, the CommitRelinquishFocus
 method incorrectly calls the FocusLost method.  The correct implementation of
 ActivateFrame and CommitRelinquishFocus can be found in the Container Part,
 located in the \TOOLKIT\BETA\SAMPLES\OPENDOC\PARTS\CNTNRPRT directory.

 The Cookbook sample part, like all the other OpenDoc samples in the Warp
 Toolkit, should be compiled with IBM C Set ++.  The sample will not compile
 with the VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 6.3.6.2. Hello World Sample Part ΓòÉΓòÉΓòÉ

The \TOOLKIT\SAMPLES\OPENDOC\PARTS\HELLO subdirectory contains the source code
for the Hello World part. This part handler demonstrates subclassing a
container, including how to properly initialize and uninitialize the part
class, store persistent data, handle specific user events, and draw the part in
an OpenDoc window.

The Hello World part handler supports the four standard view types: large and
small icon, thumbnail, and frame.

Since this sample inherits from the Container Part, see its Known Limitations
for information on known problems with the Container Part that can be seen in
this part.

The Hello World sample part, like all the other OpenDoc samples in the Warp
Toolkit, should be compiled with IBM C Set ++.  The sample will not compile
with the VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 6.3.6.3. Push Button Sample Part ΓòÉΓòÉΓòÉ

The \TOOLKIT\SAMPLES\OPENDOC\PARTS\PUSHBTN subdirectory contains the source
code for the push button part.  This part handler is an example of a PM control
as an OpenDoc part.  The control is implemented such that pressing the push
button displays a message window.  The user is able to change the view type to
large icon, small icon, thumbnail or frame view.  The push button shows how to
implement support for:

     Subclassing from a container part
     Part handler installation/registration
     Standard storage unit properties (persistent data storage and retrieval)
     Standard view types
     General drawing
     General embedding
     Simple user event handling
     Controls as parts
     Frame negotiation (embedded part)

 Generally in OpenDoc, when you click the mouse button 1 on a part, it
 activates the part and gives the part access to the menu bar.  This does not
 happen on the Push Button part because clicking of mouse button 1 actually
 presses the button.

 Since the activation border is not available, users have to press Ctrl+mouse
 button 1 to select the Push Button part.

 Anything that is dragged and dropped into the Push Button part is covered by
 the Push Button.

 Since the semantics of the Push Button part causes a press on the mouse click
 but no activation, any operation requiring activation of the Push Button part
 is restricted, including clicking on the Push Button Part to deactivate
 another part or an embedded part in the document.

 The Push Button part does not inverse its color (selection highlighting) when
 user selects this part. This part does not override any menu bar method; all
 the base menu bar items remain unchanged.

 Because the Push Button part uses a PM control, its contents cannot be rotated
 or scaled.

 Since this sample inherits from the Container Part, see its Known Limitations
 for information on known problems with the Container Part that can be seen in
 this part.

 The Push Button sample part, like all the other OpenDoc samples in the Warp
 Toolkit, should be compiled with IBM C Set ++.  The sample will not compile
 with the VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 6.3.6.4. Ticker Tape 1 Sample Part ΓòÉΓòÉΓòÉ

The \TOOLKIT\SAMPLES\OPENDOC\PARTS\TTAPE1 subdirectory contains the source code
for the Ticker Tape 1 part. The Ticker Tape 1 part displays text retrieved from
a file in a window resembling a ticker tape, such that the file text is
scrolled from right to left. It is a simple example of subclassing a container
part, where parts can be embedded within the Ticker Tape 1 part.  (Ticker Tape
1 subclasses from the sample container part located in the
\TOOLKIT\BETA\SAMPLES\OPENDOC\CNTNRPRT subdirectory.)

Note that the embedded parts are displayed only when the ticker tape text is
not scrolling.  Scrolling writes over the embedded parts.  To stop the
scrolling of the ticker tape text, click over the Ticker Tape 1 part with mouse
button 1. The text stops scrolling, the embedded parts are displayed, and new
parts can be embedded.  Scrolling starts when you click with mouse button 1
anywhere outside of the Ticker Tape 1 part.

You can select a text file to replace the text scrolling from right to left
within the rectangular window.  A pop-up menu appears when you click over the
part with mouse button 2.  From the pop-up menu you can select the Open Text
File menu item to select a new file.  Note that the maximum size of the text
file you can select is 32,000 bytes.

For an example of how to register an OpenDoc part handler using a REXX command
file, see the TAPEINST.CMD file in the \TOOLKIT\SAMPLES\OPENDOC\PARTS\TTAPE1
subdirectory.

Since this sample inherits from the Container Part, see its Known Limitations
for information on known problems with the Container Part that can be seen in
this part.

The Ticker Tape 1 sample part, like all the other OpenDoc samples in the Warp
Toolkit, should be compiled with IBM C Set ++.  The sample will not compile
with the VisualAge C++ compiler.

Note:  When compiling the Ticker Tape 1 sample part, you may get a "String
       Buffer Exceeded" error from the SOM compiler.  To avoid this problem,
       edit the Ticker Tape 1 part's makefile, TTAPE1.MAK, and add the
       following option to the SOM compiler statement:

              -S50000


ΓòÉΓòÉΓòÉ 6.3.6.5. Ticker Tape 2 Sample Part ΓòÉΓòÉΓòÉ

The \TOOLKIT\SAMPLES\TTAPE2 subdirectory contains the source code for the
Ticker Tape 2 part. This part handler is an example of how new features can be
built upon a part handler by subclassing from that part handler.

The Ticker Tape 2 part handler subclasses from Ticker Tape 1 and so inherits
all of Ticker Tape 1 part's features.  Because the Ticker Tape 1 part handler
subclasses from the Container part, Ticker Tape 2 also inherits Container part
features such as the ability to embed parts.

The Ticker Tape 2 part handler improves upon the updating of ticker tape text
by dynamically updating from the Ticker Tape 2 part handler's storage unit.
When a text file is selected to replace the ticker tape text, the text is
externalized to the storage unit (and Ticker Tape 1 part's text buffer is
deleted).  When more text to display is needed, a fixed amount of text is
retrieved from the storage unit.  This allows the amount of memory required to
display the text to be small, regardless of how large the original text file
is.

The Ticker Tape 2 part updates its text from its storage unit, but it can be
modified easily to update from any data stream.

Since this sample inherits from the Container Part, see its Known Limitations
for information on known problems with the Container Part that can be seen in
this part.

The Ticker Tape 2 sample part, like all the other OpenDoc samples in the Warp
Toolkit, should be compiled with IBM C Set ++.  The sample will not compile
with the VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 6.3.7. OS/2 Sample Programs ΓòÉΓòÉΓòÉ

The OS/2 sample programs are as follows:

     CLOCK
     DLLAPI
     EAS
     HANOI
     NPIPE
     QUEUES
     SEMAPH
     SORT
     VMM
     WORMS


ΓòÉΓòÉΓòÉ 6.3.7.1. CLOCK Sample Program ΓòÉΓòÉΓòÉ

CLOCK (located in \TOOLKIT\SAMPLES\OS2\TIMESERV), demonstrates how to use and
implement window timers and system-resource timers. This sample program
displays both an analog and digital clock. To simulate elapsed seconds, the
main PM thread repeatedly sets a one-second window timer that updates the
current time.

CLOCK features an audible and visual alarm that the user can set. When the time
expires, the sample makes use of the DOS timer services and notifies the user
by sounding an alarm and displaying a message box.


ΓòÉΓòÉΓòÉ 6.3.7.2. DLLAPI Sample Program ΓòÉΓòÉΓòÉ

DLLAPI (located in \TOOLKIT\SAMPLES\OS2\DLLAPI), demonstrates how to write and
use a dynamic link library (DLL). The sample has a .DLL file and an executable
(.EXE) file. The .DLL provides the 32-bit API function that is called by the
.EXE file.

The .DLL uses protected memory on its shared data, and exception management to
validate the pointer parameters for a 32-bit API function. The .EXE file
demonstrates how to handle a divide-by-zero exception, and calls the function
with invalid pointer parameters, followed by a call with valid pointer
parameters.


ΓòÉΓòÉΓòÉ 6.3.7.3. EAS Sample Program ΓòÉΓòÉΓòÉ

EAS (located in \TOOLKIT\SAMPLES\OS2\EAEDIT), demonstrates a multithreaded
application that retrieves, modifies, or sorts files by their extended
attribute value. Included in this sample program are PM procedures for dialog
boxes and a standard client window. The sample lets the user select an extended
attribute file name from a list, or enter a new name in an entry field. The
user can select the extended attribute type from a table.


ΓòÉΓòÉΓòÉ 6.3.7.4. HANOI Sample Program ΓòÉΓòÉΓòÉ

HANOI (located in \TOOLKIT\SAMPLES\OS2\HANOI), demonstrates a multithreaded
application with the familiar "towers of Hanoi" puzzle. When the sample program
is started, the user sees three poles (A, B, and C). Initially, pole A has on
it a stack of disks starting with the largest disks on the bottom and
succeeding smaller disks on the top. The main thread handles the PM interface
and lets the user start or stop the Hanoi routine. It also lets the user reset
the number of working disks. The second thread is created when the Start item
is selected from the Options menu. This thread starts the recursive execution
of the Hanoi algorithm, runs in the background, and moves and paints the disks.
All disks end up on pole C.


ΓòÉΓòÉΓòÉ 6.3.7.5. NPIPE Sample Program ΓòÉΓòÉΓòÉ

NPIPE (located in \TOOLKIT\SAMPLES\OS2\NPIPE), demonstrates two-way
communication between two unrelated processes using named pipe functions. This
sample program implements the game of TicTacToe with two executable files:

     CLINPIPE.EXE (the client)

      The client is the user.  For example, the client will:

        -  Connect to the server and acknowledge successful connection
           (START_MSG).
        -  Notify the server through a pipe when it wishes to begin play
           (YOU_FIRST or CLIENT_MOVE).
        -  Notify the server when it wishes to quit (CLIENT_QUIT).
        -  Send the server a valid move when requested by the server
           (CLIENT_MOVE).

     SVRNPIPE.EXE (the server)

      The server is the computer.  For example, the server will:

        -  Connect a pipe to the client through which play will be executed
           (START_MSG) upon the initial request of a client to play.
        -  Play with many clients simultaneously.
        -  Notify the client of the server's move, and request a valid move
           from the client (SERVER_MOVE).
        -  Notify the client of game-end (WIN_SERVER, WIN_CLIENT, WIN_DRAW).


ΓòÉΓòÉΓòÉ 6.3.7.6. QUEUES Sample Program ΓòÉΓòÉΓòÉ

QUEUES (located in \TOOLKIT\SAMPLES\OS2\QUEUES), demonstrates interprocess
communications (IPC) using the 32-bit queue component. It consists of two
executable programs:

     SVRQUEUE.EXE

      Creates an IPC queue; a named, shared-memory buffer for queue elements;
      and a shared, named, mutex (mutual exclusive) semaphore. After
      initializing the queue, SVRQUEUE starts a thread to read from the queue,
      prints the contents of the messages read from the queue, and terminates
      at the user's request.

     CLIQUEUE.EXE

      Opens the queue and accesses the shared-memory element buffer and mutex
      semaphore, and starts a thread to write to the queue. CLIQUEUE requests a
      string of data from the user, allocates a shared-memory element from the
      buffer, puts the string in the shared-memory element, then uses an event
      semaphore to direct the thread to write the element to the queue.
      CLIQUEUE terminates at the user's request.


ΓòÉΓòÉΓòÉ 6.3.7.7. SEMAPH Sample Program ΓòÉΓòÉΓòÉ

SEMAPH (located in \TOOLKIT\SAMPLES\OS2\SEMAPH), demonstrates the use of mutex
and event semaphores. In the sample, several threads share access to the same
resource.

A mutex semaphore is used to guarantee that only one thread has access to the
resource at a time.  A mutex semaphore is used to check for a stop event or for
a user signal to give up the resource.

An event semaphore is used to signal the thread to give up the resource. An
event semaphore can be posted by the user, or run in auto mode, in which case
the event semaphore will be posted at fixed time intervals.

Each thread can be displayed as a square of a unique color. Similarly, the
resource can be displayed as a rectangle; its color is that of the first thread
that owns it.


ΓòÉΓòÉΓòÉ 6.3.7.8. SORT Sample Program ΓòÉΓòÉΓòÉ

SORT (located in \TOOLKIT\SAMPLES\OS2\SORT), demonstrates the use of multiple
threads by performing multiple sorts at the same time. Each sorting algorithm
runs from a separate thread. The main thread is used to handle the main
window's messages, while the routine that updates the display is run from
another thread.


ΓòÉΓòÉΓòÉ 6.3.7.9. VMM Sample Program ΓòÉΓòÉΓòÉ

VMM (located in \TOOLKIT\SAMPLES\OS2\VMM), demonstrates the use of virtual
memory by using new memory-management functions to allocate and set the
attributes of memory. Users can read or write data into memory and reset the
attributes using a dialog box. The memory manager protects or opens the virtual
memory to read or write operations according to the different attributes of
each memory block. To free memory, the user enters the address of the memory.


ΓòÉΓòÉΓòÉ 6.3.7.10. WORMS Sample Program ΓòÉΓòÉΓòÉ

WORMS (located in \TOOLKIT\SAMPLES\OS2\CONSOLIO), demonstrates how to call
video (Vio), keyboard (Kbd), and mouse (Mou) 16-bit function from a 32-bit code
segment. This sample program displays earth worms aimlessly moving about the
screen. Each worm is a separate thread with a unique color combination and
movement pattern. When one worm encounters another worm, the color attribute of
the worm is set to red. The user can add or delete worms using the keyboard or
mouse.


ΓòÉΓòÉΓòÉ 6.3.8. Presentation Manager Sample Programs ΓòÉΓòÉΓòÉ

The PM sample programs are as follows:

     CLIPBRD
     DIALOG
     DRAGDROP
     GRAPHIC
     HELLO
     IMAGE32
     IPF
     JIGSAW
     PALETTE
     PRINT
     STYLE
     TEMPLATE


ΓòÉΓòÉΓòÉ 6.3.8.1. CLIPBRD Sample Program ΓòÉΓòÉΓòÉ

CLIPBRD (located in \TOOLKIT\SAMPLES\PM\CLIPBRD), demonstrates how to provide a
PM interface to the clipboard. Initially, this sample program displays a
standard window with a bit map. The user can cut and paste rectangular images
in this window, using the system clipboard as an intermediate storage area.


ΓòÉΓòÉΓòÉ 6.3.8.2. DIALOG Sample Program ΓòÉΓòÉΓòÉ

DIALOG (located in \TOOLKIT\SAMPLES\PM\DIALOG), demonstrates how to associate a
dialog box with a standard window. The dialog box is defined as a dialog
template in a resource file.

This sample program also demonstrates how to implement entry fields, push
buttons, and message boxes. Message boxes are only displayed for error
conditions.


ΓòÉΓòÉΓòÉ 6.3.8.3. DRAGDROP Sample Program ΓòÉΓòÉΓòÉ

DRAGDROP (located in \TOOLKIT\SAMPLES\PM\DRAGDROP), demonstrates how to move
files between directories by using the drag and drop operation of direct
manipulation. This sample program creates a drop-down list box that contains a
scrollable file name list of the current directory.

To change the current directory, select the Window option and type in the
directory name, and press Enter. To change the current directory to one higher
in the directory tree, select File from the menu bar, then Open. The Select
subdirectory window appears. Type in the name of the subdirectory, then select
OK.

DRAGDROP must be started twice, so that there are two running instances of the
sample. Then, using a mouse, the user can:

     Display a directory file list in the first sample
     Select a file name from the second sample
     Drag the file name (using mouse button 2) to the directory in the first
      sample
     Drop the file name into the directory in the first sample.

 The file is now moved to the chosen directory of the first sample.


ΓòÉΓòÉΓòÉ 6.3.8.4. GRAPHIC Sample Program ΓòÉΓòÉΓòÉ

GRAPHIC (located in \TOOLKIT\SAMPLES\PM\GRAPHIC), demonstrates how to use
default viewing transformation functions of the PM. It also demonstrates how to
use an asynchronous drawing thread. This sample program lets the user load
metafiles using a dialog box. The dialog box contains a Help push button. When
the Help push button is activated, it provides instructions on loading a
metafile from another directory. The user also can print a metafile or graphic
circle.


ΓòÉΓòÉΓòÉ 6.3.8.5. HELLO Sample Program ΓòÉΓòÉΓòÉ

HELLO (located in \TOOLKIT\SAMPLES\PM\STDWND), demonstrates how to create and
display a standard window that conforms to the Common User Access requirements.

This sample program also demonstrates how to use resources defined in a script
file. Initially, HELLO displays a standard window with the text "Hello". The
Options conditional-cascaded menu contains three items. Each item paints a
different text string in the window.

This sample also shows how to override the Ctrl+C key combination.


ΓòÉΓòÉΓòÉ 6.3.8.6. IMAGE32 Sample Program ΓòÉΓòÉΓòÉ

IMAGE32 (located in \TOOLKIT\SAMPLES\PM\PORTING), demonstrates how to migrate
from an existing OS/2 16-bit application to a 32-bit application.

This sample also demonstrates how to display an image using the GpiImage
function. The image data comes from a file that the user must select using the
standard File Open menu item.


ΓòÉΓòÉΓòÉ 6.3.8.7. IPF Sample Program ΓòÉΓòÉΓòÉ

IPF (located in \TOOLKIT\SAMPLES\PM\IPF), demonstrates how to use the IPF to
create an online document. This sample program features customized windows that
display text, graphics, and animation.

Two files are associated with this sample:

     IPF online document (INF)

      The .INF file is the compiled IPF document. The source contains tagging
      that defines different types of windows. Tags that control the format and
      display of text also are included in this file.

     OS/2 dynamic link library (DLL)

      The .DLL file is the compiled OS/2 C language source for the code object
      that is called when the .INF file is read at run time. A series of bit
      maps used for animation are included in the .DLL.


ΓòÉΓòÉΓòÉ 6.3.8.8. JIGSAW Sample Program ΓòÉΓòÉΓòÉ

JIGSAW (located in \TOOLKIT\SAMPLES\PM\BMPSAMP), demonstrates the use of bit
maps in a graphics application. This sample provides a jigsaw puzzle based on
the decomposition of an arbitrary bit map loaded from a file. The user can
jumble the pieces, then drag them with a mouse. The image can be made smaller,
larger, scrolled horizontally, or scrolled vertically.

This sample program also demonstrates how to call the Information Presentation
Facility help hook, to create instance and associate the instance with the
active application window.


ΓòÉΓòÉΓòÉ 6.3.8.9. PALETTE Sample Program ΓòÉΓòÉΓòÉ

PALETTE (located in \TOOLKIT\SAMPLES\PM\PALETTE), demonstrates 32-bit graphics
functions including:

     Creating a window using a custom palette and animation.
     Using menus with switches, and modifying the menu text.
     Using multiple threads and semaphores in the Presentation Manager
      environment.
     Displaying graphics on the screen using outline fonts and clip paths.
     Online help.

 When started, PALETTE displays a standard window with a large OS/2 logo in the
 foreground. You have the ability to change the OS/2 logo to the IBM logo. If
 you resize the window, the logo is scaled and redrawn to fit the new window
 size. You can also control the animation speed from the PALETTE menu.

 The animation is performed by:

     Creating a clip path which represents the outline of the logo characters
      (which are displayed using an outline font).
     Setting the clip path to the presentation space.
     Drawing a series of lines to the presentation space.

 Each line drawn with an incremental color index. Palette animation is
 performed using the 32-bit GpiAnimatePalette call.

 In order to PALETTE to remain responsive to system and user messages, no
 animation is performed on the main window procedure thread. A second thread is
 created from which all animation is performed.

 Hardware requirements:

     XGA adapter
     1MG of RAM
     32-bit graphics engine


ΓòÉΓòÉΓòÉ 6.3.8.10. PRINT Sample Program ΓòÉΓòÉΓòÉ

PRINT (located in \TOOLKIT\SAMPLES\PM\PRINT), demonstrates how to display and
print text, metafiles, and bit maps. It also demonstrates how to:

     Query and display system printer configurations
     Interact with printer drivers to change job properties
     Query and display available printer and screen fonts
     Query and display printer forms and setup margins
     Selectively print part or all of a document on an asynchronous thread.


ΓòÉΓòÉΓòÉ 6.3.8.11. STYLE Sample Program ΓòÉΓòÉΓòÉ

STYLE (located in \TOOLKIT\SAMPLES\PM\CONTROLS), demonstrates a PM application
that conforms with the Common User Access requirements and implements the
following controls:

     Container
     Notebook
     Slider
     Spin button
     Value set

 This sample program also demonstrates secondary windows, such as dialogs and
 message boxes. The program lets the user edit and save text files. The source
 for online help, in IPF format, is also provided.

 STYLE also demonstrates the detection of a font that does not conform to the
 International Standards Organization (ISO 9241). When the user is running the
 sample on an ISO-compliant monitor and selects a non-compliant font in the
 standard font dialog, a message box is displayed to inform the user.

 The code in STYLE is structured so that the addition of a new function is
 handled in an efficient manner. For example, to add a new command to an
 existing menu, you need only add the command to the resource file, then add
 the appropriate message-processing routines to the STY_USER.C file.


ΓòÉΓòÉΓòÉ 6.3.8.12. TEMPLATE Sample Program ΓòÉΓòÉΓòÉ

TEMPLATE (located in \TOOLKIT\SAMPLES\PM\TEMPLATE), demonstrates the structure
common to all PM applications. This sample program shows how to structure an
application that has more than one source file. It includes the initialization
file (which is used and then discarded), the resident code, and the
non-resident code that is loaded only when needed.

TEMPLATE also demonstrates how to:

     Create a standard window
     Load resources from a resource file
     Create a dialog box and a button control
     Display a message box
     Open a file
     Close a file
     Print text
     Paint a window
     Process a message from a menu
     Run a thread in the background
     Exit a process.

 Several online help files are also provided in IPF format.


ΓòÉΓòÉΓòÉ 6.3.9. REXX Sample Programs ΓòÉΓòÉΓòÉ

The REXX sample programs are as follows:

     CALLREXX
     DEVINFO
     PMREXX
     REXXCALC
     REXXUTIL
     RXMACDLL
     REXX Animal SOM Class Sample
     REXX Workplace Shell Class Sample
     REXX Workplace Shell Folder Sample
     REXX Complex Number Sample
     REXX Concurrency Sample
     REXX Directives Sample
     REXX Display Month Array Sample
     REXX Factorial Sample
     REXX Guard and Reply Sample
     REXX Pipe Sample
     REXX Query Date Sample
     REXX Query Time Sample
     REXX Semaphore Class Sample
     REXX Stack Sample
     REXX Start and Guard Sample


ΓòÉΓòÉΓòÉ 6.3.9.1. CALLREXX Sample Program ΓòÉΓòÉΓòÉ

CALLREXX demonstrates how a C-language application calls a REXX application. To
run the REXX application BACKWARD.FNC, CALLREXX.C issues RexxStart. RexxStart
calls the REXX interpreter and passes it a parameter string. BACKWARD.FNC
returns a result string to the C-language application.


ΓòÉΓòÉΓòÉ 6.3.9.2. DEVINFO Sample Program ΓòÉΓòÉΓòÉ

DEVINFO issues DosDevConfig and returns the data in a collection of compound
variables when all available items are requested, or a single variable when
only one item is requested. This is a REXX subcommand handler and variable pool
example. This sample can be run in an OS/2 full-screen session, an OS/2
text-window session, or in PMREXX.


ΓòÉΓòÉΓòÉ 6.3.9.3. PMREXX Sample Program ΓòÉΓòÉΓòÉ

PMREXX provides a PM window in which the user can display the output from a
REXX procedure or from any programs called by the REXX procedure. The window
has an entry field into which the user can type.


ΓòÉΓòÉΓòÉ 6.3.9.4. REXXCALC Sample Program ΓòÉΓòÉΓòÉ

REXXCALC illustrates the steps required to develop enhanced applications.


ΓòÉΓòÉΓòÉ 6.3.9.5. REXXUTIL Sample Program ΓòÉΓòÉΓòÉ

REXXUTIL demonstrates a set of external functions packaged in a dynamic link
library, including:

     Use of OS/2 system functions in REXX external functions
     Techniques for passing large amounts of data to a REXX program using REXX
      compound variables as arrays.

 REXXUTIL runs on 32-bit OS/2. It can be run in an OS/2 full-screen session, an
 OS/2 window session, or in PMREXX.


ΓòÉΓòÉΓòÉ 6.3.9.6. RXMACDLL Sample Program ΓòÉΓòÉΓòÉ

RXMACDLL demonstrates the macrospace interface with the two following
C-language programs and that are compiled into two separate dynamic link
libraries (DLLs):

     MACRO.C

      Contains REXX external functions, which perform REXX macrospace
      operations.

     RXNLSINF.C

      Contains a REXX external function that provides information related to
      national language support (for example, as a currency symbol and
      separator).

 RXMACDLL.CMD uses MACRO.DLL to load NLSMONEY.CMD into the macrospace and calls
 NLSMONEY.CMD several times to format currency amounts. NLSMONEY.CMD formats
 the amounts according to the specifications provided by RXNLSINF.DLL.

 RXMACDLL can be run in an OS/2 full-screen session, an OS/2 window session, or
 in PMREXX.


ΓòÉΓòÉΓòÉ 6.3.9.7. REXX Animal SOM Class Sample ΓòÉΓòÉΓòÉ

The sample code in the \TOOLKIT\SAMPLES\REXX\SOM\ANIMAL directory illustrates
the use of a simple metaclass to provide customized constructors and to perform
basic instance tracking.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.8. REXX Workplace Shell Class Sample ΓòÉΓòÉΓòÉ

The WPSORXCL.CMD sample in the \TOOLKIT\SAMPLES\REXX\WPS directory demonstrates
how to use the OS/2 Workplace Shell folders to represent Object REXX classes.
This is presented in a tree view where an Object REXX class is a folder and
subclasses are subfolders. The top folder title is updated as classes are added
for a progress indicator.  Methods in a class can be represented as abstract
WPS objects; but the default is not to create them because it is quite time
consuming.

For this sample to function properly, the OpenDoc Pak must be installed first.

The REXX Workplace Shell samples also require the REXX classes first be
registered with the Workplace Shell. To register REXX classes with the
Workplace Shell, type the following at an OS/2 command prompt:

     WPSINST

The WPSINST.CMD program can be used at any time to query REXX classes and to
register and deregister them. To deregister the REXX classes, type the
following at an OS/2 command prompt:

     WPSINST -


ΓòÉΓòÉΓòÉ 6.3.9.9. REXX Workplace Shell Folder Sample ΓòÉΓòÉΓòÉ

The WPSORXFL.CMD sample in the \TOOLKIT\SAMPLES\REXX\WPS directory demonstrates
useful routines for folders.  The first routine will take a WPS folder as input
and return an array of SOM objects; one for each object in that folder.  The
second routine will take an array of WPS objects and a string; returning an
array of objects that match the string.  The sample also uses three methods to
iterate over arrays as iteration examples.

For this sample to function properly, the OpenDoc Pak must be installed first.

The REXX Workplace Shell samples also require the REXX classes first be
registered with the Workplace Shell. To register REXX classes with the
Workplace Shell, type the following at an OS/2 command prompt:

     WPSINST

The WPSINST.CMD program can be used at any time to query REXX classes and to
register and deregister them. To deregister the REXX classes, type the
following at an OS/2 command prompt:

     WPSINST -


ΓòÉΓòÉΓòÉ 6.3.9.10. REXX Complex Number Sample ΓòÉΓòÉΓòÉ

The COMPLEX.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how
to create a complex number class using the ::class and ::method directives.
Also shown is an example of subclassing the complex number class (the vector
subclass).  Finally, the stringlike class demonstrates the use of a mixin to
provide some string behavior to the complex number class.

The USECOMP.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the
use of the ::requires directive to use the complex number class defined in
COMPLEX.CMD.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.11. REXX Concurrency Sample ΓòÉΓòÉΓòÉ

The CCREPLY.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how
to use reply to run two methods at the same time.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.12. REXX Directives Sample ΓòÉΓòÉΓòÉ

The GUESS.CMD sample in the \TOOLKIT\SAMPLES\REXX directory creates a simple
node class and uses it to create a logic tree.  The logic tree is filled in by
playing a simple guessing game.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.13. REXX Display Month Array Sample ΓòÉΓòÉΓòÉ

The MONTH.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the
use of arrays to replace stems.  This sample displays the days of the month.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.14. REXX Factorial Sample ΓòÉΓòÉΓòÉ

The FACTOR.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates a way
to define a factorial class using the subclass method and the .methods
environment symbol.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.15. REXX Guard and Reply Sample ΓòÉΓòÉΓòÉ

The GREPLY.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the
difference between Guarded and UnGuarded methods.  In the first example, the
method is guarded, so it does not begin execution until the final result is
tallied.  In the second example, the method is unguarded so it can begin
execution while method sum_up is still looping.  In fact, unguarded_get often
runs immediately after the Reply, so we use a guard instruction to ensure
sum_up runs for a bit before unguarded_get returns with the intermediate sum.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.16. REXX Pipe Sample ΓòÉΓòÉΓòÉ

The PIPE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the use
of the ::class and ::method directives to create a simple implementation of a
CMS-like pipeline function.

The USEPIPE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how
to use the pipes implemented in the PIPE.CMD sample.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.17. REXX Query Date Sample ΓòÉΓòÉΓòÉ

The QDATE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory displays the
current date and moon phase for that date in English.


ΓòÉΓòÉΓòÉ 6.3.9.18. REXX Query Time Sample ΓòÉΓòÉΓòÉ

The QTIME.CMD sample in the \TOOLKIT\SAMPLES\REXX directory displays the
current time in English.


ΓòÉΓòÉΓòÉ 6.3.9.19. REXX Semaphore Class Sample ΓòÉΓòÉΓòÉ

The SEMCLS.CMD sample in the \TOOLKIT\SAMPLES\REXX directory implements a
semaphore class in Object REXX.  The class is defined to the Global OREXX
environment.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.20. REXX Stack Sample ΓòÉΓòÉΓòÉ

The STACK.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how to
implement a stack class using the ::class and
::method directives.  This sample also includes a short example of the use of a
stack.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.9.21. REXX Start and Guard Sample ΓòÉΓòÉΓòÉ

The KTGUARD.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the
use of the start method and the guard instruction to control execution of
several programs.  In this sample, the programs are controlled by one "guarded"
variable.

For this sample to function properly, the OpenDoc Pak must be installed first.


ΓòÉΓòÉΓòÉ 6.3.10. SOM Sample Programs ΓòÉΓòÉΓòÉ

Note:  The ANIMALS and TP (text processing) sample programs are not included in
       the Warp Toolkit. Refer to the SOMobjects Developer Toolkit for
       accessing them and obtaining information on them.


ΓòÉΓòÉΓòÉ 6.3.11. Workplace Shell Sample Programs ΓòÉΓòÉΓòÉ

The Workplace Shell sample programs are as follows:

     BROWSE
     CAR
     CARPP
     TEXTFLDR
     WPCAR
     WPSTUTOR
     WSFILE

 Note:  All Workplace Shell samples require SOM 2.1 in order to execute
        properly.


ΓòÉΓòÉΓòÉ 6.3.11.1. BROWSE Sample Program ΓòÉΓòÉΓòÉ

BROWSE displays file system objects in a hexadecimal or text format in a PM
window. Open a view of an object is the default format (hexadecimal).  This is
done by:

     Dropping a file system object on the Browse-O-Matic icon
     Double-clicking mouse button 1 and entering the name of a file to view.

 A view of an object can be opened in either hexadecimal or text format by
 selecting the Open Text View or Open Hex View item of the Open
 conditional-cascaded menu. This is done by single-clicking mouse button 2 on
 the Browse-O-Matic icon. The default view format can be changed in the
 Settings notebook page by selecting:

   1. Settings menu item

   2. Menu notebook tab

   3. ~Open choice of the "Available menus" drop-down list box

   4. Settings... push button

   5. ~Settings, Open ~Hex View or Open ~Text View option of the "Default
      action" drop-down list box.


ΓòÉΓòÉΓòÉ 6.3.11.2. CAR Sample Program ΓòÉΓòÉΓòÉ

CAR demonstrates how to create a Workplace Shell object using basic
object-oriented programming techniques and the SOM, including:

     Initializing an object
     Adding settings pages to an object
     Saving and restoring the state of an object
     Modifying an object's context menus (adding and deleting menu items)
     Querying object class data
     Processing context menu items
     Implementing settings page dialog processing
     Handling exceptions.


ΓòÉΓòÉΓòÉ 6.3.11.3. CARPP Sample Program ΓòÉΓòÉΓòÉ

CARPP is a C++ version of the CAR sample program. CARPP demonstrates how to
create a Workplace Shell object using basic object-oriented programming
techniques and the SOM, including:

     Initializing an object
     Adding settings pages to an object
     Saving and restoring the state of an object
     Modifying an object's context menus (adding and deleting menu items)
     Querying object class data
     Processing context menu items
     Implementing settings page dialog processing
     Handling exceptions.


ΓòÉΓòÉΓòÉ 6.3.11.4. TEXTFLDR Sample Program ΓòÉΓòÉΓòÉ

TEXTFLDR allows only plain text objects to be placed into the folder. Objects
that are not plain text, that is, control- or extended-ASCII characters, are
rejected. Objects are considered to be plain text if the "Associated type"
field of the Settings notebook is set to plain text. If there is no associated
type set, the first 500 bytes are placed into the folder.


ΓòÉΓòÉΓòÉ 6.3.11.5. WPCAR Sample Program ΓòÉΓòÉΓòÉ

WPCAR, the Workplace Shell WPDataFile subclass sample, is the C++ version of
the CAR sample.


ΓòÉΓòÉΓòÉ 6.3.11.6. WPSTUTOR Sample Program ΓòÉΓòÉΓòÉ

WPSTUTOR displays the order in which object methods are invoked by the
Workplace Shell. When a sample object's class method is executed, the method's
name and a description of its function are displayed in a PM window. The sample
saves the object's title and its icon title backwards.

This object class subclasses the WPDataFile class. Most Workplace Shell
instance and class methods are overridden so that information about the methods
can be displayed to the user.

This sample is designed to be more of a tutorial for Workplace Shell
programming than a programming example.

Note:  The SHOWDESC.EXE file should be renamed to SHOWDESC.BAK (or something
       else) to turn off the sample. Rename the file back to SHOWDESC.EXE to
       turn the sample back on.


ΓòÉΓòÉΓòÉ 6.3.11.7. WSFILE Sample Program ΓòÉΓòÉΓòÉ

WSFILE displays, creates, and installs Workplace objects of two classes: WSFILE
and WSFOLDER. The WSFILE class is a subclass of the WPDataFile class, and the
WSFOLDER class is a subclass of class WPFolder.


ΓòÉΓòÉΓòÉ 6.4. Tools ΓòÉΓòÉΓòÉ

This section provides a brief description of each tool with just enough detail
to get you started at the OS/2 command line.

The tools are categorized as follows:

     Development Tools
     OpenDoc
     Presentation Manager - PM
     Multimedia
     SOM
     Workplace Shell

 For complete information about the tools described here, please refer to the
 online OS/2 Tools Reference.

 Note:  The Wave Doctor, previously available with the OS/2 Multimedia Toolkit
        product, is not included in the Warp Toolkit.


ΓòÉΓòÉΓòÉ 6.4.1. Development Tools ΓòÉΓòÉΓòÉ

The Developer tools help you develop OS/2 programs. As programmers, we tend to
use such tools as they are needed, and the ones covered here are not likely to
be used as much as the compiler and linker. Nonetheless, they are handy to
have. Perhaps you will only use a few of them in your programming career, but
it is important to know where you can find information about them, in the event
you will ever need them. The tools included in this section are:

     EXEHDR - Executable-Header Files
     FWDSTAMP - Forwarders
     IMPLIB - Import a Library
     KwikINF - Quick Information
     LINK386
     MARKEXE
     MKMSGF - Make Message File
     MSGBIND - Message Binding
     NMAKE
     PACK and UNPACK
     PACK2 and UNPACK2


ΓòÉΓòÉΓòÉ 6.4.1.1. EXEHDR ΓòÉΓòÉΓòÉ

EXEHDR provides a listing of the contents of the executable-header file; it
also provides a listing of the attributes of all segments in the file.

Uses of EXEHDR include:

     Determining whether a file is an application or a dynamic link library
     Modifying and viewing the attributes set by the module definition file
     Viewing the number and size of code and data segments.


ΓòÉΓòÉΓòÉ 6.4.1.1.1. Starting EXEHDR ΓòÉΓòÉΓòÉ

To start EXEHDR from the command line, type:

   EXEHDR [options] filename

where:

 options        Is the name of the EXEHDR option that modifies the header file.
                Regardless of options, EXEHDR always generates a listing of the
                header file.

 filename       Is the name of the application or dynamic link library file.
                You can specify any number of files.


ΓòÉΓòÉΓòÉ 6.4.1.2. FWDSTAMP ΓòÉΓòÉΓòÉ

FWDSTAMP adds entry points, called forwarders, to a dynamic link library (.DLL)
file. Forwarders point to API functions or other exported code or data. They
contain an import reference so that the final target address of the forwarded
entry is contained in a different module. A forwarder might be called an
imported export.

When a file has a fix-up to a forwarded entry point, the loader resolves that
fix-up to the address of the entry point that the forwarder imports by
traversing the chain of forwarders until the end of the chain (a non-forwarded
export) is reached. All forwarders are implicitly exported.

The imported entry point that a forwarder refers to may itself be another
forwarder. The loader will process a chain of forwarders until a non-forwarder
entry point is encountered.

There is no run-time cost to forwarders; however, there is a slight load-time
cost as the loader resolves forwarder chains with their final addresses.


ΓòÉΓòÉΓòÉ 6.4.1.2.1. Using FWDSTAMP ΓòÉΓòÉΓòÉ

You use forwarders to combine several DLLs into one without having to relink
old applications. For example, if MOUCALLS and VIOCALLS were combined into a
single DLL called NEWLIB.DLL, then MOUCALLS and VIOCALLS could be replaced with
special DLLs containing forwarders to NEWLIB.DLL.


ΓòÉΓòÉΓòÉ 6.4.1.2.2. Starting FWDSTAMP ΓòÉΓòÉΓòÉ

To start FWDSTAMP from the command line, type:

   FWDSTAMP infile deffile outfile

where:

 infile      Specifies the name of the dynamic link library file that LINK386
             created. Use the file-name extension of .DLL.

 deffile     Specifies the name of the module definition file (.DEF) that
             contains the forwarders.

 outfile     Specifies the name of the .DLL file that will contain the added
             forwarders.

 Forwarders are specified in the module definition file so that an exported
 name, which is also imported, is a forwarder. For example:

     IMPORTS
      VIOMODEWAIT=NEWLIB.123
     EXPORTS
      VIOMODEWAIT @ 25

 In the example, a forwarder entry point for VIOMODEWAIT is created and
 contains an import reference to NEWLIB.123.


ΓòÉΓòÉΓòÉ 6.4.1.3. IMPLIB ΓòÉΓòÉΓòÉ

IMPLIB is used to generate an import library (.LIB) file. IMPLIB takes a module
definition file (.DEF) as input. For each export definition in the .DEF file,
IMPLIB generates a corresponding import definition.

The .LIB file generated by IMPLIB is used as input to LINK386, which creates an
executable (.EXE) file. The .LIB file provides LINK386 with information about
imported dynamic link functions.


ΓòÉΓòÉΓòÉ 6.4.1.3.1. Creating an IMPLIB ΓòÉΓòÉΓòÉ

Import libraries are created by IMPLIB and are used to link DLLs with
applications.

Import libraries are similar in some respects to standard libraries:

     You specify import libraries and standard libraries in the same
      command-line field of LINK386.
     Both types of libraries resolve external references at link time.

 However, import libraries differ from standard libraries in that they contain
 no executable code. Rather, they identify the DLLs where the executable code
 can be found at run time.

 Creating import libraries is an extra step. Nevertheless, import libraries are
 recommended for use with all DLLs for two reasons:

     IMPLIB automates much of the program creation process for you. To use
      IMPLIB, you need to supply the .DEF file you already created for the
      dynamic link library. Without an import library, you must create a second
      .DEF file that explicitly defines all needed functions in the dynamic
      link library.

     Import libraries make it easier for one person to write a library and
      another to write the application. Much of the linking process (linking
      the .DLL file and creating the import library) can be done by the author
      of the dynamic link library. The import library and associated .DLL file
      can then be given as a unit to the person linking the application - that
      person need not worry about creating a .DEF file.


ΓòÉΓòÉΓòÉ 6.4.1.3.2. Starting IMPLIB ΓòÉΓòÉΓòÉ

You can start IMPLIB and specify all input from the command line. An example of
the syntax follows:

   IMPLIB [options] implibname {deffile... | dllfile...}

where:

 options        Is the name of the option that modifies the output of IMPLIB.
                All options are described as follows:

                               Syntax                   Description
                               /HELP                    Displays a short
                                                        summary of IMPLIB
                                                        syntax.
                               /IGNORECASE              Turns case sensitivity
                                                        off. This is the
                                                        default.
                               /NOIGNORECASE            Turns case sensitivity
                                                        on.
                               /NOLOGO                  Suppresses the
                                                        copyright screen when
                                                        IMPLIB starts.

 implibname     Is the name of the import library created.

 deffile        Is one or more module definition files that export routines in
                the dynamic link library.

 dllfile        Is one or more DLLs with exported entry points.

 Note:  You can specify any number of either module definition files or DLLs.

 The following command creates the import library, MYLIB.LIB, from the module
 definition file, MYLIB.DEF:

     IMPLIB MYLIB.LIB MYLIB.DEF


ΓòÉΓòÉΓòÉ 6.4.1.4. KwikINF ΓòÉΓòÉΓòÉ

KwikINF provides you with a quick and convenient method of accessing
information in online documents stored in the OS/2 BOOKSHELF from anywhere on
the Desktop, with the exception of DOS or WIN-OS/2 sessions. When KwikINF is
started, you can search for a text string of your choice directly or through a
pop-up window by pressing a user-selectable hot key. Until you configure
KwikINF, your KwikINF hot key is Alt+Q.


ΓòÉΓòÉΓòÉ 6.4.1.4.1. Starting KwikINF ΓòÉΓòÉΓòÉ

KwikINF is installed as a program object in the Development Tools folder. You
start KwikINF by double-clicking on the KwikINF program object or by entering
KwikINF from the command line of an OS/2 window. You can also start KwikINF
automatically when you start OS/2 by placing a shadow of the KwikINF object in
the Startup folder of the OS/2 System folder on the Desktop. You shadow an
object by pressing Ctrl+Shift while dragging the object to the place where you
wish to drop the shadow.

Note:  You should not add KwikINF to your STARTUP.CMD if it is followed by an
       EXIT statement.

 You can start, terminate, and configure KwikINF from a command line in an OS/2
 window by entering:

     KwikINF [no options] [/C] [/T] [/?]

 where:

 no options     Starts KwikINF.  After entering this command, the default
                KwikINF hot key (Alt+Q) is enabled.

 /C             Opens the Configure KwikINF window.  Use this window to:

                         Select another KwikINF hot key
                         Select a default online document from the BOOKSHELF
                         Search
                         Select the activation behavior of the KwikINF window.

 /T             Terminates KwikINF and disables the KwikINF hot key.

 /?             Displays the enclosed information.


ΓòÉΓòÉΓòÉ 6.4.1.4.2. Performing a Search ΓòÉΓòÉΓòÉ

How you initiate a search for information in online documents is dependent on
where you are on the Desktop when you press the KwikINF hot key:

     From an OS/2 full-screen session, a PM VIO or AVIO window, or PM MLE :

      Position the cursor on the string you want to search for and press the
      KwikINF hot key. KwikINF retrieves the word at the cursor. If you have
      configured KwikINF to display the KwikINF window when the KwikINF hot key
      is pressed, KwikINF automatically places the retrieved word in the
      "Search string" entry field of the KwikINF window. When you select Search
      or press Enter, KwikINF displays the information. If you have configured
      KwikINF to bypass the KwikINF window when the KwikINF hot key is pressed,
      KwikINF automatically displays the information.

     From a graphic-text PM window:

      Press the KwikINF hot key, then type the string you want to search for in
      the "Search string" entry field of the KwikINF window. The KwikINF
      text-retrieval feature is not available from graphic-text PM windows.


ΓòÉΓòÉΓòÉ 6.4.1.5. LINK386 ΓòÉΓòÉΓòÉ

LINK386 is used to translate object files and standard library files into a
single executable file. LINK386 also generates DLLs and device drivers.

LINK386 uses the following files as input:

     One or more object files that are linked with any optional library files
      to create the executable file.  Object files usually have a .OBJ
      extension.

     One or more library files. The library files contain object modules that
      are linked to the object files to create the executable file. Library
      files usually have a .LIB extension.

     A module definition file. The module definition file provides information
      to LINK386 about the executable file or dynamic link library file it is
      creating. The module definition file usually has a .DEF extension.

 LINK386 produces three types of output files:

     An executable file that runs under OS/2 whenever you specify a module
      definition file that has a NAME statement. The executable file usually
      has a .EXE extension.

     A dynamic link library file. A dynamic link library is produced whenever
      you specify a module definition file that has a LIBRARY statement. A
      dynamic link library file usually has a .DLL extension.

     A device driver file. A virtual or physical device driver is produced
      whenever you specify a module definition file that has the VIRTUAL DEVICE
      or PHYSICAL DEVICE statements. A device driver file usually has a .DRV
      extension.

 Note:  Object-oriented compilers may change the name of a function internally.
        LINK386 has the ability to change the name back to the original
        function name when displaying error messages.

 Three additional options are available with the Warp Toolkit:

           /E[XEPACK:{1|2}]                   Causes pages of code and data in
                                              the file to be compressed

           /NOO[UTPUTONERROR]                 Prevents the LINK386 from
                                              creating the executable file if
                                              an error is encountered.

           /NOS[ECTORALIGNCODE]               Turns off the alignment feature
                                              provided through the LINK386
                                              Linker. LINK386 normally aligns
                                              pages of code on sector (512
                                              byte) boundaries. This reduces
                                              the time to load the pages when
                                              the application is executed. The
                                              /NOSECTORALIGNCODE option aligns
                                              pages of code based on the value
                                              used in the /ALIGN option.


ΓòÉΓòÉΓòÉ 6.4.1.5.1. Starting LINK386 ΓòÉΓòÉΓòÉ

To link the object files and optional library files of your application, supply
input to LINK386 by:

     Responding to a series of LINK386 prompts
     Typing commands directly at the command prompt
     Creating a response file and entering the file name on the command line.


ΓòÉΓòÉΓòÉ 6.4.1.5.2. Responding to LINK386 Prompts ΓòÉΓòÉΓòÉ

To start LINK386, type the following at the command prompt:

   LINK386

Press Enter; a series of prompts appear, one at a time:

  Object modules [.OBJ]:
  Run file [basename.EXE]:
  List file [NUL.MAP]:
  Libraries [.LIB]:
  Definitions file [NUL.DEF]:

You can respond using any combination of upper- and lowercase letters. Enter
your responses by pressing Enter.

To extend input to a new line, type a plus sign (+) as the last character on
the current line. When the same prompt appears on a new line, you can continue.

Note:  Do not split a file name across lines.

 To select the default response to a prompt, press Enter. The next prompt
 appears.

 To select the default response to the current prompt and all remaining
 prompts, type a semicolon and press Enter.

 Note:  You must enter the name of at least one object file.

 Responses within a command line are separated by commas.

 LINK386 supplies the following default file extensions: .OBJ, .EXE, .MAP,
 .LIB, and .DEF. You can override these extensions by typing the file extension
 of your choice.


ΓòÉΓòÉΓòÉ 6.4.1.5.3. Typing Input on the Command Line ΓòÉΓòÉΓòÉ

You can start LINK386 and specify all input from the command line.  An example
of the LINK386 command is:

   LINK386 [options] objfiles[,exefile,mapfile,libraries,deffile]

where:

 options        Is the name of the LINK386 option. Any number of options may be
                specified.

                You can specify options anywhere on the response line, except
                before a comma at the end of a line of characters. If you want
                to specify more than one option, either group them at the end
                of a response, or specify them at the end of several responses.
                Each option must begin with a forward slash (/).

                To end the linking process at any point, press Ctrl+Break.

 objfiles       Is the name of the object files that you want linked.

 exefile        Is the output file that LINK386 created.  LINK386 produces
                either an executable file, a dynamic link library, or a device
                driver. If you do not specify a file name, LINK386 uses the
                name of the first object file. Use the file-name extension .EXE
                if it is an executable file, .DLL if it is a dynamic link
                library, and .DRV if it is a device driver.

 mapfile        Is the name of the file that contains the map listing. The
                default file name extension is .MAP. Use the /M option to
                include public symbols in this file. Enter NULL if you do not
                want a map file.

 libraries      Is a list of libraries for LINK386 to search. These libraries
                include standard or import libraries, but not DLLs. The library
                names should be separated by plus signs (+) or blank spaces.

 deffile        Is the name of the module definition file for the executable
                file or dynamic link library.


ΓòÉΓòÉΓòÉ 6.4.1.5.4. Creating a Response File ΓòÉΓòÉΓòÉ

To operate LINK386 using a response file, you must first create a file that
contains the responses you want LINK386 to process. You can give the file any
name, and create it with any text editor.

Type the following command at the command prompt:

   LINK386 @filename[.ext]

The @ symbol tells LINK386 that filename is a response file. If the file is not
in the working directory, you must specify the path. Begin using a response
file at any point on the LINK386 command line or at any LINK386 prompt. The
file should contain responses in the same order as the LINK386 prompts. Each
response needs to be on a separate line. If you choose to place responses on
the same line, separate them with commas.

If the file does not contain responses for all the prompts, LINK386 displays
the appropriate prompt and waits for you to supply a response. End the response
file with a semicolon.

You can use special characters in the response file the same way you would use
them in responses entered at the keyboard.


ΓòÉΓòÉΓòÉ 6.4.1.5.5. Example of a Response File ΓòÉΓòÉΓòÉ

The response file in the following example instructs LINK386 to generate an
executable file called FUN.EXE, and four object modules, FUN, SUN, RUN, and
GAMES.

  fun+sun+run+games /map
  fun.exe
  funlist
  ;

If you specify the file name, FUNLIST, LINK386 will generate a map file named
FUNLIST.MAP. Adding the /MAP option will cause LINK386 to include the public
symbols of the application in the map file.


ΓòÉΓòÉΓòÉ 6.4.1.5.6. OS2STUB.EXE ΓòÉΓòÉΓòÉ

OS2STUB.EXE is included in the executable file created by LINK386, if the STUB
statement is included in the module definition file. The stub is invoked
whenever the file is executed under DOS. By default, LINK386 adds its own
standard stub for this purpose.


ΓòÉΓòÉΓòÉ 6.4.1.6. MARKEXE ΓòÉΓòÉΓòÉ

MARKEXE lets you view and set the type of application. The type of application
identifies the OS/2 sessions in which a program can run. You can use MARKEXE in
conjunction with programs that you have created using LINK386 or with programs
created by some other means.


ΓòÉΓòÉΓòÉ 6.4.1.6.1. Starting MARKEXE ΓòÉΓòÉΓòÉ

To start MARKEXE from the command line, type:

   MARKEXE [force] [no] [display|dllinit|dllterm|type|lfns] filename

where:

 force          Marks the executable file with OS/2 as the target operating
                system even though the file was marked for another operating
                system. Using force may produce internally inconsistent
                executable files.

 no             Sets the command to the opposite condition.

 display        Displays the application type in a message. This does not
                change the file.

 dllinit        Sets per process initialization for the dynamic link library.

 dllterm        Sets per process termination for the dynamic link library.

 type           Specifies the application type of the executable file. It can
                be one of the following:

                WINDOWAPI                     Uses the API function provided by
                                              the PM. It must be executed in a
                                              PM window.

                WINDOWCOMPAT                  Runs (compatible) in a PM window
                                              or in a full-screen session.

                NOTWINDOWCOMPAT               Executes the application in a
                                              full-screen session only.

                UNSPECIFIED                   Runs an unspecified application
                                              type in an OS/2 full-screen
                                              session.

                If type is not specified, MARKEXE simply displays the current
                type of the executable file.

 lfns           Specifies that the program supports long file names.

 filename       Specifies the executable file to be marked. Any number of files
                can be marked.

 MARKEXE does not modify the file if the application type of the executable
 file is the same as the requested type. It displays the message "unchanged" to
 indicate this.


ΓòÉΓòÉΓòÉ 6.4.1.6.2. Viewing the Application Type ΓòÉΓòÉΓòÉ

You can view the application type of MYPROG.EXE by typing the following:

   MARKEXE MYPROG.EXE

MARKEXE displays the type in a message that looks like this:

   MYPROG.EXE: OS/2 2.1, WINDOWCOMPACT, LFNS


ΓòÉΓòÉΓòÉ 6.4.1.6.3. Setting the Application Type ΓòÉΓòÉΓòÉ

You can set the application type for MYPROG.EXE to WINDOWCOMPAT by typing:

  MARKEXE windowcompat myprog.exe

If you have more than one executable file to be set to the same application
type, you can supply the file names in a single command line, as in the
following example:

  MARKEXE windowcompat myprog.exe abc.exe xyz.exe


ΓòÉΓòÉΓòÉ 6.4.1.7. MKMSGF ΓòÉΓòÉΓòÉ

MKMSGF converts a text message file to an output (binary) message file that
DosGetMessage uses to display messages. Text messages in OS/2 full-screen
applications do not need to be loaded into memory with the application; they
can reside on disk until needed.

You can use the output message file by specifying a message file name and a
message number in the DosGetMessage parameter list. The messages also can be
bound to the executable file by MSGBIND.


ΓòÉΓòÉΓòÉ 6.4.1.7.1. Creating a MKMSGF ΓòÉΓòÉΓòÉ

The input message file is a standard ASCII file that contains three types of
lines:

     Comment
     Component identifier
     Component message.

 Comment lines are the first lines of a file and must begin with a semicolon. A
 component-identifier is a three-character name identifier (for example, "DOS")
 that precedes all MKMSGF message numbers.  Component-message lines consist of
 a message header and an ASCII text message.

 The following is an example of a text message source file.

    ;This is an example
    ;of a text message
    ;file
    DOS
    DOS0100E: File not found
    DOS0101?:
    DOS0102H: Usage: del [drive:][path] filename
    DOS0103?:
    DOS0104I: 1% files copied
    DOS0105?:
    DOS0106W: Warning! All data will be erased!
    DOS0107?:
    DOS0108?:
    DOS0109P: Do you wish to apply these patches (Y or N)? %0

 where:

 DOS0100E - DOS0109P      Identifies message numbers in sequence. The first
                          three characters indicate the component identifier;
                          the four-digit number indicates the message number,
                          which is followed by a letter (described below), then
                          a colon and blank space. If a message number is not
                          used, type the number, end it with a question mark
                          (?), and leave an empty entry.

 E, H, I, P, W            Indicates the type of message. Categories include
                          error (E), help (H), information (I), prompt (P), and
                          warning (W).

 %0                       Displays a prompt for input from the user, after
                          which a carriage return and line feed are inserted.


ΓòÉΓòÉΓòÉ 6.4.1.7.2. Starting MKMSGF ΓòÉΓòÉΓòÉ

To start MKMSGF from the command line, type:

   MKMSGF infile outfile [option]

where:

 infile      Specifies the input file that contains message profiles.

 outfile     Names the outfile using the three-character component identifier
             and the .MSG file extension; for example, MES.MSG.

 option      Specifies the name of the option that modifies the output file.


ΓòÉΓòÉΓòÉ 6.4.1.7.3. Starting MKMSGF Using a Message Control File ΓòÉΓòÉΓòÉ

A message control file is used to create multiple code page message files. An
example of the command-line syntax follows:

   MKMSGF @controlfile

where:

 @controlfile   Is the name of the file that contains the control statements
                used to generate a multiple code page message file.

                The @ symbol is not part of the file name; it is a required
                delimiter.

 An example of a message control file follows:

     root.in root.out /Pcodepage
     /Ddbcsrang/ctryid /LlangID,VerId /V
     sub.001 sub1.out /Pcodepage
     /Ddbcsrang/ctryid /LlangID,VerId
     .
     .
     .
     sub.00n subn.out /Pcodepage
     /Ddbcsrang/ctryid /LlangID,VerId


ΓòÉΓòÉΓòÉ 6.4.1.8. MSGBIND ΓòÉΓòÉΓòÉ

When DosGetMessage is issued, it searches for the message in the message
segment bound to the application's executable file, and then the application's
message file on a hard disk. To ensure that a message is displayed quickly, you
can bind it to the application's executable file by using the MSGBIND utility
program. For each executable file, MSGBIND specifies which message files to
scan; for each message file, it specifies which message to include in the
executable file.

Note:  The MSGBIND utility program supports the new compression format
       available with LINK386 (/EXEPACK:2) and RC (-x2).


ΓòÉΓòÉΓòÉ 6.4.1.8.1. Starting MSGBIND ΓòÉΓòÉΓòÉ

To start MSGBIND from the command line, type:

   MSGBIND [infile]

where:

 infile    Specifies the input file that contains the executable files, output
           message files, and message numbers that are to be bound.


ΓòÉΓòÉΓòÉ 6.4.1.8.2. Binding the Message File ΓòÉΓòÉΓòÉ

The input file contains three types of lines:

     > Executable file
     < Message file
     Message numbers.

 An example of an input file follows:

    >PROG1.EXE
    <\MESSAGES\PRGMSG.MSG
    PRG0100
    PRG0101
    PRG0102
    <\MESSAGES\APP.MSG
    APP0001
    APP0002
    APP0003

 where:

 >PROG1.EXE      Is the executable file to be modified

 <               Defines the first message of a series to be bound, delimited
                 either by the end of the series or a less-than symbol (<).

 <\MESSAGES\PRGMSG.MSG and <\MESSAGES\APP.MSG Names the files containing the
                 binary versions of the messages (created by MKMSGF) and their
                 identifying numbers: the three-character component identifier
                 and the four-digit message number.


ΓòÉΓòÉΓòÉ 6.4.1.9. NMAKE ΓòÉΓòÉΓòÉ

NMAKE carries out all tasks needed to create or update a program after one or
more of the source files in the program have changed. NMAKE compares the
modification dates for one set of files - the target files - with those of
another set of files - the source files.  NMAKE then carries out a given task
only if a target file is out of date. NMAKE does not compile and link all files
just because one file was updated. This can save time when creating programs
that have many source files or that take several steps to complete.

Note:  Previous releases of this program did not honor the documented behavior
       of the .SUFFIXES pseudotarget, which lists all of the extensions that
       NMAKE considers when searching for a rule to build a target that lacks
       an explicit build rule. NMAKE now uses only the suffixes given in the
       .SUFFIXES pseudotarget. If this more restrictive behavior causes some of
       your targets not to be built, you can enable NMAKE to behave in its
       former way by coding in the environment this variable:

                SET NMAKE=b


ΓòÉΓòÉΓòÉ 6.4.1.9.1. Using NMAKE ΓòÉΓòÉΓòÉ

To use NMAKE, create a description file (or makefile). A description file, in
its simplest form, lists which files depend on others and which commands need
to be executed if a file changes. You can create an NMAKE description file with
any text editor that produces ASCII files.

A description file looks like this:

    targets... : dependants...Γöé
         command              ΓöéΓöÇΓöÇΓöÇΓöÇ description block
            :                 Γöé
    targets... : dependants...
         command
            :

A dependent relationship among files is defined in a description block. A
description block indicates the relationship among various parts of the
program. It contains commands to bring all components up-to-date. The
description file can contain any number of description blocks.

Use NMAKE description files for creating backup files, configuring data files,
and running programs when data files are modified.


ΓòÉΓòÉΓòÉ 6.4.1.9.2. Starting NMAKE ΓòÉΓòÉΓòÉ

You can start NMAKE and specify all input from the command line. An example of
the syntax follows:

   NMAKE [options] [macrodefinitions] [targets] [/F filename]

where:

 options               Is the name of the option that modifies the action of
                       NMAKE.

 macrodefinitions      Is the name of the macro that replaces one text string
                       for another in the description file.

 targets               Is the name of one or more target files you want NMAKE
                       to create. If you do not list any targets, NMAKE creates
                       the first target in the description file.

 /F filename           Is the name of the option that specifies filename as the
                       name of the description file to use. If a dash (-) is
                       entered instead of a file name, NMAKE reads a
                       description file from the standard input device.


ΓòÉΓòÉΓòÉ 6.4.1.10. PACK and UNPACK ΓòÉΓòÉΓòÉ

PACK reduces the size of a file by compressing its data. You can use PACK for a
single file or a group of files, thereby reducing the disk space required for
your OS/2 application. UNPACK restores a compressed file to its original size
and copies it to a specified directory.


ΓòÉΓòÉΓòÉ 6.4.1.10.1. Starting PACK ΓòÉΓòÉΓòÉ

You can start PACK with a single command from the command line. The input
required can be specified in one of two following methods:

     Method 1: You can type the names of all the files you want to compress
      directly in the command line.
     Method 2: You can type the name of a single file that contains a list of
      all the files you want to compress.

 When using PACK, select the method that is suitable for you. Include the drive
 and path if the files are not in the working directory. You can specify file
 names with any combination of uppercase and lowercase letters. File-name
 extensions are not required; however, if you specify a file name that has an
 extension, also type the extension.

 Examples of the command-line syntax follow:

  Method 1:
     PACK sourcefile [packedfile]
                     [/H:headerpath\|/H:headerfile|/H:headerpath\headerfile]
                     [/D:headerdate] [/T:headertime] [/C] [/A] [/R]

  Method 2:
     PACK listfile [packedfile] /L
                   [/H:headerpath\|/H:headerfile|/H:headerpath\headerfile]
                   [/D:headerdate] [/T:headertime] [/C]

 where:

 sourcefile          Specifies the name of the file you want packed
                     (compressed). This parameter is required. Include the
                     drive and path if the file is not in the working
                     directory. Global file-name characters are permitted.

                     When the data is compressed, the name of the source file
                     is placed in the header of the compressed file and is used
                     as the destination file name during unpacking.

 listfile            Specifies the name of the file that contains a list of
                     files that are to be compressed. When naming a list file,
                     do not use global file-name characters.

                     For information about list files, see Creating a List
                     File.

 packedfile          Specifies the name of the file that will contain the
                     compressed data. Files that contain compressed data can be
                     recognized by the @ symbol as the last character in the
                     file name. If you do not specify this parameter, PACK
                     places the compressed data in sourcefile and modifies its
                     name to contain the @ symbol.

 /H:headerpath\ or /H:headerfile or /H:headerpath\headerfile These parameters
                     can be used separately or paired.

                     /H:headerpath\                     Specifies the
                                                        destination path (drive
                                                        letters are not
                                                        permitted) to be placed
                                                        in the header of the
                                                        file that contains the
                                                        compressed data. Unless
                                                        this path is overridden
                                                        with the UNPACK
                                                        command, it will be the
                                                        destination path when
                                                        the file is
                                                        uncompressed.
                                                        Headerpath must end
                                                        with a backslash (\).

                     /H:headerfile                      Specifies the name of
                                                        the file to be placed
                                                        in the header of the
                                                        compressed file. This
                                                        file name will be used
                                                        as the destination file
                                                        for the uncompressed
                                                        data and cannot be
                                                        overridden.

                                                        If a header file name
                                                        is not specified, PACK
                                                        automatically uses
                                                        sourcefile as the name
                                                        of the file that is
                                                        placed in the header of
                                                        the compressed file.

                     /H:headerpath\headerfile           Specifies that both a
                                                        destination path and a
                                                        destination file name
                                                        are to be placed in the
                                                        header of the file that
                                                        has the compressed
                                                        data.

 /D:headerdate       Records the date in the header of the file that has the
                     compressed data, and also in the destination file when it
                     is uncompressed.

                     The date must follow the format /D:MM-DD-YYYY.  For
                     example: /D:08-20-1991 and /D:12-30-2010.

 /T:headertime       Records the time in the header of the file that has the
                     compressed data, and also in the destination file when it
                     is uncompressed.

                     The time must follow the format /T:HH.MM. For example
                     /T:02.06 and /T:14.54. Hour 00 represents 12 a.m. and hour
                     12 represents 12 p.m.

 /A                  Adds data from sourcefile to the data in packedfile.

                     The source file can be either in a compressed or
                     uncompressed state. If the source file is in an
                     uncompressed state, the data is compressed before being
                     added to the file containing the compressed data.

 /C                  Specifies that the current path be placed in the header of
                     the file that contains the compressed data. When the
                     UNPACK command is used, this path will be the destination
                     path for the file that contains the uncompressed data.

                     You cannot use /C when the headerpath is used.

 /L                  Indicates that listfile is a list file. A list file is not
                     compressed; it simply contains a listing of the names of
                     the files that are to be compressed.

 /R                  Removes the file specified by sourcefile from the file
                     that contains only compressed data. The sourcefile
                     parameter must specify the path and file name exactly as
                     they appear in the header of the file with the compressed
                     data; otherwise, the following error message appears on
                     the screen:

                                            The specified file to remove was not found.

                     The /R parameter is valid only when used in conjunction
                     with sourcefile and packedfile.

 Note:  The path and file-name information stored in the header of the file
        that contains the compressed data can be displayed by using the /SHOW
        option available with UNPACK.


ΓòÉΓòÉΓòÉ 6.4.1.10.2. Creating a List File ΓòÉΓòÉΓòÉ

To use a list file with PACK, you must first create a file that contains the
names of the files you want to compress. You can give the list file any name.
Following is an example of specifying a list file at the command line:

   PACK DEVICE.LST DEVICE.DRV /L

The /L indicates that DEVICE.LST is a list file. If the list file is not in the
working directory, you must specify the drive and path. Global file-name
characters are not permitted in the list-file name. DEVICE.DRV is the
destination file for the end-to-end-compressed data. (End-to-end compressed
data is the data from each of the files contained in the list file. This data
is stored in a contiguous format in the destination file.)

The syntax used in the list file is similar to that used in the command line.
The syntax for a single line in the list file follows:

   sourcefile [/H:headerpath\|/H:headerfile|/H:headerpath\ headerfile]
              [/D:headerdate] [/T:headertime] [/C]

Remember, when using the list-file method (method 2), global file-name
characters are not permitted in the source-file name. Notice also that "PACK"
is excluded, and packedfile is not permitted in the list file, because they
were specified on the command line. You can include comments or blank lines by
entering a semicolon as the first character of the line. An example of a list
file follows:

   ;This is a comment
   C:\OS2\COMMAND.COM
   CONFIG.SYS /H:CONFIG.BAK /C
   \OS2\INSTALL\DDINSTAL.EXE /H:\OS2\DDINSTAL.TMP /D:10-15-91 /T:11.45


ΓòÉΓòÉΓòÉ 6.4.1.10.3. Starting UNPACK ΓòÉΓòÉΓòÉ

UNPACK restores a file of compressed data to its original size and copies it to
a specified drive and path. To start the UNPACK command, type:

  UNPACK sourcefile [destinationdrive:][destinationpath]
                    [/SHOW] [/N:singlefile] [/V] [/F]

where:

 sourcefile            Specifies the name of an existing file that contains
                       compressed data. If this file contains one or more files
                       of compressed data, UNPACK restores each file within the
                       file.

 destinationdrive:     Specifies the name of the drive to which you want UNPACK
                       to copy one or more restored files.

                       When you specify a destination drive, but not a path,
                       UNPACK uses the path information stored in the header of
                       the file that contains the compressed data.

 destinationpath       Specifies the name of the directory (and its
                       subdirectories) to which you want UNPACK to copy one or
                       more restored files.

                       When specified, the destination path overrides the path
                       information stored in the header of the file that
                       contains the compressed data.

 /SHOW                 Displays the destination path and file-name information
                       that are saved in the header of each file containing
                       compressed data.

 /N:singlefile         Extracts and uncompresses one file from a file that
                       contains multiple files of compressed data.

 /V                    Verifies that sectors written to the target disk are
                       recorded properly. This parameter lets you know that
                       critical data has been correctly recorded.

                       This parameter causes UNPACK to run slower because a
                       check is made for each entry recorded on the disk.

 /F                    Specifies that files with extended attributes should not
                       be unpacked or copied if the destination file system
                       does not support extended attributes.


ΓòÉΓòÉΓòÉ 6.4.1.11. PACK2 and UNPACK2 ΓòÉΓòÉΓòÉ

The algorithm used to compress files has been substantially enhanced. The use
of this utility program is identical to the PACK and UNPACK utility, which is
documented in the OS/2 Tools Reference.


ΓòÉΓòÉΓòÉ 6.4.2. Multimedia Tools ΓòÉΓòÉΓòÉ

This section describes the Multimedia tools which help you develop multimedia
programs. There is one multimedia tool available in this release:

 MIDICONV - MIDI Conversion Utility

Note:  The Wave Doctor, previously available with the OS/2 Multimedia Toolkit
       product, is not available with this version of the Warp Toolkit.


ΓòÉΓòÉΓòÉ 6.4.2.1. MIDICONV ΓòÉΓòÉΓòÉ

MIDICONV is a conversion utility program that lets you convert a MIDI format 1
file to a MIDI format 0 file through the use of an installable I/O procedure.

Note:  A MIDI format 0 file has only one track of music; a MIDI format 1 file
       has multiple tracks of music.


ΓòÉΓòÉΓòÉ 6.4.3. OpenDoc Tools ΓòÉΓòÉΓòÉ

The following OpenDoc tools are provided:

     OpenDoc Debugging
     OSA Resource Editor


ΓòÉΓòÉΓòÉ 6.4.3.1. OpenDoc Debugging ΓòÉΓòÉΓòÉ

To use the debug version of OpenDoc, prepend the \TOOLKIT\DEBUG path to your
PATH and LIBPATH environment variables in the CONFIG.SYS file. Remove that path
from those variables when you are ready to return to the non-debug OpenDoc
environment.

Note that symbol files for OpenDoc are also provided in with the kernel
debugger (see System Debug Support).

The debug version of OpenDoc provides the following facilities:

     Ability to browse the format of the Bento file

      Select Bento from the menu bar in the document shell to get a MLE dump of
      the Bento file.

     Ability to log various types of data

      Select Logging from the menu bar in the document shell to choose where to
      log data to or to turn on SOM tracing.

     Catching exceptions

      With the debug version of OpenDoc, when an OpenDoc exception is caught by
      the shell, a message box is displayed giving the exception type and the
      location where it was thrown. If the OS/2 environment variable
      ODBREAKONTHROW is defined, OpenDoc will execute an INT 3 instruction when
      the exception it raised.  This will cause control to transfer to the
      debugger and you can examine the call stack to try to determine the cause
      of the exception.  You can define the ODBREAKONTHROW environment variable
      by typing the following command at an OS/2 command prompt:

            SET ODBREAKONTHROW=1

      In the debug version of OpenDoc, the default destination for messages
      output using the somPrintf function is the file OpenDoc.log. The log file
      is in the default directory.  You can cause these messages to be directed
      to the PMPRINTF message queue instead by starting DOCSHELL.EXE with the
      -s option. You can then use PMPRINTF.EXE (available on The Developer
      Connection for OS/2 CD) to view the messages in a PM window.

     Ability to debug problems with reference counts

      The debugging version of OpenDoc will output debug messages under the
      following conditions:

        -  A ref-counted object is deleted with a non-zero ref count.
        -  A ref-counted object is released too many times.

      Following is an example of ref-count related messages in OpenDoc.log:

            XXX Deleted ODTransform 1794110 (with ref-count at 1)
            XXX Deleted PageLayout 12A0C10 (with ref-count at 169)
            XXX Deleted ODFrame 12EAD10 (with ref-count at 94)
            XXX Deleted SimplePart 1644C90 (with ref-count at 1)
            XXX Deleted ODFrame 1645310 (with ref-count at 4)
            XXX Deleted CMStorageUnit 164BE10 (with ref-count at 1)
            XXX Deleted CMDraft A08510 (with ref-count at 1)

      There are three environment variables that can be used to get more
      information about ref-counted objects.  If the environment variable
      ODTRACKREFCTCLASS is set to the name of a ref-counted object class (case
      sensitive), then OpenDoc will log all acquires and releases of objects of
      that class.  Following is an example of the output generated with
      ODTRACKREFCTCLASS=ODFrame: shell, a message box is displayed giving the
      exception type and the location

            +++ IncrementRefCount of ODFrame 1242E90: Now 7
            --- Release ODFrame 1242E90: Now 6
            --- Release ODFrame 12FBE10: Now 6
            +++ IncrementRefCount of ODFrame 12FBE10: Now 7
            +++ IncrementRefCount of ODFrame 1242E90: Now 7
            --- Release ODFrame 1242E90: Now 6
            +++ IncrementRefCount of ODFrame 12D9F90: Now 4
            --- Release ODFrame 12D9F90: Now 3
            +++ IncrementRefCount of ODFrame 1242E90: Now 7
            --- Release ODFrame 1242E90: Now 6
            --- Release ODFrame 12FBE10: Now 6

      If the environment variable ODTRACKREFCTOBJ is set to the hexadecimal
      address of a ref-counted object, then OpenDoc will log all acquires and
      releases for that object only.  The output is similar to that for
      tracking a class, except that all the information will be for the same
      object.

      If the environment variable ODDUMPSTACKFRAMES is set, OpenDoc will follow
      each of the above logfile messages with a symbolic dump of the call
      stack.  The numeric value of the environment variable indicates the
      number of stack frames to dump.  The following environment set commands:

            set ODTRACKREFCTCLASS=ODFrame
            set ODDUMPSTACKFRAMES=8

      results in the following example output in the OpenDoc.log file:

            --- Release ODFrame 1242E90: Now 6
            OPENDOC   TempRef<ODPart>::TempRef(ODPart*) (StdDispO.obj)
            OPENDOC   OS2DispatchModule::DispatchMouseEvent(Environment*,ODEventData*,ODEventInfo*) (StdDispO.obj)
            OPENDOC   OS2DispatchModule::Dispatch(Environment*,ODEventData*) (StdDispO.obj)
            OPENDOC   ODStandardDispatchModuleDispatch (StdDisp.obj)
            OPENDOC   ODDispatcherRemoveDispatchModuleEntries (Disptch.obj)
            OPENDOC   ODDispatcherRedispatch (Disptch.obj)
            OPENDOC   ODDispatcherRemoveDispatchModuleEntries (Disptch.obj)
            OPENDOC   ODDispatcherDispatch (Disptch.obj)
            +++ IncrementRefCount of ODFrame 1242E90: Now 7
            OPENDOC   ODExclusiveFocusModuleAcquireFocusOwner (ExcFocus.obj)
            OPENDOC   ODArbitratorPurge (Arbitrat.obj)
            OPENDOC   ODArbitratorAcquireFocusOwner (Arbitrat.obj)
            CNTNRPRT  ODArbitrator::AcquireFocusOwner(Environment*,unsigned long) (cntnrprt.obj)
            CNTNRPRT  ContainerPartDeActivatingWindow (cntnrprt.obj)
            CNTNRPRT  ContainerPart::DeActivatingWindow(Environment*,ODFrame*) (cntnrprt.obj)
            CNTNRPRT  ContainerPartHandleEvent (cntnrprt.obj)
            OPENDOC   ODPartWrapperCreateRootMenuBar (PartWrap.obj)
            --- Release ODFrame 1242E90: Now 6
            OPENDOC   BaseTempRef::~BaseTempRef() (Tempobj.obj)
            OPENDOC   BaseTempRef::~BaseTempRef() (Tempobj.obj)
            CNTNRPRT  TempRef<ODFrame>::~TempRef() (cntnrprt.obj)
            CNTNRPRT  ContainerPartDeActivatingWindow (cntnrprt.obj)
            CNTNRPRT  ContainerPart::DeActivatingWindow(Environment*,ODFrame*) (cntnrprt.obj)
            CNTNRPRT  ContainerPartHandleEvent (cntnrprt.obj)
            OPENDOC   ODPartWrapperCreateRootMenuBar (PartWrap.obj)
            OPENDOC   ODPartWrapperHandleEvent (PartWrap.obj)
            +++ IncrementRefCount of ODFrame 1242E90: Now 7
            OPENDOC   ODFrameInitFrame (Frame.obj)
            OPENDOC   CMDraftPartDeleted (CMDraft.obj)
            OPENDOC   CMDraftCreateFrame (CMDraft.obj)
            CNTNRPRT  ODDraft::CreateFrame(Environment*,char*,ODFrame*,ODShape*,ODCanvas*,ODPart*,unsigned long,unsigned long,unsigned char,unsigned char) (cntnrprt.obj)
            CNTNRPRT  ContainerPartMakeEmbeddedFrame (cntnrprt.obj)
            CNTNRPRT  ContainerPart::MakeEmbeddedFrame(Environment*,ODFrame*,ODShape*,ODTransform*,ODPart*,unsigned char) (cntnrprt.obj)
            CNTNRPRT  ContainerPartDrop (cntnrprt.obj)
            OPENDOC   ODPartWrapperCreateRootMenuBar (PartWrap.obj)

      The symbolic information for the stack dump is obtained from the debug
      information in the executable so only modules that were compiled and
      linked with the debug flags will have symbolic information displayed.
      Stack frame entries for which no symbolic information is available will
      display the module name with the hexadecimal return address.  Source file
      names and line number information are also available. where it was
      thrown. If the OS/2 environment variable ODBREAKONTHROW is defined,

      Note that the overhead of formatting and displaying the symbolic stack
      dump is significant, so excessive stack dumping can cause severe
      performance degradation.

      OpenDoc looks at the above mentioned environment variables at startup, so
      changing these variable while OpenDoc is running will have no effect.

      In addition to using the stack dump feature with reference counted
      objects, the DumpStack function is available in the debug version of
      OpenDoc for parts to call any time they want.  To use this function,
      include the header file dumpstck.h in your sourcefile. The prototype for
      DumpStack is:

            void DumpStack(long start, long depth);

      The start parameter indicates the number of stack frames to ignore before
      beginning the dump, and the depth parameter indicates the number of
      frames to dump.  DumpStack only knows how to retrieve symbolic
      information from modules compiled with IBM C Set ++ (version 2.1 or
      later) and IBM VisualAge C++ (version 3.0) compilers. It has not been
      tested with any other compilers.

      In order for OpenDoc to function properly, it is important that all
      ref-counted objects be properly cleaned up.  We encourage part developers
      to use the above mentioned tools to help identify and eliminate all
      ref-counting errors that are reported in the log file.


ΓòÉΓòÉΓòÉ 6.4.3.2. OSA Resource Editor ΓòÉΓòÉΓòÉ

The OSA Resource Editor is a tool designed for creating, editing, and browsing
AETE Resources. The OSA Resource Editor (RED) will help you create your
application's AETE Resource by using a Workplace-Shell-style user interface to
direct you and maintain the syntactic correctness of your AETE Resource.  For
instructions on starting this tool, see Starting the OSA Resource Editor.

The AETE (Apple Event Terminology Extension) Resource is the way an application
describes its vocabulary to the rest of the world. It provides information on
the kind of objects that the application handles and the actions that can be
performed on them.  OSA's Scripting Components use this resource in order to
associate names with internal events in the system. The application's
vocabulary, or terminology, are the nouns and verbs that the application
supports.

The AETE Resource allows scripting components to interpret scripts correctly
and send the appropriate events (verbs) to the application during script
execution. If you want your application to be scriptable, you will have to
supply an AETE Resource with it. The verbs and nouns that are in the resource
can then be used by script writers when scripting the application.

OSA's Scripting Components use the AETE Resource to interpret the
human-language terms used in scripts that control your application, and
associate them with the corresponding IDs, keywords, and other codes used in
events.

The AETE Resource is a binary file with a strict structure. It consists of
several suites, that hold the events (verbs) and classes (nouns). The suite is
an organizational unit that allows categorization of the objects that an
application supports. Each suite contains the following information:

     ID defined for each suite
     Events defined for each suite
     Parameters defined for each event
     Event object classes defined for each suite
     Properties defined for each object class
     Elements defined for each object class
     Key forms defined for each element class
     Comparison operators defined for each suite
     Values for enumerators defined for each suite

 Note:  Since the OS/2 AETE Resource is binary compatible with the Macintosh
        AETE Resource, AETE Resources can also be built on the Macintosh using
        a tool such as Rez or Resorcerer. A utility is needed to transfer the
        Macintosh AETE Resource from the resource fork to the data fork before
        it can be brought over to OS/2.

 AEUT Resource

 The Apple Event User Terminology (AEUT) Resource contains terminology
 information for all the standard suites of events defined in the Apple Event
 Registry: Standard Suites [4]. The Event Registry is an effort for
 standardizing the vocabulary used by applications and is maintained by CI
 Labs.


ΓòÉΓòÉΓòÉ 6.4.3.2.1. Starting the OSA Resource Editor (RED) ΓòÉΓòÉΓòÉ

You can start the OSA Resource Editor in two ways:

     From the command line, change to the TOOLKIT\BETA\BIN\OSARED subdirectory
      and type:

              RED

     From the Desktop, open the Toolkit folder and then:

        1. Open the Try Me! folder.

        2. Double-click on OSA Resource Editor.

 When the OSA Resource Editor is started, a folder named RED OSA Resource
 Editor is opened. This folder (the "editor folder") contains helpful tools and
 all of the AETE Resources being edited. In the editor folder you will find a
 Templates folder, a Library folder, and an OSA Aware Applications folder. When
 you create new resources, or open existing resources, their icons will be
 added to the editor folder.

 See Creating an AETE Resource for detailed instructions on how to create a
 resource using the OSA Resource Editor.


ΓòÉΓòÉΓòÉ 6.4.3.2.2. Creating an AETE Resource ΓòÉΓòÉΓòÉ

The organization of the terms in your resource directly affects the ability of
users to explore and control your application through scripting. This section
provides guidance for using the OSA Resource Editor (RED) to create your
application's resource.

To create an AETE Resource, do the following:

   1. Select Create resource from the RED menu on the RED OSA Resource Editor
      folder menu bar.

      This will open a properties notebook for a new resource. On the first
      page of the notebook (the AETE page), you can fill in the general
      information of the resource (its major and minor versions, the language
      code, and the script code). On the second page (the File page), you can
      fill in your application's name (which is also the file stem for saving
      your AETE Resource), and a path in which the resource's file should be
      saved.

   2. Select Create at the bottom of the notebook and the resource will be
      created (its icon will be added to the editor folder).

   3. Specify the standard suites that your application supports by opening the
      Library folder (located within the RED OSA Resource Editor folder).

      In the Library folder you can find the set of all standard suites. Simply
      drag (use Ctrl+mouse button keys) the ones your application supports onto
      the newly created resource. Once the supported standard suites are in the
      resource, they may be extended or overridden. If you do not wish to
      support a suite as a whole, you may choose one of the following two
      options:

          If the part you do wish to support is rather small, you should open
           the suite's properties notebook and modify the suite's ID to '****'.
           You can now choose the objects you do wish to support from the
           Library and drag them onto the suite.

          If you wish to support most of the suite, you should delete those
           objects that you do not want. This will automatically modify the
           suite's ID to '****', after prompting you to confirm that this is
           indeed your intention.

   4. You can now add your own, uninherited, objects to the resource by doing
      the following:

        a. Open the Templates folder (located in the RED OSA Resource Editor
           folder).

           In the Templates folder you can find the Resource template and a set
           of templates for the different types of objects that may be in a
           resource including: Suite, Event, Class, Comparison Operator,
           Enumeration, Enumerator, Parameter, Property, Element, and Key Form.

           Note:  A resource can not go inside a resource. Its icon is included
                  in the Templates folder for completeness.

        b. Drag the templates of the desired objects onto your resource. The
           Resource Editor will maintain the strict structure of the AETE
           Resource by not enabling the drop of a template anywhere in the
           containment hierarchy, but in the right place. Thus, you will only
           be able to drop an event on a suite, a key form, an element, and so
           on.

 You are ready to use the tool. There are few features of the OSA Resource
 Editor that are worth mentioning. Snooping into existing applications:
 OSA-aware applications (that are already installed and are in the OSA
 database), can be found in the OSA Aware Applications folder. You can bring
 those into the editor in order to study their structure. Binary files of AETE
 resources can be imported from the Apple Mac platform or created on OS/2. They
 can be opened by selecting Open resource from the RED menu, which will pop a
 file dialog.

 If you opened a resource and want to browse it, remember the following:

     Tree view of the resource gives an overview of the whole tree structure
      of the resource.
     Details view of the other objects lets you see the properties of all the
      contained objects at once.

 When working on a new resource it is helpful to look at the names that are
 already in use. The dictionary panel provides a list of all the names in the
 AETE+AEUT name space. Each object window has an Options choice on its menu
 bar. Selecting Open dictionary from the Options menu will open the dictionary
 panel. The other selection in the Options menu is Open browser. The browser
 displays a listing of the resource.

 When you are finished editing a resource and ready to save it, there are two
 output formats:  binary and text. Most of the time you save to a binary file.
 This binary file can eventually be installed into the OSA-aware applications
 database. It maintains binary compatibility with the Apple Mac platform. You
 save to a text file for getting a hard copy of the resource. The name of the
 file may be entered through a file dialog or in the File page in the
 resource's properties notebook.


ΓòÉΓòÉΓòÉ 6.4.4. Presentation Manager (PM) Tools ΓòÉΓòÉΓòÉ

This section describes the Presentation Manager tools which help you develop
Presentation Manager programs:

     DLGEDIT - Dialog Editor
     FONTEDIT - Font Editor
     ICONEDIT - Icon Editor
     IPFC - Information Presentation Facility Compiler
     RC - Resource Script


ΓòÉΓòÉΓòÉ 6.4.4.1. DLGEDIT ΓòÉΓòÉΓòÉ

DLGEDIT (Dialog Editor) is used to create and modify dialog boxes and specify
the controls and text within dialog boxes. As you create a dialog box and add
controls, the dialog editor draws it to the screen. You can resize and
reposition the dialog box, then test its controls before you incorporate it in
your application.

Although the dialog editor draws box outlines and controls to the screen so
that you can view it from a user's perspective, the dialog editor does not save
it as a graphic. Instead, the dialog editor stores a description of the dialog
box and its controls in a text file that has a file-name extension of .DLG. It
also creates a compiled form of the .DLG file into a resource file that has an
extension of .RES. The dialog-box and resource files can each contain
descriptions of more than one dialog box. The resource file can contain other
application resources, such as icons, bit maps, and string tables. It is
attached to the application's executable (.EXE) file after the compile and link
processes.

This version of the Dialog Editor is enhanced for use with Pen for OS/2. With
this enhanced version, handwriting and sketch controls are available.


ΓòÉΓòÉΓòÉ 6.4.4.1.1. Starting DLGEDIT ΓòÉΓòÉΓòÉ

To start the dialog editor, select the PM Development Tools folder, then select
the Dialog Editor object.

The File Edit menu bar choices provide two ways to create a dialog box:

     From the Edit menu, select the New Dialog item. The editor opens a new
      dialog in the current file.

      Notice that the dialog editor does not tell you that it has opened the
      resource files. You can open a new include file or an existing one.

     From the File menu, select the New item. This opens new resource files
      with the extensions .RES and .DLG, as shown in the following figure:

 When you edit a dialog box, the names of the resource and include files are
 shown in the title bar of the dialog editor. If you are editing a new file
 that has not yet been named or saved, "Untitled" appears in the title bar in
 place of a name.


ΓòÉΓòÉΓòÉ 6.4.4.1.2. Replacing DLGEDIT ΓòÉΓòÉΓòÉ

IBM supports the version of DLGEDIT (Dialog Editor) in this release of the Warp
Toolkit, but will not be enhancing or otherwise changing the Dialog Editor in
future releases. URE (Universal Resource Editor) will become the editor of
choice for creating and modifying dialogs and other resources.


ΓòÉΓòÉΓòÉ 6.4.4.2. FONTEDIT ΓòÉΓòÉΓòÉ

FONTEDIT (Font Editor) is used to design and save fonts for use in
applications. A font is a set of alphanumeric characters, punctuation marks,
and other symbols that share a common typeface design and line weight.

When the font editor creates a font file, it supplies an .FNT file-name
extension. The font file contains a header, which describes the font in general
terms, and a section that contains bit maps of the characters themselves.


ΓòÉΓòÉΓòÉ 6.4.4.2.1. Starting FNTEDIT ΓòÉΓòÉΓòÉ

To start the font editor select the PM Development Tools folder, then select
the Font Editor object. The following window appears:

The quadrille to the left of the screen has within it an enlarged version of
the character selected from the long, scrollable, horizontal box at the bottom
of the screen. To edit the enlarged version of the character in the quadrille,
use the mouse to switch the enlarged representation to black or white. You can
change a series of pels by holding mouse button 1 down and moving the pointer
through the pels.

Several choices are available from the menu bar that enable you to tailor
individual fonts. With these choices you can:

     Create a font file or open an existing file
     Edit a new or existing font
     Define the characteristics of the font
     Specify character spacing (fixed or proportional)
     Name the typeface
     Identify a type style (italic, underscored)
     Change the width and weight of individual characters
     Insert or delete a column in the character.


ΓòÉΓòÉΓòÉ 6.4.4.2.2. Font Resource Files ΓòÉΓòÉΓòÉ

All resources, except fonts, can be bound to the application's executable file
or compiled into a dynamic link library (DLL). Fonts must be put in a separate
.DLL using the RC. You then link the file at run time and load the resources
into your application by using DosLoadModule or GpiLoadFonts. A .DLL containing
font resources must have a file-name extension of .FON. The .FON file can be
installed on the system.


ΓòÉΓòÉΓòÉ 6.4.4.3. ICONEDIT ΓòÉΓòÉΓòÉ

ICONEDIT (Icon Editor) is used to create icons, pointers, and bit maps. In the
PM, an icon is a graphic symbol that identifies a data object, a system action,
or a minimized application. A pointer is a small shape on the screen that
reflects the movement of the mouse. Pointers have a hot spot that identifies
their exact location on the screen.

Icons, pointers, and bit maps produced by the Icon Editor are graphic symbols
comprised of pels in any of the following display states:

     Black
     White
     Color
     Screen (background color)
     Inverse screen (inverse of background color).

 Mini-icons (also called small icons) are icons that are one-half the size of
 normal icons (also called large icons). Normal icons are 32x32 or 40x40 pels
 (depending on the monitor resolution). Mini-icons are 16x16 or 20x20 pels.
 They are used in areas where a normal icon is too large, for example, in
 toolbars.

 If you previously had OS/2 installed on your system, and if you did not update
 your icon profile when you installed this Warp Toolkit, then you need to run
 the Icon Editor once with its profile update options in order to use the
 mini-icon forms. To do this, enter:

  X:\TOOLKIT\BIN\ICONEDIT /t /i

 where:

 X         Is the drive location for the installed Warp Toolkit.

 After the initial run of Icon Editor, the new mini-icons will be part of your
 profile and you will not need to use options /t /i again.


ΓòÉΓòÉΓòÉ 6.4.4.3.1. Starting ICONEDIT ΓòÉΓòÉΓòÉ

To start the Icon Editor, select the PM Development Tools folder, then select
the Icon Editor object. The following window appears:

Notice the information area at the top of the Icon Editor window; the items
displayed from left to right include:

     A two-button mouse, showing the color currently selected for each button
     An actual-size image of the current figure that you are editing
     A status area that provides:


        -  Size (in pels using x and y coordinates)
        -  Pen location
        -  Pen size (from 1-by-1 to 9-by-9)
        -  Hot spot (for icons and pointers, but not bit maps)
        -  Figure type (icon, pointer, or bit map)
        -  Form name.

 The palette window, in the lower-right corner, displays the colors that are
 available for use during editing. The colors currently selected are marked
 with frames.

 The editing window is the largest part of your working area. Use the mouse to
 paint the enlarged representation with the selected color.

 The menu-bar choices provide access to the many functions of the Icon Editor.
 These choices enable you to:

     Create a new icon, pointer, or bit map
     Edit an existing icon, pointer, or bit map
     Test the new icon or pointer
     Superimpose a grid over the editing window (for drawing a symmetrical
      figure)
     Restrict a drawing to straight vertical or horizontal lines
     Make transparent pels (for icons or pointers) visible
     Change the shape and size of the pen
     Select system preferences (to set prompts or suppress warnings)
     Define hot spots (where the mouse pointer is directed).


ΓòÉΓòÉΓòÉ 6.4.4.4. IPFC ΓòÉΓòÉΓòÉ

IPF (Information Presentation Facility) is a set of tools used to create an
online help facility for an application. IPF also is used to create online
information that can be viewed independent of an application. It is a tool for
both the information author and the application programmer.

As an author of online information, you can define the windows in which
information is displayed. For example, a window can be split so that scrollable
text can be displayed beside a stationary illustration that the text describes.
The following figure shows an IPF application-control-window.

Note:  A new, 32-bit version of the Information Presentation Facility Compiler
       (IPFC) is included in the Warp Toolkit. The new compiler provides the
       following enhancements:

        -  Ability to specify output files
        -  Expanded use of environment variables
        -  Improved error messages
        -  More sophisticated use of support files
        -  New command-line interface
        -  New tag (:hdref.)
        -  Two new macros (.nameit and .ce)
        -  Upgraded overall performance and increased limits


ΓòÉΓòÉΓòÉ 6.4.4.4.1. Developing Online Information ΓòÉΓòÉΓòÉ

IPF makes it possible for you to design your information in two types of
formats:

     An online document format for reference books
     A help-window format for context-sensitive help for your application
      programs.

 To produce either format, you must create a text file using a text editor and
 two IPF elements:

     The IPF tagging language - consists of instructions for formatting and
      displaying your document on the screen.
     The IPFC - interprets the tags and converts the source file into an IPF
      format.


ΓòÉΓòÉΓòÉ 6.4.4.4.2. Starting IPFC ΓòÉΓòÉΓòÉ

You can start the IPFC and specify all input from the command line. An example
of the syntax follows:

  IPFC [-switch] [-option] infile [outfile]

where:

 -switch   Performs the functions in the following list. They can be used
           either individually or combined.

                          i         Compiles the source file as an online
                                    document.
                          s         Suppresses the performance of the search
                                    function.
                          x         Generates and displays a cross-reference
                                    list.

 -option   Performs the functions in the following list. They can be used
           either individually or combined.

                          C         Character code page.
                          D         DBCS range or country code.
                          L         Language ID.
                          W         Warning level.

 infile    Specifies the name of your IPF source file.

           If you do not give a file-name extension, the IPFC uses .IPF by
           default. If your file has a file-name extension other than IPF,
           include that file-name extension in the command-line syntax.

 outfile   Specifies the name of the output file. If this parameter is not
           used, the output file will have the same file name as the input file
           and an extension of either .INF (if used in conjunction with the i
           switch) or .HLP. If you need to store the outfile in a different
           location, a path can be specified.

 The interface from earlier levels of the compiler is still supported. An
 example of the syntax follows:

    IPFC filename [/INF] [/S] [/X] [/Wn] [> messageoutputfilename]

 where:

 filename                 Specifies the name of your IPF source file.

                          If you do not give a file-name extension, the IPFC
                          uses .IPF by default. If your file has a file-name
                          extension other than IPF, include that file-name
                          extension in the command line.

 /INF                     Compiles the source file as an online document.

                          If this parameter is not included, the default is to
                          compile the source file as a help library (with a
                          file-name extension of .HLP).

 /S                       Suppresses the performance of the Search function.
                          This parameter increases compression of compiled data
                          by about 10% to further reduce the storage it
                          requires.

 /X                       Generates and displays a cross-reference list.

 /Wn                      Generates and displays a list of error messages.  The
                          value of n indicates the level of error messages you
                          want to receive. Values you can specify for n are 1,
                          2, or 3.

                              Warning Level 1  (the most severe)
                              Warning Level 2  (moderately severe)
                              Warning Level 3  (the least severe and is the
                               default).

 messageoutputfilename    Specifies the name of the file where error and cross
                          reference messages are sent. If you do not specify
                          this parameter, messages generated by /X and /Wn are
                          sent to the display screen.


ΓòÉΓòÉΓòÉ 6.4.4.4.2.1. Compiling Help Files ΓòÉΓòÉΓòÉ

To compile a source file that is intended as a help-text window, use the IPFC
command without the /INF option. For example:

  IPFC myhelp.hlp


ΓòÉΓòÉΓòÉ 6.4.4.4.2.2. Compiling with International Language Considerations ΓòÉΓòÉΓòÉ

The following parameters provide international language support:

 /COUNTRY  = nnn  (where nnn is the 3-digit country code)
 /CODEPAGE = nnnn  (where nnnn is the 3 or 4-digit code page)
 /LANGUAGE = xxx  (where xxx is a 3-letter identifier that
             indicates an international language file is to be used)

An example of the command-line syntax follows:

  IPFC myfile.txt /INF /COUNTRY=033 /CODEPAGE=437 /LANGUAGE=FRA

You can now add additional languages to IPFC by providing an IPFxxx.NLS file
where xxx matches the name of the language supplied with the /LANGUAGE or -L
switch.

You can also add additional code pages by providing an APSYxxxx.APS file where
xxxx matches the number of the code page. Four-digit code pages are supported.
Three-digit code pages have a leading 0 in their APSYxxxx.APS file name, but
the leading 0 does not have to be passed with the /CODEPAGE or -C switch.  The
underlying operating system must support the supplied code page.

Note:  When adding new language or code page files, be sure they are located in
       the same subdirectory where your IPFC program files are located.


ΓòÉΓòÉΓòÉ 6.4.4.4.2.3. IPFC Environment Variables ΓòÉΓòÉΓòÉ

There are four environment variables that can be used to specify the location
of source files:

 IPFC               Specifies the location of the .IPF support files (such as
                    APSYMBOL.APS and IPF*.NLS).

 IPFCIMBED          Searches for files imbedded with the .im macro.

 IPFCARTWORK        Specifies the location of artwork files and artlink files.

 TMP                Indicates where the compiler should store the temporary
                    files it creates during the compilation.


ΓòÉΓòÉΓòÉ 6.4.4.4.2.4. Viewing an Online Document ΓòÉΓòÉΓòÉ

If you want to see your formatted online document, you can use the VIEW command
to display it.

An online document has an extension of .INF. It can be viewed by entering its
name as a parameter to the VIEW command; for example:

  VIEW myfile

You do not need to include the .INF file extension.

Note:  You cannot use VIEW to display help-text windows for application
       programs. However, for test viewing purposes, you can compile the help
       text as .INF files and use VIEW to look at the information.


ΓòÉΓòÉΓòÉ 6.4.4.5. RC ΓòÉΓòÉΓòÉ

RC (Resource Script) is a tool that lets you add application resources, such as
message strings, pointers, menus, and dialog boxes, to your application's
executable file. The primary purpose of RC is to prepare data for applications
that use functions such as WinLoadString, WinLoadPointer, WinLoadMenu, and
WinLoadDlg. These functions load resources from the application's executable
file or another specified executable file. The application then can use the
loaded resources as needed.

RC and the resource functions let you define and modify application resources
without recompiling the application itself. RC can modify the resources in an
executable file at any time without affecting the rest of the file. You can
create custom applications from a single executable file by using RC to add the
custom resources you need to each application.  RC is especially important for
international language support because it lets you define all
language-dependent data, such as message strings, as resources. Preparing the
application for a new language is simply a matter of adding new resources to
the existing executable file.

The effective limit to the length of a string value of a macro to the RC
preprocessor is 794 bytes.  To count to the limit, count one for each byte
interior to the string, one byte for the beginning and ending double quotation
marks of each segment of the string as defined, plus one byte for the
whitespace separating the ending and beginning double quotation marks of
concatenated string segments.

The RC program recognizes the accelerator flags (constants named like AF_*)
when expressed in an ACCELTABLE statement. The flags may be expressed singly or
in combination with the bitwise OR operator.

The ID numbers of messages in MESSAGETABLE resources range from 0 to 65535 of
any positive integer. This range is the same range as string IDs inside
STRINGTABLE resources.

The RC program can read from the INCLUDE environment variable any HPFS
filenames containing embedded blanks, without the need to enclose such names
inside quotation marks. RC uses the semicolon as a directory separator in the
INCLUDE environment variable.

The RC program offers two new switches with the Warp Toolkit:

 /nologo   Suppresses display of the copyright banner each time the program
           starts.
 /?        Displays the command-line syntax and options.

 A new option is available with the Warp Toolkit.

     -x[{1|2}]

 This option causes resources to be compressed.  These resources will be
 automatically decompressed when the resource is accessed.


ΓòÉΓòÉΓòÉ 6.4.4.5.1. Creating an RC File ΓòÉΓòÉΓòÉ

All resources are defined in a resource script file. You use a text editor to
create a resource script file that has an .RC extension. Resources are defined
either explicitly in statements in the resource script file, or in other files
(such as output files from the resource editors). The .RC file is the input
file to the RC; the output has an .RES extension. The .RC file can contain
statements that define resources and that include resources from other files.
Text-based resources such as menus, accelerator keys, and text strings are
defined in the .RC file. Non-text-based resources are specified in the .RC file
as file names of the external files where these resources reside. Such
resources include icons, pointers, and bit maps. The syntax for including
external files in a resource script varies according to the nature of the
resources defined or contained in the files. Fonts have a resource file to
themselves.

Make sure that none of the include files in your resource script file contain
an end-of-file character. When the RC sees an end-of-file character, it assumes
it to be the end of all input.

For an example of a resource script file, see the sample program TEMPLATE.


ΓòÉΓòÉΓòÉ 6.4.4.5.2. Starting RC ΓòÉΓòÉΓòÉ

You can start RC in three ways:

     Compile a resource script file and bind it to an executable file:

      To compile the resource script file EXAMPLE.RC and bind the resulting
      compiled resource (.RES) file to the executable file, EXAMPLE.EXE, use
      the following command:

              RC EXAMPLE

      You do not need to specify the .RC extension for EXAMPLE. The RC program
      creates the resource file EXAMPLE.RES and then adds the compiled resource
      to the executable file EXAMPLE.EXE.

     Compile a resource script file but do not bind it to the executable file:

      To compile the resource script file, EXAMPLE.RC, into a resource file
      without binding the resources to an executable file, use the following
      command:

              RC -R EXAMPLE

      The compiler creates the resource file EXAMPLE.RES.

     Compile a resource script file and put it in a DLL:

      Instead of binding a resource file to your application, you can put it in
      a dynamic link library. To add the compiled resources to a dynamic link
      library, use the following command:

              RC EXAMPLE.RES DYNALINK.DLL

      You can then link the file at run time and load the resources into your
      application by using DosLoadModule or GpiLoadFonts. However, you cannot
      switch from binding resources to putting resources into a dynamic link
      library without changing your application source code.


ΓòÉΓòÉΓòÉ 6.4.5. SOM Tools ΓòÉΓòÉΓòÉ

SOM tools help you develop SOM programs. This section describe the SOM tools:

     CTOI
     IRDUMP - Information Repository Dump
     PDL - Public Definition Language
     PREGIMPL  - PM version of REGIMPL
     REGIMPL - Implementation Registration
     SC - SOM Compiler
     SOMCORBA - SOM CORBA
     SOMDCHK - SOM Check
     SOMDD - SOM DSOM Daemon
     SOMDSRV - SOM Server
     SOMENV - SOM Environment
     SOMSTARS
     SOMXH - SOM .XH Header Files
     WPIDL2XH - Workplace Shell .IDL To .XH Files


ΓòÉΓòÉΓòÉ 6.4.5.1. CTOI ΓòÉΓòÉΓòÉ

CTOI automates the conversion process from the SOM 1.0 format (.CSC files) to
SOM 2.0 format (.IDL files). An example of the syntax follows:

  CTOI f1

where:

 f1   Is the name of the .CSC file to be converted.

 You may require some modifications to your environment and your existing code
 in order to use this tool successfully. For more information, see the article
 titled Using the SOM CTOI Tool in the online version of The Developer
 Connection News, Volume 5. This newsletter can be found by opening the
 following folders, starting with The Developer Connection folder:

    The Developer Connection Browser
      The Developer Connection for OS/2 References
        The Developer Connection News


ΓòÉΓòÉΓòÉ 6.4.5.2. IRDUMP ΓòÉΓòÉΓòÉ

IRDUMP (Information Repository Dump) verifies that a class exists in the
Information Repository. An example of the syntax follows:

  IRDUMP [-o] [-w] [-?] [object]

where:

 -o       Includes file offset information.
 -w       Follows dump with "within" operation.
 -?       Shows this usage information.
 object   Is a simple or fully-qualified name of an object in the Interface
          Repository.

 The default action is to dump all objects.


ΓòÉΓòÉΓòÉ 6.4.5.3. PDL ΓòÉΓòÉΓòÉ

PDL (Public Definition Language) is a separate program that performs the same
function as the Public Definition Language (PDL) emitter used with the SOM
Compiler.  That emitter generates a copy of an .IDL file which has the portions
designated as private removed. The file generated is the same as the .IDL file
from which it is produced, except that it removes all items within the .IDL
file that are marked as "private". An item is marked as private by surrounding
it with #ifdef __PRIVATE__ and #endif directives.  Thus, the PDL emitter can be
used to generate a "public" version of an .IDL file. (Generally, client
programs will need only the "public" methods and attributes.)

The PDL program can be invoked independently of the SOM Compiler.  In addition,
the PDL program can remove any kind of items in the .IDL file that are preceded
by a user-specified #ifdef directive and followed by an #endif directive.

The PDL program is invoked as follows:

  PDL [-c] [-d] [-f] [-h] [-s] [-/] files

where:

 -c cmd         Specifies that, for each .IDL file, the PDL program is to run
                the specified system command. This command may contain a single
                occurrence of the string %s, which will be replaced with the
                source file name before the command is executed. For example
                the option -c sc -sh %s has the same effect as issuing the SC
                command with the -sh option.

 -d dir         Specifies a directory in which the output files are to be
                placed. (The output files are given the same name as the input
                files). If no directory is specified, the output files are
                named <fileStem>.PDL (where fileStem is the file stem of the
                input file) and are placed in the current working directory.

 -h             Requests this description of the PDL command syntax and
                options.

 -f             Specifies that output files are to replace existing files with
                the same name, even if the existing files are read-only. By
                default, files are replaced only if they have write access.

 -s smemit      Specifies the SMEMIT variable with which the PDL program is to
                invoke the SOM Compiler.

 -/ <string>    Specifies the #ifdef pattern for which the PDL program will
                strip out .IDL statements.  The default value is #ifdef
                __PRIVATE__.

 files          Specifies one or more .IDL files whose specified #ifdef
                sections are to be removed. Filenames must be completely
                specified (with the .IDL extension). If no #ifdef directive is
                specified (by including a -/<string> option), then the #ifdef
                __PRIVATE__ sections will be removed by default.

 Selected options can be specified individually, as a string of option
 characters, or as a combination of both. Any option that takes an argument
 either must be specified individually or must appear as the final option in a
 string of option characters.


ΓòÉΓòÉΓòÉ 6.4.5.4. PREGIMPL ΓòÉΓòÉΓòÉ

PREGIMPL is a Presentation Manager version of the REGIMPL tool.


ΓòÉΓòÉΓòÉ 6.4.5.5. REGIMPL ΓòÉΓòÉΓòÉ

Before an implementation (a server program and class libraries) can be used by
client applications, it must be registered with DSOM by running the
Implementation Registration utility, REGIMPL. This facility is available
primarily for use in command (.CMD) files.

During execution of REGIMPL, DSOM updates its database to include the new
server implementation and the associated classes. This enables DSOM to find
and, if necessary, to activate the server so that clients can invoke methods on
it.

Below are some examples on how you can use REGIMPL.

     To enter interactive mode:

              REGIMPL

     To add implementation:

              REGIMPL -A -i <str> [-p <str>] [-v <str>] [-f <str>] [-b <str>]
                                  [-h <str>] [-m {on|off}] [-z <str>]

     To update implementation:

              REGIMPL -U -i <str> [-p <str>] [-v <str>] [-f <str>] [-b <str>]
                                  [-h <str>] [-m {on|off}]

     To delete implementation:

              REGIMPL -D -i <str> [-i ...]

     To list implementation(s):

              REGIMPL -L [-i <str> [-i ...]]

     To list aliases:

              REGIMPL -S

     To add class(es):

              REGIMPL -a -c <str> [-c ...] -i <str> [-i ...]

     To delete class(es):

              REGIMPL -d -c <str> [-c ...] [-i <str> [-i ...]]

     To list classes associated with implementation(s):

              REGIMPL -l [-i <str> [-i ...]]

      where:

      -i <str>            Is the implementation alias name.
      -p <str>            Is the server program name. The default value is
                          SOMDSVR.EXE.
      -v <str>            Is the server-class name. The default value is
                          SOMDServer.
      -f <str>            Is the reference data file name.  Use NULL to delete.
      -b <str>            Is the reference data backup file name. Use NULL to
                          delete.
      -h <str>            Is the host machine name. The default value is
                          localhost.
      -m {on|off}         Enables multi-threaded server.
      -z <str>            Is the implementation ID.
      -c <str>            Is the class name.


ΓòÉΓòÉΓòÉ 6.4.5.6. SC ΓòÉΓòÉΓòÉ

The OS/2 operating system provides a programming interface that allows
applications to implement Desktop objects. This programming interface enables
you to create Desktop objects that conforms to the CUA architecture using basic
object-oriented programming interface. The interface is implemented using the
IBM SC (SOM Compiler).

The SOM Compiler (SC) helps implementers build classes in which interface and
implementation are decoupled.  The SOM Compiler reads the IDL definition of a
class interface and generates:

     An implementation skeleton for the class
     Bindings for implementors
     Bindings for client programs

 Bindings are language-specific macros and procedures that make implementing
 and using SOM classes more convenient. These bindings offer a convenient
 interface to SOM that is tailored to a particular programming language. For
 instance, C programmers can invoke methods in the same way they make ordinary
 procedure calls. The C++ bindings "wrap" SOM objects as C++ objects, so that
 C++ programmers can invoke methods on SOM objects in the same way they invoke
 methods on C++ objects. In addition, SOM objects receive full C++
 typechecking, just as C++ objects do. Currently, the SOM Compiler can generate
 both C and C++ language bindings for a class.


ΓòÉΓòÉΓòÉ 6.4.5.6.1. Starting SC ΓòÉΓòÉΓòÉ

The SOM compiler is actually a precompiler and a collection of code emitters
that produce binding files from the output of the precompiler. The files have
several forms, including C-header files, a C-implementation template, and the
language-neutral version of the class definition file.

To start the SOM precompiler from the command line, type:

 SC [-C] [-D] [-E] [-I] [-S] [-U] [-V] [-c] [-d] [-h] [-i] [-m] [-p] [-r]
    [-s] [-u] [-v] [-w] f1 f2 ...

where:

  -C <n>                Is the size of the comment buffer. The default value is
                        49152.
  -D <DEFINE>           Is the same as the -D option for cpp.
  -E <var>=<value>      Is the set environment variable.
  -I <INCLUDE>          Is the same as the -I option for cpp.
  -S <n>                Is the size of the string buffer. The default is 49152.
  -U <UNDEFINE>         Is the same as the -U option for cpp.
  -V                    Shows the version number of the compiler.
  -c                    Ignores all comments.
  -d <dir>              Is the output directory for each emitted file.
  -h                    Is this message.
  -i <file>             Uses this file name as supplied.
  -m <name[=value]>     Adds a global modifier.
  -p                    Is a shorthand for -D__PRIVATE__.
  -r                    Checks if the releaseorder entries exist. The default
                        value is FALSE.
  -s <string>           Replaces the SMEMIT variable with a <string>.
  -u                    Updates the interface repository.
  -v                    Verboses the debugging mode. The default value is
                        FALSE.
  -w                    Does not display warnings. The default value is FALSE.
 file1, file2           Is the name of a file that contains an OIDL class
                        definition. If you do not specify a file-name
                        extension, the compiler uses .IDL by default.

 The options can be specified individually, as a string of option characters,
 or as a combination of these forms. Any option that takes an argument must be
 specified individually or be the final option in a string of option
 characters.

 The modifiers are as follows:

 addprefixes            Adds functionprefix to method names in template file
 [no]addstar            Does not add a * to C bindings for interface
                        references.
 corba                  Checks the source for CORBA compliance.
 csc                    Forces running of the OIDL compiler.
 emitappend             Appends the emitted files at the end of an existing
                        file.
 noheader               Does not add a header to the emitted file.
 noint                  Does not warn about int causing portability problems.
 nolock                 Does not lock the IR during update.
 nopp                   Does not run the source through the pre-processor.
 notc                   Does not use typecodes for emit information.
 nouseshort             Does not generate short names for types.
 pp=<path>              Specifies a local pre-processor to use.
 tcconsts               Generates CORBA type code constants.


ΓòÉΓòÉΓòÉ 6.4.5.6.2. SMEMIT Environment Variable ΓòÉΓòÉΓòÉ

SMEMIT is used to indicate which emitter programs should be executed. Like the
SMINCLUDE environment variable it can consist of a list of items separated by
semicolons. Each item designates a particular emitter by the name of the file
extension the emitter produces. The syntax is as follows:

  SMEMIT=[h;ih;c;xh;xih;xc;def;ir;pdl]

The default values are h and ih. For example:

  SET SMEMIT=H;IH;DEF;

indicates that EMITH.EXE, EMITIH.EXE, and EMITDEF.EXE programs should be
executed to produce .H, .IH, and .DEF files, respectively. By default all
emitted output files are placed in the same directory as the input file. If the
SMEMIT environment variable is not defined, the SOM compiler will perform a
syntax check of your class definition but no output will be produced.

Note:  All command-line modifiers can be set in the environment by changing
       them to UPPERCASE and preappending SM to them.


ΓòÉΓòÉΓòÉ 6.4.5.6.3. SMINCLUDE Environment Variable ΓòÉΓòÉΓòÉ

The SOM compiler uses an environment variable called SMINCLUDE to locate
included class definitions. SMINCLUDE specifies where to search for .IDL and
.EFW files. Because every SOM class will have an include file for its parent
class definition, you must set SMINCLUDE before running the SOM compiler. Its
form is similar to the OS/2 PATH or DPATH environment variables, in that it can
consist of one or more directory names, separated by a semicolon. Directory
names can be specified with absolute or relative path names. The syntax is as
follows:

  SMINCLUDE=<dir1>[;<dir2>]+

For example:

  SET SMINCLUDE=.;C:\TOOLKIT\SOM\INCLUDE;C:\TOOLKIT\IDL;

Note:  All command-line modifiers can be set in the environment by changing
       them to UPPERCASE and preappending SM to them.


ΓòÉΓòÉΓòÉ 6.4.5.6.4. SMKNOWNEXTS Environment Variable ΓòÉΓòÉΓòÉ

SMKNOWNEXTS add headers to user written emitters. The syntax is as follows:

  SMKNOWNEXTS=ext[;ext]+

Note:  All command-line modifiers can be set in the environment by changing
       them to UPPERCASE and preappending SM to them.


ΓòÉΓòÉΓòÉ 6.4.5.6.5. SMTMP Environment Variable ΓòÉΓòÉΓòÉ

The SMTMP environment variable specifies the name of a directory that the SOM
compiler uses to hold intermediate output files. The syntax is as follows:

  SMTMP=<dir>

For example:

  SET SMTMP=%TMP%

tells the SOM compiler to use the same directory for temporary files as given
by the setting of the TMP environment variable. As a general rule, the
directory indicated by SMTMP should never coincide with the directory used by
the SOM compiler for its input or the emitted output files.

Note:  All command-line modifiers can be set in the environment by changing
       them to UPPERCASE and preappending SM to them.


ΓòÉΓòÉΓòÉ 6.4.5.6.6. SOMIR Environment Variable ΓòÉΓòÉΓòÉ

SOMIR provides a list of IRs to search for. The syntax is as follows:

 SOMIR=<path>[;<path>]+

Note:  All command-line modifiers can be set in the environment by changing
       them to UPPERCASE and preappending SM to them.


ΓòÉΓòÉΓòÉ 6.4.5.6.7. #pragma Directives ΓòÉΓòÉΓòÉ

There are two pragma directives:

 #pragma somemittypes on                 Turns on the emission of global types.

 #pragma somemittypes off                Turns off the emission of global
                                         types.

 #pragma modifier <modifier stm>         Used instead of modifier statement.


ΓòÉΓòÉΓòÉ 6.4.5.6.8. Running SOM Emitters ΓòÉΓòÉΓòÉ

You complete the SOM compilation process by running the emitters. You can
control the output of the emitters from the command line by typing:

  COMMAND [-o filename] [-a name[=value]]*

where:

 command              Is one of the following:

                                    EMITH
                                    EMITIH
                                    EMITC
                                    EMITDEF

 -o                   Is an explicit name (including drive, path, and file-name
                      extension) for the emitted output file. If this option is
                      not specified, the output file is placed in the current
                      directory, and the file-name extension defaults to a type
                      appropriate to the selected emitter program.

 -a name[=value]      Adds a global attribute.


ΓòÉΓòÉΓòÉ 6.4.5.7. SOMCORBA ΓòÉΓòÉΓòÉ

SOMCORBA is a command script to convert to implicit pointers (like CORBA) for
interface references.


ΓòÉΓòÉΓòÉ 6.4.5.8. SOMDCHK ΓòÉΓòÉΓòÉ

SOMDCHK evaluates the environment to verify whether DSOM can operate correctly.
The program generates messages that evaluate the DSOM environment. It
determines whether the necessary SOM DLLs can be located, whether DSOM is
enabled for workgroup (cross-machine) communication, whether Interface and
Implementation Repositories can be located, and it displays the settings of
important environment variables. In its "verbose" mode, SOMDCHK gives the
default settings for DSOM environment variables and explains how DSOM uses
them.

The program is invoked from the command line using the syntax given below. The
optional verbose setting can be turned on by including the -v option with the
following command:

  SOMDCHK [-v]


ΓòÉΓòÉΓòÉ 6.4.5.9. SOMDD ΓòÉΓòÉΓòÉ

SOMDD is the DSOM daemon. It must be started prior to running a DSOM
application. The daemon can be started manually from the command line, or it
could be started automatically from a start-up script run at boot time. It may
be run in the background with the following command:

  START SOMDD

The SOMDD program requires no parameters. An optional -q  parameters can be
used to set "quiet" mode, to suppress messages.

Note:  The SOMDD.EXE program shipped with VisualAge C++ is incompatible with
       the version of SOM used with Warp Toolkit and should not be used. You
       will need to update both your LIBPATH and PATH statements to ensure that
       the Warp Toolkit path is ahead of the VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 6.4.5.10. SOMDSVR ΓòÉΓòÉΓòÉ

SOMDSVR is the "generic" server program. It can be started either from the
command line or automatically upon demand. When starting SOMDSVR from the
command line, the server's implementation ID or alias must be supplied as an
argument. The command syntax for starting a generic SOM server is:

  SOMDSVR [impl_id | -a alias]


ΓòÉΓòÉΓòÉ 6.4.5.11. SOMENV ΓòÉΓòÉΓòÉ

SOMENV is a command script to set the environment variables required for SOM
programming. This command script requires that the SOMBASE environment variable
be set.


ΓòÉΓòÉΓòÉ 6.4.5.12. SOMSTARS ΓòÉΓòÉΓòÉ

SOMSTARS is a command script to convert to explicit pointers for interface
references.


ΓòÉΓòÉΓòÉ 6.4.5.13. SOMXH ΓòÉΓòÉΓòÉ

SOMXH is a command script to create the .XH header files from the .IDL files
located in the \TOOLKIT\SOM\INCLUDE subdirectory.


ΓòÉΓòÉΓòÉ 6.4.5.14. WPIDL2XH ΓòÉΓòÉΓòÉ

WPIDL2XH.CMD is a command file to emit .XH header files from Workplace Shell
.IDL files.

To re-generate the .XH headers for C++, invoke this command file on each
Workplace Shell class .IDL file from the Toolkit. It is only necessary to do
this when you upgrade to a new level of SOM.  Invoking the SOMXH command script
will create .XH files for you, as the Workplace Shell classes currently only
maintain passthru sections for .H files for C. The syntax is as follows:

  WPIDL2XH <inputfile>


ΓòÉΓòÉΓòÉ 6.4.6. Workplace Shell Tools ΓòÉΓòÉΓòÉ

This section describes the Workplace Shell tools which help you develop
Workplace Shell programs. There are two Workplace Shell tools in this release:

     OBJUTIL - Object Utility/2
     WPCLSLST - Workplace Class List


ΓòÉΓòÉΓòÉ 6.4.6.1. OBJUTIL ΓòÉΓòÉΓòÉ

OBJUTIL (Object Utility/2) is a new Workplace Shell tool that provides a
facility for registering classes, and creating and modifying instances of
classes.


ΓòÉΓòÉΓòÉ 6.4.6.2. WPCLSLST ΓòÉΓòÉΓòÉ

WPCLSLST (Workplace Class List) creates a workplace object class and an
instance of a workplace object class. Workplace objects are constructed using
the SOM protocol and are instances of one of the following workplace object
classes:

 Predefined     These classes are defined by the system. Examples of predefined
                workplace object classes are WPObject, WPFileSystem, and
                WPAbstract.

 Subclass       These classes are derived from existing predefined workplace
                object classes. They add or remove function; however, they
                retain the basic behavior of that class.

 Replaced       These classes replace the class being subclassed. They notify
                the behavior of an instance of a predefined workplace object
                class without the instance being aware of the new class.


ΓòÉΓòÉΓòÉ 6.4.6.2.1. Starting WPCLSLST ΓòÉΓòÉΓòÉ

To start the Workplace Class List, select the PM Development Tools folder, then
select the WP Class List object. A window similar to the following appears:

Using this window, you can:

     Add, delete, and browse registered Workplace Class Objects
     Create an instance of a Workplace Class Object
     View the registered Workplace Class Object in the system.


ΓòÉΓòÉΓòÉ 6.5. Online Documentation ΓòÉΓòÉΓòÉ

The following list describes manuals available online that might be of interest
to users who develop applications for OS/2 Warp Version 3. The OS/2 Warp
Version 3 Technical Library provides both guidance and reference information
and can be used for OS/2 Warp Version 3 development. The library includes the
following online books:

     Bidirectional Language Support Dev. Guide and Reference
     Control Program Guide and Reference
     Debug Kernel Reference
     Graphics Programming Guide and Reference
     IBM Developer API Extensions for OS/2 Programming Guide
     Information Presentation Facility Guide and Reference
     Multimedia Application Programming Guide
     Multimedia Programming Reference
     Multimedia Subsystem Programming Guide
     OpenDoc Programming Guide
     OpenDoc Programming Reference
     OpenDoc User Interface Guidelines
     Open Scripting Architecture Guide and Reference
     Presentation Manager Programming Guide and Reference
     SOM Programmers Reference
     SOM User's Guide
     Tools Reference
     Workplace Shell Programming Guide
     Workplace Shell Programming Reference

 These books are located in the \TOOLKIT\BOOK subdirectory. You can also access
 them from the Desktop by opening the Toolkit folder and then the Toolkit
 Information folder.


ΓòÉΓòÉΓòÉ 6.5.1. Bidirectional Language Support Dev. Guide and Reference ΓòÉΓòÉΓòÉ

This book provides information about the interface (API) for the Arabic and
Hebrew languages thus allowing programmers to create Arabic or Hebrew
applications for this environment.

The Bidirectional support in PM is provided in the Arabic and Hebrew language
versions of the OS/2 operating system. The support is active/configured when
the COUNTRY selection during OS/2 installation is Arabic or Hebrew in these
versions.


ΓòÉΓòÉΓòÉ 6.5.2. Control Program Guide and Reference ΓòÉΓòÉΓòÉ

This book provides the C-language syntax for each of the base operating-system
application programming interface (API), including input and output parameters,
data structures, data types, return codes, and example codes. Guidance
information is also provided to assist you in developing applications using
these items. API functions (indicated by the prefix "Dos") are presented by
component; such as Error Management, Exception Management, and File System. The
API functions, within each of the components to which they apply, are listed in
alphabetic order. API functions also are available from a single alphabetic
list. The online Control Program Guide and Reference contains the information
of the Control Program Programming Guide and the Control Program Programming
Reference books.


ΓòÉΓòÉΓòÉ 6.5.3. Debug Kernel Reference ΓòÉΓòÉΓòÉ

This book provides details on the debug kernel, installation, debugging
commands and syntax, and the debug PM interface.


ΓòÉΓòÉΓòÉ 6.5.4. Graphics Programming Guide and Reference ΓòÉΓòÉΓòÉ

This book describes the concepts associated with graphical output--presentation
spaces, device contexts, graphic primitives, fonts--and how to prepare
graphical output for display and printing.  It provides the C-language syntax
for all the graphical programming interface (GPI), including input and output
parameters, data structures, data types, return codes, and example codes.
Guidance information is also provided to assist you in developing applications
using these items. GPI functions (indicated by the prefix "Gpi") are listed in
alphabetic order. The online Graphics Programming Guide and Reference contains
the information of the Graphics Programming Guide and the Graphics Programming
Reference books.


ΓòÉΓòÉΓòÉ 6.5.5. IBM Developer API Extensions for OS/2 Programming Guide ΓòÉΓòÉΓòÉ

The IBM Developer API Extensions for OS/2 Programming Guide provides
information on the following topics:

     What the IBM Developer API Extensions for OS/2 are and how they help you
      either:

        -  Migrate Windows code to OS/2 code
        -  Write common source code for OS/2 and Windows

     How to use the SMART tool to analyze Windows code and see how much effort
      is involved to migrate it to OS/2 code

     Differences in behavior between some IBM Developer API Extensions for
      OS/2 functions and their Windows counterparts

     Changes to the Resource Compiler due to IBM Developer API Extensions for
      OS/2

     The functions supported by the IBM Developer API Extensions for OS/2


ΓòÉΓòÉΓòÉ 6.5.6. Information Presentation Facility Guide and Reference ΓòÉΓòÉΓòÉ

This book describes the concepts--help windows, hypertext linking,
author-controlled viewports, dynamic data formatting--and the functions used
for implementing help in OS/2 applications. It describes how to create online
help and information. It also contains an alphabetic list of IPF tags, symbols,
and control words. The IPFC error messages, window functions, dynamic data
formatting functions, and help manager messages and functions are included.


ΓòÉΓòÉΓòÉ 6.5.7. Multimedia Application Programming Guide ΓòÉΓòÉΓòÉ

This book describes the concepts associated with managing audio and video data
and hardware using an extendable architecture that includes logical media
devices (amplifier-mixer, waveform audio, MIDI sequencer, CD-audio, CD-XA,
digital video, and videodisc) and I/O procedures for supporting various file
formats.


ΓòÉΓòÉΓòÉ 6.5.8. Multimedia Programming Reference ΓòÉΓòÉΓòÉ

This book describes the media control interface, PM graphic push buttons,
secondary windows functions, multimedia I/O services, direct interface video
extensions (DIVE), and subsystem services for synchronization and streaming.


ΓòÉΓòÉΓòÉ 6.5.9. Multimedia Subsystem Programming Guide ΓòÉΓòÉΓòÉ

This book describes the subsystem components--media control driver, stream
handler, and I/O procedure--that support a multimedia device.


ΓòÉΓòÉΓòÉ 6.5.10. OpenDoc Programming Guide ΓòÉΓòÉΓòÉ

This guide is intended for application developers creating programs using the
OpenDoc interface for OS/2 Warp who want to gain an understanding of the
OpenDoc programming environment and to develop part editors.


ΓòÉΓòÉΓòÉ 6.5.11. OpenDoc Programming Reference ΓòÉΓòÉΓòÉ

This book is a detailed technical reference for application programmers
creating programs using the OpenDoc interface for OS/2 Warp. It gives reference
information and code examples to enable you to write source code using
Workplace classes and methods.


ΓòÉΓòÉΓòÉ 6.5.12. OpenDoc User Interface Guidelines ΓòÉΓòÉΓòÉ

The OpenDoc User Interface Guidelines describe the human interface mechanisms
and interactions essential to the OpenDoc software architecture. It combines a
discussion of the philosophy of the OpenDoc Human Interface with the actual
implementation of interface elements. In addition to text-based discussions,
this document makes use of screen captures and user scenarios to further
facilitate the developer's understanding of OpenDoc.


ΓòÉΓòÉΓòÉ 6.5.13. Open Scripting Architecture Guide and Reference ΓòÉΓòÉΓòÉ

This reference is a detailed technical guide and reference for application
programmers creating programs using OS/2 Warp. It gives reference information
and code examples to enable you to write source code using OSA functions,
classes, methods, and data types.


ΓòÉΓòÉΓòÉ 6.5.14. OS/2 Tools Reference ΓòÉΓòÉΓòÉ

This book describes the tools that are included in the IBM Developer's Toolkit
for OS/2 Warp.


ΓòÉΓòÉΓòÉ 6.5.15. Presentation Manager Programming Guide and Reference ΓòÉΓòÉΓòÉ

This book provides the C-language syntax for the base operating-system
application programming interface (API), including input and output parameters,
data structures, data types, return codes, and example codes. API function
prefixes include Drg (dragdrop), Ddf (dynamic data format), Prf (profile), Spl
(spooler), and Win (window). Also included are application hooks and PM
messages. The online Presentation Manager Programming Guide and Reference is a
combination of the information found in the hardcopy Presentation Manager
Programming Guide and Presentation Manager Programming Reference.


ΓòÉΓòÉΓòÉ 6.5.16. REXX Program Reference ΓòÉΓòÉΓòÉ

This book provides detailed descriptions of the REXX functions.


ΓòÉΓòÉΓòÉ 6.5.17. SOM Programmers Reference ΓòÉΓòÉΓòÉ

This book is a complete reference for each of the classes and methods used for
the object-oriented programming environment. Also included are System Object
Model (SOM) C-language and C++ bindings, the Object Interface Definition
Language syntax, and the SOM compiler command syntax.


ΓòÉΓòÉΓòÉ 6.5.18. SOM User's Guide ΓòÉΓòÉΓòÉ

This book explains how programmers using C, C++, and other languages can:

     Implement class libraries that exploit the SOM library-packaging
      technology

     Develop client programs that use class libraries that were built using
      SOM

     Develop applications that use the frameworks supplied with the SOMobjects
      Toolkit, class libraries that facilitate development of object-oriented
      applications.


ΓòÉΓòÉΓòÉ 6.5.19. Workplace Shell Programming Guide ΓòÉΓòÉΓòÉ

This book describes the concepts associated with object-oriented programming
for the OS/2 operating system--SOM, Workplace Shell classes and methods--and
how to create object-oriented applications for the OS/2 Desktop.


ΓòÉΓòÉΓòÉ 6.5.20. Workplace Shell Programming Reference ΓòÉΓòÉΓòÉ

This book provides the detailed descriptions of the Workplace Shell
object-oriented programming interface.


ΓòÉΓòÉΓòÉ 6.5.21. How to Use Online Documents ΓòÉΓòÉΓòÉ

The online documents in the Warp Toolkit were developed with IPF. IPF displays
information through a familiar user interface and lets you do the following:

     View a table of contents from which you can quickly gain access to a
      category
     View the category and select related topics from a menu
     View multiple windows of related information for comparison values
     Search for a topic throughout the document
     Copy the contents of a topic to the system clipboard for editing with the
      OS/2 System Editor, the Enhanced Editor, or any other editor with this
      capability
     Copy the contents of a topic to a temporary file for editing with a text
      editor.

 When installed, the online documents are added to the Toolkit Information
 folder. To access the online documents, double-click on the folder, then
 select the appropriate book. A window that has a table of contents (Contents
 window) will appear.

 When the Contents window first appears, some categories have a plus sign (+)
 beside them. The plus sign indicates that additional topics are available.
 Using mouse button 1, click on the plus sign to expand the category.

 For more information about using the Warp Toolkit online documents, refer to
 the How to Use the Using Your Toolkit Book section.


ΓòÉΓòÉΓòÉ 6.6. Try Me! ΓòÉΓòÉΓòÉ

The Try Me! component, formerly called NeatStuff, contains new tools or samples
that execute on generally available versions of OS/2, such as OS/2 Warp Version
3. These tools and samples are provided to obtain feedback from you, our
customers. We are considering adding these tools and samples to the Toolkit
permanently. The content of this component can vary from volume to volume of
The Developer Connection for OS/2.

Try Me! is installed by default by the Developer's Toolkit for OS/2
installation program, but the component can be deselected prior to installing
to save space on your hard disk. All files installed via the Try Me! component
are installed in the \TOOLKIT\BETA directory structure by default.

Note:  These utilities are pre-release and unsupported versions, and are
       provided on an "as is" basis for evaluation and demonstration. They are
       not intended for use with production code.


ΓòÉΓòÉΓòÉ 6.6.1. Development Tools ΓòÉΓòÉΓòÉ

This section describes the following tools provided to help you develop OS/2
programs:

     ALP - Assembly Language Processor
     P2STRING
     URE - Universal Resource Editor


ΓòÉΓòÉΓòÉ 6.6.1.1. ALP ΓòÉΓòÉΓòÉ

ALP (Assembly Language Processor) is a macro assembler that runs under the
32-bit OS/2 operating system. In its initial form, ALP is designed as a
functional replacement for the Microsoft Macro Assembler (MASM), Version 5.1.
It accepts the full syntax of the Intel 80X86 architecture, and a subset of
MASM's high-level directive language. ALP creates standard Object Module Format
(.OMF) files that can be linked to produce DOS or OS/2 executables, and can
generate line number debug information compatible with IBM's Presentation
Manager Debugger. In addition, this tool offers a rich set of command line
options, as well as a comprehensive listing file with user-tailored formatting,
allowing a visual perspective not possible with other assemblers.

ALP translates assembly language source files (typically having a filename
extension of .ASM) into object (.OBJ) files. The LINK386 utility can then be
used to combine multiple object files into a single executable file, dynamic
link library, or device driver.

While ALP is designed as a functional replacement for the Microsoft MASM
assembler in terms of source code compatibility, it does not use the MASM
command line syntax. ALP uses a free-form syntax, has a comprehensive set of
options, and allows assembly of multiple input files with a single command line
invocation.

For each corresponding input source file, ALP can produce the following types
of output files:

     Object (.OBJ) files containing program data and executable code.
     Listing (.LST) files which document the results of the assembly.
     Message (.MSG) files which can contain all error, warning, and
      informational messages produced during the assembly.

 An online document, Assembly Language Processor Reference Guide, is available
 in the Beta Information folder. You can access this folder by opening the
 Toolkit folder and then opening the BETA folder. Online help is also available
 from the command line for all ALP options.


ΓòÉΓòÉΓòÉ 6.6.1.1.1. Starting ALP ΓòÉΓòÉΓòÉ

To start ALP from the command line, change to the TOOLKIT\BETA\BIN subdirectory
and type:

  ALP

Note:  ALP cannot be started from the Desktop.


ΓòÉΓòÉΓòÉ 6.6.1.2. P2STRING ΓòÉΓòÉΓòÉ

P2STRING is used to test OS/2 multimedia subsystems through the media control
interface string commands in OS/2 multimedia environment. This tool processes
script files (containing string commands and tool directives) to test the
behavior of subsystems in OS/2 multimedia.  P2STRING extracts the strings from
the script files and processes the commands through the mciSendString function.
Messages and error conditions of the processes included in the scripts are
logged to an output file and displayed in windows.

P2STRING provides subsystem developers with an effective testing and because it
alleviates the need for extensive test code to be written. Developers can write
script files to test all relevant scenarios, and it also aids in debugging
using log files.

Note:  Refer to the README file in the P2STRING subdirectory for information
       about how to use P2STRING and how to create script files that it can
       process.


ΓòÉΓòÉΓòÉ 6.6.1.3. URE ΓòÉΓòÉΓòÉ

URE (Universal Resource Editor) provides a graphical user interface by which
you can design dialogs, menus, and other OS/2 program resources. You can create
binary resource files, resource scripts, and symbol definition files.

For any new resource design, URE allows you to:

     Select the applicable operating environment, file names and formats from
      the New Design dialog.
     Choose the type of presentation from the New Dialog/Window dialog.
     Set the appearance of your window from the Window/Dialogue Styles dialog.
     Select controls for your window from the Tools window.
     Include multiple windows and file resources with any design.
     Save your finished resource design to a binary file for later attachment
      to an executable program.
     Edit an existing resource design and copy parts from one design to
      another.

 This tool has been significantly enhanced with the following:

     Double-byte character set (DBCS) support for input and output of
      double-byte characters
     Enhanced user interface and documentation

 This level of URE runs on a Warp system but does not run in an OS/2 2.1
 environment. The URE shipped with the Warp Toolkit on the Developer Connection
 for OS/2, Volume 8 must be used to edit resource files defined for an OS/2 2.1
 environment.

 An online document, Universal Resource Editor for OS/2 User's Guide, is
 available in the Try Me! folder. Online help is also available for menus,
 buttons, and dialogs you use while running URE and related samples.

 Note:  IBM supports the version of Dialog Editor in this release of the Warp
        Toolkit, but will not be enhancing or otherwise changing Dialog Editor
        in future releases. URE (Universal Resource Editor) will become the
        editor of choice for creating and modifying dialogs and other
        resources.


ΓòÉΓòÉΓòÉ 6.6.1.3.1. Starting URE ΓòÉΓòÉΓòÉ

You can start URE in two ways:

     From the command line, change to the TOOLKIT\BETA\BIN subdirectory and
      type:

              URE

      URE has a number of sample programs that are installed into
      subdirectories below the TOOLKIT\BETA\SAMPLES\URE subdirectory path.

     From the Desktop, open the Toolkit folder and then:

        1. Open the Try Me! folder.

        2. Double-click on Universal Resource Editor.


ΓòÉΓòÉΓòÉ 6.6.1.3.2. Replacing DLGEDIT ΓòÉΓòÉΓòÉ

IBM supports the version of DLGEDIT (Dialog Editor) in this release of the Warp
Toolkit, but will not be enhancing or otherwise changing the Dialog Editor in
future releases. URE (Universal Resource Editor) will become the editor of
choice for creating and modifying dialogs and other resources.


ΓòÉΓòÉΓòÉ 6.6.2. OpenDoc Samples ΓòÉΓòÉΓòÉ

The following OpenDoc source code is provided as is:

     Container Part
     Public Utilities Library


ΓòÉΓòÉΓòÉ 6.6.2.1. Container Part ΓòÉΓòÉΓòÉ

The \TOOLKIT\BETA\SAMPLES\OPENDOC\PARTS\CNTNRPRT subdirectory contain the
source code for the Container part. This part handler demonstrates changing the
menu, embedding other parts, and drag and drop.

See Known Limitations for a list of items to consider when using the Container
part.


ΓòÉΓòÉΓòÉ 6.6.2.1.1. Known Limitations ΓòÉΓòÉΓòÉ

The Container part has the following known limitations. Note that the behavior
described below will be exhibited by all samples which subclass from the
Container part.

     A SYS3175 error occurs when you select Open As->Details from the
      Container part's View menu.  This error will close the document.

     A SYS3175 error occurs when saving a document containing a selected
      Container part inside a root Container part.  It will occur if the
      selected part subclasses from the Container part.  This error does not
      occur if the selected part, for example, is the Cookbook part.

     The Container part's Show As menu selection from the View menu does not
      work correctly. This selection will incorrectly change the view type of
      selected parts, when it should only change the activated part's view
      type. The correct way to change the view type of selected parts would be
      to select Show selection as from the Edit menu.

     The Move selection from the Edit menu is incorrectly enabled for an
      activated part. The Move selection, like all Edit menu selections, are
      for selected parts only.

     A part that subclasses from the Container part may not have its intrinsic
      content clipped correctly to the embedded parts.  The Container part
      correctly handles the clipping of its embedded parts, but there is no way
      for a part that subclasses from the Container part to tell the Container
      part how to clip the embedded parts to its own content. Generally, the
      subclass part's intrinsic content will write over the embedded parts.


ΓòÉΓòÉΓòÉ 6.6.2.2. Public Utilities Library ΓòÉΓòÉΓòÉ

The Public Utilities Library is located in the
\TOOLKIT\BETA\SAMPLES\OPENDOC\PUBUTILS directory.

The Public Utilities Library is a static library built using the IBM C Set ++
compiler. If you are not using that compiler, you must recompile the library
using your own C++ compiler in order for the functions in the library to work
properly.

See the OpenDoc Programming Guide for more information on the public utilities.


ΓòÉΓòÉΓòÉ 6.6.3. OpenDoc Tools ΓòÉΓòÉΓòÉ

The following OpenDoc tool is available for you to try:

     PartMeister Code Generation Tool


ΓòÉΓòÉΓòÉ 6.6.3.1. PartMeister Code Generation Tool ΓòÉΓòÉΓòÉ

PartMeister is an easy to use tool for creating OpenDoc components from
templates.  It ships with a template for a container parent component.

New components can be generated with the IDL, CPP, make and resource files
being created.

New templates can be added, providing greater function for the tool.

See the PartMeister User's Guide for more information.  (You can access this
book from the Desktop by opening the Toolkit folder and then the Try Me!
folder.)

This version of PartMeister is full function with the exception of being able
to add and remove templates. This function is available in the downloadable
version.

Updated versions of PartMeister and additional templates are available at
http://www.software.ibm.com/clubopendoc/ on the World Wide Web.


ΓòÉΓòÉΓòÉ 6.6.4. Online Documentation ΓòÉΓòÉΓòÉ

This section describes the online documentation (located in \TOOLKIT\BETA\BOOK)
available via the Try Me! component. You can access these books from the
Desktop by opening the Try Me! folder which is located within the Toolkit
folder.

     Assembly Language Processor Reference Guide
     PartMeister User's Guide
     Universal Resource Editor User's Guide


ΓòÉΓòÉΓòÉ 6.6.4.1. Assembly Language Processor Reference Guide ΓòÉΓòÉΓòÉ

This book describes how to install and run the ALP assembler. It provides a
complete description of the following:

     Installation
     Command line syntax
     Environment variables
     Assembler return codes
     Message descriptions and recovery


ΓòÉΓòÉΓòÉ 6.6.4.2. PartMeister User's Guide ΓòÉΓòÉΓòÉ

This book provides guidance for using the PartMeister Code Generation Tool.
Information is provided on the following topics:

     Installation and Configuration
     Creating a Template


ΓòÉΓòÉΓòÉ 6.6.4.3. Universal Resource Editor User's Guide ΓòÉΓòÉΓòÉ

This book provides information on the following URE features:

     Using the tool bar, status window, and symbol definition window
     Using all dialogs
     Designing an application with URE
     Adding backing code to a design
     Running a prototype
     Adding new elements to a process
     Rebuilding an application
     Using PM control extensions
     Setting styles and CUA guidelines
     Creating resource DLLs
     Using accelerators in a resource design.


ΓòÉΓòÉΓòÉ 6.7. BETA ΓòÉΓòÉΓòÉ

The BETA component contains new tools, samples, online documentation and API
support for function in future versions of the operating system. Execution of
these pieces will typically require additional runtime support provided by a
Beta version of OS/2 Warp. In general, Beta versions of the operating system
are available on The Developer Connection for OS/2. However, there will be
cases, as in this volume's entertainment samples and tools, where the runtime
support is included with the Developer's Toolkit for OS/2 Warp.

The content of this component can vary from volume to volume of The Developer
Connection for OS/2. This component is not installed by default by the
Developer's Toolkit for OS/2 installation program, but the component can be
selected prior to installing. All files installed via the BETA component are
installed in the \TOOLKIT\BETA directory structure by default.

In this release of the Warp Toolkit, the BETA component includes Entertainment
Support.


ΓòÉΓòÉΓòÉ 6.7.1. BRender Samples ΓòÉΓòÉΓòÉ

There is one BRender sample in this release:

 ROBOT - Walking Robot


ΓòÉΓòÉΓòÉ 6.7.1.1. ROBOT ΓòÉΓòÉΓòÉ

Note:  You must read the Argonaut Non-Commercial License before using this
       sample.

 ROBOT demonstrates how to use the new OS/2 version of Argonaut's BRender
 technology. The BRender technology allows for real-time, three-dimensional
 (3D) manipulation of actors. An actor can be the actual object model, a
 camera, or a light. The objects are composed of polygons. These polygons can
 be moved independently or in conjunction with each other.

 While BRender provides all the functions necessary for the 3D transformation
 of the scene, it requires that system-specific code be used for blitting to
 the screen.  There are two parts to the design. One is the use of BRender to
 perform the 3D manipulations, and the other is the use of DIVE (DIVE provides
 a faster method of blitting) to allocate and display the image buffer and to
 do any palette manipulations.

 ROBOT does the following:

     Performs initialization
     Imports data for models, materials and textures
     Renders the scene
     Modifies object positions and orientations via user interface.

 This sample demonstrates a robot walking. The mouse can be used to zoom in and
 out and also to rotate the robot in 3D space.


ΓòÉΓòÉΓòÉ 6.7.1.1.1. Starting ROBOT ΓòÉΓòÉΓòÉ

You can start ROBOT in two ways:

     From the command line, change to the TOOLKIT\BETA\BRENDER\SAMPLES\ROBOT
      subdirectory and type:

              ROBOT

     From the Desktop, open the Toolkit folder and then:

        1. Open the BETA folder.

        2. Open the BRender folder.

        3. Open the BRender Samples folder.

        4. Double-click on Robot.


ΓòÉΓòÉΓòÉ 6.7.2. BRender Tools ΓòÉΓòÉΓòÉ

The following BRender tool is provided in this release: 3DS2BR


ΓòÉΓòÉΓòÉ 6.7.2.1. 3DS2BR ΓòÉΓòÉΓòÉ

3DS2BR is a DOS command line tool which runs in protected mode using a DOS/4GW
extender.  It expects a minimum configuration of a 486DX-33 PC with 8 MB RAM.
Some large 3DS files can require more memory.

In general terms, 3DS2BR reads any 3DS Binary file and interprets all elements
of the file that relate to triangle mesh geometry, materials (including texture
mapping), object hierarchy, lights and cameras.  It completely ignores
information in the file that it is not designed to understand, such as certain
undocumented elements saved by 3D Studio Releases 3 and 4, but this extra data
does not cause 3DS2BR to malfunction.  For a detailed breakdown of what 3DS
information is and is not converted, see the 3D Studio to BRender Converter
online documentation for a description of Studio binary file elements.

3DS2BR converts the interpreted information to its nearest BRender equivalent
and then, depending on the command line flags you have set, saves any one, two
or all three of the following BRender .DAT. files:  a file containing all the
meshes in the model; another file containing all the materials in the model and
a third containing a BRender actor hierarchy which ties them together. These
are saved separately for convenience, but they can be safely concatenated
together to form one single .DAT file if you do not need this separation.


ΓòÉΓòÉΓòÉ 6.7.3. Entertainment Samples ΓòÉΓòÉΓòÉ

The entertainment samples provided with this release are categorized as
follows:

     Audio Samples
     Input Device Sample
     Network Sample
     Video Samples

 If you have a question that is specific to the Entertainment Support provided
 with the Warp Toolkit, refer to the entertainment online documentation as a
 first step. If you still need assistance, call 1-800-553-1623 for technical
 support.


ΓòÉΓòÉΓòÉ 6.7.3.1. Audio Samples ΓòÉΓòÉΓòÉ

There are two audio samples in this release:

     DAUDIO - Direct Audio
     MIDISAMP - Real Time MIDI


ΓòÉΓòÉΓòÉ 6.7.3.1.1. DAUDIO ΓòÉΓòÉΓòÉ

DAUDIO (direct audio) demonstrates the use of the direct audio interface. This
high speed audio interface allows an application to send audio data directly to
the amp-mixer device. The sample demonstrates the steps required to set up and
use this new interface for playing and recording digital audio data.

Hardware requirements:

     Computer capable of running OS/2 Warp
     Sound card
     Speakers or headphones

 Software requirements:

     OS/2 Warp
     Multimedia support

 Note:  Refer to the README file located in the
        \TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\DAUDIO subdirectory for
        instructions on building and compiling the Direct Audio sample with
        VisualAge C++.


ΓòÉΓòÉΓòÉ 6.7.3.1.1.1. Installing DAUDIO ΓòÉΓòÉΓòÉ

This version of the entertainment samples and tools includes Beta versions of
AMPMXMCD.DLL and AUDIOSH.DLL. The original versions of these files (located in
MMOS2\DLL) must be replaced with the Beta files before any application
utilizing the direct audio interface can work. The Beta versions of these .DLL
files are located in the TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\DAUDIO
subdirectory. To replace these .DLL files:

     Double-click on Sound located in the Multimedia folder and ensure Enable
      system sound is not selected.

     Shut down and restart your system. This will unlock the AMPMXMCD.DLL and
      AUDIOSH.DLL files.

     Back up the AMPMXMCD.DLL and AUDIOSH.DLL files.

     Copy the AMPMXMCD.DLL and AUDIOSH.DLL files (located in
      \TOOLKIT\BETA\DLL) to the MMOS2\DLL subdirectory.

     Double-click on Sound located in the Multimedia folder and select Enable
      system sounds.


ΓòÉΓòÉΓòÉ 6.7.3.1.1.2. Starting DAUDIO ΓòÉΓòÉΓòÉ

You can start DAUDIO in two ways:

     From the command line, change to the
      TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\DAUDIO subdirectory and type:

              DAUDIO

     From the Desktop, open the Toolkit folder and then:

        1. Open the BETA folder

        2. Open the Beta Entertainment Samples folder.

        3. Open the Audio Samples folder.

        4. Double-click on Direct Audio.


ΓòÉΓòÉΓòÉ 6.7.3.1.2. MIDISAMP ΓòÉΓòÉΓòÉ

MIDISAMP illustrates the use of the real-time MIDI support programming concepts
and usage of the new real-time MIDI API. This sample program illustrates the
use of the new real-time MIDI API by initializing and setting up a small MIDI
node network and subsequently sending a MIDI message from an application node
to a hardware node, thereby demonstrating MIDI playback.

Hardware requirements:

     Computer capable of running OS/2 Warp
     Speaker or headphones
     Sound card

      Note:  The README for MIDISAMP contains specific information regarding
             device driver installation for running MIDISAMP. (This README is
             located in the TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\MIDI
             subdirectory.)

      Software requirements:
        -  OS/2 Warp
        -  Multimedia support
        -  Standard MIDI file


ΓòÉΓòÉΓòÉ 6.7.3.1.2.1. Known Limitations ΓòÉΓòÉΓòÉ

Currently, MIDISAMP might halt when another process attempts to play a sound
(including system sounds) while the sample is running. Therefore, you should
disable system sound before running MIDISAMP. To disable system sound,
double-click on Sound located in the Multimedia folder and ensure Enable system
sound is not selected.


ΓòÉΓòÉΓòÉ 6.7.3.1.2.2. Starting MIDISAMP ΓòÉΓòÉΓòÉ

You can start MIDISAMP in two ways:

     From the command line, change to the
      TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\MIDI subdirectory and type:

              MIDISAMP filename.mid

      where:

      filename.mid  is a MIDI file.

     From the Desktop, open the Toolkit folder and then:

        1. Open the BETA folder.

        2. Open the Beta Entertainment Samples folder.

        3. Open the Audio Samples folder.

        4. Double-click on MIDI Samp.

 Sample MIDI files are located in the MMOS2\SOUNDS subdirectory.


ΓòÉΓòÉΓòÉ 6.7.3.2. Input Device Sample ΓòÉΓòÉΓòÉ

There is one input device sample in this release:

JOYSTICK


ΓòÉΓòÉΓòÉ 6.7.3.2.1. JOYSTICK ΓòÉΓòÉΓòÉ

JOYSTICK (OS/2 Joystick device driver) allows an OS/2 Warp application to
access the machine's game port.  The driver provides an interface or a set of
API function calls for reading the joysticks.

The Joystick API is implemented within the OS/2 Joystick device driver. This
sample code shows how to use the OS/2 Joystick API and supports any two
standard joysticks or one joystick with an advanced feature, such as a hatch or
throttle control.

Currently, there are no high-level versions of access to these functions,
except through the IOCtl interface. This sample issues DosDevIOCtl to request
status or sends commands to the OS/2 Joystick device driver. The API function
number, an input parameter to DosDevIOCtl, is defined by the OS/2 Joystick
device driver.

JOYSTICK registers with the OS/2 Joystick device driver via DosOpen, with the
device name "GAME$". It sends commands to the Joystick device driver via
DosDevIOCtl after opening the new GAME$ device. These commands or IOCtls are
subfunctions that are issued through DosDevIOCtl.

This sample passes proper parameters and required data buffers or data
structures when calling the API. The returned data is examined and a proper
message is displayed to the screen. If the call is unsuccessful, an error
message will be displayed and the sample will be terminated.

JOYSTICK shows how to interface with the OS/2 Joystick API via the following
functions:

     Get the version number of the driver, API function x'01'.
     Get the device parameters, API function x'02'.
     Set the device parameters, API function x'03'.
     Get the calibration values, API function x'04'.
     Get the current joystick status, API function x'10'.
     Get the joystick status at next button press, API function x'11'.
     Get the joystick status at next sample, API function x'12'.

 It also accesses other OS/2 functions such as:

     DosOpen

      DosOpen function must be called first to open the device driver name
      (GAME$) prior to any API function call to the OS/2 Joystick device
      driver.

     DosClose

      When the program terminates, DosClose must be called to end the program
      properly.

 Hardware Requirements:

     Joystick device

 Software Requirements:

     OS/2 Warp
     IBM C Set ++ compiler 2.x or 3.x
     Developer's Toolkit 3.0
     GAMEDD.SYS driver

      Note:  An error message will be displayed and the program will terminate
             if the driver is not installed.

 The design of this sample is based on the set of functions provided by the
 OS/2 Joystick device driver.

 The CONFIG.SYS should include the following statement:

  DEVICE=pathname\GAMEDD.SYS

 where:

 pathname  is the path where GAMEDD.SYS is located.


ΓòÉΓòÉΓòÉ 6.7.3.2.1.1. Starting JOYSTICK ΓòÉΓòÉΓòÉ

You can start JOYSTICK in two ways:

     From the command line, change to the
      TOOLKIT\BETA\SAMPLES\ENTOOLKT\INPUT\JOYSTICK subdirectory and type:

              JOYSTICK

     From the Desktop, open the Toolkit folder and then:

        1. Open the BETA folder.

        2. Open the Beta Entertainment Samples folder.

        3. Open the Input Samples folder.

        4. Double-click on Joytest.


ΓòÉΓòÉΓòÉ 6.7.3.3. Network Sample ΓòÉΓòÉΓòÉ

There is one network sample in this release:

 TICTAC - TicTacToe


ΓòÉΓòÉΓòÉ 6.7.3.3.1. TICTAC ΓòÉΓòÉΓòÉ

TICTAC (TicTacToe) demonstrates how to use networking functions to develop a
multiplayer, networked game.

These networking support functions are referred to as OS/2 Warp networking
functions. These functions support multiple transports such as TCP/IP, SPX/IPX,
and OEM stacks. The current functions implement support for TCP/IP transport
only.

This sample uses the Warp networking functions to illustrate a 2-player
TicTacToe game, where two players play against each other.

Software Requirements:

     WARPNET.DLL
     OS/2 TCP/IP Version 2.x or higher
     OS/2 Warp 3.0 or higher


ΓòÉΓòÉΓòÉ 6.7.3.3.1.1. Starting TICTAC ΓòÉΓòÉΓòÉ

You can start TICTAC in two ways:

     From the command line, change to the
      TOOLKIT\BETA\SAMPLES\ENTOOLKT\NETWORK\TICTAC subdirectory and type:

              TICTAC

     From the Desktop, open the Toolkit folder and then:

        1. Open the BETA folder.

        2. Open the Beta Entertainment Samples folder.

        3. Open the Network Samples folder.

        4. Double-click on TicTac.


ΓòÉΓòÉΓòÉ 6.7.3.3.1.2. Warp Networking Functions ΓòÉΓòÉΓòÉ

The Warp networking functions represent a standard application layer interface
to OS/2 entertainment software for networked multiplayer support. These
networking functions support multiple transports such as TCP/IP, SPX/IPX, and
OEM stacks. Warp networking functions enable creation of multiplayer networked
entertainment software, such as games. This first implementation of the Warp
networking functions uses TCP/IP.

Warp networking functions define a well known UDP port just for entertainment
software. The Warp networking game server or the daemon monitors the well-known
game port and routes packets received at this port to the application.

Note:  The TCP/IP Services file (located in \TCPIP\ETC\SERVICES) must be
       modified to include the well known Game port entry. The modification
       would look similar to the following:

                GAMED 5022/UDP #Well Known UDP based Game Port.


ΓòÉΓòÉΓòÉ 6.7.3.3.1.3. Known Limitations ΓòÉΓòÉΓòÉ

Currently, the receive function (WarpnetPackRecv) for Warp networking can only
receive header information with no packet data.


ΓòÉΓòÉΓòÉ 6.7.3.4. Video Samples ΓòÉΓòÉΓòÉ

There are two video samples in this release:

     BEEHIVE - Sprite Compiler
     FSDIVE - Full Screen DIVE


ΓòÉΓòÉΓòÉ 6.7.3.4.1. BEEHIVE ΓòÉΓòÉΓòÉ

BEEHIVE (sprite compiler) demonstrates the power of compiled sprites by
comparing the performance of a typical sprite algorithm against a compiled
sprite. When the application first starts, it will display a single sprite
moving in a random path around the application window. The user can add sprites
by holding down the H key. As the sprite count increases, the effects on the
frame rate will become evident. The actual frame rate will be displayed on the
title bar. The user will be able to switch the application from compiled
sprites to normal sprites from a menu. As the number of sprites increases, the
difference in performance from compiled to normal sprites will become more
dramatic.

While DIVE offers a high performance API for blitting images to the screen, it
was not designed for implementing sprites. BEEHIVE demonstrates a technique for
implementing high performance sprites in a Warp/DIVE environment. The source
code provided offers a good starting point for building a high performance
sprite engine.


ΓòÉΓòÉΓòÉ 6.7.3.4.1.1. Starting BEEHIVE ΓòÉΓòÉΓòÉ

You can start BEEHIVE in two ways:

     From the command line, change to the
      TOOLKIT\BETA\SAMPLES\ENTOOLKT\VIDEO\BEEHIVE subdirectory and type:

              BEEHIVE

     From the Desktop, open the Toolkit folder and then:

        1. Open the BETA folder.

        2. Open the Beta Entertainment Samples folder.

        3. Open the Video Samples folder.

        4. Double-click on Beehive.


ΓòÉΓòÉΓòÉ 6.7.3.4.2. FSDIVE ΓòÉΓòÉΓòÉ

FSDIVE (full-screen DIVE) demonstrates the use of multimedia's direct interface
video extensions (DIVE) by repeatedly displaying a short animation sequence.
The animation is performed by sequentially displaying a series of up to 16 bit
maps in a PM window. You can display the default bit maps, shipped with the
sample, or specify the bit maps by passing the file names as command line
parameters.

After the application is started, you can move or resize the window and observe
the effects on the frame rate of the animation (displayed on the title bar).

The latest version of the DIVE interface has been enhanced to allow an
application to take over the display and change the resolution. This allows an
application to run in a full screen without paying the performance penalty of
maintaining a high-resolution Desktop.

Note:  Before the full-screen DIVE sample can run in full-screen mode,
       full-screen support must be installed by running GSRVINST.EXE (located
       in \TOOLKIT\BETA\SAMPLES\ENTOOLKT\VIDEO\FSDIVE). See the GAMESRVR.DOC
       file in the same directory for more details. Once the game server DLL is
       installed, full-screen DIVE can be activated by using the Alt+Home hot
       key.


ΓòÉΓòÉΓòÉ 6.7.3.4.2.1. Starting FSDIVE ΓòÉΓòÉΓòÉ

You can start FSDIVE in two ways:

     From the command line, change to the
      TOOLKIT\BETA\SAMPLES\ENTOOLKT\VIDEO\FSDIVE subdirectory and type:

              FSDIVE

     From the Desktop, open the Toolkit folder and then:

        1. Open the BETA folder.

        2. Open the Beta Entertainment Samples folder.

        3. Open the Video Samples folder.

        4. Double-click on FS Dive.


ΓòÉΓòÉΓòÉ 6.7.4. Entertainment Tools ΓòÉΓòÉΓòÉ

The following Beta entertainment tool is available with this release:

 RINST2 - REXX Installation Aid for Games DOS Programs


ΓòÉΓòÉΓòÉ 6.7.4.1. RINST2 ΓòÉΓòÉΓòÉ

RINST2 is a REXX tool that assists you in installing any entertainment or DOS
program. It creates a Workplace Shell program, associates an icon, and sets the
DOS setting as appropriate. It also offers the chance to run a setup program as
part of the installation. This tool can easily be used to install any type of
program.

Note:  OS/2 REXX must be installed and loaded prior to running this program.


ΓòÉΓòÉΓòÉ 6.7.4.1.1. Starting RINST2 ΓòÉΓòÉΓòÉ

To start RINST2 from the command line, change to the TOOLKIT\BETA\BIN
subdirectory and type:

  RINST2


ΓòÉΓòÉΓòÉ 6.7.4.1.2. Using RINST2 ΓòÉΓòÉΓòÉ

To customize this tool, use a text editor and change the title, Raptor, and the
program name, RAP.EXE, to meet your needs.

  title = "Raptor"
  rc    = SysFileTree("RAP.EXE",fspec,"FO")


ΓòÉΓòÉΓòÉ 6.7.5. Entertainment Online Documentation ΓòÉΓòÉΓòÉ

The following entertainment online books are located in the \TOOLKIT\BETA\BOOK
subdirectory:

     3D Studio to BRender Converter
     BRender Concise Guide
     BRender Technical Reference
     Direct Audio Interface
     Entertainment Programming Guide and Reference
     Real Time MIDI

 You can also access these books from the Desktop by opening the Toolkit
 folder, then the BETA folder, and then the Beta Toolkit Information folder.


ΓòÉΓòÉΓòÉ 6.7.5.1. 3D Studio to BRender Converter ΓòÉΓòÉΓòÉ

3DS2BR is a DOS command line program for converting Autodesk 3D Studio(TM)
(3DS) objects in the .3DS binary file format to one or more BRender .DAT format
files. This document briefly describes the Version 1.1 release, detailing:

     A general overview of the program
     The platform required to run the program
     The command line options and their effects
     Differences from the previous release, Version 1.0
     Processing of palettes, shade tables and texture maps you must do
     Which 3DS features the program converts to exact BRender equivalents
     Which 3DS features it modifies during conversion, as no exact equivalent
      exists
     Which 3DS features are specifically ignored in the conversion process


ΓòÉΓòÉΓòÉ 6.7.5.2. BRender Concise Guide ΓòÉΓòÉΓòÉ

This book describes the BRender Power Rendering System Application Programming
Interface (API), shows how the components of the BRender system work as a
whole, and gives some idea of the capabilities of this system.


ΓòÉΓòÉΓòÉ 6.7.5.3. BRender Technical Reference ΓòÉΓòÉΓòÉ

This book provides documentation support for the BRender Power Rendering
System, a real-time, 3D graphics software by Argonaut Technologies Ltd.

Argonaut's BRender 3D graphics API is only distributed under Argonaut's
end-user license. The BRender Sample provides a limited license permitting you
to evaluate the product. Should you wish to include the BRender Power Rendering
System in your entertainment software, you need to contact Argonaut for a
commercial license.


ΓòÉΓòÉΓòÉ 6.7.5.4. Direct Audio Interface ΓòÉΓòÉΓòÉ

This book provides an overview of the direct audio interface including
descriptions of messages and associated data types.


ΓòÉΓòÉΓòÉ 6.7.5.5. Entertainment Programming Guide and Reference ΓòÉΓòÉΓòÉ

This book is written for the developer interested in writing entertainment
software for OS/2 Warp. It contains information about video support, audio
support, networking, and input devices used specifically in entertainment
development, such as:

     OS/2 Joystick device driver
     Full-screen DIVE (Direct Interface Video Extensions)
     Multiplayer networking API


ΓòÉΓòÉΓòÉ 6.7.5.6. Real Time MIDI ΓòÉΓòÉΓòÉ

This book provides a discussion of the new real-time MIDI architecture and
introduces the real-time MIDI application programming interface (API) including
detailed descriptions of the real-time MIDI functions and associated data
types.


ΓòÉΓòÉΓòÉ 7. Programming Considerations ΓòÉΓòÉΓòÉ

Programming considerations apply for the following areas of the OS/2 Warp
Version 3 operating system:

     Important Considerations
     Kernel Debugger
     IBM Developer API Extensions for OS/2
     OpenDoc for OS/2
     Presentation Manager
     SOM
     VisualAge (C Set ++ Compiler)
     Workplace Shell


ΓòÉΓòÉΓòÉ 7.1. Important Considerations ΓòÉΓòÉΓòÉ

Included in this section are important items that can affect your future
development efforts when using the IBM Developer's Toolkit for OS/2 Warp.

     Compiling with IBM C/2
     Compiling with VisualAge (C Set ++)
     Known Limitations for the Container Part
     Known Limitations for DIVE
     Known Limitations for MIDISAMP
     Known Limitations for Warp Networking
     Replacing DLGEDIT - Dialog Editor
     Replacing IPFCBIDI - Bidirectional Information Presentation Facility
      Compiler


ΓòÉΓòÉΓòÉ 7.1.1. Compiling with IBM C/2 ΓòÉΓòÉΓòÉ

The Developer's Toolkit for OS/2 Warp is not intended to be used with the IBM
C/2, Version 1.1 compiler. If you choose to use that compiler, you should use
version 1.3 of the Toolkit. (An unsupported version of that Toolkit is
available on The Developer Connection for OS/2 CD.)

The Warp Toolkit is intended to be used with the IBM VisualAge C++ compiler.


ΓòÉΓòÉΓòÉ 7.1.2. Compiling with VisualAge (C Set ++) ΓòÉΓòÉΓòÉ

The latest version of the C Set ++ compiler (now called VisualAge C++) has been
released. VisualAge C++ is shipped with its own version of the Warp Toolkit
which includes updated sample makefiles. Changes to the sample makefiles relate
to the new linker (ILINK) and to the new library (CPPOM30.LIB).

With this version of the Warp Toolkit, the same sample makefile changes have
been made so that you can use VisualAge C++.  However, the IBM Developer's API
Extensions (DAPIE) and OpenDoc samples are an exception; those sample makefiles
use the IBM C Set++ compiler.  Use the following instructions to build the
DAPIE and OpenDoc samples with VisualAge C++:

     Replace LINK386.EXE with ILINK.EXE
     Add the /nofree option to the ILINK.EXE step

      Note:  This /nofree option must be the first option listed.

     Insert spaces in between each ILINK flag. For example:

              LFLAGS = /MAP /CO /NOD

     Add the library CPPOM30I.LIB to the list of libraries to be linked.

 Note:  When using ILINK, the /batch switch is no longer supported and must be
        removed or linking will fail.

 There are several other link switches that have been dropped but they only
 cause link warnings. Only /batch causes linking to fail.

 For the samples shipped with the Warp Toolkit that use VisualAge C++, you can
 compile those samples with C Set ++ (using LINK386) by changing any reference
 to CPPOM30.LIB to:

    DDE4MBS.LIB

 and changing any reference to ILINK to LINK386. Note that the /nofree option
 must be removed from the LINK386 statement.


ΓòÉΓòÉΓòÉ 7.1.3. Known Limitations for the Container Part ΓòÉΓòÉΓòÉ

The Container part has the following known limitations. Note that the behavior
described below will be exhibited by all samples which subclass from the
Container part.

     A SYS3175 error occurs when you select Open As->Details from the
      Container part's View menu.  This error will close the document.

     A SYS3175 error occurs when saving a document containing a selected
      Container part inside a root Container part.  It will occur if the
      selected part subclasses from the Container part.  This error does not
      occur if the selected part, for example, is the Cookbook part.

     The Container part's Show As menu selection from the View menu does not
      work correctly. This selection will incorrectly change the view type of
      selected parts, when it should only change the activated part's view
      type. The correct way to change the view type of selected parts would be
      to select Show selection as from the Edit menu.

     The Move selection from the Edit menu is incorrectly enabled for an
      activated part. The Move selection, like all Edit menu selections, are
      for selected parts only.

     A part that subclasses from the Container part may not have its intrinsic
      content clipped correctly to the embedded parts.  The Container part
      correctly handles the clipping of its embedded parts, but there is no way
      for a part that subclasses from the Container part to tell the Container
      part how to clip the embedded parts to its own content. Generally, the
      subclass part's intrinsic content will write over the embedded parts.


ΓòÉΓòÉΓòÉ 7.1.4. Known Limitations for DIVE ΓòÉΓòÉΓòÉ

DIVE will not run in direct mode on some systems if the video card requires
bank switching. To determine if your video card requires bank switching, select
Query Caps from the Options menu of the DIVE sample. If the Screen access
requires bank switch field is set to YES, setting a lower Desktop resolution in
the System Setup may fix this.

DIVE may not work on some systems when the Desktop is set to 16 million colors.
If your system is set to 16 million colors and DIVE does not work properly, try
setting the Desktop to fewer colors in the System Setup.


ΓòÉΓòÉΓòÉ 7.1.5. Known Limitations for MIDISAMP ΓòÉΓòÉΓòÉ

Currently, MIDISAMP might halt when another process attempts to play a sound
(including system sounds) while the sample is running. Therefore, you should
disable system sound before running MIDISAMP. To disable system sound,
double-click on Sound located in the Multimedia folder and ensure Enable system
sound is not selected.


ΓòÉΓòÉΓòÉ 7.1.6. Known Limitations for Warp Networking ΓòÉΓòÉΓòÉ

Currently, the receive function (WarpnetPackRecv) for Warp networking can only
receive header information with no packet data.


ΓòÉΓòÉΓòÉ 7.1.7. Replacing DLGEDIT ΓòÉΓòÉΓòÉ

IBM supports the version of DLGEDIT (Dialog Editor) in this release of the Warp
Toolkit, but will not be enhancing or otherwise changing the Dialog Editor in
future releases. URE (Universal Resource Editor) will become the editor of
choice for creating and modifying dialogs and other resources.


ΓòÉΓòÉΓòÉ 7.1.8. Replacing IPFCBIDI ΓòÉΓòÉΓòÉ

The Developer's Toolkit for OS/2 Warp on The Developer Connection for OS/2 now
includes only one version of the IPF compiler:  IPFC.EXE. The bidirectional
version of IPFC.EXE (IPFCBIDI.EXE) is not included as a separate program with
this version of the Warp Toolkit. However, the bidirectional support in
IPFCBIDI has been integrated into the American version of the program,
IPFC.EXE.  It will be necessary for you to modify any makefiles that reference
IPFCBIDI.EXE to reference IPFC.EXE instead.


ΓòÉΓòÉΓòÉ 7.2. Kernel Debugger Considerations ΓòÉΓòÉΓòÉ

New kernel debug files are available.  If you are installing the Warp Toolkit
from The Developer's Connection for OS/2, you have two options:

     Install the kernel debug files directly from the CD.
     Create diskettes from which you can later install the kernel debug files.

 To install directly from the CD, choose the appropriate Kernel Debugger
 product in the Developer Connection for OS/2 Catalog and install it. This will
 run an installation program that installs the appropriate kernel debug files.

 To create kernel debug diskettes, choose the appropriate Kernel Debugger
 product in the Developer Connection for OS/2 Catalog and install it. This will
 bring up a utility that will create the kernel debug diskettes for you. Once
 you have created the diskettes, insert the first kernel debug diskette into a
 diskette drive, switch to that drive, and type INSTALL at an OS/2 command
 prompt.


ΓòÉΓòÉΓòÉ 7.3. IBM Developer API Extensions for OS/2 Considerations ΓòÉΓòÉΓòÉ

The information in the following sections should be noted for the IBM Developer
API Extensions for OS/2:

     Functions
     Messages
     Child Window Controls
     Installation of Win32 DLLs
     MDI Windows Menu Differences
     Programmable Job Properties with Printers
     Superclassing of Preregistered Classes
     Text Mode Applications
     World Coordinate Transformations
     IBM Developer API Extensions and OpenDoc Interoperability


ΓòÉΓòÉΓòÉ 7.3.1. Functions ΓòÉΓòÉΓòÉ

Take the following into consideration when using these IBM Developer API
Extensions functions:

     CreatePolygonRgn and CreatePolyPolygonRgn

      Regions created with these functions will not display on machines with a
      VGA video driver.

     Chord and Pie

      Chords and pie slices can only be drawn with solid pens. This is a
      limitation of the way that PM draws chords and pie slices.

     CreatePatternBrush

      If you try to create a pattern brush from a black bit map (size 5 x 5)
      and then PatBlt using this brush, you get dots in the output pattern on
      some display drivers.

     DrawText

      Do not use DrawText to write text to a printer device context (DC).  Use
      TextOut to write text to a printer DC.

     RegQueryInfoKey

      If parameter 3 (lpcchClass) is set to 0 and parameter 2 is NULL,
      ERROR_INVALID_PARAM is returned. However, if parameter 3 is set to 0 and
      parameter 2 is not NULL, the size of the needed buffer is returned in
      parameter 3 and ERROR_INSUFFICIENT_BUFFER is returned.


ΓòÉΓòÉΓòÉ 7.3.2. Messages ΓòÉΓòÉΓòÉ

IBM Developer API Extensions for OS/2 does not support the following messages:

      WM_NCACTIVATE
      WM_NCCALCSIZE
      WM_NCCREATE
      WM_NCDESTROY
      WM_NCPAINT


ΓòÉΓòÉΓòÉ 7.3.3. Child Window Controls ΓòÉΓòÉΓòÉ

IBM Developer API Extensions for OS/2 does not support borders and other frame
controls on non-frame child windows.


ΓòÉΓòÉΓòÉ 7.3.4. Installation of Win32 DLLs ΓòÉΓòÉΓòÉ

Although you cannot load Win32 DLLs in OS/2, if you try to, you will get a
successful return code.  The load of the DLLs will fail despite the successful
return code.


ΓòÉΓòÉΓòÉ 7.3.5. MDI Windows Menu Differences ΓòÉΓòÉΓòÉ

For Multiple Document Interface (MDI) applications, as MDI child windows are
opened, their titles are added to the specified window's pop-up menu.  The OS/2
pop-up menu is slightly different from Windows NT.  These differences are as
follows:

     On OS/2, the child windows are not numbered in the pop-up menu, so there
      is no key sequence for selecting an entry.  Instead, you must highlight
      the menu entry to select it.

     On NT, only the first 9 windows opened will be in the pop-up menu.  If a
      10th window is opened, a menu entry "More Windows" is added to the
      pop-up.  When you select this, you are taken to a dialog box  containing
      the names of all the open MDI child windows.  On OS/2, this will not
      happen.  There is no limit to the number of window titles which will fit
      under the OS/2 pop-up menu.


ΓòÉΓòÉΓòÉ 7.3.6. Programmable Job Properties with Printers ΓòÉΓòÉΓòÉ

When using IBM Developer API Extensions for OS/2, if you want to use
programmable (dynamic) job properties with printers, you need the following:

     An OS/2 application that supports programmable job properties

     IBM Developer API Extensions for OS/2 pack

     Printer driver update

 If you received the IBM Developer API Extensions for OS/2 update on CD-ROM,
 the printer drivers are on the CD-ROM.  If you downloaded the IBM Developer
 API Extensions for OS/2 from a bulletin board service (BBS), you must download
 the printer driver update.


ΓòÉΓòÉΓòÉ 7.3.7. Superclassing of Preregistered Classes ΓòÉΓòÉΓòÉ

IBM Developer API Extensions for OS/2 applications do not support superclassing
of the preregistered classes.


ΓòÉΓòÉΓòÉ 7.3.8. Text Mode Applications ΓòÉΓòÉΓòÉ

IBM Developer API Extensions for OS/2 does not support text mode applications.
If you have a text mode application, it will not run; it simply returns.


ΓòÉΓòÉΓòÉ 7.3.9. World Coordinate Transformations ΓòÉΓòÉΓòÉ

Regions in PM are defined in device coordinates.  Therefore, IBM Developer API
Extensions for OS/2 applications are restricted in that simple scaling and
translation transformations will work with regions, but other transformations
such as shearing and rotating will not.


ΓòÉΓòÉΓòÉ 7.3.10. IBM Developer API Extensions for OS/2 and OpenDoc Interoperability ΓòÉΓòÉΓòÉ

This version of OpenDoc for OS/2 does not support the Win32 API.  Therefore,
the IBM Developer API Extensions for OS/2 cannot be used to develop an OpenDoc
part. However, a user can run an application which was created using the IBM
Developer API Extensions for OS/2 while simultaneously editing or viewing an
OpenDoc for OS/2 document.


ΓòÉΓòÉΓòÉ 7.4. OpenDoc for OS/2 Considerations ΓòÉΓòÉΓòÉ

The following lists covers aspects of OpenDoc development that you will need to
consider:

     OpenDoc returns an exception for errors which should be caught by your
      part using the SOM_TRY, SOM_CATCH and SOM_ENDTRY macros. Passing bad or
      illegal parameters results in either an exception or a trap.

     The Bento subsystem returns exceptions not listed in ERRORDEF.IDL.

     Shape::IsRectangular does not work correctly when the shape contains
      colinear points.

     The FocusLib public utility does not handle off-screen canvases.

     Focusing to a non-existent property in a storage unit, creates a property
      with that name.

     The OD_PRINT message is not dispatched to monitors or dispatch modules.

     The document property pName cannot be set by sending an OSAEvent to the
      rootpart.

     There is no default accessor for Icon property of cPart class.


ΓòÉΓòÉΓòÉ 7.5. Presentation Manager Considerations ΓòÉΓòÉΓòÉ

Making modifications to Microsoft Windows programs to enable dynamic data
exchange (DDE) communications with PM programs helps facilitate a gradual
migration of applications to PM. Not all data formats are automatically
converted when using DDE between Windows programs and PM programs (DDE set
public).

The following formats are converted automatically by the OS/2 operating system:

 ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
 Γöé PM Application       Γöé Windows Application  Γöé
 Γöé Data Format          Γöé Interpretation       Γöé
 ΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöé
 Γöé PM bit map           Γöé Windows DIB          Γöé
 Γöé PM private           Γöé Windows private      Γöé
 Γöé Text                 Γöé Text (codepage 819)  Γöé
 Γöé---------------------------------------------Γöé
 Γöé Windows Application  Γöé PM Application       Γöé
 Γöé Data Format          Γöé Interpretation       Γöé
 Γö£ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöñ
 Γöé Text (codepage 819)  Γöé Text                 Γöé
 Γöé Windows DIB          Γöé PM Bit map           Γöé
 Γöé Windows private      Γöé PM Private           Γöé
 ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  Code page translation (Windows 819 to/from current PM code page) is
       performed for topic name in all cases.

When data conversion is not automatically performed, programs can still
communicate using dynamic data exchange if the two programs are able to perform
the data conversion and pass private data formats.


ΓòÉΓòÉΓòÉ 7.6. SOM Considerations ΓòÉΓòÉΓòÉ

This version of the Warp Toolkit contains a subset of the SOMobjects
Developer's Toolkit. The following SOM programming considerations are briefly
described:

     Distributed SOM
     SNGLICLS.HH
     SOM 1.0 OIDL
     SOM Bindings
     SOM Coding Styles
     SOM Compiler
     SOM DLLs
     SOM and OpenDoc for OS/2


ΓòÉΓòÉΓòÉ 7.6.1. Distributed SOM (DSOM) ΓòÉΓòÉΓòÉ

New features, known limitations, and restrictions pertain to the Distributed
SOM (DSOM).  There are briefly described as follows:

     DSOM now provides a PM version of the REGIMPL tool for registering
      servers in the implementation repository. It is called PREGIMPL and is
      similar in functionality to REGIMPL. To invoke the tool, type PREGIMPL on
      a command line. Remember to select File Save before exiting to commit any
      changes made.

     You are now able to control the number of request threads created per
      server. The environment variable SOMDNUMTHREADS is used to indicate the
      maximum size of the thread pool. If this environment variable is not set,
      a separate thread will be created for each request.

     The OUT_LIST_MEMORY, IN_COPY_VALUE, and DEPENDENT_LIST flags, used with
      the dynamic invocation interface, are not supported.

     Concurrent updates to the implementation repository are currently not
      properly serialized, and can conflict.

     The is_nil method of SOMDObject has been changed from a true method to a
      procedure, so that is_nil can be safely invoked on a NULL object pointer.
      As a result, the syntax for invoking is_nil from C++ client programs has
      changed. The new syntax is:

                obj->is_nil(obj,env);

      Rather than:

                obj->is_nil(env);

      where:

      obj            Is an object pointer of type SOMDObject.
      env            Is of type Environment.


ΓòÉΓòÉΓòÉ 7.6.2. SNGLICLS.HH ΓòÉΓòÉΓòÉ

The Direct To SOM version of the SNGLICLS header file cannot be emitted with
the version of the SOM Compiler shipped with this Toolkit.  Therefore, this
file (SNGLICLS.HH) is provided as part of the SOM Direct To SOM headers.


ΓòÉΓòÉΓòÉ 7.6.3. SOM 1.0 OIDL Users ΓòÉΓòÉΓòÉ

If you need to recompile an OIDL class that overrides somDumpSelf or
somDumpSelfInt, you will need to change the data type of the level parameter in
the function definition in your C source program from INT to LONG.  For
example, if your original class source program had a somDumpSelfInt override
procedure similar to:

  SOM_Scope void SOMLINK somDumpSelfInt(
       <className> *somSelf, INT level)
  {
    ...
  }

Change it to read:

  SOM_Scope void SOMLINK somDumpSelfInt(
       <className> *somSelf, LONG level)
  {
   ...
  }

Because both INT and LONG data types require 4 bytes on OS/2, this does not
affect the binary interface of your class.


ΓòÉΓòÉΓòÉ 7.6.4. SOM Bindings ΓòÉΓòÉΓòÉ

The XH and H files shipped with this Warp Toolkit will only work with the IDL
files shipped with this Toolkit. You will need to generate new SOM bindings if
you install a new version of SOM. This means that the XH and H files will need
to be re-emitted if new versions of the IDL files are made available. There are
two steps that you will need to take.

If you install version 'Y' of SOM on top of version 'X', you will need to
generate SOM bindings for version 'Y'. The version 'X' SOM bindings are not
guaranteed to be compatible with version 'Y'.

     Use the SOMSTARS.CMD file to generate the SOMSTARS version of the
      bindings.

     Use SOMCORBA.CMD to generate the SOMCORBA version of the bindings. This
      will upgrade your SOM bindings.

 The command file WPIDL2XH.CMD is provided to upgrade Workplace Shell bindings,
 for developers that upgrade their SOMobjects Toolkit in the future. This
 command file emits the .XH header files from the Workplace Shell .IDL files.
 The file should be invoked upon each of the .IDL files from the Warp Toolkit
 to regenerate the headers for C++. This is only necessary when you upgrade to
 a new level of the SOMobjects Toolkit. Invoking the SOM compiler's .XH emitter
 on the Workplace Shell .IDL will not emit .XH files for you, because the
 Workplace Shell classes currently only maintain passthru sections for .H files
 for C.


ΓòÉΓòÉΓòÉ 7.6.5. SOM Coding Styles ΓòÉΓòÉΓòÉ

There are two possible forms of C bindings for SOM programming:

 SOMCORBA       The strict CORBA-compliant form in which pointer references
                ('*'s) are NOT exposed in object references.

 SOMSTARS       The OIDL-compatible C++ form in which pointer references ('*'s)
                are visible in object references.

 The SOMSTARS form is more appropriate if you plan to move your class
 implementations from C to C++ at some future point. This choice will determine
 how object references will appear in all of your C programs. For example, to
 declare a reference to an instance of class Foo, you would code either:

    Foo afoo;   /* Strict CORBA compliant form          */
    OR
    Foo *afoo; /* C++ migration or OIDL-compatible form */

 If you later decide to switch from one SOM coding style to the other, you will
 have to convert any C code that you have already written in one style to the
 other style.

 The Workplace Shell uses the SOMSTARS version of the SOM header files.
 Therefore, the Warp Toolkit installs the SOMSTARS version of the header files.

 The Workplace Shell interface definition language (IDL) files (WP*.IDL) are
 the counterparts for the documented Workplace Shell classes' SC files provided
 with the OS/2 2.1 Toolkit. The WP*.H and WP*.XH files emitted from the
 Workplace Shell's IDL files by the SOM compiler are also provided.

 The OS/2 makefiles for the Workplace Shell Warp Toolkit samples are written
 assuming the SOMSTARS style of coding. If you have the SOMobjects Toolkit, the
 C samples provided with the SOMobjects Toolkit use the SOMCORBA style of
 coding (these samples are not part of the IBM Developer's Toolkit for OS/2).


ΓòÉΓòÉΓòÉ 7.6.6. SOM Compiler ΓòÉΓòÉΓòÉ

New features, known limitations, and restrictions pertain to the SOM compiler.
There are briefly described as follows:

     Mutually recursive IDL struct and union are not currently supported. The
      following is an example of unsupported mutual recursion:

              struct X;
              struct Y
              {
                sequence<X> indirectSelf;
              };
              struct X
              {
                sequence<Y> indirectSelf;
              };

     The C bindings do not permit the use of multiple methods with the same
      name that also take an argument of data type VA_LIST within the same
      module. For example, the following legal IDL will result in incorrect C
      usage bindings:

              module X
              {
                interface Y
                {
                  void Foo (in LONG f, in VA_LIST ap);
                };
                interface Z
                {
                  void Foo (in LONG f, in VA_LIST ap);
                };
              };

     The SOM C++ language bindings are built assuming use of the OS/2 C Set ++
      compiler, but other C++ compilers should be able to use these bindings as
      well. For example, to use BCOS2 (the Borland C++ compiler for OS/2), use
      -DSOMLINK=_syscall on the compile line, and make sure that SOMobjects'
      include directory is consulted before BCOS2/include (because
      BCOS2/include contains older SOM.H include files).

     If the SOM compiler is interrupted by the user (using Ctrl+C, for
      example), it sometimes leaves a temporary file with a .CTN extension in
      the temporary directory specified by the SMTMP environmental variable.
      These should be removed periodically.

     When direct references to SOMFOREIGN types are made in an IDL struct or
      union, the C or C++ language bindings are generated incorrectly. To refer
      to a SOMFOREIGN type (for example, "somId") in a struct  or union  it is
      necessary to supply a secondary typedef for "somId". For example:

              #include <somobj.idl>
              struct S1
              {
                somId badId;    /* Generates incorrect */
              };                /* C/C++ bindings      */
              #include <somobj.idl>
              typedef somId somId2;
              struct S1
              {
                somId2 badId;   /* OK                  */
              };


ΓòÉΓòÉΓòÉ 7.6.7. SOM Dynamic Link Libraries (DLLs) ΓòÉΓòÉΓòÉ

When SOMobjects 2.0 (NOT the version shipped with this Warp Toolkit) is
installed on OS/2 Warp Version 3, the LIBPATH, PATH, and DPATH environment
variables in CONFIG.SYS are changed to place the SOMobjects directories before
the operating system directories in the search order for DLLs, EXEs, and data
files. This will cause the Workplace Shell to encounter an unrecoverable error
the next time the system is restarted because it requires the SOM DLLs that are
contained in the \OS2\DLL subdirectory.

In order to allow SOMobjects 2.0 Workstation applications to run successfully,
you must edit CONFIG.SYS and change the LIBPATH, PATH, and DPATH statements
before restarting the system. These statements must be changed to place the
operating system directories before the SOMobjects directories.

Note:  This only applies to SOMobjects Workstation applications, not Workgroup
       applications.

 The same problem will occur for any application that ships SOMobjects 2.0 DLLs
 if the application places its DLL directory first in the LIBPATH. Once again,
 the workaround is to assure that the \OS2\DLL subdirectory is before any other
 directory that contains earlier versions of the SOM DLLs. Any changes made to
 the PATH and DPATH environment variables by the application installation must
 also be reversed.


ΓòÉΓòÉΓòÉ 7.6.8. SOM and OpenDoc for OS/2 ΓòÉΓòÉΓòÉ

This version of OpenDoc for OS/2 uses the SOM programming model.  In it, the
headers are replaced by CORBA-compliant IDL files.  (CORBA stands for Common
Object Request Broker Architecture.)  The following general guidelines can be
used for writing code using SOM:

     Class implementers should probably avoid pass-by-value object parameters
      for methods.  If a class implementer does introduce such a method, then
      the comments for the method should make very clear the extent to which
      the argument might be modified, allowing the user to decide whether or
      not a copy should be passed (and then destroyed, after the method
      returns).

     Class users should avoid by-value object assignment.  This will not work
      if either the left-hand side or the right-hand side is a DSOM proxy.

     Class implementers should support all public data with attributes. Then,
      all public data access will be through attributes, which is supported by
      DSOM.

     Class implementers should avoid direct access to instance data from
      within static member functions.  This will not work on proxies. A useful
      and important rule of thumb is that, in general, the only code that
      should access instance data directly should be code that implements
      virtual or nonstatic methods.

     Class implementers should be aware of the fact that static member data is
      machine- (and perhaps process-) local.  Thus, static member data might or
      might not make sense, depending on the purpose for the data.

 One technique allowed by C++ that is strongly discouraged in SOM programming
 involves invoking an object's ancestor method directly, instead of letting
 normal method resolution via inheritance take its course.

 For example, consider the following class inheritance tree:

           A   B
           \ /
           C
           |
           D

 A method pointing to an instance of D can, in C++, explicitly ask for the foo
 method of A with syntax like "A::foo".  This avoids the normal inheritance and
 method resolution that would occur when sending the foo message to an instance
 of D.  That instance may well invoke the foo method defined by A, but it would
 first try to invoke one defined by D or C.

 This invocation will not work in SOM, particularly if you are planning to
 distribute objects.  The "instance of D" described in the previous paragraph
 might not, in fact, be an instance of D but a proxy to an instance of D.
 Normally, SOM hides the difference from you and properly accesses the D
 instance data members when needed.  When you go around normal message sending
 and method resolution, however, the data members for the "instance of D" would
 not be properly bound to the code in A::foo.

 Note that ancestor method calls for the target object of the current
 method--"this" in C++ or "self" in SOM--work fine.  Only when you try to call
 an ancestor method of an object that is not the current target object is there
 an issue.

 In general, if you find yourself using this technique, it is a strong
 indication that your class inheritance hierarchy needs to be redesigned.  In
 particular, you have probably collapsed two very different capabilities into
 one class.  Factoring out the capabilities will yield two class hierarchies,
 in which there is no need to skip over some classes to get to the right
 methods in others.


ΓòÉΓòÉΓòÉ 7.7. Workplace Shell Considerations ΓòÉΓòÉΓòÉ

When including an OBJECTID=<....> keyname=value pair in a setup string, you
must specify it at the end of the setup string.


ΓòÉΓòÉΓòÉ 8. System Debug Support ΓòÉΓòÉΓòÉ

This section introduces you to the interface that installs the debug kernel,
symbol files, and debug version of the PM. It also describes tools that support
your debugging efforts. The tools are categorized as follows:

     Communications
     The Debug Files
     Installing the Debug Installation Program
     MAPSYM
     T (Terminal Emulator)

 Additional details on the debug kernel can be found in the online Kernel Debug
 Reference in the Toolkit Information folder.


ΓòÉΓòÉΓòÉ 8.1. Communications ΓòÉΓòÉΓòÉ

Local and remote debugging are the same, except for the location of the system
to be debugged (also known as the system under test). If the system to be
debugged is close to the debug terminal, use a null modem cable to connect
them. If the system is physically distant, use modems. The default setup for
the communication port of the debug kernel is:

 Baud rate        9600
 Parity           none
 Data bits        8
 Stop bits        1


ΓòÉΓòÉΓòÉ 8.2. The Debug Files ΓòÉΓòÉΓòÉ

The files described in this section are referred to as either a retail or debug
version. "Retail" refers to the files that came with your OS/2 operating
system; "debug" refers to the files that are part of the Kernel Debugger
product.

Several versions of the Kernel Debugger product are available on The Developer
Connection for OS/2. Look for the following in the Developer Connection for
OS/2 Catalog under the Developer Toolkits category:

      Kernel Debugger for OS/2 2.x and Warp (IBM):  CD Install

      Kernel Debugger for OS/2 for SMP v2.11 (IBM):  CD Install

      Kernel Debugger for OS/2 for SMP v2.11 (IBM):  Diskettes

      Kernel Debugger for OS/2 Japan 2.1 CSD BJC006 (IBM):  CD Install

      Kernel Debugger for OS/2 Japan 2.11 (IBM):  CD Install

      Kernel Debugger for OS/2 ServicePak XR06300 v2.1 (IBM):  CD Install

      Kernel Debugger for OS/2 2.11 (IBM):  Diskettes

      Kernel Debugger for OS/2 Warp with WIN-OS2 (IBM):  Diskettes

      Kernel Debugger for OS/2 Warp Version 3 (IBM):  Diskettes


ΓòÉΓòÉΓòÉ 8.2.1. Debug Kernel ΓòÉΓòÉΓòÉ

The debug kernel, a special version of the OS/2 kernel, makes it possible to
set breakpoints and trace programs. It also permits the use of symbolic
addresses. You can interact with the debug kernel by using a modem or null
modem and a second asynchronous debug terminal.

Note:  You can only use the debug kernel files with the version of the OS/2
       operating system with which they are associated.


ΓòÉΓòÉΓòÉ 8.2.2. Debug Presentation Manager Interface ΓòÉΓòÉΓòÉ

The debug PM interface is a special version of the PM DLLs. The debugger
detects errors in your PM application and issues messages to the terminal. This
interface is not required to run the debug kernel.


ΓòÉΓòÉΓòÉ 8.3. Installing the Debug Installation Program ΓòÉΓòÉΓòÉ

The menu-based debug installation program installs debug replacement files for
the kernel and the PM interface. Once the program is installed, you can install
other debug files, or restore retail files, from an OS/2 command prompt.

During initial installation, two files are copied to the root directory of your
specified installation drive:

 DBINST.CMD               A command file that can be executed separately. This
                          file calls DBUGINST.EXE with the requested
                          installation drive as a command-line argument.

 DBUGINST.EXE             This executable file is the user interface. The user
                          can choose which parts of the debug system to
                          install, or which parts to restore to the retail
                          version.


ΓòÉΓòÉΓòÉ 8.3.1. Selecting Installation Options ΓòÉΓòÉΓòÉ

The user interface consists of a menu that provides installation choices in
three optional parts. It also provides the ability to restore two of those
parts to their corresponding retail versions.

The following is an illustration of the screen that appears:

When prompted to enter a debug installation option, choose the options in the
order they appear on the screen.

Review Editing the CONFIG.SYS File after your selections are complete.


ΓòÉΓòÉΓòÉ 8.3.2. Editing the CONFIG.SYS File ΓòÉΓòÉΓòÉ

When you complete the debug installation procedure, you may need to edit your
CONFIG.SYS file. The following paragraphs explain:

For the Debug Kernel:

If you installed only the debug kernel, shutdown and restart your system.

Restoring the Kernel:

To restore the retail kernel, run the debug installation program and select the
Restore retail kernel option.

For the Debug Presentation Manager Interface:

If you have installed the debug version of the PM interface, modify the DEVICE
statement with the PMDD.SYS line as follows:

  DEVICE=C:\OS2\DEBUG\DLL\PMDD.SYS  /Cn

The DEVICE statement includes the C drive as the installation drive and allows
you to call the debug version of PMDD.SYS from the OS2\DEBUG\DLL subdirectory.
The /C switch is set with n as the communication port for the debug output.

Modify the LIBPATH statement by adding the DEBUG\DLL subdirectory as follows:

  LIBPATH=C:\OS2\DEBUG\DLL; ...

Shut down and restart your system to have the changes take effect.

Restoring the Presentation Manager Interface:

To restore the retail PM, do the following:

   1. Restore the device statement:

              DEVICE=C:\OS2\PMDD.SYS

   2. Modify the LIBPATH statement by removing the DEBUG\DLL subdirectory.

   3. Shut down and restart your system to have the changes take effect.


ΓòÉΓòÉΓòÉ 8.4. MAPSYM ΓòÉΓòÉΓòÉ

MAPSYM is used to generate binary files that the debug kernel uses to associate
a symbolic name with an address in memory.


ΓòÉΓòÉΓòÉ 8.4.1. Starting MAPSYM ΓòÉΓòÉΓòÉ

MAPSYM creates public symbol (.SYM) files from map (.MAP) files. You must start
MAPSYM from the directory in which the map file is located. An example of the
syntax follows:

  MAPSYM filename  [options]

where:

 filename    Is the name of the map file. You do not have to type the .MAP
             file-name extension.

 options     Is the name of the MAPSYM option that modifies the action of
             MAPSYM.

 Note:  Be sure the .SYM files are in the same subdirectory as their
        corresponding DLLs.


ΓòÉΓòÉΓòÉ 8.5. T (Terminal Emulator) ΓòÉΓòÉΓòÉ

T is a terminal emulator and is used by the debug kernel to communicate with
the system to be debugged. You can use any ASCII terminal emulator; the Warp
Toolkit provides T. A terminal emulator allows a device, such as a personal
computer, to enter and receive data from a computer system as if it were a
particular type of attached terminal. For example, you use T to send and
receive ASCII files.

Hardware Requirements:

Make sure your system has a properly installed asynchronous-port and
communication-port driver, and that your CONFIG.SYS file has the following
line:

   DEVICE=C:\OS2\COM.SYS


ΓòÉΓòÉΓòÉ 8.5.1. Starting T ΓòÉΓòÉΓòÉ

You can start T at the command line by typing its executable name:

  T

A blank screen appears. Press F1; a menu appears that allows you to:

     Display function-key assignments
     Set up communication-port parameters
     Set the file name and start sending
     View the text that has scrolled off the screen
     Send the text that was written to a screen, to a file (capture mode)
     Toggle to the capture mode
     Set the file name or delete the current capture file
     Exit from the terminal program.

 Note:  Capture mode can be started automatically when T is executed by placing
        the line: Capture=yes in the initialization file.


ΓòÉΓòÉΓòÉ 9. Toolkit Support ΓòÉΓòÉΓòÉ

To ensure your success with the IBM Developer's Toolkit for OS/2 Warp, IBM
offers you not only excellent online and printed documentation but also a
"Getting Started" period.

What kind of support can I expect?

The IBM Developer's Toolkit for OS/2 Warp Technical Support Team can assist you
with the following kind of activities during a 60-day period that we call your
"Getting Started" period:

     Installing and using the IBM Developer's Toolkit for OS/2 Warp
     Reporting suspected system defects as a result of applying the IBM
      Developer's Toolkit for OS/2 Warp.

 When should I call?

 As a first step, use the online or hardcopy guide and reference manuals. If
 you still need assistance several options are available to you:

     CompuServe: 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 order number to the Developer Connection Administrator
      at CompuServe user id 73423,2767. To access the forum:

        1. Type GO OS2DF2 at the ! prompt

        2. Select the Developer Connection section

     Internet: Send questions or comments to [e-mail].

     OS/2 BBS: The DEVCON CFORUM or OS2TLKIT CFORUM, under TalkLink, is a
      feature under the IBMLink Commercial Services.

     If you do not have access to either CompuServe, Internet, or OS/2 BBS,
      then call us Monday through Friday between 8:00 a.m. and 5:00 p.m. your
      time, excluding U.S. national holidays.  Here's how:

        -  Locate your registration number for service entitlement on your
           Customer Service and Support brochure.

        -  Dial 1-800-992-4777.

      You will be presented with pre-recorded help options. Request to speak to
      a service representative who will make a note of your needs and dispatch
      them to a technical support person. Your call will be returned before the
      end of the next business day.

 Your 60 days of "Getting Started" support begins with this call.

 Note:  If you have a specific question regarding the Beta version
        entertainment components, you can call 1-800-553-1623 for technical
        support.


ΓòÉΓòÉΓòÉ 9.1. OpenDoc for OS/2 Support ΓòÉΓòÉΓòÉ

This section explains how to access information about OpenDoc and provide
feedback on the OpenDoc for OS/2 content of the Warp Toolkit.

     CompuServe:  You can use CompuServe to provide feedback on OpenDoc.
      Appends placed in this section will reach the OpenDoc development team.
      To access the forum:

        1. Type GO OS2DF1 at the ! prompt

        2. Select "OpenDoc for OS/2," section 14.

     Internet:  The Internet can also be used to send comments about OpenDoc.
      Send comments to [e-mail].

      Note:  This ID is not intended for technical support.

     World Wide Web:  You can get more information about OpenDoc at
      http://www.software.ibm.com/clubopendoc/ or http://www.cilabs.org/ on the
      World Wide Web.

     CI Labs:  CI Labs has a server on the Internet to provide mailing lists
      and other services for members and anyone interested in CI Labs
      activities.

      The sections that follow explain how to use the information provided by
      CI Labs:

        -  Using CI Labs Lists
        -  Subscribing to a List
        -  Removing Yourself From a List
        -  Accessing ListProc Live
        -  Using CI Labs Files
        -  Finding CI Labs Information

      Note:  The CI Labs support described here applies only to OpenDoc.


ΓòÉΓòÉΓòÉ 10. Ordering Information ΓòÉΓòÉΓòÉ

This section provides ordering information for the following:

     Hardcopy documentation
     Hyperwise
     The Developer Connection for OS/2


ΓòÉΓòÉΓòÉ 10.1. Hardcopy Documentation ΓòÉΓòÉΓòÉ

The hardcopy books can be ordered weekdays between 8 a.m. and 8 p.m. (Eastern
time).

For Canada and the United States, the following telephone or fax numbers can be
used for placing orders:

 Country             Telephone Number
 Canada              1-800-465-1234
 United States       1-800-879-2755

 For Asia/Pacific, Brazil, Europe, Japan, and Mexico mail your order to the
 following address:

  IBM Software Manufacturing Solutions (ISMS)
  Attn:  Direct Services
  Sortemosevey 21
  DK-3450 Alleroed
  Denmark

 When placing an order, please provide the part number (for books), quantity,
 and your credit card information ready. Charge your order to one of the
 following credit cards:

     American Express
     Diners Club
     Discover
     MasterCard
     VISA

 Please allow one to two weeks for delivery of telephone orders.

 The following list describes books available in hardcopy that might be of
 interest to users who develop applications for OS/2 Warp Version 3. The OS/2
 Warp Version 3 Technical Library provides both guidance and reference
 information and can be used for OS/2 Warp Version 3 development. The library
 includes the following printed books:

     Control Program Programming Guide
     Control Program Programming Reference
     Graphics Programming Interface Programming Guide
     Graphics Programming Interface Programming Reference
     Information Presentation Facility Programming Guide and Reference
     Multimedia Application Programming Guide
     Multimedia Programming Reference
     Multimedia Subsystem Programming Guide
     Presentation Manager Programming Guide - The Basics
     Presentation Manager Programming Guide - Advanced Topics
     Presentation Manager Programming Reference
     REXX User's Guide
     REXX Reference
     Tools Reference
     Workplace Shell Programming Guide
     Workplace Shell Programming Reference

 Programming guide information is organized by topic and contains everything an
 application developer needs--function details, data structures, and message
 descriptions--to design, write, and build function into an OS/2 application.

 Programming reference information provides detailed descriptions of the
 application programming interface (API) and contains remarks and examples to
 assist application developers in implementing each function.

 Application developers can choose to order the complete set of books, or order
 individual books separately.

 The information available in hardcopy is basically the same as the information
 in the online books contained in this Warp Toolkit.


ΓòÉΓòÉΓòÉ 10.1.1. OS/2 Technical Library Publications ΓòÉΓòÉΓòÉ

The following figure presents you each book of the OS/2 Version 3 Technical
Library with its associated part number. To order the full set use part number
G25H-7116.


ΓòÉΓòÉΓòÉ 10.1.2. Control Program Programming Guide ΓòÉΓòÉΓòÉ

This book describes the components of the OS/2 Control Program--file systems,
interprocess communication, program execution and control, memory management,
exception and error management, device I/O--and how to create an OS/2
application using Dosxxx functions.

A hardcopy version of this book is available separately with order part number
G25H-7101.


ΓòÉΓòÉΓòÉ 10.1.3. Control Program Programming Reference ΓòÉΓòÉΓòÉ

This book provides the detailed descriptions for the Dosxxx functions of the
OS/2 Control Program.

A hardcopy version of this book is available separately with order part number
G25H-7102.


ΓòÉΓòÉΓòÉ 10.1.4. Graphics Programming Interface Programming Guide ΓòÉΓòÉΓòÉ

This book describes the concepts associated with graphical output--presentation
spaces, device contexts, graphic primitives, fonts--and how to prepare
graphical output for display and printing, using Gpixxx functions.

A hardcopy version of this book is available separately with order part number
G25H-7106.


ΓòÉΓòÉΓòÉ 10.1.5. Graphics Programming Interface Programming Reference ΓòÉΓòÉΓòÉ

This book provides the detailed descriptions for the Gpixxx functions of the
Graphics Programming Interface.

A hardcopy version of this book is available separately with order part number
G25H-7107.


ΓòÉΓòÉΓòÉ 10.1.6. Information Presentation Facility Programming Guide and Reference ΓòÉΓòÉΓòÉ

This book describes the concepts--help windows, hypertext linking,
author-controlled viewports, dynamic data formatting--and the functions used
for implementing help in OS/2 applications. It describes how to create online
help and information. It also contains an alphabetic list of IPF tags, symbols,
and control words. The IPFC error messages, window functions, dynamic data
formatting functions, and help manager messages and functions are included.

A hardcopy version of this book is available separately with order part number
G25H-7110.


ΓòÉΓòÉΓòÉ 10.1.7. Multimedia Application Programming Guide ΓòÉΓòÉΓòÉ

This book describes the concepts associated with managing audio and video data
and hardware using an extendable architecture that includes logical media
devices (amplifier-mixer, waveform audio, MIDI sequencer, CD-audio, CD-XA,
digital video, and videodisc) and I/O procedures for supporting various file
formats.

A hardcopy version of this book is available separately with order part number
G25H-7112.


ΓòÉΓòÉΓòÉ 10.1.8. Multimedia Programming Reference ΓòÉΓòÉΓòÉ

This book describes the media control interface, PM graphic push buttons,
secondary windows functions, multimedia I/O services, and subsystem services
for synchronization and streaming.

A hardcopy version of this book is available separately with order part number
G25H-7114.


ΓòÉΓòÉΓòÉ 10.1.9. Multimedia Subsystem Programming Guide ΓòÉΓòÉΓòÉ

This book describes the subsystem components--media control driver, stream
handler, and I/O procedure--that support a multimedia device.

A hardcopy version of this book is available separately with order part number
G25H-7113.


ΓòÉΓòÉΓòÉ 10.1.10. Presentation Manager Programming Guide - Advanced Topics ΓòÉΓòÉΓòÉ

This book describes the advanced features of a sophisticated OS/2 window
application--font and file dialogs, containers, notebooks, hooks, dynamic data
exchange, direct manipulation--and how to implement them, using Winxxx and
other PM functions.

A hardcopy version of this book is available separately with order part number
G25H-7104.


ΓòÉΓòÉΓòÉ 10.1.11. Presentation Manager Programming Guide - The Basics ΓòÉΓòÉΓòÉ

This book describes the components of a basic OS/2 window application--windows
and message queues, window controls such as scroll bars, title bars, and
menus--and how to create them using Winxxx functions.

A hardcopy version of this book is available separately with order part number
G25H-7103.


ΓòÉΓòÉΓòÉ 10.1.12. Presentation Manager Programming Reference ΓòÉΓòÉΓòÉ

This book provides the detailed descriptions for Winxxx and other functions of
the OS/2 PM.

A hardcopy version of this book is available separately with order part number
G25H-7105.


ΓòÉΓòÉΓòÉ 10.1.13. REXX Reference ΓòÉΓòÉΓòÉ

This book provides detailed descriptions of the REXX functions.

A hardcopy version of this book is available separately with order part number
S10G-6268.


ΓòÉΓòÉΓòÉ 10.1.14. REXX User's Guide ΓòÉΓòÉΓòÉ

This book describes the REXX programming language and provides examples for
writing programs using REXX.

A hardcopy version of this book is available separately with order part number
S10G-6269.


ΓòÉΓòÉΓòÉ 10.1.15. Tools Reference ΓòÉΓòÉΓòÉ

This book describes the tools that are included in the IBM Developer's Toolkit
for OS/2 Warp.

A hardcopy version of this book is available separately with order part number
G25H-7111.


ΓòÉΓòÉΓòÉ 10.1.16. Workplace Shell Programming Guide ΓòÉΓòÉΓòÉ

This book describes the concepts associated with object-oriented programming
for the OS/2 operating system--System Object Model (SOM), Workplace Shell
classes and methods--and how to create object-oriented applications for the
OS/2 Desktop.

A hardcopy version of this book is available separately with order part number
G25H-7108.


ΓòÉΓòÉΓòÉ 10.1.17. Workplace Shell Programming Reference ΓòÉΓòÉΓòÉ

This book provides the detailed descriptions of the Workplace Shell
object-oriented programming interface.

A hardcopy version of this book is available separately with order part number
G25H-7109.


ΓòÉΓòÉΓòÉ 10.2. Hyperwise ΓòÉΓòÉΓòÉ

IBM has announced Hyperwise Version 2.0.  Hyperwise is a WYSIWYG editor for
development of OS/2 and Windows application helps and online books.  Its drag
and drop methods are far superior to the old tagging methods. Hyperwise Version
2.0 runs on OS/2 Warp and incorporates audio, video, graphics and animation
files into its helps and books.  The new features for version 2.0 are as
follows:

     Enhanced search
     Enhanced performance and usability
     HTML Export
     RTF Import
     Spellcheck
     Tutor/2 (an interactive tutorial manager)

 To obtain the latest pricing information or to order Hyperwise Version 2.0,
 contact your IBM Authorized Remarketer, or IBM marketing representative.
 Upgrade paths from Hyperwise Version 1.0 are also available from some
 participating IBM Authorized Remarketers.

 Hyperwise Version 2.0
 Product Order Number          30H1731
 Phone Number                  1-800-3IBMOS2 (1-800-342-6672) or Indelible Blue
                               at 1-800-776-8284


ΓòÉΓòÉΓòÉ 10.3. The Developer Connection for OS/2 ΓòÉΓòÉΓòÉ

The following telephone or fax numbers can be used for placing orders.

When placing an order, please have your credit card information ready. Charge
your order to one of the following credit cards:

     American Express
     Diners Club
     Discover
     MasterCard
     VISA

 Please allow one to two weeks for delivery of telephone orders.

 For more information double-click mouse button 2 anywhere on the map.


ΓòÉΓòÉΓòÉ 11. Give Us Your Feedback! ΓòÉΓòÉΓòÉ

We're interested in your feedback. Send us your comments and suggestions by
taking the Toolkit Survey and sending us Book Comments.


ΓòÉΓòÉΓòÉ 11.1. Toolkit Survey ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 11.2. Book Comments ΓòÉΓòÉΓòÉ

If there is something you like or dislike about any of the Warp Toolkit books,
please let us know! You can use one of the methods listed below to send your
comments to IBM. Include the book title and the name of the topic you are
commenting on.

The comments you send should pertain only to the information in the book and
its presentation. To request additional publications, ask questions, or make
comments about the functions of IBM products or systems, talk to your IBM
reseller or IBM marketing representative.

When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate without incurring
any obligation to you.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéCompuServe          Γöé[72410,624]                   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéInternet            Γöé[e-mail]           Γöé
Γöé                    Γöé[e-mail]         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéIBMMAIL             ΓöéUSIB66YK at IBMMAIL           Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

In addition to sending us electronic mail, you can also participate in these
forums monitored by IBM:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéProvider            ΓöéForum name                                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCompuServe          ΓöéOS/2 Developer Forum 1 - Developer Documentation  Γöé
Γöé                    Γöé(GO OS2DF1)                                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéOS/2 BBS            ΓöéDEVCON CFORUM                                     Γöé
ΓöéTalkLink            Γöé                                                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéIBM Internal        ΓöéOS2PUBS FORUM                                     Γöé
Γöé                    Γöé(IBMPC Conferencing Facility)                     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 12. Notices ΓòÉΓòÉΓòÉ

Fourth Edition (January 1996)

The following paragraph does not apply to the United Kingdom or any country
where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS
MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states
do not allow disclaimer of express or implied warranties in certain
transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time.

It is possible that this publication may contain reference to, or information
about, IBM products (machines and programs), programming, or services that are
not announced in your country.  Such references or information must not be
construed to mean that IBM intends to announce such IBM products, programming,
or services in your country.

Requests for technical information about IBM products should be made to your
IBM reseller or IBM marketing representative.


ΓòÉΓòÉΓòÉ 12.1. Copyright Notices ΓòÉΓòÉΓòÉ

(C)Copyright International Business Machines Corporation 1995, 1996. All rights
reserved.
Note to U.S. Government Users - Documentation related to restricted rights -
Use, duplication or disclosure is subject to restrictions set forth in GSA ADP
Schedule Contract with IBM Corp.


ΓòÉΓòÉΓòÉ 12.2. Disclaimers ΓòÉΓòÉΓòÉ

References in this publication to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program or service is not intended
to state or imply that only that IBM product, program, or service may be used.
Subject to IBM's valid intellectual property or other legally protectable
rights, any functionally equivalent product, program, or service may be used
instead of the IBM product, program, or service. The evaluation and
verification of operation in conjunction with other products, except those
expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:

      IBM Director of Licensing
      IBM Corporation
      500 Columbus Avenue
      Thornwood, NY  10594
      U.S.A.

 Licensees of this program who wish to have information about it for the
 purpose of enabling:  (i) the exchange of information between independently
 created programs and other programs (including this one) and (ii) the mutual
 use of the information which has been exchanged, should contact IBM
 Corporation, Department RM1A, 1000 N.W. 51st Street, Boca Raton, FL 33431,
 U.S.A.  Such information may be available, subject to appropriate terms and
 conditions, including in some cases, payment of a fee.


ΓòÉΓòÉΓòÉ 12.3. Trademarks ΓòÉΓòÉΓòÉ

The following terms are trademarks of the IBM Corporation in the United States
or other countries or both:

 AVC                      OS/2
 C/2                      Presentation Manager
 Common User Access       SOMobjects
 C Set ++                 Ultimotion
 CUA                      VisualAge
 Hyperwise                WIN-OS2
 IBM                      Workplace Shell

 The following terms are trademarks of other companies:

 1-2-3/G                  Lotus Development Corp.
 American Express         American Express Incorporated
 Ami Pro                  Lotus Development Corp.
 Apple                    Apple Computer, Inc.
 Bento                    Apple Computer, Inc.
 Borland C++              Borland International, Inc.
 BRender                  Argonaut Technologies Limited
 C++                      American Telephone and Telegraph Company
 CompuServe               CompuServe Incorporated
 CORBA                    Object Management Group, Inc.
 Diners Club              Diners Club of America
 Discover                 Sears, Roebuck and Co.
 MASM                     Microsoft Corporation
 MasterCard               MasterCard International, Incorporated
 Microsoft                Microsoft Corporation
 OpenDoc                  Apple Computer, Inc.
 VISA                     VISA International Services Association
 Win32                    Microsoft Corporation
 Windows NT               Microsoft Corporation
 WinTV                    Hauppauge Computer Works, Inc.
 WordPerfect              WordPerfect Corporation

 Windows is a trademark of Microsoft Corporation.

 Other company, product, and service names, which may be denoted by a double
 asterisk (**), may be trademarks or service marks of others.


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\BETA Subdirectories ΓòÉΓòÉΓòÉ

 BETA                         - Contains Beta versions of new
  Γöé                             tools, samples, and online books
  Γö£ΓöÇ\BIN                      - Beta versions of new tools
  Γö£ΓöÇ\BOOK                     - Beta versions of new online books
  Γö£ΓöÇ\BRENDER                  - BRender samples and tools
  Γöé   Γö£ΓöÇ\DAT                  - Miscellaneous data files for
  Γöé   Γöé                          BRender samples
  Γöé   Γö£ΓöÇ\INCLUDE              - BRender header files
  Γöé   Γö£ΓöÇ\LIB                  - BRender libraries
  Γöé   Γö£ΓöÇ\SAMPLES              - BRender samples
  Γöé   Γöé   ΓööΓöÇ\ROBOT            - Robot Walking sample
  Γöé   ΓööΓöÇ\TOOLS                - BRender tools (3DS2BR.EXE)
  Γö£ΓöÇ\DLL                      - Dynamic link library (.DLL) files
  Γö£ΓöÇ\H                        - C and C++ header files
  Γö£ΓöÇ\HELP                     - Help (.HLP) files
  Γö£ΓöÇ\ICON                     - Icon (.ICO) files
  Γö£ΓöÇ\LIB                      - Import library (LIB) files
  Γö£ΓöÇ\SAMPLES                  - Beta versions of new samples
  Γöé   Γö£ΓöÇ\ENTOOLKT             - Entertainment samples
  Γöé   Γöé   Γö£ΓöÇ\AUDIO            - Audio samples
  Γöé   Γöé   Γöé   Γö£ΓöÇ\DAUDIO       - Direct Audio sample
  Γöé   Γöé   Γöé   ΓööΓöÇ\MIDI         - Real Time MIDI sample
  Γöé   Γöé   Γö£ΓöÇ\INPUT            - Input Device sample
  Γöé   Γöé   Γöé   ΓööΓöÇ\JOYSTICK     - Joystick sample
  Γöé   Γöé   Γö£ΓöÇ\NETWORK          - Networking sample
  Γöé   Γöé   Γöé   ΓööΓöÇ\TICTAC       - TicTacToe sample
  Γöé   Γöé   ΓööΓöÇ\VIDEO            - Video sample
  Γöé   Γöé       Γö£ΓöÇ\BEEHIVE      - Sprite Compiler sample
  Γöé   Γöé       ΓööΓöÇ\FSDIVE       - Full-Screen DIVE sample
  Γöé   Γö£ΓöÇ\OPENDOC              - Contains OpenDoc samples
  Γöé   Γöé   Γö£ΓöÇ\PARTS            - Contains OpenDoc part handler samples
  Γöé   Γöé   Γöé   Γö£ΓöÇ\CNTNRPART    - Container part handler sample
  Γöé   Γöé   Γöé   ΓööΓöÇ\PUBLIC       - Common files for OpenDoc part
  Γöé   Γöé   Γöé                      handler samples
  Γöé   Γöé   ΓööΓöÇ\PUBUTILS         - Public utilities library source
  Γöé   Γöé                          code
  Γöé   ΓööΓöÇ\URE
  Γöé       Γö£ΓöÇ\3D         - 3D PM control URE sample
  Γöé       Γö£ΓöÇ\3DLINE     - 3D line PM control URE sample
  Γöé       Γö£ΓöÇ\CHKMARK    - Check mark PM control URE sample
  Γöé       Γö£ΓöÇ\CLRWHEEL   - Color wheel PM control URE sample
  Γöé       Γö£ΓöÇ\COMBOBOX   - Super combination box PM control URE sample
  Γöé       Γö£ΓöÇ\COMBOMIN   - Super minimized combination box PM
  Γöé       Γöé                control URE sample
  Γöé       Γö£ΓöÇ\CONTROL    - Custom PM control URE sample
  Γöé       Γö£ΓöÇ\DATEFLD    - Date entry field PM control URE sample
  Γöé       Γö£ΓöÇ\EXAMPLE    - Main entry point PM control URE sample
  Γöé       Γö£ΓöÇ\FRAME      - Shadowed frame PM control URE sample
  Γöé       Γö£ΓöÇ\IMAGEBTN   - Image button PM control URE sample
  Γöé       Γö£ΓöÇ\LIB        - URE import library (LIB) files
  Γöé       Γö£ΓöÇ\LISTBOX    - Super list box PM control URE sample
  Γöé       Γö£ΓöÇ\MULTIWIN   - Multiple window URE sample
  Γöé       Γö£ΓöÇ\NOTEBOOK   - Notebook URE sample
  Γöé       Γö£ΓöÇ\NOTEPAGE   - Super notebook custom PM control URE sample
  Γöé       Γö£ΓöÇ\PATTERN    - Pattern PM control URE sample
  Γöé       Γö£ΓöÇ\RESOURCE
  Γöé       Γöé   ΓööΓöÇ\386    - Contains assembly language code for URE
  Γöé       Γöé                resource-only samples
  Γöé       Γö£ΓöÇ\SPINBTN    - Super spin button PM control URE sample
  Γöé       Γö£ΓöÇ\STATBAR    - Status bar PM control URE sample
  Γöé       Γö£ΓöÇ\SUPPORT    - Window controls support code
  Γöé       Γö£ΓöÇ\TESTBED    - Test bed URE application sample
  Γöé       ΓööΓöÇ\TIMEFLD    - Time entry field PM control URE sample
  ΓööΓöÇ\SYS                - System (.SYS) files


ΓòÉΓòÉΓòÉ <hidden> Ordering Information - Supplement ΓòÉΓòÉΓòÉ

When calling from the following countries:

The Developer Connection for OS/2 can be ordered from the following countries.
For Asia/Pacific, please ensure that you dial the international access code
applicable to your country before the listed phone number. Note that 61 is the
country code for Australia.

 Country                Telephone Number
 Asia/Pacific           61 2 3547684
   Fax                  61 2 3547766
 Canada                 1-800-561-5293 (Toll free)
 Germany                0 130 812177   (Toll free)
 United States          1-800-6DEVCON
                        (Toll free: 1-800-633-8266)
  Fax                   1-303-330-7655

 In Central and South America:

 Country                Telephone Number
 Argentina              01-313-0014
 Bolivia                02-351840
 Brazil                 0800-111205  (Toll free)
   Fax                  011-886-3222
 Chile                  02-633-4400
 Colombia               01-257-0111
 Costa Rica             223-6222
 Dominican Republic     566-5161
 Ecuador                02-565100
 El Salvador            02-985011
 Guatemala              02-315859
 Honduras               32-2319
 Mexico                 91-800-00316  (Toll free)
  Mexico City           [phone]
 Panama                 02-639977
 Paraguay               021-444094
 Peru                   014-366345
 Uruguay                02-923617
 Venezuela              02-908-8901

 In Europe:

 The Developer Connection for OS/2 can be ordered direct from IBM SPC in
 Denmark (45 is the country code) if you are calling outside the countries
 listed above. Please ensure that you dial the international access code
 applicable to your country before dialing the appropriate phone number. This
 applies to both telephone and fax orders. Operators speaking the following
 languages are available:

 Language               Telephone
 Spoken                 Number
 Danish                 45 4 8101300
 Dutch                  45 4 8101400
 English                45 4 8101500
 Finnish                45 4 8101650
 French                 45 4 8101200
 German                 45 4 8101000
 Italian                45 4 8101600
 Norwegian              45 4 8101250
 Spanish                45 4 8101100
 Swedish                45 4 8101150
 Fax                    45 4 8142207


ΓòÉΓòÉΓòÉ <hidden> Using CI Labs Lists ΓòÉΓòÉΓòÉ

The CILABS-ANNOUNCE list carries announcements from CI Labs. CILABS-INTEREST is
a forum for interested parties to discuss CI Labs issues. Other lists discuss
specific CI Labs technologies, requirements for additional technologies, or
component software in general.

The following CI Labs lists are open to the public:

 CILABS-ANNOUNCE          A read-only list with announcements regarding
                          Component Integration Laboratories (CI Labs).

 CILABS-INTEREST          Open forum for nontechnical discussion of CI Labs
                          plans and charter.

 OPENDOC-ANNOUNCE         A read-only list with announcements of broad
                          interests regarding OpenDoc.

 OPENDOC-INTEREST         Open forum for discussion of OpenDoc, a compound
                          document architecture.

 BENTO-ANNOUNCE           A read-only list with announcements of broad
                          interests regarding Bento.

 BENTO-INTEREST           Open forum for discussion of Bento, a persistent
                          object storage format.


ΓòÉΓòÉΓòÉ <hidden> Subscribing to a List ΓòÉΓòÉΓòÉ

To subscribe to a list, send either of the following commands in the first line
(not on the "Subject:" line) of the body of e-mail addressed to
[e-mail]:

  subscribe <PUT-LIST-NAME-HERE> <Your full name>
 or

  join <PUT-LIST-NAME-HERE> <Your full name>
 For example:

  subscribe OPENDOC-INTEREST Jane Doe
  join OPENDOC-INTEREST Jane Doe

ListProc only requires your name, and will take your e-mail address from the
header information.  After [e-mail] processes your request, you will
receive a "Welcome" message that will give you more information on the list,
information on other resources that might be available to you, and a password
for use with a live session. (See Accessing ListProc Live for more
information.)

The line following your request may need to read, "end" to prevent confusion if
your mailer adds a signature to your message.


ΓòÉΓòÉΓòÉ <hidden> Removing Yourself From a List ΓòÉΓòÉΓòÉ

If you do not feel that you should be on this list, or later want to remove
yourself from a list, send the following command in the first line (not on the
"Subject:" line) of the body of an e-mail to [e-mail]:

  which PARTIAL-EMAIL-ADDRESS

[e-mail] will return an email with a list of all of the lists to
which you currently subscribe. Then send either of the following commands in
the first line of the body of an e-mail to [e-mail] for each list
you wish to unsubscribe:

  unsubscribe PUT-LIST-NAME-HERE
 or

  signoff PUT-LIST-NAME-HERE
 For example:

  unsubscribe OPENDOC-INTEREST

The line following the your request may need to say "end" to prevent confusion
if your mailer adds a signature to your message.

If you are sending your unsubscribe request from the same account that you
subscribed with, you will receive an acknowledgement from [e-mail]
that you have been unsubscribed.  If you unsubscribe from a different account,
the list administrators will receive an unsubscribe approval request that might
take a day or so to process.

If you have trouble unsubscribing, you can send the command HELP to
[e-mail], or send mail to [e-mail], and we will be glad to
manually unsubscribe you from any lists that you do not wish to belong to.


ΓòÉΓòÉΓòÉ <hidden> Accessing ListProc Live ΓòÉΓòÉΓòÉ

In addition to being able to subscribe, unsubscribe, and set list options
through mail, ListProc allows subscribers to connect and modify their list
options.

In order to connect, you will require an ILP (Interactive ListProcessor)
client. As clients are developed, we will make them available on the CILABS.ORG
server. Announcements of new client releases will be sent to the
CILABS-ANNOUNCE mailing list.

If you have an ILP client, simply type:

  ilp cilabs.org

You will be asked to provide an email address and the password sent to you upon
initial subscription to CI Labs lists.  Once connected as a subscriber, you
will be able to set preferences for how you wish to receive your mail, get list
statistics, and, of course, subscribe to and unsubscribe from lists.


ΓòÉΓòÉΓòÉ <hidden> Using CI Labs Files ΓòÉΓòÉΓòÉ

CI Labs also maintains a number of files on FTP.CILABS.ORG, including
information on OpenDoc, Bento specifications, and other information on CI Labs.
These files are available via anonymous FTP at FTP.CILABS.ORG, via Mosaic or
World Wide Web at ftp://ftp.cilabs.org/pub/, or via FTPMail.

To request information on how to use FTPMail, send a message to
[e-mail] with the single word HELP in the body of the message (again,
commands in the "Subject:" line are not processed).

If you are having difficulties finding information on CILABS.ORG, or have
additional questions regarding how to access information from the
FTP.CILABS.ORG server, please send mail to [e-mail].

In the interim, we encourage you to add your name to one of CI Labs electronic
mail information lists at CILABS.ORG or to download files from our server at
FTP.CILABS.ORG.


ΓòÉΓòÉΓòÉ <hidden> Finding CI Labs Information ΓòÉΓòÉΓòÉ

If for some reason you are unable to get files from our server, you can get an
information packet by sending your mailing address to [e-mail] or to
this U.S. mail address:

     Component Integration Laboratories, Inc.
     PO Box 61747
     Sunnyvale, CA 94088-1747
     [phone] Telephone
     [phone] Fax


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SOM Subdirectories ΓòÉΓòÉΓòÉ

  SOM              - SOM subdirectories
   Γöé
   Γö£ΓöÇ\BIN          - SOM executable (.EXE) files
   Γö£ΓöÇ\COMMON       - SOM common-file subdirectories,
   Γöé   Γöé             which contains the runtime files
   Γöé   Γö£ΓöÇ\DLL        common with OS/2 Warp Version 3
   Γöé   Γö£ΓöÇ\ETC
   Γöé   Γö£ΓöÇ\INSTALL
   Γöé   ΓööΓöÇ\SYSTEM
   Γö£ΓöÇ\INCLUDE      - SOM .IDL, .SC, .H, .XH, .HC, .HS,
   Γöé                 and .EFW header files
   Γö£ΓöÇ\LIB          - SOM library (.LIB & .DLL) files
   ΓööΓöÇ\MSG          - SOM message (.MSG) file


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES Subdirectories ΓòÉΓòÉΓòÉ

 \SAMPLES      - Contains common information for all
    Γöé            samples, as well as SAMPLES.DOC
    Γöé
    Γö£ΓöÇ\BIDI    - Bidirectional (BIDI) samples
    Γö£ΓöÇ\DAPIE   - IBM Developer API Extensions for OS/2 samples
    Γö£ΓöÇ\MM      - Multimedia samples
    Γö£ΓöÇ\OPENDOC - OpenDoc samples
    Γö£ΓöÇ\OS2     - Control Program samples
    Γö£ΓöÇ\PM      - Presentation Manager samples
    Γö£ΓöÇ\REXX    - Common information for the C-language REXX samples
    ΓööΓöÇ\WPS     - Workplace Shell samples


ΓòÉΓòÉΓòÉ <hidden> \SAMPLES ΓòÉΓòÉΓòÉ

\SAMPLES
  Γö£ΓöÇ\BIDI
  Γö£ΓöÇ\DAPIE
  Γö£ΓöÇ\MM
  Γö£ΓöÇ\OPENDOC
  Γö£ΓöÇ\OS2
  Γö£ΓöÇ\PM
  Γö£ΓöÇ\REXX
  ΓööΓöÇ\WPS


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES\BIDI Subdirectories ΓòÉΓòÉΓòÉ

 \BIDI           - Contains the bidirectional (BIDI) samples
   Γö£ΓöÇ\ARABIC      - Contains the Arabic-specific BIDI samples
   Γöé   Γö£ΓöÇ\STYLE   - Arabic Style sample
   Γöé   ΓööΓöÇ\TELDIR  - Arabic Telephone Directory sample
   ΓööΓöÇ\HEBREW      - Contains the Hebrew-specific BIDI samples
       Γö£ΓöÇ\STYLE   - Hebrew Style sample
       ΓööΓöÇ\TELDIR  - Hebrew Telephone directory sample


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES\MM Subdirectories ΓòÉΓòÉΓòÉ

 \MM            - Contains the Multimedia samples,templates,
   Γöé              and command tables
   Γö£ΓöÇ\ADMCT     - Waveform Audio Media Control Driver sample
   Γö£ΓöÇ\ASYMREC   - Asymmetric Recording sample
   Γö£ΓöÇ\AVCINST   - AVC I/O Procedure Installation sample
   Γö£ΓöÇ\CAPDLL    - Caption sample support files (DLL)
   Γö£ΓöÇ\CAPSAMP   - Caption sample
   Γö£ΓöÇ\CAPTION   - Caption Creation Utility program
   Γö£ΓöÇ\CASECONV  - Case Converter I/O procedure sample
   Γö£ΓöÇ\CDMCIDRV  - CD Audio Media Control Driver sample
   Γö£ΓöÇ\CF        - Control File templates
   Γö£ΓöÇ\CLOCK     - Memory Playlist sample
   Γö£ΓöÇ\CODEC     - Compressor/Decompressor sample
   Γö£ΓöÇ\DIVE      - Direct Interface Video Extensions sample
   Γö£ΓöÇ\DOUBPLAY  - Double Buffering Playlist sample
   Γö£ΓöÇ\DUET1     - Streaming Device Duet sample
   Γö£ΓöÇ\DUET2     - Streaming and Non-Streaming Device Duet sample
   Γö£ΓöÇ\FSSHT     - File System Stream Handler sample
   Γö£ΓöÇ\MCDTBL    - Media Control Driver (MCD) command tables
   Γö£ΓöÇ\MCDTEMP   - Media Control Driver (MCD) template
   Γö£ΓöÇ\MCISPY    - Message Monitoring sample
   Γö£ΓöÇ\MCISTRNG  - Media Control Interface String Test sample
   Γö£ΓöÇ\MMBROWSE  - Image Browser sample
   Γö£ΓöÇ\MMIOPROC  - M-Motion I/O procedure sample
   Γö£ΓöÇ\MOVIE     - Movie sample
   Γö£ΓöÇ\RECORDER  - Audio Recording sample
   Γö£ΓöÇ\SHORTCF   - Control File templates (subset of the \CF directory)
   Γö£ΓöÇ\SHRCFILE  - Stream Handler Resource File sample
   Γö£ΓöÇ\TUNER     - TV Tuner sample
   Γö£ΓöÇ\ULTIEYES  - Non-Linear Video sample
   ΓööΓöÇ\ULTIMOIO  - Ultimotion I/O procedure sample


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES\OS2 Subdirectories ΓòÉΓòÉΓòÉ

 \OS2             - Contains the Control Program samples
   Γö£ΓöÇ\CONSOLIO    - Console I/O sample (Worms)
   Γö£ΓöÇ\DLLAPI      - Dynamic Link Library sample
   Γö£ΓöÇ\EAEDIT      - Extended Attributes Editor sample (EAS)
   Γö£ΓöÇ\HANOI       - Multithreaded sample (Towers of Hanoi)
   Γö£ΓöÇ\NPIPE       - Named Pipes sample
   Γö£ΓöÇ\QUEUES      - Interprocess Communication Queue sample
   Γö£ΓöÇ\SEMAPH      - Semaphore sample
   Γö£ΓöÇ\SORT        - Multithreaded sample (Sorting Algorithm)
   Γö£ΓöÇ\TIMESERV    - Timer Services sample (Clock)
   ΓööΓöÇ\VMM         - Virtual Memory Management sample


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES\PM Subdirectories ΓòÉΓòÉΓòÉ

 \PM              - Contains the Presentation Manager samples
   Γö£ΓöÇ\BMPSAMP     - Bit map Manipulation sample (Jigsaw)
   Γö£ΓöÇ\CLIPBRD     - Clipboard sample
   Γö£ΓöÇ\CONTROLS    - PM Controls sample (Style)
   Γö£ΓöÇ\DIALOG      - Introductory Dialog Box sample
   Γö£ΓöÇ\DRAGDROP    - Direct Manipulation (Dragdrop) sample
   Γö£ΓöÇ\GRAPHIC     - Non-retained Graphic sample
   Γö£ΓöÇ\IPF         - Information Presentation Facility sample
   Γö£ΓöÇ\PALETTE     - Palette Manager sample
   Γö£ΓöÇ\PORTING     - PM 16-bit to 32-bit Porting sample (Image32)
   Γö£ΓöÇ\PRINT       - Printer sample
   Γö£ΓöÇ\STDWND      - Standard Window sample (Hello)
   ΓööΓöÇ\TEMPLATE    - Application Template sample


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES\REXX Subdirectories ΓòÉΓòÉΓòÉ

 \REXX              - Contains REXX samples
   Γö£ΓöÇ\API           - Contains the REXX API samples
   Γöé   Γö£ΓöÇ\CALLREXX  - REXX Interpreter Invocation sample
   Γöé   Γö£ΓöÇ\DEVINFO   - REXX Variable Pool Interface sample
   Γöé   Γö£ΓöÇ\PMREXX    - Presentation Manager REXX Interface sample
   Γöé   Γö£ΓöÇ\REXXCALC  - Presentation Manager REXX Calculator sample
   Γöé   Γö£ΓöÇ\REXXUTIL  - REXX Utility Functions sample
   Γöé   ΓööΓöÇ\RXMACDLL  - External Functions in REXX Macrospace sample
   Γö£ΓöÇ\SOM           - Contains the REXX SOM interface samples
   Γöé   ΓööΓöÇ\ANIMAL    - SOM class sample
   ΓööΓöÇ\WPS           - Contains the REXX WPS interface samples


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES\WPS Subdirectories ΓòÉΓòÉΓòÉ

 \WPS             - Contains the Workplace Shell samples
   Γö£ΓöÇ\BROWSE      - ASCII/Hex File Browser sample
   Γö£ΓöÇ\CAR         - WPDataFile Subclass (C) sample
   Γö£ΓöÇ\CARPP       - WPDataFile Subclass (C++) sample
   Γö£ΓöÇ\TEXTFLDR    - Text Folder sample
   Γö£ΓöÇ\WPSTUTOR    - Tutorial sample
   ΓööΓöÇ\WSFILE      - Workplace File object sample


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES\OPENDOC Subdirectories ΓòÉΓòÉΓòÉ

 \OPENDOC          - Contains the OpenDoc samples
   ΓööΓöÇ\PARTS        - OpenDoc part handler samples
       Γö£ΓöÇ\COOKBOOK - Cookbook part handler sample
       Γö£ΓöÇ\HELLO    - Hello World part handler sample
       Γö£ΓöÇ\PUSHBTN  - Push Button part handler sample
       Γö£ΓöÇ\TTAPE1   - Ticker Tape 1 part handler sample
       ΓööΓöÇ\TTAPE2   - Ticker Tape 2 part handler sample


ΓòÉΓòÉΓòÉ <hidden> \TOOLKIT\SAMPLES\DAPIE Subdirectories ΓòÉΓòÉΓòÉ

 \DAPIE             - IBM Developer API Extensions for OS/2 samples
   Γö£ΓöÇ\BROWSER       - Browser Sample (Windows version)
   Γö£ΓöÇ\BROWSER2      - Browser Sample (OS/2 version)
   Γö£ΓöÇ\DLLENTRY      - DLL initialization entry point
   Γö£ΓöÇ\HIWORLD       - HiWorld sample (Windows version)
   Γö£ΓöÇ\HIWORLD2      - HiWorld sample (OS/2 version)
   Γö£ΓöÇ\TOYBOX        - Bitmap Manipulation Sample (Windows version)
   Γö£ΓöÇ\TOYBOX2       - Bitmap Manipulation Sample (OS/2 version)
   ΓööΓöÇ\WINMAIN       - WinMain wrapper function