What's New in the Developer's Toolkit for OS/2 Warp, Version 3

by Robert Spinneweber

The Developer's Toolkit for OS/2 was created to help you with your OS/2 application development efforts. But now with the introduction of OS/2 Warp, Version 3, your 2.1 toolkit just won't suffice, will it? Well, not to worry. Our Toolkit group has enhanced the Developer's Toolkit for OS/2 2.1, now bringing you the Developer's Toolkit for OS/2 Warp, Version 3, which is provided on your accompanying Developer Connection for OS/2 Special Edition CD-ROM. Besides giving ourselves a new look, we've substantially enhanced the development tools, provided new samples, and updated our online documentation. In addition, we've integrated the Multimedia and a subset of the SOMobjects Developer's Toolkits with the base OS/2 toolkit you've come to know.

Where is Everything Now?
Having trouble finding where a specific file now exists in the Toolkit? The following handy diagram shows the new Toolkit directory structure; we hope it helps you locate the files you're looking for.

TOOLKIT - Root subdirectory for the Toolkit
 * \BIN - Toolkit tools (executable files)
 * \BIN\BETA - Toolkit Beta tools (executable files)
 * \BITMAP - Multimedia Bitmaps
 * \BOOK - Online technical information
 * \DEBUG - Kernel debug files
 * \DLL - DLLs for the Toolkit
 * \H - H and XH (C and C++) header files
 * \HELP - Toolkit help (HLP) files
 * \ICON - Icons for the Toolkit
 * \IDL - Contains Workplace Shell IDL files
 * \INC - INC (Assembler header) files
 * \IPFC - Files used by IPFC compiler
 * \LIB - Import library (LIB) files
 * \SAMPLES - Contains common information for all samples
 * \BIDI - Contains all bidirectional (BIDI) samples
 * \ARABIC - Contains all Arabic-specific BIDI samples
 * \STYLE - BIDI Arabic Style sample
 * \TELDIR - BIDI Arabic Telephone Directory sample
 * \HEBREW - Contains all Hebrew-specific BIDI samples
 * \STYLE - BIDI Hebrew Style sample
 * \TELDIR - BIDI Hebrew Telephone Directory sample
 * \CREXX - Common information for the CREXX samples
 * \CALLREX - CALLREXX REXX sample
 * \DEVINFO - DEVINFO REXX sample
 * \PMREXX - PMREXX REXX sample
 * \REXXCALC - REXXCALC REXX sample
 * \REXXUTIL - REXXUTIL REXX sample
 * \RXMACDLL - RXMACDLL REXX sample
 * \MM
 * \ADMCT - Audio Media Driver sample
 * \ASYMREC - Asymmetric Compression sample
 * \AVCINST - AVC IO Procedure Installation sample
 * \CAPDLL - Caption DLL sample
 * \CAPSAMP - Caption Application sample
 * \CAPTION - Caption creation utility
 * \CASECONV - Case Converter IO procedure
 * \CDMCIDRV - CD Audio Media Component Interface drivers
 * \CF - Full Control File sample
 * \CLOCK - Multimedia Clock sample
 * \CODEC - Compression/Decompression sample
 * \DIVE - Direct Interface Video Extensions sample
 * \DUET1 - Waveaudio With Waveaudio sample
 * \DUET2 - Waveaudio With CD-Audio sample
 * \FSSHT - File Stream Handler sample
 * \MCDTBL - MCD Command Table sample
 * \MCDTEMP - MCI Driver Template
 * \MCISPY - MCISpy sample
 * \MCISTRING - Media Control Interface String sample
 * \MMBROWSE - Contains the Image Browser sample
 * \MMIOPROC - M-Motion IO Procedure sample
 * \MOVIE - Movie Sample Application
 * \RECORDER - Audio Recorder sample
 * \SHORTCF - Short Control File sample
 * \SHRCFILE - Stream Handler Resource File sample
 * \ULTIEYES - Contains the Non-Linear video sample
 * \ULTIMOIO - Ultimotion IO Procedure sample
 * \OS2 - Contains the Control Program sample
 * \CONSOLIO - Console I/O sample
 * \DLLAPI - Dynamic Link Library sample
 * \EAEDIT - Edit Extended Attributes sample
 * \HANOI - Towers of Hanoi sample
 * \NPIPE - Named Pipe sample
 * \QUEUES - Queues sample
 * \SEMAPH - Semaphore sample
 * \SORT - Sorting Algorithm sample
 * \TIMESERV - Clock sample
 * \VMM - Virtual Memory Management sample
 * \PM - Contains all Presentation Manager samples
 * \BMPSAMP - PM Jigsaw Puzzle sample
 * \CLIPBRD - PM Clipboard sample
 * \CONTROLS - PM Style sample
 * \DIALOG - PM Dialog sample
 * \DRAGDROP - PM Drag/Drop sample
 * \GRAPHICS - PM Graphic sample
 * \IPF - PM IPF sample
 * \PALETTE - PM Palette sample
 * \PORTING - PM Porting sample
 * \PRINT - PM Print sample
 * \STDWND - PM Standard Window sample
 * \TEMPLATE - PM Template sample
 * \WPS - Contains all Workplace Shell samples
 * \BROWSE - Workplace Shell ASCII/Hex File Browser sample
 * \CAR - WPDataFile Subclass sample (Car)
 * \TEXTFLDR - Workplace Shell Text Only Folder sample
 * \WPSTUTOR - Workplace Shell Tutorial sample
 * \SOM - SOMobjects Toolkit files
 * \BIN - SOMobjects Toolkit tools (executable files)
 * \INCLUDE - H, XH, HC, HS, EFW, and API (C and C++) SOMobjects Tookit header files
 * \LIB - DLL files and import libraries
 * \MSG - Files reg'd by SOMobjects Toolkit MSG directory
 * \COMMON - Run time files common w/ OS/2
 * \DLL - SOMobjects Toolkit DLLs
 * \ETC - Files reg'd by SOMobjects Toolkit directory
 * \INSTALL - SYS level files for SOMobjects run times
 * \SYSTEM - SOMobjects Toolkit MSG files

New Tools
The BIDI Information Presentation Facility Compiler (IPFCBIDI) is the Bidirectional language version of IPFC. With it, you create bidirectional help and documents.

The PACK2 utility is an enhanced version of PACK.EXE that has incorporated a more efficient packing algorithm. Use PACK2.EXE in conjunction with UNPACK2.EXE, which is shipped with the base operating system.

The Object Utility/2 program provides the ability to register Workplace Shell classes. You can also use it to create and modify instances of Workplace Shell classes.

Tools Updated to 32-Bit
Executable File Header Utility (EXEHDR) allows you to display or modify the contents of an executable-file header.

The FWDSTAMP program provides the ability to add entry points known as forwarders to a dynamic link library (.DLL).

The Information Presentation Facility Compiler (IPFC) allows you to create online documents from a special tagging language.

The MAPSYM program creates symbol (.SYM) files from map (.MAP) files that are used by the kernel debugger for symbolic debugging.

The MARKEXE program enables you to view and set the program type, .DLL initialization and termination, and long file-name support for an executable file.

The MKMSGF program translates an ASCII input file into a binary message file that can be used by your application to display messages.

The MSGBIND program binds a message segment to an executable program.

The Program Maintenance Utility (NMAKE) allows you to automate the process by which you create your applications.

Enhanced Tools

 * NEW COMMAND-LINE PARAMETERS

LINK386
 * /EXEPACK:1|2, which causes pages of code and data in the executable file to be compressed.
 * /NOOUTPUTONERROR, which prevents LINK386 from creating an executable file if it encounters an error.
 * /NOSECTORALIGNCODE, which turns off the normal alignment of pages of code on sector (512) byte boundaries. Pages of code are instead aligned based on the value specified in the /ALIGN option.

Resource Compiler (RC)
 * x1|2, which causes resources to be compressed. These compressed resources will be automatically decompressed when the resource is accessed.


 * IPF COMPILER (IPFC) ENHANCEMENTS

Increased Document Limits:
 * Maximum number of unique words is now 64,000.
 * Maximum number of unique words in a panel is now 64,000.
 * Maximum number of panels is now 64,000.
 * Maximum number of external databases is now 255.

New Tag:
 * hdref. creates a hypertext link to the referenced heading.

New Macros:
 * .ce centers a line of text. .name performs symbol substitution.

New Command-Line Interface:
 * Although a new command-line interface has been created, the old one is still supported.

New Environment Variables:
 * IPFCIMBED searches for files that have been imbedded with the .im macro.
 * IPFCARTWORK specifies the location for artwork and artlink files.
 * TMP specifies where the compiler should store intermediate files created during compilation.

Output File:
 * You can specify the name of the output file on the command line.

Support File Enhancements:
 * The BMTAG.TAG file is no longer necessary.
 * Improvements have been made in the APSYMBOL.APS file.
 * The IPF*.NLS files have been updated.

Output Messages:
 * Output messages from the compiler now indicate error for severe errors and warning for other types of errors.


 * ADDITIONAL ENHANCEMENTS
 * The MSGBIND utility has been enhanced to support the new compression format available with LINK386 and the RC.
 * The Icon Editor now includes support for mini-icons. Mini-icons are one-half the size of normal icons.
 * The Dialog Editor has been enhanced for use with Pen for OS/2. Handwriting and sketch controls are available.
 * The Workplace Class Lister has been converted from SOM 1.0 to SOM 2.x.

Header Files and Libraries
For those of you who have used the Toolkit before, you probably noticed that two sets of header files existed for developing OS/2 programs. If you were developing your program in C, you used one set, but if you were developing your program in C++, you had to use a different set. This could get confusing if you were developing an application that was a mixture of C and C++! You might not realize you were using the wrong set of header files until you started compiling and the compiler started generating error messages.

We thought that having two sets of the same header files was an inconvenience, so we decided to modify the header files so there would be no doubt about which header files you should use. Now you don't need to worry about changing include paths if you switch between C and C++ development when developing OS/2 programs. You use the same header files and let the compiler do the work for you!

Note: If you are doing Workplace Shell C++ programming, you must use the .XH version of the header files; you cannot use the .H files.

Two new header files have been added to the Toolkit that you can use for developing applications that use Bidirectional Language Support (BIDI); PMBIDI.H and LAYOUT.H.

The corresponding library, PMBIDI.LIB, is also new and must be used with the header files to develop your BIDI applications.

Four new samples have been included to provide a programming model on how to create programs that make use of the Bidirectional Language Support feature of OS/2 Warp, Version 3.

Samples
The Toolkit contains numerous sample programs that you can reference when developing your own applications. Each sample was designed and coded to exploit a particular feature supported by the operating system.

Workplace Shell Samples
The following new Workplace Shell samples have been developed to demonstrate various Workplace Shell programming techniques.
 * Workplace Shell ASCII/HEX File Browser
 * Displays file system objects in a hexadecimal or text format in a Presentation Manager window.


 * Text-Only Folder
 * Allows only plain text objects to be placed into it.
 * Objects that are not plain text are rejected.


 * Workplace Shell Tutorial
 * Demonstrates the order in which object methods are invoked by the Workplace Shell. When you execute a method for the sample object class, the method's name and a description of its function appear in a window.


 * Workplace Shell WPDataFile Subclass (Car)
 * Demonstrates the steps necessary to create a Workplace Shell object using SOM 2.x.

BIDI Samples
For those of you who develop programs that are used world-wide, we included four new samples that demonstrate how you can easily add Bidirectional Language Support to your applications. The style samples are meant to demonstrate the Bidirectional Language support features of the PM controls and other system components.
 * Arabic Style
 * Arabic Telephone Directory
 * Hebrew Style
 * Hebrew Telephone Directory

The Telephone Directory samples are simple bilingual applications that demonstrate how language and orientation selections can be set dynamically if the application is "bidi-aware".

Note: These samples can only be run on an OS/2 Arabic or Hebrew system, respectively.

REXX Samples

 * Presentation Manager REXX Calculator (REXXCALC)
 * Demonstrates how you can use C and REXX code together to create a Presentation Manager calculator.

Online Documentation
To help you make use of the new Toolkit features and enhancements, we provided the following new online documentation as a reference: Of course, we updated the following online documentation to include detailed descriptions of the enhancements that we've made to the tools, as well as to provide the information you need to program to the new features available in OS/2 Warp, Version 3:
 * OS/2 Bidirectional Language Support Development Guide
 * Multimedia Application Programming Guide
 * Multimedia Subsystem Programming Guide
 * Multimedia Programming Reference
 * SOM Programming Guide
 * Control Program Guide and Reference
 * Graphics Programming Guide and Reference
 * IPF Programming Guide and Reference
 * Presentation Manager Guide and Reference
 * Workplace Shell Programming Reference
 * OS/2 Tools Reference
 * SOM Programming Reference
 * Kernel Debug Reference

System Object Model
The SOM 1.0 compiler that was included as a part of the Developer's Toolkit for OS/2 2.1 has been replaced with the portions of the SOMObjects Developer's Toolkit (SOM 2.1 Beta) necessary for application development.

If you're going to use SOM, you'll want to become familiar with the following tools:
 * SOM Compiler, which is comprised of the following files:
 * SC.EXE
 * SCOBJ.EXE
 * SOMCPP.EXE
 * SOMIPC.EXE
 * SOMPP.EXE
 * DSOM Daemon (SOMDD.EXE)
 * Generic Server Program (SOMDSVR.EXE)
 * CSC to IDL Conversion Utility (CTOI.CMD)
 * SOMCORBA Bindings Generation Utility (SOMCORBA.CMD)
 * SOMSTARS Bindings Generation Utility (SOMSTARS.CMD)
 * Interface Repository Display Utility (IRDUMP.EXE)
 * Public Definition Language Emitter (PDL.EXE)
 * Implementation Registration Utility (REGIMPL.EXE)
 * Presentation Manager version of the Implementation Registration Utility (PREGIMPL.EXE)

Multimedia Toolkit
By exploiting the multimedia capabilities of OS/2 Warp, Version 3, you can add a whole new dimension to your applications. That's why we are excited to announce that the Multimedia Toolkit is now a part of the Developer's Toolkit. You will find all the tools, header files, libraries, and documentation you'll need to add the power of multimedia to your programs! To help you along the way, we provide several sample programs that you can use as a guide.


 * Image Browser (MMBROWSE):Illustrates how to use the Multimedia I/O subsystem (MMIO) to install I/O procedures for various image formats and then convert those image formats to OS/2 bitmaps.
 * MCISPY:Monitors media control interface messages that are exchanged between applications and the OS/2 multimedia subsystem.
 * Direct Interface Video Extensions (DIVE):Provides optimized blitting performance for full-motion video subsystems and applications that perform rapid screen updates. Using the DIVE interfaces, applications can either write directly to video memory or use the DIVE blitter.
 * Non-Linear Video (ULTIEYES):Demonstrates the use of non-linear video by displaying segments from a movie clip in response to input from the mouse.

Summary
We hope that the changes made to the Developer's Toolkit will satisfy your development needs. Your feedback on this new version of the Tookit, through The Developer Connection support channels, is appreciated and encouraged. It is this feedback that drives our development efforts. So let us know ...we will be listening!