________________________________________________________________

        IBM DEVELOPER'S TOOLKIT FOR OS/2 WARP, VERSION 3
                           README FILE
________________________________________________________________

Welcome to the IBM* Developer's Toolkit for OS/2* Warp, Version 3
(Toolkit).  This release of the Toolkit contains new and updated
tools, samples, header files, and online technical documentation.

This README file introduces the Toolkit, explains the contents and
directory structure, describes how to install the Toolkit, and
discusses some of the things that have been changed and added for
this release.

For best viewing, use a non-proportional font to view this file.

This file contains the following sections:

   - STRUCTURE OF THE TOOLKIT
   - UPDATES TO CONFIG.SYS
   - INSTALLING THE TOOLKIT FROM DISKETTE
   - USING THE TOOLKIT DIRECTLY FROM THE CD
   - CHANGES IN THE TOOLS
   - CHANGES IN THE HEADER FILES
   - CHANGES IN THE SAMPLES
   - CHANGES IN THE TECHNICAL DOCUMENTATION
   - PROGRAMMING CONSIDERATIONS
   - BOOKS FOR APPLICATION DEVELOPERS
   - SOM README INFORMATION

The contents of the MMPM/2 Toolkit have been merged into this Toolkit.
Therefore, there are multimedia samples, header files, libraries, and
technical documentation included in the corresponding subdirectories.

This version of the Toolkit can be installed from a CD-ROM drive over
a LAN.


STRUCTURE OF THE TOOLKIT
________________________________________________________________

The tools, samples, and technical documentation in the Toolkit are
available in two ways.  You can access them through the Toolkit folder
and its sub-folders on the Workplace Shell* desktop, or you can access
them using an OS/2 window or OS/2 full screen session and changing
into the TOOLKIT directory and its subdirectories.


FOLDER HIERARCHY
----------------
The Toolkit package has the following Workplace Shell folder hierarchy:

  IBM Developer's Toolkit               - Root folder of the Toolkit.
  for OS/2 Warp, Version 3                Contains the README file and the
   ³                                      other Toolkit folders
   ³
   ÃÄ Development Tools                 - Programming tools
   ³
   ÃÄ Toolkit Information               - Online technical books
   ³
   ÃÄ OS/2 Sample Programs              - Control Program sample programs
   ³
   ÃÄ PM Sample Programs                - Presentation Manager* (PM) sample
   ³                                      programs
   ³
   ÃÄ Workplace Shell Sample Programs   - Workplace Shell sample programs
   ³
   ÃÄ CREXX Sample Programs             - REXX sample programs
   ³
   ÃÄ Multimedia Sample Programs        - Multimedia sample programs
   ³
   ÃÄ Multimedia Bitmaps                - Sample multimedia bitmaps
   ³
   ÀÄ NeatStuff                         - Beta versions of new tools.  See
                                          NEAT STUFF later in this README.



DIRECTORY HIERARCHY
-------------------
The Toolkit package has the following directory structure:

  \TOOLKIT                 - Root subdirectory for the Toolkit.
    ³                        Contains this README file.
    ³
    ÃÄ\BIN                 - Toolkit tools (executable files)
    ³   ÀÄ\BETA            - Beta versions of new tools
    ÃÄ\BITMAP              - Sample multimedia bitmaps
    ÃÄ\BOOK                - Online technical information
    ÃÄ\DLL                 - DLLs for the Toolkit
    ÃÄ\H                   - C and C++** header files
    ÃÄ\HELP                - Toolkit help (.HLP) files
    ÃÄ\ICON                - Icons for the Toolkit
    ÃÄ\IDL                 - Workplace Shell IDL files
    ÃÄ\INC                 - INC (Assembler header) files
    ÃÄ\IPFC                - Files used by the IPFC compiler
    ÃÄ\LIB                 - Import library (LIB) files
    ÃÄ\TMP                 - Used to store temporary files
    ÃÄ\SOM                 - SOM subdirectories
    ³   ÃÄ\BIN             - SOM executable files
    ³   ÃÄ\COMMON\...      - SOM common-file subdirectories, which contain the
    ³   ³                    runtime files common with OS/2 Warp, Version 3
    ³   ÃÄ\INCLUDE         - SOM IDL, SC, H, XH, HC, HS, and EFW header files
    ³   ÃÄ\LIB             - SOM library files
    ³   ÀÄ\MSG             - SOM message files
    ³
    ÀÄ\SAMPLES             - Contains common information for all
        ³                    samples, as well as SAMPLES.DOC
        ³
        ÃÄ\BIDI            - Contains all bidirectional (BIDI) samples
        ³   ÃÄ\ARABIC      - Contains all Arabic-specific BIDI samples
        ³   ³   ÃÄ\STYLE   - Arabic Style sample
        ³   ³   ÀÄ\TELDIR  - Arabic Telephone Directory sample
        ³   ÀÄ\HEBREW      - Contains all Hebrew-specific BIDI samples
        ³       ÃÄ\STYLE   - Hebrew Style sample
        ³       ÀÄ\TELDIR  - Hebrew Telephone Directory sample
        ³
        ÃÄ\CREXX           - Contains common information for the
        ³   ³                C-language REXX 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
        ³
        ÃÄ\OS2             - Contains the Control Program sample
        ³   ÃÄ\CONSOLIO    - Console I/O sample (WORMS)
        ³   ÃÄ\DLLAPI      - Dynamic Link Library sample
        ³   ÃÄ\EAEDIT      - Extended Attributes Editor
        ³   ÃÄ\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 (Clock) sample
        ³   ÀÄ\VMM         - Virtual Memory Management sample
        ³
        ÃÄ\PM              - Contains all Presentation Manager samples
        ³   ÃÄ\BMPSAMP     - Bitmap Manipulation sample (Jigsaw)
        ³   ÃÄ\CLIPBRD     - Clipboard sample
        ³   ÃÄ\CONTROLS    - PM Controls sample (Style)
        ³   ÃÄ\DIALOG      - Introductory Dialog Box sample
        ³   ÃÄ\DRAGDROP    - Direct Manipulation (Dragdrop) sample
        ³   ÃÄ\GRAPHICS    - Non-retained Graphics sample
        ³   ÃÄ\IPF         - Information Presentation Facility sample
        ³   ÃÄ\PALETTE     - Palette sample
        ³   ÃÄ\PORTING     - PM 16-bit to 32-bit Porting sample (Image)
        ³   ÃÄ\PRINT       - Print sample
        ³   ÃÄ\STDWND      - Standard Window sample (Hello)
        ³   ÀÄ\TEMPLATE    - Application Template
        ³
        ÃÄ\WPS             - Contains all Workplace Shell samples
        ³   ÃÄ\BROWSE      - Workplace Shell ASCII/Hex File Browser
        ³   ÃÄ\CAR         - Workplace Shell WPDataFile Subclass (C) sample
        ³   ÃÄ\TEXTFLDR    - Workplace Shell Text Only Folder sample
        ³   ÀÄ\WPSTUTOR    - Workplace Shell Tutorial sample
        ³
        ÀÄ\MM
            ÃÄ\ADMCT       - Waveform Audio Media Control Driver Sample
            ÃÄ\ASYMREC     - Asymmetric Recording sample
            ÃÄ\AVCINST     - AVC I/O Procedure Installation Sample
            ÃÄ\CAPDLL      - Caption Sample Application support files
            ÃÄ\CAPSAMP     - Caption Sample Application
            ÃÄ\CAPTION     - Caption Creation Utility
            ÃÄ\CASECONV    - Case Converter I/O Procedure
            ÃÄ\CDMCIDRV    - CD Audio Media Control Driver sample
            ÃÄ\CF          - Install Control Files
            ÃÄ\CLOCK       - Memory Playlist sample
            ÃÄ\CODEC       - Compressor/Decompressor sample
            ÃÄ\DIVE        - Direct Interface Video Extensions (DIVE) sample
            ÃÄ\DUET1       - Waveaudio With Waveaudio sample
            ÃÄ\DUET2       - Waveaudio With CD-Audio sample
            ÃÄ\FSSHT       - File System Stream Handler sample
            ÃÄ\MCDTBL      - Media Control Driver Command Tables
            ÃÄ\MCDTEMP     - Media Control Driver Template
            ÃÄ\MCISPY      - 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 Application
            ÃÄ\RECORDER    - Audio Recording sample
            ÃÄ\SHORTCF     - Control File Templates
            ÃÄ\SHRCFILE    - Stream Handler Resource File sample
            ÃÄ\ULTIEYES    - Non-Linear Video sample
            ÀÄ\ULTIMOIO    - Ultimotion I/O Procedure sample


UPDATES TO CONFIG.SYS
________________________________________________________________

The Toolkit installation program prepends the paths of all needed
environment variables with the appropriate Toolkit path.  These
variables include, but are not limited to:

        PATH
        DPATH
        LIBPATH
        BOOKSHELF
        HELP
        INCLUDE
        LIB
        TMP
        SMINCLUDE
        SMEMIT
        SOMBASE
        SOMIR

By default, the Toolkit installation program updates your system's
CONFIG.SYS file.  To change this default, take the following steps:

   1. Click on the Options pushbutton to bring up the Installation
      Options dialog box.
   2. Deselect the "Write CONFIG.SYS updates to:" checkbox.
   3. Click on the OK pushbutton to close the dialog box.

These actions will prevent the modification of your CONFIG.SYS file.


INSTALLING THE TOOLKIT FROM DISKETTE
________________________________________________________________

To install the Toolkit from diskette, take the following steps:

   1. Start an OS/2 full screen or OS/2 window session.

   2. Make sure the drive containing the Toolkit install diskette
      is the working drive.

   3. Type "TKINSTAL" at the command prompt and press Enter.

   4. The Toolkit Installation Program will present you with
      the various installation choices.  After selecting the
      options you would like to install, click on the Install
      pushbutton.



USING THE TOOLKIT DIRECTLY FROM THE CD
______________________________________

By default, the Toolkit installation will copy chosen files to your
machine and update CONFIG.SYS with respect to the locally installed
files.

In order to use the Toolkit without copying files to your machine,
the same installation program is used, but before clicking on the
Install pushbutton, two additional steps must be taken to ensure
that the CONFIG.SYS updates are correct.

    1) Click on the Options pushbutton to bring up the Installation
       Options dialog box
    2) Deselect the "Install selected files" checkbox.
    3) Click on the OK pushbutton to close the dialog box.
    4) Highlight the root level (top-most) component in the
       component tree, then fill in the Destination entry field
       with the source path on the CD.  For example, if the the
       Toolkit is being installed from The Developer's Connection
       from the E: drive, the path should be set to
       E:\DEVTOOLS\WARPTLKT\TOOLKIT.

NOTE: If the entire Toolkit is not required, components may still
      be deselected in the usual manner.  However, it is important
      that the paths are not changed from their defaults for all
      components other than the root, since the directory structure
      on the CD cannot be changed.



CHANGES IN THE TOOLS
________________________________________________________________

Enhancements have been made to several of the tools that come with the
OS/2 operating system.  This section provides a brief description of
the enhancements.  For additional information, see the OS/2 Tools
Reference, available online with the Toolkit.

The tools described in this section are:
    - LINK386 Linker
    - Resource Compiler
    - MSGBIND
    - Information Presentation Facility Compiler
    - Icon Editor
    - Dialog Editor
    - Object Utility/2
    - Pack2
    - TK21DESK
    - NEAT STUFF


LINK386
-------
Three additional options are available for LINK386.

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

    /NOO[UTPUTONERROR]
        This option will prevent LINK386 from creating the
        executable file if an error is encountered.

    /NOS[ECTORALIGNCODE]
        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 is provided to turn off this feature.  Pages of
        code would then be aligned based on the value used in
        the /ALIGN option.


RC - THE RESOURCE COMPILER
--------------------------
A new option is available for RC, the Resource Compiler.

    -x[{1|2}]
        This option causes resources to be compressed.  These
        resources will be automatically decompressed when the
        resource is accessed.


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


INFORMATION PRESENTATION FACILITY COMPILER
------------------------------------------
A new, 32-bit version of the Information Presentation Facility
Compiler (IPFC) is included in this release of the Toolkit.
The new compiler provides the following enhancements:

    - Improved overall performance and increased limits
    - A new tag (:hdref.) and two new macros (.nameit and .ce)
    - A new command-line interface
    - Expanded use of environment variables
    - The ability to specify output files
    - More sophisticated use of support files
    - Enhanced error messages


ICON EDITOR
-----------
Mini-icons are icons that are one-half the size of normal icons.
Normal icons are 32x32 or 40x40 pels (depending on 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 Toolkit, then you
need to run 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 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 switches /t /i again.


DIALOG EDITOR
-------------
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.


OBJECT UTILITY/2
----------------
Object Utility/2 is a new Workplace Shell tool that provides a
facility for registering Workplace Shell classes, and creating and
modifying instances of Workplace Shell classes.


PACK2
-----
The algorithm used to compress files has been substantially enhanced.
The use of this utility program is identical to the PACK utility,
which is documented in the Tools Reference.


TK21DESK
--------
The TK21DESK.CMD command, used to recreate the Toolkit's icons/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/diskette that
contains the install program (TKINSTAL.EXE), start the program, and
follow these steps:

    1) Click on the Options pushbutton to open the Installation
       Options dialog box.
    2) Deselect the "Install selected files" and "Write CONFIG.SYS
       update to:" checkboxes (only "Register WPS classes" and
       "Create desktop objects" should be checked).
    3) Click on the OK pushbutton to close the Installation Options
       dialog box.
    4) Highlight the root level (top-most) component in the
       component tree, then fill in the Destination entry field
       with the location of your Toolkit subdirectory.
    5) Click on the Install pushbutton.


NEAT STUFF
----------
The "NeatStuff" folder (the BIN\BETA subdirectory) contains beta
versions of some new tools that you might find beneficial.  The only
tool in this directory at this time is P2STRING.  See the README file
in that folder/subdirectory for more details.

Note:  These utilities are prerelease versions and are provided on an
as-is basis for evaluation and demonstration.  They are not intended
for use with production code.

Please provide us with feedback if you find these tools useful and
would like to see them move into the "Toolkit proper".  Feedback can
be given on any OS/2 multimedia BBS.

Also, the Wave Doctor, previously available with the MMPM Toolkit/2
product, is not available with this version of the Toolkit.


CHANGES IN THE HEADER FILES
________________________________________________________________

NEW LOCATION
------------
The header files for C and C++ have been merged and placed in a new
directory, H, which is directly off the TOOLKIT directory rather than
being the OS2H subdirectory under the C or CPLUS directories.


ADDITION TO THE WORKPLACE SHELL HEADER FILES
--------------------------------------------
The following #defines are needed by the wpQueryClashNameOptions
Workplace Shell method 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 if you are going to use wpQueryClashNameOptions.


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 they switch 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

CDAUDOS2.H and MIDIOS2.H must be specified manually.  The rest will be
included automatically by adding "#define INCL_OS2MM" to your source
file before the inclusion of OS2ME.H.


MULTIMEDIA HEADER FILES -- PART 2
---------------------------------
There is a known problem with the AUDIO.H header file when compiling
for C++.  The typedef for the audio_update structure must be modified
from:

    typedef struct audio_update FAR *UPDATE;

to:

    typedef audio_update FAR *UPDATE;


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

    #define SELECTOROF(p)   (((PUSHORT)&(p))[1])
    #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.


DOS* PROGRAMMING INTERFACE
--------------------------
The DosSetDOSProperty() and DosQueryDOSProperty() functions in
BSEDOS.H are not supported.  Do not use these application programming
interfaces.


CHANGES IN THE SAMPLES
________________________________________________________________

Several new samples have been written to help you in your programming
efforts.  The new samples are listed briefly in this section.  For
more information, see the SAMPLES.DOC file in the SAMPLES subdirectory.


NEW AND CHANGED WORKPLACE SHELL SAMPLES
---------------------------------------
The Workplace Shell Car Sample program has been enhanced and several
new Workplace Shell samples have been added to the Toolkit.  (All
Workplace Shell samples now require SOM 2.1 in order to execute
properly.)  The new samples include a file browser, a text-only
folder, and a Workplace Shell Tutorial.  These, and other samples, are
described in SAMPLES.DOC, which is in the \TOOLKIT\SAMPLES
subdirectory.

WORKPLACE SHELL ASCII/HEX FILE BROWSER SAMPLE
    The ASCII/Hex File Browser sample displays file system objects
    in a hexadecimal or text format in a Presentation Manager window.

TEXT-ONLY FOLDER SAMPLE
    The TEXTFLDR sample only allows Plain Text objects to be placed
    in the folder.  Objects that are not Plain Text are rejected.

WORKPLACE SHELL TUTORIAL SAMPLE
    WPSTUTOR sample demonstrates the order in which object methods
    are invoked by the Workplace Shell.

Note:  The C++ version of the Workplace Shell Car sample is not
available with this version of the Toolkit.


MULTIMEDIA SAMPLES
------------------
Many multimedia samples have been added to the OS/2 Toolkit.  These
samples are written in C and demonstrate the use of the multimedia
interface.  Included are examples of using the new DIVE interface,
creating and handling I/O procedures, and controlling streaming and
nonstreaming devices.

SOME RESTRICTIONS
If you installed the Toolkit from diskette, the Movie Sample
Application (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 Toolkit samples installed, and the target name of the file
should be MOVIE.AVI.

The Waveaudio with Waveaudio 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.

The UltiEyes sample (located in TOOLKIT\SAMPLES\MM\ULTIEYES)
demonstrates the use of nonlinear video using OS/2 multimedia and
Ultimotion.  The UltiEyes sample does not work on 8514 or VGA
displays, because these displays do not support direct frame buffer
access.

In order for the Captioning sample (located in
TOOLKIT\SAMPLES\MM\CAPSAMP) to work correctly, Captioning must be
enabled in the operating system.  To enable Captioning, open the
Multimedia Setup object in the Multimedia folder, go to the System
page, and put a checkmark in the "Captioning" checkbox.

The Nonlinear Video (UltiEyes), Direct Interface Video Extensions
(DIVE), and MCISpy samples require 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 MCISpy sample can be manually set up to run on earlier versions
of the operating system (the 2.x versions).  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 Toolkit in the
       LIBPATH so it is recognized prior to the MDM.DLL file in
       MMOS2\DLL.  The source code for the stub MDM.DLL is
       included in the MCISPY sample.
    4) Reboot your machine.

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().

For more information on each sample, see the SAMPLES.DOC file in the
SAMPLES subdirectory.


BIDI SAMPLES
------------
The Toolkit contains sample programs and an online guide for creating
applications that make use of the OS/2 system support for Arabic and
Hebrew (also known as Bidirectional Language Support, or BIDI).  In
addition, a bidirectional version of the IPFC Compiler is included
(IPFCBIDI.EXE).

Note that 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.


CHANGES IN THE TECHNICAL DOCUMENTATION
________________________________________________________________

In addition to updating the technical documentation for the new
function in the operating system, the online technical books have
been enhanced in several ways.

The Graphics Programming Interface (GPI) and Workplace Shell API
information has been taken from the PM Reference and put in their own
online books.  In addition, information from the hardcopy programming
guides has been added to the PM and GPI online books.  This is similar
to what was done for the Control Program Guide and Reference in OS/2
2.1.  Information from the Workplace Shell Programming Guide has been
added as a separate online book.

The file names for the following online books have been simplified.
    - Control Program Guide and Reference
    - Presentation Manager Guide and Reference
    - Graphics Programming Interface Guide and Reference
    - Workplace Shell Reference

Each INF file that makes up a book now consists of a short
abbreviation and a number.  The abbreviation indicates what book the
INF file is part of, and the number indicates the order in which the
files are concatenated at run-time to view the complete book.  As an
example, the three files in the Control Program Guide and Reference
are named CP1.INF, CP2.INF, and CP3.INF.


PROGRAMMING CONSIDERATIONS
________________________________________________________________

DDE BETWEEN PM AND WINDOWS PROGRAMS
-----------------------------------
Making modifications to Microsoft Windows programs to enable
dynamic data exchange (DDE) communications with Presentation Manager
(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 BITMAP                    Windows DIB
    TEXT                         TEXT (codepage 819)
    PM private                   Windows private


    Windows Application          PM Application
    Data Format                  Interpretation
    --------------------         --------------------
    Windows DIB                  PM BITMAP
    TEXT (codepage 819)          TEXT
    Windows private              PM Private


Notes:

1.  Code page translation (Windows 819 to/from current PM code
    page) is performed for topic name in all cases.

2.  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.


OBJECTID KEYNAMES
-----------------
When including an OBJECTID=<....> keyname/value pair in a setup
string, you must specify it at the end of the setup string.


NEW KERNEL DEBUG FILES AVAILABLE
--------------------------------

New kernel debug files are available.  If you are installing the
Toolkit from The Developer's Connection for OS/2, you have two
options:  installing the kernel debug files directly from the CD, or
creating diskettes from which you can later install the kernel debug
files.

To install directly from the CD, find the icon named "Kernel Debugger"
and select it.  This will run an installation program which will
install the appropriate kernel debug files.  To create kernel debug
diskettes, find the icon named "Kernel Debugger for OS/2 Warp, Version
3" and select it.  This will bring up a utility which will create the
kernel debug diskettes for you.

If you are installing the Toolkit from diskette, two Kernel Debug
diskettes are included with the package.  To install the Kernel Debug
files from these diskettes, insert the first Kernel Debug diskette
into a diskette drive, switch to that drive, and type "INSTALL" at
an OS/2 command prompt.


BOOKS FOR APPLICATION DEVELOPERS
________________________________

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.

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
application programming interfaces (APIs) 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.

Please note that the information available in hardcopy is basically
the same as the information in the online books contained in this
Toolkit.

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.

CONTROL PROGRAM PROGRAMMING REFERENCE
This book provides the detailed descriptions for the Dosxxx functions
of the OS/2 Control Program.

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.

PRESENTATION MANAGER PROGRAMMING GUIDE - ADVANCED TOPICS
This book describes the advanced features of a sophisticated OS/2
window application--font and file dialogs, containers and notebooks,
hooks, Dynamic Data Exchange, direct manipulation--and how to
implement them, using Winxxx and other Presentation Manager functions.

PRESENTATION MANAGER PROGRAMMING REFERENCE
This book provides the detailed descriptions for Winxxx and other
functions of the OS/2 Presentation Manager.

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.

GRAPHICS PROGRAMMING INTERFACE PROGRAMMING REFERENCE
This book provides the detailed descriptions for the Gpixxx functions
of the Graphics Programming Interface.

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.

WORKPLACE SHELL PROGRAMMING REFERENCE
This book provides the detailed descriptions of the Workplace Shell
object-oriented programming interface.

INFORMATION PRESENTATION FACILITY PROGRAMMING GUIDE
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 also
describes how to create online help and information.

TOOLS REFERENCE
This book describes the tools that are included in the IBM Developer's
Toolkit for OS/2 Warp, Version 3.

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.

MULTIMEDIA SUBSYSTEM PROGRAMMING GUIDE
This book describes the subsystem components--media control driver,
stream handler, and I/O procedure--that support a multimedia device.

MULTIMEDIA PROGRAMMING REFERENCE
This book describes the media control interface, multimedia I/O
services, Presentation Manager graphic push buttons, secondary windows
functions, multimedia I/O services, and subsystem services for
synchronization and streaming.

REXX USER'S GUIDE
This book describes the REXX programming language and provides
examples for writing programs using REXX.

REXX REFERENCE
This book provides detailed descriptions of the REXX functions.


OS/2 TECHNICAL LIBRARY PUBLICATIONS
-----------------------------------

Description                                                      Part Number
----------------------------------------------------------------------------
OS/2 Warp, Version 3 Technical Library                           G25H-7116
(Contains the following books)
     Control Program Programming Guide                           G25H-7101
     Control Program Programming Reference                       G25H-7102
     Presentation Manager Programming Guide - The Basics         G25H-7103
     Presentation Manager Programming Guide - Advanced Topics    G25H-7104
     Presentation Manager Programming Reference                  G25H-7105
     Graphics Programming Interface Programming Guide            G25H-7106
     Graphics Programming Interface Programming Reference        G25H-7107
     Workplace Shell Programming Guide                           G25H-7108
     Workplace Shell Programming Reference                       G25H-7109
     Information Presentation Facility Programming Guide         G25H-7110
     Tools Reference                                             G25H-7111
     Multimedia Application Programming Guide                    G25H-7112
     Multimedia Subsystem Programming Guide                      G25H-7113
     Multimedia Programming Reference                            G25H-7114
     REXX User's Guide                                           S10G-6269
     REXX Reference                                              S10G-6268
----------------------------------------------------------------------------
Please call for prices and availability--see TELEPHONE ORDERS below.
---------------------------------------------------------------------------


TELEPHONE ORDERS
----------------
Books can be ordered by calling toll free 1-800-342-6672 weekdays
between 8 a.m. and 8 p.m. (EST).  In Canada, call 1-800-465-4234.

When placing an order, please have the part number, quantity, and your
credit card information ready when you call.  Charge your order to
your VISA**, MasterCard**, American Express**, Discover**, or Diners
Club** credit card.

Please allow 1 - 2 weeks for delivery of telephone orders.


SOM README INFORMATION
________________________________________________________________

This version of the Toolkit contains a subset of the SOMobjects*
Developer's Toolkit.

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, or

    SOMSTARS -- The OIDL-compatible C++ form in which pointer
    references ('*'s) are visible in object references.

This second 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 Toolkit installs the SOMSTARS version of
the header files.

The Workplace Shell Interface Definition Language (IDL) files
(WP*.IDL) are provided 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 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).


SOM BINDINGS
------------
The .XH and .H files shipped with this 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, and 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 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.


SOM 1.0 OIDL USERS
------------------
If you need to recompile an OIDL class that overrides the somDumpSelf
or somDumpSelfInt methods, you will need to change the 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 method 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)
    {
    ...
    }

Since both types "int" and "long" require 4 bytes on OS/2, this
does not affect the binary interface of your class.


OS/2 WARP, VERSION 3 APPLICATIONS USING PRIOR LEVEL SOM DLLs
------------------------------------------------------------
When SOMobjects 2.0 (NOT the version shipped with this 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 rebooted because it requires the SOM DLLs that are contained
in \OS2\DLL.

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 rebooting the system.  These statements
must be changed to place the operating system directories before the
SOMobjects directories.

Please note that 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
directory 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.

This workaround will not work for applications that require the
SOMobjects Workgroup capability.  SOMobjects Workgroup applications
will require the next release of SOMobjects, which will be available
in the 4th quarter of 1994.


NEW FEATURES, KNOWN LIMITATIONS, AND RESTRICTIONS
--------------------------------------------------

    SOM Compiler
    ------------
    1. Mutually recursive IDL structures and unions 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;
            };

     2. The C bindings do not permit the use of multiple methods
        with the same name that also take an argument of 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);
                };
            };

     3. 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 SOMobject's include directory is consulted
        before BCOS2/include (because BCOS2/include contains
        older SOM.H include files).

     4. 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.

     5. When direct references to SOMFOREIGN types are made in an IDL
        struct or union, the C/C++ language bindings are generated
        incorrectly.  To refer to a SOMFOREIGN type (for example,
        "somId") in a structure or a 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. */
            };

     6. Do not use the '-r' option when invoking the SOM compiler
        in this Toolkit.  If you use this option, certain messages that
        should be classified as warnings will be classified as errors.
        This will be corrected for the final release.


    Distributed SOM
    ---------------
     1. 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" and "Save"
        before exiting to commit any changes made.

     2. 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.

     3. The OUT_LIST_MEMORY, IN_COPY_VALUE, and DEPENDENT_LIST
        flags, used with the Dynamic Invocation Interface, are
        not supported.

     4. Concurrent updates to the Implementation Repository
        are currently not properly serialized, and can conflict.

     5. 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*, and
        "env" is of type Environment*.


________________________________________________________________

                Thank you for your continued interest
                    in the OS/2 Operating System.
________________________________________________________________


TRADEMARK INFORMATION
_____________________

The following terms, denoted by an asterisk (*) in this file, are
trademarks or registered trademarks of the IBM Corporation in the
United States or other countries:

     -------------------------------------------------------
     C Set ++
     -------------------------------------------------------
     IBM
     -------------------------------------------------------
     OS/2
     -------------------------------------------------------
     Presentation Manager
     -------------------------------------------------------
     SOMobjects
     -------------------------------------------------------
     Workplace Shell
     -------------------------------------------------------


The following terms, denoted by a double asterisk (**) in this
publication, are trademarks of other companies as follows:

     -----------------------------------------------------------
     American Express   American Express Incorporated
     -----------------------------------------------------------
     C++                AT&T, Inc.
     -----------------------------------------------------------
     Borland C++        Borland International, Inc.
     -----------------------------------------------------------
     Diners Club        Diners Club of America
     -----------------------------------------------------------
     Discover           Sears, Roebuck and Co.
     -----------------------------------------------------------
     MasterCard         MasterCard International, Incorporated
     -----------------------------------------------------------
     Microsoft          Microsoft Corporation
     -----------------------------------------------------------
     VISA               VISA International Services Association
     -----------------------------------------------------------
     Windows            Microsoft Corporation
     -----------------------------------------------------------


IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED,
INCLUDING WITHOUT LIMITATION, WARRANTIES OF FITNESS AND
MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS
DOCUMENT.  BY FURNISHING THIS DOCUMENT, IBM GRANTS NO
LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS.

Copyright IBM Corporation, 1994, all rights reserved.

________________________________________________________________

                     END-OF-README-FILE
________________________________________________________________
