IBM OS/2 Developer's Toolkit

Modified version of toolkit's JIGSAW.EXE example which uses current directory.

________________________________________________________________ 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 ________________________________________________________________