═══ 1. How to Use This Book ═══ Before you start reading the information in this book, it might be helpful to review the following topics, which explain how to use this book:  Using the Contents  Getting Additional Information  Using the Action Bar Choices  Documentation Conventions ═══ 1.1. Using the Contents ═══ When the Contents window first appears, some topics have a plus (+) sign beside them. The plus sign indicates that additional topics are available. To expand the Contents if you are using a mouse, click on the plus sign. If you are using the keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus (+) key. For example, Toolkit Roadmap has a plus sign beside it. To see additional topics for that heading, click on the plus sign or highlight that topic and press the plus (+) key. To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press the Enter key). ═══ 1.2. Getting Additional Information ═══ After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words and phrases are highlighted in green letters, or in white letters on a black background. These are called hypertext terms. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word, and then press the Enter key. Additional information then appears in a window. ═══ 1.3. Using Action Bar Choices ═══ Several choices are available for managing information presented in this book. There are three pull-down menus on the action bar:  Services menu  Options menu  Help menu ═══ 1.3.1. Services Menu ═══ The actions that are selectable from the Services menu operate on the active window currently displayed on the screen. These actions include the following:  Bookmark Option  Copy Option  Print Option  Search Option ═══ 1.3.1.1. Bookmark Option ═══ The Bookmark option allows you to set a placeholder so you can retrieve information of interest to you. When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty. To set a bookmark, do the following: 1. Select a topic from the Contents. 2. When that topic appears, choose the Bookmark option from the Services pull-down. 3. If you want to change the name used for the bookmark, type the new name in the field. 4. Click on the Place radio button or press the Up or Down Arrow key to select it. 5. Click on OK or select it and press Enter. The bookmark is then added to the bookmark list. ═══ 1.3.1.2. Copy Option ═══ The Copy option allows you to copy a topic that you are viewing to the System Clipboard or to a file that you can edit. You will find this particularly useful for copying syntax definitions and program samples into the application that you are developing. You can copy a topic that you are viewing in two ways:  Copy copies the topic that you are viewing into the System Clipboard. If you are using a Presentation Manager editor (for example, the System Editor) that copies or cuts (or both) to the System Clipboard and pastes to the System Clipboard, you can easily add the copied information to your program source module.  Copy to file copies the topic that you are viewing into a temporary file named TEXT.TMP. You can later edit that file by using any editor. You will find TEXT.TMP in the directory where your viewable document resides. To copy a topic, do the following: 1. Expand the Contents list and select a topic. 2. When the topic appears, choose Copy to file from the Services pull-down. 3. The system puts the text pertaining to that topic into the temporary file named TEXT.TMP. For information on one of the other choices in the Services pull-down, highlight the choice and press the F1 key. ═══ 1.3.1.3. Print Option ═══ The Print option allows you to print one or more topics. You can also print a set of topics by first marking the topics in the Contents list. To print the document contents list do the following: 1. Choose Print from the Services pull-down. 2. Click on Contents (or press the Up or Down Arrow key to select it). 3. Click on Print (or select it and press Enter). 4. The Contents list is printed on your printer. ═══ 1.3.1.4. Search Option ═══ The Search option allows you to find occurrences of a word or phrase in the current topic, selected topics, or all topics. You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list. To search for a word or phrase in all topics, do the following: 1. Choose the Search option from the Services pull-down. Type the word or words to be searched for. 2. Click on All sections or press the Up or Down Arrow keys to select it. 3. Click on Search or select it and press Enter to begin the search. 4. The list of topics where the word or phrase appears is displayed. ═══ 1.3.2. Options Menu ═══ The actions that are selectable from the Options menu allow you to change the way your Contents list is displayed. To expand the Contents and show all levels for all topics, choose Expand all from the Options pull-down. You can also press Ctrl+*. For information on one of the other choices in the Options pull-down, highlight the choice and press the F1 key. ═══ 1.3.3. Help Menu ═══ The actions that are selectable from the Help menu allow you to select different types of help information. You can also press the F1 key for help information about the Information Presentation Facility (IPF). ═══ 1.4. Documentation Conventions ═══ Throughout the Using Your Toolkit, the following conventions distinguish the different elements of text: plain text Function names, structure names, data type names, message names, enumerated types, and constant names. Initial capitalization Key names, push buttons, check boxes, radio buttons, group-box controls, drop-down list box, dialog windows, spin buttons, combo-boxes, single-line entry (SLE) and multiple-line entry (MLE) fields. CAPITALS File names and error codes. monospace Programming examples and user input at the command line prompt or into an entry field. bold Window sub-titles, action bar choices and menu items. italics Parameters, structure fields, titles of documents, and first occurrences of words with special meaning. ═══ 2. Introduction ═══ Welcome to the IBM Developer's Toolkit for OS/2 Warp, Version 3 (Warp Toolkit). This book documents the following:  Additions and updates made to the IBM Developer's Toolkit for OS/2 Warp, which was shipped on The Developer Connection for OS/2, Volumes 6 and 7  Additions and updates applied to header files, program samples, tools, and online technical documentation of the IBM Developer's Toolkit for OS/2 Warp which was shipped on The Developer Connection for OS/2, Volume 5 Special Edition  Descriptions of hardcopy and online documentation, code samples, and tools  Ordering information for hardcopy books and The Developer Connection for OS/2  Programming considerations that have been changed or added  System debug support which introduces you to the interface that installs the debug kernel, symbol files, and debug version of the PM  Toolkit roadmap that covers the folder hierarchy and the contents and directory structure  Toolkit support information that assists you in installing or using the Warp Toolkit, or reporting suspected system defects as a result of applying the Warp Toolkit  Toolkit survey that gives you an opportunity to mail us your ideas and comments about the Warp Toolkit. Note: The contents of the OS/2 Multimedia Toolkit have been merged into this Warp Toolkit. Therefore, there are multimedia samples, header files, libraries, and technical documentation included in the corresponding subdirectories. ═══ 3. README ═══ ═══ 4. What's New ═══ What's New provides information on the latest release of the Warp Toolkit available on The Developer Connection for OS/2. We have added two new major components to the Toolkit installation: BETA and Try Me! These components are provided to give you a sneak preview of new samples, tools, and online documentation we are considering adding to the Toolkit permanently, as well as insight on what is coming in the Toolkit for future support on the operating system. The BETA component in this release of the Warp Toolkit includes Entertainment Support and IBM Developer API Extensions for OS/2. The Try Me! component in this release of the Warp Toolkit includes the Assembly Language Processor (ALP) and the Universal Resource Editor (URE). ═══ 4.1. Important Information ═══ Included in this section are important items that can affect your future development efforts when using the IBM Developer's Toolkit for OS/2 Warp, Version 3.  Compiling with IBM C/2  Compiling with VisualAge (C Set ++)  Replacing DLGEDIT - Dialog Editor  Replacing IPFCBIDI - Bidirectional Information Presentation Facility Compiler ═══ 4.2. BETA ═══ The BETA component contains new tools, samples, online documentation and API support for function in future versions of the operating system. Execution of these pieces will typically require additional runtime support provided by a Beta version of OS/2 Warp. In general, Beta versions of the operating system are available on The Developer Connection for OS/2. However, there will be cases, as in this volume's entertainment samples and tools, where the runtime support is included with the Developer's Toolkit for OS/2 Warp. The content of this component can vary from volume to volume of The Developer Connection for OS/2. This component is not installed by default by the Developer's Toolkit for OS/2 installation program, but the component can be selected prior to installing. All files for installation via the BETA component are installed in the \TOOLKIT\BETA directory structure by default. In this release of the Warp Toolkit, the BETA component includes Entertainment Support and IBM Developer API Extensions for OS/2. Summer games are here! PC game developers have been asking for code, tools, and samples specifically related to their entertainment software and games requirements. So, we have created new entertainment samples and tools just for you--the entertainment software developer. In our very first Beta version, you will find audio, video, networking, and joystick functionality that has been created or enhanced with PC gamers in mind. If you have a question regarding any of the entertainment components, refer to the entertainment online documentation as a first step. If you still need assistance, call 1-800-553-1623 for technical support. ═══ 4.2.1. Entertainment Samples and Tools ═══ Included in this Beta are new entertainment samples and tools. For those developers who are mostly interested in programming for PC entertainment, this is the Toolkit you will want to have! For starters, this Beta contains samples, tools, and online documentation for the following entertainment-related functions:  BRender real-time 3D graphic technology: ROBOT Now, you can make that jet plane in your game rotate, dip, and roll, or your creature from outerspace move body parts or twist and turn, using the technology brought to you by Argonaut Technologies Limited.  Direct Audio RouTines (DART): DAUDIO The door creeks as it is opened, the monster groans as he is destroyed... Create all the audible actions and reactions you want to hear. Your imagination is the only limit for what the high-speed audio interface can provide.  DIVE with full-screen support: FSDIVE Not only can that jet plane rotate, it can move faster in full-screen mode now. No more little windows for the people who play your game to squint at.  Joystick Device Drivers for OS/2 and DOS: JOYSTICK These new joystick device drivers allow you to use joysticks for hatch or thrust controls in addition to the one or two buttons, included on most standard joysticks.  Multiplayer networking support: TICTAC Games that allow you to compete against or conspire with other players are now possible using the entertainment samples and tools. We are starting with TCP/IP networking support in this first Beta. More platforms to follow!  Real-time MIDI support: MIDISAMP Finally you have true MIDI support for OS/2. This subsystem provides a 32-bit real-time environment for playing, recording, and processing MIDI data. This initial version provides support for playback only.  REXX installation help: RINST2 This Beta tool assists you in the installation of any entertainment or DOS program. Let the entertainment begin! This is just our first Beta so stay tuned for more entertainment-related functions in the future. ═══ 4.2.1.1. DAUDIO ═══ DAUDIO (direct audio) demonstrates the use of the direct audio interface. This high speed audio interface allows an application to send audio data directly to the amp-mixer device. The sample demonstrates the steps required to set up and use this new interface for playing and recording digital audio data. Hardware requirements:  Computer capable of running OS/2 Warp  Sound Card  Speakers or Headphones. Software requirements:  OS/2 Warp  Multimedia support. ═══ 4.2.1.2. FSDIVE ═══ FSDIVE (full-screen DIVE) demonstrates the use of multimedia's direct interface video extensions (DIVE) by repeatedly displaying a short animation sequence. The animation is performed by sequentially displaying a series of up to 16 bit maps in a PM window. You can display the default bit maps, shipped with the sample, or specify the bit maps by passing the file names as command line parameters. After the application is started, you can move or resize the window and observe the effects on the frame rate of the animation (displayed on the title bar). The latest version of the DIVE interface has been enhanced to allow an application to take over the display and change the resolution. This allows an application to run in a full screen without paying the performance penalty of maintaining a high-resolution desktop. Note: Before the full-screen DIVE sample can run in full-screen mode, full-screen support must be installed by running GSRVINST.EXE (located in \TOOLKIT\BETA\SAMPLES\ENTOOLKT\VIDEO\FSDIVE). See the GAMESRVR.DOC file in the same directory for more details. Once the game server DLL is installed, full-screen DIVE can be activated by using the Alt+Home hot key. ═══ 4.2.1.3. JOYSTICK ═══ JOYSTICK (OS/2 Joystick device driver) allows an OS/2 Warp application to access the machine's game port. The driver provides an interface or a set of API function calls for reading the joysticks. The Joystick API is implemented within the OS/2 Joystick device driver. This sample code shows how to use the OS/2 Joystick API and supports any two standard joysticks or one joystick with an advanced feature, such as a hatch or throttle control. Currently, there are no high-level versions of access to these functions, except through the IOCtl interface. This sample issues DosDevIOCtl to request status or sends commands to the OS/2 Joystick device driver. The API function number, an input parameter to DosDevIOCtl, is defined by the OS/2 Joystick device driver. JOYSTICK registers with the OS/2 Joystick device driver via DosOpen, with the device name "GAME$". It sends commands to the Joystick device driver via DosDevIOCtl after opening the new GAME$ device. These commands or IOCtls are subfunctions that are issued through DosDevIOCtl. This sample passes proper parameters and required data buffers or data structures when calling the API. The returned data is examined and a proper message is displayed to the screen. If the call is unsuccessful, an error message will be displayed and the sample will be terminated. JOYSTICK shows how to interface with the OS/2 Joystick API via the following functions:  Get the version number of the driver, API function x'01'.  Get the device parameters, API function x'02'.  Set the device parameters, API function x'03'.  Get the calibration values, API function x'04'.  Get the current joystick status, API function x'10'.  Get the joystick status at next button press, API function x'11'.  Get the joystick status at next sample, API function x'12'. It also accesses other OS/2 functions such as:  DosOpen DosOpen function must be called first to open the device driver name (GAME$) prior to any API function call to the OS/2 Joystick device driver.  DosClose When the program terminates, DosClose must be called to end the program properly. Hardware Requirements:  Joystick device Software Requirements:  OS/2 Warp  IBM C Set ++ compiler 2.x or 3.x  Developer's Toolkit 3.0  GAMEDD.SYS driver Note: An error message will be displayed and the program will terminate if the driver is not installed. The design of this sample is based on the set of functions provided by the OS/2 Joystick device driver. The CONFIG.SYS should include the following statement: DEVICE=pathname\GAMEDD.SYS where: pathname is the path where GAMEDD.SYS is located. ═══ 4.2.1.4. MIDISAMP ═══ MIDISAMP illustrates the use of the real-time MIDI support programming concepts and usage of the new real-time MIDI API. This sample program illustrates the use of the new real-time MIDI API by initializing and setting up a small MIDI node network and subsequently sending a MIDI message from an application node to a hardware node, thereby demonstrating MIDI playback. Hardware requirements:  Computer capable of running OS/2 Warp  Speaker or headphones  Sound card Note: The README for MIDISAMP contains specific information regarding device driver installation for running MIDISAMP. (This README is located in the TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\MIDI subdirectory.) Software requirements:  OS/2 Warp  Multimedia support  Standard MIDI file ═══ 4.2.1.4.1. Known Limitations ═══ Currently, MIDISAMP might halt when another process attempts to play a sound (including system sounds) while the sample is running. Therefore, you should disable system sound before running MIDISAMP. To disable system sound, double-click on Sound located in the Multimedia folder and ensure Enable system sound is not selected. ═══ 4.2.1.5. RINST2 ═══ RINST2 is a REXX tool that assists you in installing any entertainment or DOS program. It creates a Workplace Shell program object, associates an icon, and sets the DOS setting as appropriate. It also offers the chance to run a setup program as part of the installation. ═══ 4.2.1.6. ROBOT ═══ Note: You must read the Argonaut Non-Commercial License before using this sample. ROBOT demonstrates how to use the new OS/2 version of Argonaut's BRender technology. The BRender technology allows for real-time, three-dimensional (3D) manipulation of actors. An actor can be the actual object model, a camera, or a light. The objects are composed of polygons. These polygons can be moved independently or in conjunction with each other. While BRender provides the API necessary for the 3D transformation of the scene, it requires that system-specific code be used for blitting to the screen. There are two parts to the design. One is the use of BRender to perform the 3D manipulations, and the other is the use of DIVE (DIVE provides a faster method of blitting) to allocate and display the image buffer and to do any palette manipulations. ROBOT does the following:  Performs initialization  Imports data for models, materials and textures  Renders the scene  Modifies object positions and orientations via user interface. This sample demonstrates a robot walking. The mouse can be used to zoom in and out and also to rotate the robot in 3D space. ═══ 4.2.1.7. TICTAC ═══ TICTAC (TicTacToe) demonstrates how to use networking functions to develop a multiplayer, networked game. These networking support functions are referred to as OS/2 Warp networking functions. These functions support multiple transports such as TCP/IP, SPX/IPX, and OEM stacks. The current functions implement support for TCP/IP transport only. This sample uses the Warp networking functions to illustrate a 2-player TicTacToe game, where two players play against each other. Software Requirements:  WARPNET.DLL  OS/2 TCP/IP Version 2.x or higher  OS/2 Warp 3.0 or higher. ═══ 4.2.1.7.1. Known Limitations ═══ Currently, the receive function (WarpnetPackRecv) for Warp networking can only receive header information with no packet data. ═══ 4.2.2. Entertainment Online Documentation ═══ The Developer Connection for OS/2 offers you five entertainment online books, which are located in the \TOOLKIT\BETA\BOOK subdirectory.  BRender Concise Guide  BRender Technical Reference  Direct Audio Interface  Entertainment Programming Guide and Reference  Real Time MIDI You can also access these books from the Desktop by opening the Toolkit folder, then the BETA folder, and then the Beta Toolkit Information folder. ═══ 4.2.2.1. BRender Concise Guide ═══ This book describes the BRender Power Rendering System Application Programming Interface (API), shows how the components of the BRender system work as a whole, and gives some idea of the capabilities of this system. ═══ 4.2.2.1.1. BRender Technical Reference ═══ This book provides documentation support for the BRender Power Rendering System, a real-time, 3D graphics software by Argonaut Technologies Ltd. Argonaut's BRender 3D graphics API is only distributed under Argonaut's end-user license. The BRender Sample provides a limited license permitting you to evaluate the product. Should you wish to include the BRender Power Rendering System in your entertainment software, you need to contact Argonaut for a commercial license. ═══ 4.2.2.2. Direct Audio Interface ═══ This book provides an overview of the direct audio interface including descriptions of messages and associated data types. ═══ 4.2.2.3. Entertainment Programming Guide and Reference ═══ This book is written for the developer interested in writing entertainment applications for OS/2 Warp. It contains information about video support, audio support, networking, and input devices used specifically in entertainment development, such as:  OS/2 Joystick Device Driver  Full-screen DIVE (Direct Interface Video Extensions)  Multiplayer Networking API ═══ 4.2.2.4. Real Time MIDI ═══ This book provides a discussion of the new real-time MIDI architecture and introduces the real-time MIDI application programming interface (API) including detailed descriptions of the real-time MIDI functions and associated data types. ═══ 4.2.3. IBM Developer API Extensions for OS/2 ═══ The IBM Developer API Extensions for OS/2 extends the OS/2 Warp application programming interface (API) set so that application developers can develop a common source code base for OS/2 Warp and Windows platforms. The SMART and Hyperwise tools are available on this Beta CD to analyze existing Windows applications and to migrate the source code, resources, and help files to code that will compile on both OS/2 Warp and Windows platforms. The following are prerequisites for using the IBM Developer API Extensions for OS/2:  Developer's Toolkit for OS/2 Warp Version 3  SMART Version 2.1B  One of the following C compilers: - IBM C Set ++ Program Package (3.5), part number 61G1175 - IBM C Set ++ Program Package (CD-ROM), part number 61G1412 - IBM VisualAge C++ for OS/2 Version 3.0 ═══ 4.2.3.1. IBM Developer API Extensions for OS/2 Samples ═══ The following samples are included supporting the IBM Developer API Extensions for OS/2:  HiWorld  ToyBox  WinMain Wrapper Function (MAIN.C)  DLL Initialization Entry Point (DLLMAIN.C) ═══ 4.2.3.2. IBM Developer API Extensions for OS/2 Documentation ═══ The IBM Developer API Extensions for OS/2 Programming Guide is a new online book included with this release of the Warp Toolkit. This book is located in the \TOOLKIT\BETA\BOOK subdirectory and provides information on the following topics:  What the IBM Developer API Extensions for OS/2 are and how they can help you to: - Migrate Windows code to OS/2 code - Write common source code for OS/2 and Windows  How to use the SMART tool to analyze Windows code and see how much effort is involved to migrate it to OS/2 code  Differences in behavior between some IBM Developer API Extensions for OS/2 functions and their Windows counterparts  Changes to the Resource Compiler due to IBM Developer API Extensions for OS/2  The functions supported by the IBM Developer API Extensions for OS/2 You can access this book from the Desktop by opening the Toolkit folder, then the BETA folder, and then the Beta Toolkit Information folder. ═══ 4.3. Try Me! ═══ The Try Me! component, formerly called NeatStuff, contains new tools and samples that execute on generally available versions of OS/2, such as OS/2 Warp Version 3. These tools and samples are provided to obtain feedback from you, our customers. We are considering adding these tools and samples to the Toolkit permanently. The content of this component can vary from volume to volume of The Developer Connection for OS/2. Try Me! is installed by default by the Developer's Toolkit for OS/2 installation program, but the component can be deselected prior to installing to save space on your hard disk. All files installed via the Try Me! component are installed in the \TOOLKIT\BETA directory structure by default. In this release of the Warp Toolkit, there are two new entries in the Try Me! component:  ALP - Assembly Language Processor  URE - Universal Resource Editor The P2String tool is also in the Try Me! component. Note: These utilities are pre-release, unsupported versions and are provided on an "as is" basis for evaluation and demonstration. They are not intended for use with production code. IBM supports the version of Dialog Editor in this release of the Warp Toolkit, but will not be enhancing or otherwise changing Dialog Editor in future releases. URE (Universal Resource Editor) will become the editor of choice for creating and modifying dialogs and other resources. Take our Toolkit Survey and send it in! We are interested in your feedback! Please use any of the mechanisms listed below to give us your comments:  Internet - tink@vnet.ibm.com  CompuServe - 72410,624  Mail - IBM Corporation Attn: Rick Timkovich Zip 1606 P.O. Box 1328 Boca Raton, FL 33429-1328 ═══ 4.3.1. ALP ═══ ALP (Assembly Language Processor) is a macro assembler that runs under the 32-bit OS/2 operating system. In its initial form, ALP is designed as a functional replacement for the Microsoft Macro Assembler (MASM), Version 5.1. It accepts the full syntax of the Intel 80X86 architecture, and a subset of MASM's high-level directive language. ALP creates standard Object Module Format (.OMF) files that can be linked to produce DOS or OS/2 executables, and can generate line number debug information compatible with IBM's Presentation Manager Debugger. In addition, this tool offers a rich set of command line options, as well as a comprehensive listing file with user-tailored formatting, allowing a visual perspective not possible with other assemblers. ALP translates assembly language source files (typically having a file name extension of .ASM) into object (.OBJ) files. The LINK386 utility can then be used to combine multiple object files into a single executable file, dynamic link library, or device driver. While ALP is designed as a functional replacement for the Microsoft MASM assembler in terms of source code compatibility, it does not use the MASM command line syntax. ALP uses a free-form syntax, has a comprehensive set of options, and allows assembly of multiple input files with a single command line invocation. For each corresponding input source file, ALP can produce the following types of output files:  Object (.OBJ) files containing program data and executable code.  Listing (.LST) files which document the results of the assembly.  Message (.MSG) files which can contain all error, warning, and informational messages produced during the assembly. ═══ 4.3.2. URE ═══ URE (Universal Resource Editor) is a Presentation Manager tool which enables you to create and maintain the resource files for your applications. This tool has been significantly enhanced with the following:  Enhanced user interface and documentation  Double-byte character set (DBCS) support for input and output of double-byte characters This level of URE runs on a Warp system but does not run in an OS/2 2.1 environment. The URE shipped with the Warp Toolkit on the Developer Connection for OS/2, Volume 8 must be used to edit resource files defined for an OS/2 2.1 environment. Note: URE will replace DLGEDIT (Dialog Editor) in a future release of the Warp Toolkit. ═══ 4.3.3. Try Me! Online Documentation ═══ The Developer Connection for OS/2, Volume 8 offers you two new online books describing tools. These books are located in the \TOOLKIT\BETA\BOOK subdirectory. You can also access them through the TRYME folder located within the Toolkit folder.  Assembly Language Processor Reference Guide  Universal Resource Editor User's Guide ═══ 4.3.3.1. Assembly Language Processor Reference Guide ═══ This book describes how to install and run the ALP assembler. It provides a complete description of the following:  Installation  Command line syntax  Environment variables  Assembler return codes  Message descriptions and recovery ═══ 4.3.3.2. Universal Resource Editor User's Guide ═══ This book provides information on the following URE features:  Using the tool bar, status window, and symbol definition window  Using all dialogs  Designing an application with URE  Adding backing code to a design  Running a prototype  Adding new elements to a process  Rebuilding an application  Using PM control extensions  Setting styles and CUA guidelines  Creating resource DLLs  Using accelerators in a resource design. ═══ 4.4. Tool Updates ═══ This release of the Warp Toolkit contains the following tool updates:  IPFC Enhancements  Replacing DLGEDIT  Replacing IPFCBIDI  Resource Compiler Enhancements ═══ 4.4.1. IPFC Enhancements ═══ The following enhancements have been made to the Information Presentation Facility Compiler (IPFC):  Capability to add additional languages and code pages to IPFC.  Incorporation of the following languages into IPFC: Czech, Greek, Hungarian, Korean (code page 949), Polish, Russian, Simplified Chinese (code page 1381), Thai, and Turkish. See Compiling with International Language Considerations for more detailed information on these enhancements. ═══ 4.4.2. Replacing DLGEDIT ═══ IBM supports the version of DLGEDIT (Dialog Editor) in this release of the Warp Toolkit, but will not be enhancing or otherwise changing the Dialog Editor in future releases. URE (Universal Resource Editor) will become the editor of choice for creating and modifying dialogs and other resources. ═══ 4.4.3. Replacing IPFCBIDI ═══ The Developer's Toolkit for OS/2 Warp on The Developer Connection for OS/2 includes two IPF compilers: IPFC.EXE and IPFCBIDI.EXE (the bidirectional version of IPFC.EXE). For this version of the Warp Toolkit, these programs are identical, as the bidirectional support has been integrated into the American version, IPFC.EXE. However, in a future release of the Warp Toolkit on The Developer Connection for OS/2, only IPFC.EXE will be included. Therefore, it will be necessary for you to modify any makefiles that reference IPFCBIDI.EXE to reference IPFC.EXE instead. ═══ 4.4.4. Resource Compiler Enhancements ═══ As an enhancement for the IBM Developer API Extensions for OS/2, the OS/2 Resource Compiler (RC) now supports string IDs for resources in addition to numbers. You can use either SMART or the Resource Compiler to convert resources. If you use the Resource Compiler, you do not need to include the hhh file with your code. OS/2 supports string IDs with double quotes. See the discussion of the RESOURCE statement in the IBM Developer API Extensions for OS/2 Programming Guide for more information. ═══ 5. Installation ═══ The TK21DESK.CMD command, used to recreate the Toolkit's icons or objects on the Desktop, is no longer necessary. The function, formerly part of TK21DESK, is now a part of the installation program. To restore your Toolkit Desktop objects, insert the CD or diskette that contains the install program (TKINSTAL.EXE), start the program, and follow these steps: 1. Click on the Options push button to open Installation options. 2. Deselect Install selected files and Write CONFIG.SYS updates to: (only Register WPS classes and Create desktop objects should be selected). 3. Click on the OK push button to close Installation options. 4. Highlight the root (top-most) component in the component tree, then fill in the Destination: field with the location of your Toolkit subdirectory. 5. Click on the Install push button. ═══ 6. Toolkit Roadmap ═══ The tools, samples, and technical documentation in the Warp Toolkit are available in two ways. You can access them through the Toolkit folder and its subfolders on the Desktop, or you can access them using an OS/2 window or OS/2 full-screen session and changing into the \TOOLKIT subdirectory and its subdirectories. ═══ 6.1. Directory Hierarchy ═══ The Warp Toolkit package has the following directory structure: \TOOLKIT - Root subdirectory for the Toolkit. │ ├─\BETA - Beta version of new samples, tools (EXE), and online books ├─\BIN - Programming tools ├─\BITMAP - Sample multimedia bit maps ├─\BOOK - Online technical information ├─\DLL - Toolkit dynamic link language (DLL) files ├─\H - C and C++ header files ├─\HELP - Toolkit help (HLP) files ├─\ICON - Toolkit icons (ICO) files ├─\IDL - Workplace Shell interface definition language (IDL) files ├─\INC - Assembler header (INC) files ├─\IPFC - Information Presentation Facility Compiler (IPFC) files ├─\LIB - Import library (LIB) files ├─\SAMPLES - Contains common information for all │ samples, as well as SAMPLES.DOC ├─\SOM - SOM subdirectories └─\TMP - Used to store temporary files Note: If you have not installed the Warp Toolkit on your system and you are reading from The Developer Connection for OS/2 CD, the \TOOLKIT subdirectory is located in the \DEVTOOLS\WARPTLKT directory. ═══ 6.2. Folder Hierarchy ═══ The Warp Toolkit package has the following Workplace Shell folder hierarchy: IBM Developer's Toolkit - Root folder of the Toolkit. for OS/2 Warp, Version 3 Contains the README file and the │ other Toolkit folders │ ├─Development Tools - Programming tools ├─Multimedia Bitmaps - Sample multimedia bit maps ├─Multimedia Sample Programs - Multimedia sample programs ├─OS/2 Sample Programs - Control Program sample programs ├─PM Sample Programs - Presentation Manager (PM) sample programs ├─REXX Sample Programs - REXX sample programs ├─Toolkit Information - Online technical books ├─Workplace Shell Sample Programs - Workplace Shell (WPS) sample programs │ ├─BETA - Beta version of books, samples, and tools │ ├─Developer API Extensions Samples - IBM Developer API Extensions for │ │ OS/2 samples │ ├─BRender - BRender components │ │ └─BRender Samples - BRender samples │ ├─Beta Entertainment Samples - Entertainment samples │ │ ├─Audio Samples - Audio samples │ │ ├─Input Samples - Input samples │ │ ├─Network Samples - Network samples │ │ └─Video Samples - Video samples │ └─Beta Toolkit Information - Online technical books └─TRYME - Beta version of samples and tools ═══ 7. Toolkit Contents ═══ This section represents the main body of the Using Your Toolkit. It contains the following sections:  Header files -- describes the changes that have occurred in the Control Program, Multimedia, OS/2, and Workplace Shell header files.  Sample programs -- provide descriptions of the OS/2, BIDI, REXX, Presentation Manager, Multimedia, and Workplace Shell code samples that are included in the Warp Toolkit.  Tools -- provide descriptions of the Presentation Manager, Multimedia, SOM, and Workplace Shell tools. It also introduces you to the interface that installs the debug kernel, symbol files, and debug version of the PM, and describes tools that support your debugging efforts.  Online documentation -- describes the single and combined online books of the Warp Toolkit.  BETA -- Beta version of entertainment samples, tools, and online documentation.  Try Me! -- Beta version of tools and online documentation. ═══ 7.1. Header Files ═══ The header files for C and C++ have been merged and placed in a new directory, H, which is located directly off the \TOOLKIT subdirectory. In previous versions these header files were located in the \OS2H subdirectory under the \C or \CPLUS directories. Changes in the header files have occurred in the following sections:  Control Program  Multimedia  OS/2  Workplace Shell Note: For compatibility with the C Set ++, Version 3.0, the #pragma checkout directives in all header files have been changed to #pragma info. The #pragma checkout directive is no longer supported by C Set ++. Because the #pragma info directive provides similar function to #pragma checkout, the header file changes should not affect code that uses the header files. If you use the #pragma checkout directive with C Set ++, Version 3.0, it generates an "unsupported pragma" error for both C and C++ compilers. Refer to the C Set ++ Language Reference for more details. ═══ 7.1.1. Control Program Header Files ═══ DosSetDOSProperty() and DosQueryDOSProperty() in BSEDOS.H are not supported. Do not use these functions. ═══ 7.1.2. Multimedia Header Files ═══ The multimedia header files listed below are delivered in two different versions. One version uses conventions compatible with the standard OS/2 header-file format. The other version uses conventions compatible with Microsoft Windows header files. The Windows-style headers are currently shipped for compatibility with earlier multimedia applications, but will be removed from the Toolkit in the future. New applications should use the OS/2-style header files. Applications that use the Windows-style headers will need to modify their source code when moving to the new headers. Windows-Style OS/2-Style CDAUDIO.H CDAUDOS2.H MCIDRV.H MMDRVOS2.H MIDI.H MIDIOS2.H MMIO.H MMIOOS2.H MMSYSTEM.H MCIOS2.H Note: There is a known problem with the AUDIO.H header file when compiling for C++. The typedef for the audio_update structure must be changed: from: typedef struct audio_update FAR *UPDATE; to: typedef audio_update FAR *UPDATE; ═══ 7.1.3. OS/2 Header Files ═══ Instead of using the SELECTOROF macro in the OS2DEF.H header file, use one of the following two macros to obtain the selector of a 16:16 address: #define SELECTOROF(p) (((PUSHORT)&(p))[1]) OR #define SELECTOROF(p) ((ULONG)(p)>>16) If you use the selector returned from one of the above macros with the OFFSETOF and MAKEP macros in the OS2DEF.H header file, you can successfully convert a 16:16 address to a 0:32 address. ═══ 7.1.4. Workplace Shell Header Files ═══ The following #defines are needed by wpQueryNameClashOptions but are not in the Workplace Shell header files: #define NO_NAMECLASH_RENAME 0x10 #define NO_NAMECLASH_APPEND 0x20 #define NO_NAMECLASH_REPLACE 0x40 #define NO_NAMECLASH_DIALOG 0x80 You should define them when using wpQueryNameClashOptions. ═══ 7.2. Sample Programs ═══ This section describes the sample programs available with the Warp Toolkit. The sample programs are categorized as follows:  BIDI  Multimedia  OS/2  Presentation Manager  REXX  Workplace Shell Most sample programs are written in C language and demonstrate the use of the functions of the control program (CP, base OS/2 operating system), the PM interface, the multimedia (MM) interface, and the Workplace Shell (WPS). Each sample program serves as a template that can be easily modified for your own purposes. These programs let you investigate the best way to implement your own application requirements. Some of the sample programs require specific hardware devices. When appropriate, the hardware is listed following the program descriptions. Without these devices, you can still compile and run the sample programs; however, you might not receive the full effect of the program. For example, if a multimedia sample program has audio, you will not hear it unless you have an audio adapter supported by OS/2 multimedia and speakers installed. Most samples also contain the overhead routines necessary to create a PM application, as well as stubs for the basic menu items that all applications should have. There are many comments within the source code that clarify technical information. Note: Names of the sample programs, in most cases, correspond to their Toolkit subdirectory names. ═══ 7.2.1. Starting Sample Programs ═══ There are two ways to start a sample program:  From the Desktop: When installed, all sample programs (with the exception of the bidirectional samples, some of the Multimedia samples, and some of the Workplace Shell samples) appear in the sample programs folders located within the Toolkit folder. To start a sample program, open the Toolkit folder, open the folder representing the type of samples you wish to execute, then select the appropriate sample program.  From an OS/2 command prompt: Change to the subdirectory where the sample is located, type the name of the executable file and press Enter. Most samples include a description file (or makefile) you can use to build the sample yourself. The name of the makefile is either MAKEFILE or filename.MAK, where filename refers to the name of the sample. To build the sample, 1. Go to an OS/2 command prompt and change to the subdirectory where the makefile is located. You must execute these commands from the subdirectory where the makefile is located in order to build the sample correctly. 2. Enter one of the following, depending on the name of the makefile:  When the name of the makefile is MAKEFILE, type: NMAKE  When the name of the makefile is filename.MAK, type: NMAKE /f filename.MAK For information about the NMAKE tool, refer to the OS/2 Tools Reference. Note: The makefile assumes that the IBM C Set ++ compiler is used for code compilation. ═══ 7.2.2. BIDI Sample Programs ═══ These samples demonstrate the use of the Bidirectional Language support available in the Arabic and Hebrew versions of OS/2. There are two sets of samples provided: one set for the Arabic language and the other set for the Hebrew language. For both languages, there are two samples:  STYLE  TELDIR Note: Programs that use the bidirectional support functions will run only on the Arabic and Hebrew versions of the OS/2 operating system, which are currently the only versions of the operating system that support these features. ═══ 7.2.2.1. STYLE Sample Program ═══ STYLE is a sample program that demonstrates the bidirectional language support features of PM controls and other system components. Note: The Arabic versions of this sample (located in \TOOLKIT\SAMPLES\BIDI\ARABIC), require the Arabic version of OS/2 to run, and the Hebrew versions of this sample (located in \TOOLKIT\SAMPLES\BIDI\HEBREW), require the Hebrew version of OS/2 to run. ═══ 7.2.2.2. TELDIR Sample Program ═══ TELDIR is a simple bilingual telephone directory application that demonstrates how language and orientation selections can be set dynamically by a "BIDI-aware" application. Note: The Arabic versions of this sample require the Arabic version of OS/2 to run, and the Hebrew versions of this sample require the Hebrew version of OS/2 to run. ═══ 7.2.3. Device Driver Sample Programs ═══ Physical device driver (PDD) and virtual device driver (VDD) samples are not included in the IBM Developer's Toolkit for OS/2 Warp, Version 3. See the Developer Connection Device Driver Kit (DDK) for device driver samples. ═══ 7.2.4. Multimedia Sample Programs ═══ The Multimedia sample programs are as follows:  ADMCT  ASYMREC  AVCINST  CAPSAMP  CAPTION  CASECONV  CDMCIDRV  Control File Templates  CLOCK  CODEC  DIVE  DOUBPLAY  DUET1  DUET2  FSSHT  MCD Command Tables  MCDTEMP  MCISPY  MCISTRNG  MMBROWSE  MMOTTK  MOVIE  RECORDER  Short Control File Templates  SHRC  TUNER  ULTIEYES  ULIOT ═══ 7.2.4.1. ADMCT Sample Program ═══ ADMCT (located in \TOOLKIT\SAMPLES\MM\ADMCT), is an example of a media control driver (MCD) that demonstrates how to control a streaming device. Streaming devices use the services of the sync/stream manager (SSM) of OS/2 multimedia to control the data stream from a source location to a target location. ═══ 7.2.4.2. ASYMREC Sample Program ═══ ASYMREC (located in \TOOLKIT\SAMPLES\MM\ASYMREC), illustrates how to include asymmetric recording function in your multimedia application. Modules include source code extracted from the Video IN recorder application, which enables frame-step recording using Ultimotion compression techniques. ═══ 7.2.4.3. AVCINST I/O Procedure Sample ═══ AVCINST (located in \TOOLKIT\SAMPLES\MM\AVCINST), illustrates how an application can install and remove an I/O procedure to use multimedia input/output (MMIO) file services. The AVC I/O procedure installation sample is a simple PM application that allows you to install or de-install the audio AVC I/O procedure, AVCAPROC.DLL. Hardware requirements:  Computer capable of running OS/2 Warp. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.4. CAPSAMP Sample Program ═══ CAPSAMP (located in \TOOLKIT\SAMPLES\MM\CAPSAMP), and the caption utility functions (located in \TOOLKIT\SAMPLES\MM\CAPDLL) are part of the sample captioning system provided with the Warp Toolkit. CAPSAMP demonstrates how captioning can be integrated into applications using caption files in conjunction with the caption utility functions. Hardware requirements:  Computer capable of running OS/2 Warp  Speaker or headphones  Sound card. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.5. CAPTION Sample Program ═══ CAPTION (located in \TOOLKIT\SAMPLES\MM\CAPTION), is part of the sample captioning system provided with the Warp Toolkit. The caption creation utility program creates a "caption" file. It enables a user to synchronize an audio file with a text file. This concept can be extended beyond audio and text to apply to many possibilities, such as synchronizing audio and video, or synchronizing video and text. Note: In order for the Caption sample to work correctly, captioning must be enabled in the operating system. To enable captioning proceed as follows: - Open the Multimedia Setup object in the Multimedia folder - Go to the System page - Indicate a checkmark in the Captioning check box. ═══ 7.2.4.6. CASECONV I/O Procedure Sample ═══ CASECONV (located in \TOOLKIT\SAMPLES\MM\CASECONV), provides a simple example of how to write a file format I/O procedure (without illustrating the use of data translation). This sample performs case conversion of text. ═══ 7.2.4.7. CDMCT Sample Program ═══ CDMCT (located in \TOOLKIT\SAMPLES\MM\CDMCIDRV), is an example of a media control driver (MCD) that demonstrates how to control a non-streaming device. Non-streaming devices stream data within the device. ═══ 7.2.4.8. Control File Templates ═══ The \TOOLKIT\SAMPLES\MM\CF subdirectory contains control file templates you can utilize when installing a program using MINSTALL. ═══ 7.2.4.9. CLOCK Sample Program ═══ CLOCK (located in \TOOLKIT\SAMPLES\MM\CLOCK), illustrates the use of the memory playlist feature of OS/2 multimedia. The memory playlist feature provides for easy manipulation of multimedia in memory to create unique effects based on user input or other dynamic events. Hardware requirements:  Computer capable of running OS/2 Warp  Speaker or headphones  Sound card. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.10. CODEC Sample Program ═══ CODEC (located in \TOOLKIT\SAMPLES\MM\CODEC), illustrates how to write a CODEC procedure to include compression and decompression routines in your multimedia applications. A CODEC procedure operates on data within a file or buffer. ═══ 7.2.4.11. DIVE Sample Program ═══ DIVE (located in \TOOLKIT\SAMPLES\MM\DIVE), illustrates the use of the direct interface video extensions. DIVE provides optimized blitting performance for motion video subsystems and applications that perform rapid screen updates in the OS/2 PM and full-screen environments. Using DIVE interfaces, applications can either write directly to video memory or use the DIVE blitter. The DIVE blitter will take advantage of acceleration hardware when present and applicable to the function being performed. Note: The DIVE sample requires OS/2 Warp, Version 3 in order to execute properly. The files for the samples will be installed when the samples are selected, but Workplace Shell objects will not be created for them if the installed operating system is not OS/2 Warp, Version 3. The OS/2 Warp color support defaults to 16 colors. This means that your setup needs to be updated, otherwise the DIVE sample will not run. The maximum window size of this sample has been limited to 640x480 because larger window sizes may cause excessive swapping on machines with less than 16MB. The DIVE sample that comes with this release of The Developer Connection for OS/2 will not work with the original DIVE.DLL file. For this release of the Warp Toolkit, an updated .DLL file is shipped with the sample. A .DLL file with equivalent function will be included in a future version of OS/2 Warp. Hardware requirements:  Computer capable of running OS/2 Warp  SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system). Software requirements:  OS/2 Warp  Multimedia support  Software motion video. ═══ 7.2.4.12. DOUBPLAY Sample Program ═══ DOUBPLAY (located in \TOOLKIT\SAMPLES\MM\DOUBPLAY), allows an application to play audio files directly from application memory buffers. An array of multiple playlist structures can be constructed that combines playlist commands with data buffers to perform complex operations on multiple buffers. This sample takes a single wave file, MYWAVE.WAV, and plays it using a memory playlist. The playlist is constructed as a circular buffer composed of a series of small buffers, the sum of which may or may not be larger than the size of the .WAV file. This circular buffer is used to repeatedly play an audio file when the PLAY button is selected. As each buffer in the playlist is expended, the application refills the expended buffer with new data from the .WAV file. When all the buffers in the playlist have been expended, the playlist branches back to the first buffer to play the new data. This circular buffering process continues until the STOP button is selected or the application is closed. Hardware requirements:  Computer capable of running OS/2 Warp  Speakers or headphones  Sound Card. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.13. DUET1 Sample Program ═══ DUET1 (located in \TOOLKIT\SAMPLES\MM\DUET1), illustrates the OS/2 multimedia concept of device grouping and integrating multimedia into an application's help information. This sample demonstrates the concepts of grouping two streaming devices. Note: The Streaming Device Duet sample (DUET1, located in \TOOLKIT\SAMPLES\MM\DUET1) requires that the IBM M-Audio Capture and Playback Adapter card be installed in order for the sample to execute properly. Hardware requirements:  Computer capable of running OS/2 Warp  Speaker or headphones  Sound card (capable of playing two mono wave files simultaneously such as the IBM M-AUDIO card). Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.14. DUET2 Sample Program ═══ DUET2 (located in \TOOLKIT\SAMPLES\MM\DUET2), illustrates the OS/2 multimedia concept of device grouping and integrating multimedia into an application's help information. This sample demonstrates how one of the devices in the multimedia device group can be a non-streaming device. Hardware requirements:  Computer capable of running OS/2 Warp  Speaker or headphones  Sound card  CD ROM. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.15. FSSHT Sample Program ═══ FSSHT (located in \TOOLKIT\SAMPLES\MM\FSSHT), contains a sample file system stream handler. ═══ 7.2.4.16. MCD Command Tables ═══ Before a media control driver (MCD) can interpret a string command, the media device manager (MDM) must use a command table to change the string into an equivalent procedural command. Represented as resources to the driver, command tables are created using the RCDATA type of resource. The resource number of the RCDATA block is the device type number. The \TOOLKIT\SAMPLES\MM\MCDTBL subdirectory contains command tables for each of the following devices:  Amp Mixer  CD-ROM/XA  CD Audio  Digital Video  Sequencer  Videodisc  Wave Audio If you want to support device-specific messages, you must create a device- specific command table. ═══ 7.2.4.17. MCDTEMP Template ═══ MCDTEMP (located in \TOOLKIT\SAMPLES\MM\MCDTEMP), provides a basic template to write a media control driver (MCD). Refer to the \ADMCT and \CDMCIDRV subdirectories for specific streaming or to the multimedia I/O (MMIO) samples. ═══ 7.2.4.18. MCISPY Sample Program ═══ MCISPY (located in \TOOLKIT\SAMPLES\MM\MCISPY), monitors media control interface messages that are exchanged between applications and the OS/2 multimedia subsystem. In addition to teaching you about multimedia messages, MCISPY also serves as a powerful debugging aid. The MCISpy sample must be manually set up. To do so, follow these steps: 1. Copy the MDM.DLL file located in the \MMOS2\DLL subdirectory to the \TOOLKIT\DLL subdirectory. 2. Use the DLLRNAME tool from C Set ++ for OS/2 to rename the copy to MCI.DLL (type DLLRNAME MDM.DLL MDM=MCI). 3. Place the stub MDM.DLL provided with the Warp Toolkit in the LIBPATH so that it is recognized prior to the MDM.DLL file located in the \MMOS2\DLL subdirectory. The source code for the stub MDM.DLL is included in the MCISpy sample. 4. Restart your system. Note: Driver notifications may not be visible in releases prior to OS/2 Warp, Version 3. These notifications include all multimedia messages routed through mdmDriverNotify(). Hardware requirements:  Computer capable of running OS/2 Warp. Software requirements:  Multimedia support  OS/2 Warp Note: The files for the samples will be installed when the samples are selected, but Workplace Shell objects will not be created for them if the installed operating system is not OS/2 Warp, Version 3. ═══ 7.2.4.19. MCISTRNG Sample Program ═══ MCISTRNG (located in \TOOLKIT\SAMPLES\MM\MCISTRNG), serves as a powerful testing and debugging tool that enables developers writing media drivers to control their devices at the application level. The string test sample illustrates how an application uses the interpretive string interface provided by the media control interface. This sample also illustrates how notification messages are returned from the media drivers to the application. Hardware requirements:  Computer capable of running OS/2 Warp. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.20. MMBROWSE Sample Program ═══ MMBROWSE (located in \TOOLKIT\SAMPLES\MM\MMBROWSE), illustrates how to use the multimedia I/O (MMIO) subsystem to install I/O procedures for various image formats and then convert these image formats to OS/2 bit maps. Hardware requirements:  Computer capable of running OS/2 Warp. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.21. MMOTTK I/O Procedure Sample ═══ MMOTTK (located in \TOOLKIT\SAMPLES\MM\MMIOPROC), provides an example of how to write an I/O procedure for use with image file formats. This sample enables file format transparency for M-Motion still video files and illustrates the use of data translation. ═══ 7.2.4.22. MOVIE Sample Program ═══ MOVIE (located in \TOOLKIT\SAMPLES\MM\MOVIE), demonstrates device control of a software motion video device. This sample also illustrates how to cut, copy, paste, and delete movie data from an application. A movie can be played in an application-defined window or in the system default window provided by the software motion video subsystem. Note: If you installed the Warp Toolkit from diskette, the Movie sample (located in \TOOLKIT\SAMPLES\MM\MOVIE) does not contain the MOVIE.AVI file necessary to execute the application. Copy any .AVI file from the \MMOS2\MOVIES subdirectory on the drive you have Multimedia installed. The .AVI file should be copied to the \TOOLKIT\SAMPLES\MM\MOVIE subdirectory on which you have the Warp Toolkit samples installed, and the target name of the file should be MOVIE.AVI. Hardware requirements:  Computer capable of running OS/2 Warp  Speakers or headphones  Sound card  SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system). Software requirements:  OS/2 Warp  Multimedia support  Software motion video. ═══ 7.2.4.23. RECORDER Sample Program ═══ RECORDER (located in \TOOLKIT\SAMPLES\MM\RECORDER), illustrates the concept of recording audio through the media control interface and how to query a device to find out the recording capabilities. This sample also illustrates how to change the audio recording and audio device properties, such as bits per sample, samples per second, input level, and input source. Hardware requirements:  Computer capable of running OS/2 Warp  Speaker or headphones  Sound card. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.2.4.24. Short Control File Templates ═══ The \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory contains a simple example of control file templates you can use when installing a program using MINSTALL. ═══ 7.2.4.25. SHRC Sample Program ═══ SHRC (located in \TOOLKIT\SAMPLES\MM\SHRC), provides a sample stream handler resource file. ═══ 7.2.4.26. TUNER Sample Program ═══ TV tuner cards allow a desktop PC to receive and display broadcasted television signals. TUNER (located in \TOOLKIT\SAMPLES\MM\TUNER), provides an example of how to use the MCI string interface to control a tuner card. Once the application is running, the display window can be sized and a TV channel can be selected. The channel can be selected through up/down buttons or a text entry field displayed both at the bottom of the window. Hardware requirements:  Computer capable of running OS/2 Warp  TV tuner card (such as the WinTV Basic). Software requirements:  OS/2 Warp  Multimedia support  Appropriate drivers for installed tuner card. Note: A TV tuner card is handled as a digital video device by the multimedia subsystem. A typical system has one or more digital video devices, with digital video 1 assigned to software motion video. By default this sample opens the digital video 2 device. If the tuner card is not assigned to digital video 2 an alternate device ordinal must be provided at the command line with the following format: /d=digitalvideoxx where: xx Is a two digit number, padded on the left with zero. For example: /d=digitalvideo03 Most TV tuner cards, such as the Hauppauge WinTV card, support several video sources. The connector number that corresponds to the tuner video source is dependent on the hardware and may not be the same for each tuner card. The connector number is not changed by this sample. Instead, it uses the default connector number that is set by the Multimedia Setup program. ═══ 7.2.4.27. ULTIEYES Sample Program ═══ ULTIEYES (located in \TOOLKIT\SAMPLES\MM\ULTIEYES), demonstrates the use of non-linear video by displaying segments from a movie clip in response to input from the mouse. Hardware requirements:  SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system). Software requirements:  Multimedia support  Software motion video  OS/2 Warp Note: The files for the samples will be installed when the samples are selected, but Workplace Shell objects will not be created for them if the installed operating system is not OS/2 Warp, Version 3. ═══ 7.2.4.28. ULIOT I/O Procedure Sample ═══ ULIOT (located in \TOOLKIT\SAMPLES\MM\ULTIMOIO), provides a detailed example of what you need to consider when writing I/O procedures for software motion video file formats. This sample program includes CODEC support and illustrates how to integrate common and file-format-specific code to support multiple I/O procedures. ═══ 7.2.5. OS/2 Sample Programs ═══ The OS/2 sample programs are as follows:  CLOCK  DLLAPI  EAS  HANOI  NPIPE  QUEUES  SEMAPH  SORT  VMM  WORMS ═══ 7.2.5.1. CLOCK Sample Program ═══ CLOCK (located in \TOOLKIT\SAMPLES\OS2\TIMESERV), demonstrates how to use and implement window timers and system-resource timers. This sample program displays both an analog and digital clock. To simulate elapsed seconds, the main PM thread repeatedly sets a one-second window timer that updates the current time. CLOCK features an audible and visual alarm that the user can set. When the time expires, the sample makes use of the DOS timer services and notifies the user by sounding an alarm and displaying a message box. ═══ 7.2.5.2. DLLAPI Sample Program ═══ DLLAPI (located in \TOOLKIT\SAMPLES\OS2\DLLAPI), demonstrates how to write and use a dynamic link library (DLL). The sample has a .DLL file and an executable (.EXE) file. The .DLL provides the 32-bit API function that is called by the .EXE file. The .DLL uses protected memory on its shared data, and exception management to validate the pointer parameters for a 32-bit API function. The .EXE file demonstrates how to handle a divide-by-zero exception, and calls the function with invalid pointer parameters, followed by a call with valid pointer parameters. ═══ 7.2.5.3. EAS Sample Program ═══ EAS (located in \TOOLKIT\SAMPLES\OS2\EAEDIT), demonstrates a multithreaded application that retrieves, modifies, or sorts files by their extended attribute value. Included in this sample program are PM procedures for dialog boxes and a standard client window. The sample lets the user select an extended attribute file name from a list, or enter a new name in an entry field. The user can select the extended attribute type from a table. ═══ 7.2.5.4. HANOI Sample Program ═══ HANOI (located in \TOOLKIT\SAMPLES\OS2\HANOI), demonstrates a multithreaded application with the familiar "towers of Hanoi" puzzle. When the sample program is started, the user sees three poles (A, B, and C). Initially, pole A has on it a stack of disks starting with the largest disks on the bottom and succeeding smaller disks on the top. The main thread handles the PM interface and lets the user start or stop the Hanoi routine. It also lets the user reset the number of working disks. The second thread is created when the Start item is selected from the Options menu. This thread starts the recursive execution of the Hanoi algorithm, runs in the background, and moves and paints the disks. All disks end up on pole C. ═══ 7.2.5.5. NPIPE Sample Program ═══ NPIPE (located in \TOOLKIT\SAMPLES\OS2\NPIPE), demonstrates two-way communication between two unrelated processes using named pipe functions. This sample program implements the game of TicTacToe with two executable files:  CLINPIPE.EXE (the client) The client is the user. For example, the client will: - Connect to the server and acknowledge successful connection (START_MSG). - Notify the server through a pipe when it wishes to begin play (YOU_FIRST or CLIENT_MOVE). - Notify the server when it wishes to quit (CLIENT_QUIT). - Send the server a valid move when requested by the server (CLIENT_MOVE).  SVRNPIPE.EXE (the server) The server is the computer. For example, the server will: - Connect a pipe to the client through which play will be executed (START_MSG) upon the initial request of a client to play. - Play with many clients simultaneously. - Notify the client of the server's move, and request a valid move from the client (SERVER_MOVE). - Notify the client of game-end (WIN_SERVER, WIN_CLIENT, WIN_DRAW). ═══ 7.2.5.6. QUEUES Sample Program ═══ QUEUES (located in \TOOLKIT\SAMPLES\OS2\QUEUES), demonstrates interprocess communications (IPC) using the 32-bit queue component. It consists of two executable programs:  SVRQUEUE.EXE Creates an IPC queue; a named, shared-memory buffer for queue elements; and a shared, named, mutex (mutual exclusive) semaphore. After initializing the queue, SVRQUEUE starts a thread to read from the queue, prints the contents of the messages read from the queue, and terminates at the user's request.  CLIQUEUE.EXE Opens the queue and accesses the shared-memory element buffer and mutex semaphore, and starts a thread to write to the queue. CLIQUEUE requests a string of data from the user, allocates a shared-memory element from the buffer, puts the string in the shared-memory element, then uses an event semaphore to direct the thread to write the element to the queue. CLIQUEUE terminates at the user's request. ═══ 7.2.5.7. SEMAPH Sample Program ═══ SEMAPH (located in \TOOLKIT\SAMPLES\OS2\SEMAPH), demonstrates the use of mutex and event semaphores. In the sample, several threads share access to the same resource. A mutex semaphore is used to guarantee that only one thread has access to the resource at a time. A mutex semaphore is used to check for a stop event or for a user signal to give up the resource. An event semaphore is used to signal the thread to give up the resource. An event semaphore can be posted by the user, or run in auto mode, in which case the event semaphore will be posted at fixed time intervals. Each thread can be displayed as a square of a unique color. Similarly, the resource can be displayed as a rectangle; its color is that of the first thread that owns it. ═══ 7.2.5.8. SORT Sample Program ═══ SORT (located in \TOOLKIT\SAMPLES\OS2\SORT), demonstrates the use of multiple threads by performing multiple sorts at the same time. Each sorting algorithm runs from a separate thread. The main thread is used to handle the main window's messages, while the routine that updates the display is run from another thread. ═══ 7.2.5.9. VMM Sample Program ═══ VMM (located in \TOOLKIT\SAMPLES\OS2\VMM), demonstrates the use of virtual memory by using new memory-management functions to allocate and set the attributes of memory. Users can read or write data into memory and reset the attributes using a dialog box. The memory manager protects or opens the virtual memory to read or write operations according to the different attributes of each memory block. To free memory, the user enters the address of the memory. ═══ 7.2.5.10. WORMS Sample Program ═══ WORMS (located in \TOOLKIT\SAMPLES\OS2\CONSOLIO), demonstrates how to call video (Vio), keyboard (Kbd), and mouse (Mou) 16-bit function from a 32-bit code segment. This sample program displays earth worms aimlessly moving about the screen. Each worm is a separate thread with a unique color combination and movement pattern. When one worm encounters another worm, the color attribute of the worm is set to red. The user can add or delete worms using the keyboard or mouse. ═══ 7.2.6. Presentation Manager Sample Programs ═══ The PM sample programs are as follows:  CLIPBRD  DIALOG  DRAGDROP  GRAPHIC  HELLO  IMAGE32  IPF  JIGSAW  PALETTE  PRINT  STYLE  TEMPLATE ═══ 7.2.6.1. CLIPBRD Sample Program ═══ CLIPBRD (located in \TOOLKIT\SAMPLES\PM\CLIPBRD), demonstrates how to provide a PM interface to the clipboard. Initially, this sample program displays a standard window with a bit map. The user can cut and paste rectangular images in this window, using the system clipboard as an intermediate storage area. ═══ 7.2.6.2. DIALOG Sample Program ═══ DIALOG (located in \TOOLKIT\SAMPLES\PM\DIALOG), demonstrates how to associate a dialog box with a standard window. The dialog box is defined as a dialog template in a resource file. This sample program also demonstrates how to implement entry fields, push buttons, and message boxes. Message boxes are only displayed for error conditions. ═══ 7.2.6.3. DRAGDROP Sample Program ═══ DRAGDROP (located in \TOOLKIT\SAMPLES\PM\DRAGDROP), demonstrates how to move files between directories by using the drag and drop operation of direct manipulation. This sample program creates a drop-down list box that contains a scrollable file name list of the current directory. To change the current directory, select the Window option and type in the directory name, and press Enter. To change the current directory to one higher in the directory tree, select File from the menu bar, then Open. The Select subdirectory window appears. Type in the name of the subdirectory, then select OK. DRAGDROP must be started twice, so that there are two running instances of the sample. Then, using a mouse, the user can:  Display a directory file list in the first sample  Select a file name from the second sample  Drag the file name (using mouse button 2) to the directory in the first sample  Drop the file name into the directory in the first sample. The file is now moved to the chosen directory of the first sample. ═══ 7.2.6.4. GRAPHIC Sample Program ═══ GRAPHIC (located in \TOOLKIT\SAMPLES\PM\GRAPHIC), demonstrates how to use default viewing transformation functions of the PM. It also demonstrates how to use an asynchronous drawing thread. This sample program lets the user load metafiles using a dialog box. The dialog box contains a Help push button. When the Help push button is activated, it provides instructions on loading a metafile from another directory. The user also can print a metafile or graphic circle. ═══ 7.2.6.5. HELLO Sample Program ═══ HELLO (located in \TOOLKIT\SAMPLES\PM\STDWND), demonstrates how to create and display a standard window that conforms to the Common User Access requirements. This sample program also demonstrates how to use resources defined in a script file. Initially, HELLO displays a standard window with the text "Hello". The Options conditional-cascaded menu contains three items. Each item paints a different text string in the window. This sample also shows how to override the Ctrl+C key combination. ═══ 7.2.6.6. IMAGE32 Sample Program ═══ IMAGE32 (located in \TOOLKIT\SAMPLES\PM\PORTING), demonstrates how to migrate from an existing OS/2 16-bit application to a 32-bit application. This sample also demonstrates how to display an image using the GpiImage function. The image data comes from a file that the user must select using the standard File Open menu item. ═══ 7.2.6.7. IPF Sample Program ═══ IPF (located in \TOOLKIT\SAMPLES\PM\IPF), demonstrates how to use the IPF to create an online document. This sample program features customized windows that display text, graphics, and animation. Two files are associated with this sample:  IPF online document (INF) The .INF file is the compiled IPF document. The source contains tagging that defines different types of windows. Tags that control the format and display of text also are included in this file.  OS/2 dynamic link library (DLL) The .DLL file is the compiled OS/2 C language source for the code object that is called when the .INF file is read at run time. A series of bit maps used for animation are included in the .DLL. ═══ 7.2.6.8. JIGSAW Sample Program ═══ JIGSAW (located in \TOOLKIT\SAMPLES\PM\BMPSAMP), demonstrates the use of bit maps in a graphics application. This sample provides a jigsaw puzzle based on the decomposition of an arbitrary bit map loaded from a file. The user can jumble the pieces, then drag them with a mouse. The image can be made smaller, larger, scrolled horizontally, or scrolled vertically. This sample program also demonstrates how to call the Information Presentation Facility help hook, to create instance and associate the instance with the active application window. ═══ 7.2.6.9. PALETTE Sample Program ═══ PALETTE (located in \TOOLKIT\SAMPLES\PM\PALETTE), demonstrates 32-bit graphics functions including:  Creating a window using a custom palette and animation.  Using menus with switches, and modifying the menu text.  Using multiple threads and semaphores in the Presentation Manager environment.  Displaying graphics on the screen using outline fonts and clip paths.  Online help. When started, PALETTE displays a standard window with a large OS/2 logo in the foreground. You have the ability to change the OS/2 logo to the IBM logo. If you resize the window, the logo is scaled and redrawn to fit the new window size. You can also control the animation speed from the PALETTE menu. The animation is performed by:  Creating a clip path which represents the outline of the logo characters (which are displayed using an outline font).  Setting the clip path to the presentation space.  Drawing a series of lines to the presentation space. Each line drawn with an incremental color index. Palette animation is performed using the 32-bit GpiAnimatePalette call. In order to PALETTE to remain responsive to system and user messages, no animation is performed on the main window procedure thread. A second thread is created from which all animation is performed. Hardware requirements:  XGA adapter  1MG of RAM  32-bit graphics engine. ═══ 7.2.6.10. PRINT Sample Program ═══ PRINT (located in \TOOLKIT\SAMPLES\PM\PRINT), demonstrates how to display and print text, metafiles, and bit maps. It also demonstrates how to:  Query and display system printer configurations  Interact with printer drivers to change job properties  Query and display available printer and screen fonts  Query and display printer forms and setup margins  Selectively print part or all of a document on an asynchronous thread. ═══ 7.2.6.11. STYLE Sample Program ═══ STYLE (located in \TOOLKIT\SAMPLES\PM\CONTROLS), demonstrates a PM application that conforms with the Common User Access requirements and implements the following controls:  Container  Notebook  Slider  Spin button  Value set This sample program also demonstrates secondary windows, such as dialogs and message boxes. The program lets the user edit and save text files. The source for online help, in IPF format, is also provided. STYLE also demonstrates the detection of a font that does not conform to the International Standards Organization (ISO 9241). When the user is running the sample on an ISO-compliant monitor and selects a non-compliant font in the standard font dialog, a message box is displayed to inform the user. The code in STYLE is structured so that the addition of a new function is handled in an efficient manner. For example, to add a new command to an existing menu, you need only add the command to the resource file, then add the appropriate message-processing routines to the STY_USER.C file. ═══ 7.2.6.12. TEMPLATE Sample Program ═══ TEMPLATE (located in \TOOLKIT\SAMPLES\PM\TEMPLATE), demonstrates the structure common to all PM applications. This sample program shows how to structure an application that has more than one source file. It includes the initialization file (which is used and then discarded), the resident code, and the non-resident code that is loaded only when needed. TEMPLATE also demonstrates how to:  Create a standard window  Load resources from a resource file  Create a dialog box and a button control  Display a message box  Open a file  Close a file  Print text  Paint a window  Process a message from a menu  Run a thread in the background  Exit a process. Several online help files are also provided in IPF format. ═══ 7.2.7. REXX Sample Programs ═══ The REXX sample programs are as follows:  CALLREXX  DEVINFO  PMREXX  REXXCALC  REXXUTIL  RXMACDLL ═══ 7.2.7.1. CALLREXX Sample Program ═══ CALLREXX demonstrates how a C-language application calls a REXX application. To run the REXX application BACKWARD.FNC, CALLREXX.C issues RexxStart. RexxStart calls the REXX interpreter and passes it a parameter string. BACKWARD.FNC returns a result string to the C-language application. ═══ 7.2.7.2. DEVINFO Sample Program ═══ DEVINFO issues DosDevConfig and returns the data in a collection of compound variables when all available items are requested, or a single variable when only one item is requested. This is a REXX subcommand handler and variable pool example. This sample can be run in an OS/2 full-screen session, an OS/2 text-window session, or in PMREXX. ═══ 7.2.7.3. PMREXX Sample Program ═══ PMREXX provides a PM window in which the user can display the output from a REXX procedure or from any programs called by the REXX procedure. The window has an entry field into which the user can type. ═══ 7.2.7.4. REXXCALC Sample Program ═══ REXXCALC illustrates the steps required to develop enhanced applications. ═══ 7.2.7.5. REXXUTIL Sample Program ═══ REXXUTIL demonstrates a set of external functions packaged in a dynamic link library, including:  Use of OS/2 system functions in REXX external functions  Techniques for passing large amounts of data to a REXX program using REXX compound variables as arrays. REXXUTIL runs on 32-bit OS/2. It can be run in an OS/2 full-screen session, an OS/2 window session, or in PMREXX. ═══ 7.2.7.6. RXMACDLL Sample Program ═══ RXMACDLL demonstrates the macrospace interface with the two following C-language programs and that are compiled into two separate dynamic link libraries (DLLs):  MACRO.C Contains REXX external functions, which perform REXX macrospace operations.  RXNLSINF.C Contains a REXX external function that provides information related to national language support (for example, as a currency symbol and separator). RXMACDLL.CMD uses MACRO.DLL to load NLSMONEY.CMD into the macrospace and calls NLSMONEY.CMD several times to format currency amounts. NLSMONEY.CMD formats the amounts according to the specifications provided by RXNLSINF.DLL. RXMACDLL can be run in an OS/2 full-screen session, an OS/2 window session, or in PMREXX. ═══ 7.2.8. SOM Sample Programs ═══ Note: The ANIMALS and TP (text processing) sample programs are not included in the Warp Toolkit. Refer to the SOMobjects Developer Toolkit for accessing them and obtaining information on them. ═══ 7.2.9. Workplace Shell Sample Programs ═══ The Workplace Shell sample programs are as follows:  BROWSE  CAR  CARPP  TEXTFLDR  WPCAR  WPSTUTOR  WSFILE Note: All Workplace Shell samples require SOM 2.1 in order to execute properly. ═══ 7.2.9.1. BROWSE Sample Program ═══ BROWSE displays file system objects in a hexadecimal or text format in a PM window. Open a view of an object is the default format (hexadecimal). This is done by:  Dropping a file system object on the Browse-O-Matic icon  Double-clicking mouse button 1 and entering the name of a file to view. A view of an object can be opened in either hexadecimal or text format by selecting the Open Text View or Open Hex View item of the Open conditional-cascaded menu. This is done by single-clicking mouse button 2 on the Browse-O-Matic icon. The default view format can be changed in the Settings notebook page by selecting: 1. Settings menu item 2. Menu notebook tab 3. ~Open choice of the "Available menus" drop-down list box 4. Settings... push button 5. ~Settings, Open ~Hex View or Open ~Text View option of the "Default action" drop-down list box. ═══ 7.2.9.2. CAR Sample Program ═══ CAR demonstrates how to create a Workplace Shell object using basic object-oriented programming techniques and the SOM, including:  Initializing an object  Adding settings pages to an object  Saving and restoring the state of an object  Modifying an object's context menus (adding and deleting menu items)  Querying object class data  Processing context menu items  Implementing settings page dialog processing  Handling exceptions. ═══ 7.2.9.3. CARPP Sample Program ═══ CARPP is a C++ version of the CAR sample program. CARPP demonstrates how to create a Workplace Shell object using basic object-oriented programming techniques and the SOM, including:  Initializing an object  Adding settings pages to an object  Saving and restoring the state of an object  Modifying an object's context menus (adding and deleting menu items)  Querying object class data  Processing context menu items  Implementing settings page dialog processing  Handling exceptions. ═══ 7.2.9.4. TEXTFLDR Sample Program ═══ TEXTFLDR allows only plain text objects to be placed into the folder. Objects that are not plain text, that is, control- or extended-ASCII characters, are rejected. Objects are considered to be plain text if the "Associated type" field of the Settings notebook is set to plain text. If there is no associated type set, the first 500 bytes are placed into the folder. ═══ 7.2.9.5. WPCAR Sample Program ═══ WPCAR, the Workplace Shell WPDataFile subclass sample, is the C++ version of the CAR sample. ═══ 7.2.9.6. WPSTUTOR Sample Program ═══ WPSTUTOR displays the order in which object methods are invoked by the Workplace Shell. When a sample object's class method is executed, the method's name and a description of its function are displayed in a PM window. The sample saves the object's title and its icon title backwards. This object class subclasses the WPDataFile class. Most Workplace Shell instance and class methods are overridden so that information about the methods can be displayed to the user. This sample is designed to be more of a tutorial for Workplace Shell programming than a programming example. Note: The SHOWDESC.EXE file should be renamed to SHOWDESC.BAK (or something else) to turn off the sample. Rename the file back to SHOWDESC.EXE to turn the sample back on. ═══ 7.2.9.7. WSFILE Sample Program ═══ WSFILE displays, creates, and installs Workplace objects of two classes: WSFILE and WSFOLDER. The WSFILE class is a subclass of the WPDataFile class, and the WSFOLDER class is a subclass of class WPFolder. ═══ 7.3. Tools ═══ This section provides a brief description of each tool with just enough detail to get you started at the OS/2 command line. The tools are categorized as follows:  Development Tools  Bidirectional - BIDI  Presentation Manager - PM  Multimedia  SOM  Workplace Shell For complete information about the tools described here, please refer to the online OS/2 Tools Reference. Note: The Wave Doctor, previously available with the OS/2 Multimedia Toolkit product, is not included in the Warp Toolkit. ═══ 7.3.1. Development Tools ═══ The Developer tools help you develop OS/2 programs. As programmers, we tend to use such tools as they are needed, and the ones covered here are not likely to be used as much as the compiler and linker. Nonetheless, they are handy to have. Perhaps you will only use a few of them in your programming career, but it is important to know where you can find information about them, in the event you will ever need them. The tools included in this section are:  EXEHDR - Executable-Header Files  FWDSTAMP - Forwarders  IMPLIB - Import a Library  KwikINF - Quick Information  LINK386  MARKEXE  MKMSGF - Make Message File  MSGBIND - Message Binding  NMAKE  PACK and UNPACK  PACK2 and UNPACK2 ═══ 7.3.1.1. EXEHDR ═══ EXEHDR provides a listing of the contents of the executable-header file; it also provides a listing of the attributes of all segments in the file. Uses of EXEHDR include:  Determining whether a file is an application or a dynamic link library  Modifying and viewing the attributes set by the module definition file  Viewing the number and size of code and data segments. ═══ 7.3.1.1.1. Starting EXEHDR ═══ To start EXEHDR from the command line, type: EXEHDR [options] filename where: options Is the name of the EXEHDR option that modifies the header file. Regardless of options, EXEHDR always generates a listing of the header file. filename Is the name of the application or dynamic link library file. You can specify any number of files. ═══ 7.3.1.2. FWDSTAMP ═══ FWDSTAMP adds entry points, called forwarders, to a dynamic link library (.DLL) file. Forwarders point to API functions or other exported code or data. They contain an import reference so that the final target address of the forwarded entry is contained in a different module. A forwarder might be called an imported export. When a file has a fix-up to a forwarded entry point, the loader resolves that fix-up to the address of the entry point that the forwarder imports by traversing the chain of forwarders until the end of the chain (a non-forwarded export) is reached. All forwarders are implicitly exported. The imported entry point that a forwarder refers to may itself be another forwarder. The loader will process a chain of forwarders until a non-forwarder entry point is encountered. There is no run-time cost to forwarders; however, there is a slight load-time cost as the loader resolves forwarder chains with their final addresses. ═══ 7.3.1.2.1. Using FWDSTAMP ═══ You use forwarders to combine several DLLs into one without having to relink old applications. For example, if MOUCALLS and VIOCALLS were combined into a single DLL called NEWLIB.DLL, then MOUCALLS and VIOCALLS could be replaced with special DLLs containing forwarders to NEWLIB.DLL. ═══ 7.3.1.2.2. Starting FWDSTAMP ═══ To start FWDSTAMP from the command line, type: FWDSTAMP infile deffile outfile where: infile Specifies the name of the dynamic link library file that LINK386 created. Use the file-name extension of .DLL. deffile Specifies the name of the module definition file (.DEF) that contains the forwarders. outfile Specifies the name of the .DLL file that will contain the added forwarders. Forwarders are specified in the module definition file so that an exported name, which is also imported, is a forwarder. For example: IMPORTS VIOMODEWAIT=NEWLIB.123 EXPORTS VIOMODEWAIT @ 25 In the example, a forwarder entry point for VIOMODEWAIT is created and contains an import reference to NEWLIB.123. ═══ 7.3.1.3. IMPLIB ═══ IMPLIB is used to generate an import library (.LIB) file. IMPLIB takes a module definition file (.DEF) as input. For each export definition in the .DEF file, IMPLIB generates a corresponding import definition. The .LIB file generated by IMPLIB is used as input to LINK386, which creates an executable (.EXE) file. The .LIB file provides LINK386 with information about imported dynamic link functions. ═══ 7.3.1.3.1. Creating an IMPLIB ═══ Import libraries are created by IMPLIB and are used to link DLLs with applications. Import libraries are similar in some respects to standard libraries:  You specify import libraries and standard libraries in the same command-line field of LINK386.  Both types of libraries resolve external references at link time. However, import libraries differ from standard libraries in that they contain no executable code. Rather, they identify the DLLs where the executable code can be found at run time. Creating import libraries is an extra step. Nevertheless, import libraries are recommended for use with all DLLs for two reasons:  IMPLIB automates much of the program creation process for you. To use IMPLIB, you need to supply the .DEF file you already created for the dynamic link library. Without an import library, you must create a second .DEF file that explicitly defines all needed functions in the dynamic link library.  Import libraries make it easier for one person to write a library and another to write the application. Much of the linking process (linking the .DLL file and creating the import library) can be done by the author of the dynamic link library. The import library and associated .DLL file can then be given as a unit to the person linking the application - that person need not worry about creating a .DEF file. ═══ 7.3.1.3.2. Starting IMPLIB ═══ You can start IMPLIB and specify all input from the command line. An example of the syntax follows: IMPLIB [options] implibname {deffile... | dllfile...} where: options Is the name of the option that modifies the output of IMPLIB. All options are described as follows: Syntax Description /HELP Displays a short summary of IMPLIB syntax. /IGNORECASE Turns case sensitivity off. This is the default. /NOIGNORECASE Turns case sensitivity on. /NOLOGO Suppresses the copyright screen when IMPLIB starts. implibname Is the name of the import library created. deffile Is one or more module definition files that export routines in the dynamic link library. dllfile Is one or more DLLs with exported entry points. Note: You can specify any number of either module definition files or DLLs. The following command creates the import library, MYLIB.LIB, from the module definition file, MYLIB.DEF: IMPLIB MYLIB.LIB MYLIB.DEF ═══ 7.3.1.4. KwikINF ═══ KwikINF provides you with a quick and convenient method of accessing information in online documents stored in the OS/2 BOOKSHELF from anywhere on the Desktop, with the exception of DOS or WIN-OS/2 sessions. When KwikINF is started, you can search for a text string of your choice directly or through a pop-up window by pressing a user-selectable hot key. Until you configure KwikINF, your KwikINF hot key is Alt+Q. ═══ 7.3.1.4.1. Starting KwikINF ═══ KwikINF is installed as a program object in the Development Tools folder. You start KwikINF by double-clicking on the KwikINF program object or by entering KwikINF from the command line of an OS/2 window. You can also start KwikINF automatically when you start OS/2 by placing a shadow of the KwikINF object in the Startup folder of the OS/2 System folder on the Desktop. You shadow an object by pressing Ctrl+Shift while dragging the object to the place where you wish to drop the shadow. Note: You should not add KwikINF to your STARTUP.CMD if it is followed by an EXIT statement. You can start, terminate, and configure KwikINF from a command line in an OS/2 window by entering: KwikINF [no options] [/C] [/T] [/?] where: no options Starts KwikINF. After entering this command, the default KwikINF hot key (Alt+Q) is enabled. /C Opens the Configure KwikINF window. Use this window to:  Select another KwikINF hot key  Select a default online document from the BOOKSHELF  Search  Select the activation behavior of the KwikINF window. /T Terminates KwikINF and disables the KwikINF hot key. /? Displays the enclosed information. ═══ 7.3.1.4.2. Performing a Search ═══ How you initiate a search for information in online documents is dependent on where you are on the Desktop when you press the KwikINF hot key:  From an OS/2 full-screen session, a PM VIO or AVIO window, or PM MLE : Position the cursor on the string you want to search for and press the KwikINF hot key. KwikINF retrieves the word at the cursor. If you have configured KwikINF to display the KwikINF window when the KwikINF hot key is pressed, KwikINF automatically places the retrieved word in the "Search string" entry field of the KwikINF window. When you press the Search push button or the Enter key, KwikINF displays the information. If you have configured KwikINF to bypass the KwikINF window when the KwikINF hot key is pressed, KwikINF automatically displays the information.  From a graphic-text PM window: Press the KwikINF hot key, then type the string you want to search for in the "Search string" entry field of the KwikINF window. The KwikINF text-retrieval feature is not available from graphic-text PM windows. ═══ 7.3.1.5. LINK386 ═══ LINK386 is used to translate object files and standard library files into a single executable file. LINK386 also generates DLLs and device drivers. LINK386 uses the following files as input:  One or more object files that are linked with any optional library files to create the executable file. Object files usually have a .OBJ extension.  One or more library files. The library files contain object modules that are linked to the object files to create the executable file. Library files usually have a .LIB extension.  A module definition file. The module definition file provides information to LINK386 about the executable file or dynamic link library file it is creating. The module definition file usually has a .DEF extension. LINK386 produces three types of output files:  An executable file that runs under OS/2 whenever you specify a module definition file that has a NAME statement. The executable file usually has a .EXE extension.  A dynamic link library file. A dynamic link library is produced whenever you specify a module definition file that has a LIBRARY statement. A dynamic link library file usually has a .DLL extension.  A device driver file. A virtual or physical device driver is produced whenever you specify a module definition file that has the VIRTUAL DEVICE or PHYSICAL DEVICE statements. A device driver file usually has a .DRV extension. Note: Object-oriented compilers may change the name of a function internally. LINK386 has the ability to change the name back to the original function name when displaying error messages. Three additional options are available with the Warp Toolkit: /E[XEPACK:{1|2}] Causes pages of code and data in the file to be compressed /NOO[UTPUTONERROR] Prevents the LINK386 from creating the executable file if an error is encountered. /NOS[ECTORALIGNCODE] Turns off the alignment feature provided through the LINK386 Linker. LINK386 normally aligns pages of code on sector (512 byte) boundaries. This reduces the time to load the pages when the application is executed. The /NOSECTORALIGNCODE option aligns pages of code based on the value used in the /ALIGN option. ═══ 7.3.1.5.1. Starting LINK386 ═══ To link the object files and optional library files of your application, supply input to LINK386 by:  Responding to a series of LINK386 prompts  Typing commands directly at the command prompt  Creating a response file and entering the file name on the command line. ═══ 7.3.1.5.2. Responding to LINK386 Prompts ═══ To start LINK386, type the following at the command prompt: LINK386 Press Enter; a series of prompts appear, one at a time: Object modules [.OBJ]: Run file [basename.EXE]: List file [NUL.MAP]: Libraries [.LIB]: Definitions file [NUL.DEF]: You can respond using any combination of upper- and lowercase letters. Enter your responses by pressing Enter. To extend input to a new line, type a plus sign (+) as the last character on the current line. When the same prompt appears on a new line, you can continue. Note: Do not split a file name across lines. To select the default response to a prompt, press Enter. The next prompt appears. To select the default response to the current prompt and all remaining prompts, type a semicolon and press Enter. Note: You must enter the name of at least one object file. Responses within a command line are separated by commas. LINK386 supplies the following default file extensions: .OBJ, .EXE, .MAP, .LIB, and .DEF. You can override these extensions by typing the file extension of your choice. ═══ 7.3.1.5.3. Typing Input on the Command Line ═══ You can start LINK386 and specify all input from the command line. An example of the LINK386 command is: LINK386 [options] objfiles[,exefile,mapfile,libraries,deffile] where: options Is the name of the LINK386 option. Any number of options may be specified. You can specify options anywhere on the response line, except before a comma at the end of a line of characters. If you want to specify more than one option, either group them at the end of a response, or specify them at the end of several responses. Each option must begin with a forward slash (/). To end the linking process at any point, press Ctrl+Break. objfiles Is the name of the object files that you want linked. exefile Is the output file that LINK386 created. LINK386 produces either an executable file, a dynamic link library, or a device driver. If you do not specify a file name, LINK386 uses the name of the first object file. Use the file-name extension .EXE if it is an executable file, .DLL if it is a dynamic link library, and .DRV if it is a device driver. mapfile Is the name of the file that contains the map listing. The default file name extension is .MAP. Use the /M option to include public symbols in this file. Enter NULL if you do not want a map file. libraries Is a list of libraries for LINK386 to search. These libraries include standard or import libraries, but not DLLs. The library names should be separated by plus signs (+) or blank spaces. deffile Is the name of the module definition file for the executable file or dynamic link library. ═══ 7.3.1.5.4. Creating a Response File ═══ To operate LINK386 using a response file, you must first create a file that contains the responses you want LINK386 to process. You can give the file any name, and create it with any text editor. Type the following command at the command prompt: LINK386 @filename[.ext] The @ symbol tells LINK386 that filename is a response file. If the file is not in the working directory, you must specify the path. Begin using a response file at any point on the LINK386 command line or at any LINK386 prompt. The file should contain responses in the same order as the LINK386 prompts. Each response needs to be on a separate line. If you choose to place responses on the same line, separate them with commas. If the file does not contain responses for all the prompts, LINK386 displays the appropriate prompt and waits for you to supply a response. End the response file with a semicolon. You can use special characters in the response file the same way you would use them in responses entered at the keyboard. ═══ 7.3.1.5.5. Example of a Response File ═══ The response file in the following example instructs LINK386 to generate an executable file called FUN.EXE, and four object modules, FUN, SUN, RUN, and GAMES. fun+sun+run+games /map fun.exe funlist ; If you specify the file name, FUNLIST, LINK386 will generate a map file named FUNLIST.MAP. Adding the /MAP option will cause LINK386 to include the public symbols of the application in the map file. ═══ 7.3.1.5.6. OS2STUB.EXE ═══ OS2STUB.EXE is included in the executable file created by LINK386, if the STUB statement is included in the module definition file. The stub is invoked whenever the file is executed under DOS. By default, LINK386 adds its own standard stub for this purpose. ═══ 7.3.1.6. MARKEXE ═══ MARKEXE lets you view and set the type of application. The type of application identifies the OS/2 sessions in which a program can run. You can use MARKEXE in conjunction with programs that you have created using LINK386 or with programs created by some other means. ═══ 7.3.1.6.1. Starting MARKEXE ═══ To start MARKEXE from the command line, type: MARKEXE [force] [no] [display|dllinit|dllterm|type|lfns] filename where: force Marks the executable file with OS/2 as the target operating system even though the file was marked for another operating system. Using force may produce internally inconsistent executable files. no Sets the command to the opposite condition. display Displays the application type in a message. This does not change the file. dllinit Sets per process initialization for the dynamic link library. dllterm Sets per process termination for the dynamic link library. type Specifies the application type of the executable file. It can be one of the following: WINDOWAPI Uses the API function provided by the PM. It must be executed in a PM window. WINDOWCOMPAT Runs (compatible) in a PM window or in a full-screen session. NOTWINDOWCOMPAT Executes the application in a full-screen session only. UNSPECIFIED Runs an unspecified application type in an OS/2 full-screen session. If type is not specified, MARKEXE simply displays the current type of the executable file. lfns Specifies that the program supports long file names. filename Specifies the executable file to be marked. Any number of files can be marked. MARKEXE does not modify the file if the application type of the executable file is the same as the requested type. It displays the message "unchanged" to indicate this. ═══ 7.3.1.6.2. Viewing the Application Type ═══ You can view the application type of MYPROG.EXE by typing the following: MARKEXE MYPROG.EXE MARKEXE displays the type in a message that looks like this: MYPROG.EXE: OS/2 2.1, WINDOWCOMPACT, LFNS ═══ 7.3.1.6.3. Setting the Application Type ═══ You can set the application type for MYPROG.EXE to WINDOWCOMPAT by typing: MARKEXE windowcompat myprog.exe If you have more than one executable file to be set to the same application type, you can supply the file names in a single command line, as in the following example: MARKEXE windowcompat myprog.exe abc.exe xyz.exe ═══ 7.3.1.7. MKMSGF ═══ MKMSGF converts a text message file to an output (binary) message file that DosGetMessage uses to display messages. Text messages in OS/2 full-screen applications do not need to be loaded into memory with the application; they can reside on disk until needed. You can use the output message file by specifying a message file name and a message number in the DosGetMessage parameter list. The messages also can be bound to the executable file by MSGBIND. ═══ 7.3.1.7.1. Creating a MKMSGF ═══ The input message file is a standard ASCII file that contains three types of lines:  Comment  Component identifier  Component message. Comment lines are the first lines of a file and must begin with a semicolon. A component-identifier is a three-character name identifier (for example, "DOS") that precedes all MKMSGF message numbers. Component-message lines consist of a message header and an ASCII text message. The following is an example of a text message source file. ;This is an example ;of a text message ;file DOS DOS0100E: File not found DOS0101?: DOS0102H: Usage: del [drive:][path] filename DOS0103?: DOS0104I: 1% files copied DOS0105?: DOS0106W: Warning! All data will be erased! DOS0107?: DOS0108?: DOS0109P: Do you wish to apply these patches (Y or N)? %0 where: DOS0100E - DOS0109P Identifies message numbers in sequence. The first three characters indicate the component identifier; the four-digit number indicates the message number, which is followed by a letter (described below), then a colon and blank space. If a message number is not used, type the number, end it with a question mark (?), and leave an empty entry. E, H, I, P, W Indicates the type of message. Categories include error (E), help (H), information (I), prompt (P), and warning (W). %0 Displays a prompt for input from the user, after which a carriage return and line feed are inserted. ═══ 7.3.1.7.2. Starting MKMSGF ═══ To start MKMSGF from the command line, type: MKMSGF infile outfile [option] where: infile Specifies the input file that contains message profiles. outfile Names the outfile using the three-character component identifier and the .MSG file extension; for example, MES.MSG. option Specifies the name of the option that modifies the output file. ═══ 7.3.1.7.3. Starting MKMSGF Using a Message Control File ═══ A message control file is used to create multiple code page message files. An example of the command-line syntax follows: MKMSGF @controlfile where: @controlfile Is the name of the file that contains the control statements used to generate a multiple code page message file. The @ symbol is not part of the file name; it is a required delimiter. An example of a message control file follows: root.in root.out /Pcodepage /Ddbcsrang/ctryid /LlangID,VerId /V sub.001 sub1.out /Pcodepage /Ddbcsrang/ctryid /LlangID,VerId . . . sub.00n subn.out /Pcodepage /Ddbcsrang/ctryid /LlangID,VerId ═══ 7.3.1.8. MSGBIND ═══ When DosGetMessage is issued, it searches for the message in the message segment bound to the application's executable file, and then the application's message file on a hard disk. To ensure that a message is displayed quickly, you can bind it to the application's executable file by using the MSGBIND utility program. For each executable file, MSGBIND specifies which message files to scan; for each message file, it specifies which message to include in the executable file. Note: The MSGBIND utility program supports the new compression format available with LINK386 (/EXEPACK:2) and RC (-x2). ═══ 7.3.1.8.1. Starting MSGBIND ═══ To start MSGBIND from the command line, type: MSGBIND [infile] where: infile Specifies the input file that contains the executable files, output message files, and message numbers that are to be bound. ═══ 7.3.1.8.2. Binding the Message File ═══ The input file contains three types of lines:  > Executable file  < Message file  Message numbers. An example of an input file follows: >PROG1.EXE <\MESSAGES\PRGMSG.MSG PRG0100 PRG0101 PRG0102 <\MESSAGES\APP.MSG APP0001 APP0002 APP0003 where: >PROG1.EXE Is the executable file to be modified < Defines the first message of a series to be bound, delimited either by the end of the series or a less-than symbol (<). <\MESSAGES\PRGMSG.MSG and <\MESSAGES\APP.MSG Names the files containing the binary versions of the messages (created by MKMSGF) and their identifying numbers: the three-character component identifier and the four-digit message number. ═══ 7.3.1.9. NMAKE ═══ NMAKE carries out all tasks needed to create or update a program after one or more of the source files in the program have changed. NMAKE compares the modification dates for one set of files - the target files - with those of another set of files - the source files. NMAKE then carries out a given task only if a target file is out of date. NMAKE does not compile and link all files just because one file was updated. This can save time when creating programs that have many source files or that take several steps to complete. Note: Previous releases of this program did not honor the documented behavior of the .SUFFIXES pseudotarget, which lists all of the extensions that NMAKE considers when searching for a rule to build a target that lacks an explicit build rule. NMAKE now uses only the suffixes given in the .SUFFIXES pseudotarget. If this more restrictive behavior causes some of your targets not to be built, you can enable NMAKE to behave in its former way by coding in the environment this variable: SET NMAKE=b ═══ 7.3.1.9.1. Using NMAKE ═══ To use NMAKE, create a description file (or makefile). A description file, in its simplest form, lists which files depend on others and which commands need to be executed if a file changes. You can create an NMAKE description file with any text editor that produces ASCII files. A description file looks like this: targets... : dependants...│ command │──── description block : │ targets... : dependants... command : A dependent relationship among files is defined in a description block. A description block indicates the relationship among various parts of the program. It contains commands to bring all components up-to-date. The description file can contain any number of description blocks. Use NMAKE description files for creating backup files, configuring data files, and running programs when data files are modified. ═══ 7.3.1.9.2. Starting NMAKE ═══ You can start NMAKE and specify all input from the command line. An example of the syntax follows: NMAKE [options] [macrodefinitions] [targets] [/F filename] where: options Is the name of the option that modifies the action of NMAKE. macrodefinitions Is the name of the macro that replaces one text string for another in the description file. targets Is the name of one or more target files you want NMAKE to create. If you do not list any targets, NMAKE creates the first target in the description file. /F filename Is the name of the option that specifies filename as the name of the description file to use. If a dash (-) is entered instead of a file name, NMAKE reads a description file from the standard input device. ═══ 7.3.1.10. PACK and UNPACK ═══ PACK reduces the size of a file by compressing its data. You can use PACK for a single file or a group of files, thereby reducing the disk space required for your OS/2 application. UNPACK restores a compressed file to its original size and copies it to a specified directory. ═══ 7.3.1.10.1. Starting PACK ═══ You can start PACK with a single command from the command line. The input required can be specified in one of two following methods:  Method 1: You can type the names of all the files you want to compress directly in the command line.  Method 2: You can type the name of a single file that contains a list of all the files you want to compress. When using PACK, select the method that is suitable for you. Include the drive and path if the files are not in the working directory. You can specify file names with any combination of uppercase and lowercase letters. File-name extensions are not required; however, if you specify a file name that has an extension, also type the extension. Examples of the command-line syntax follow: Method 1: PACK sourcefile [packedfile] [/H:headerpath\|/H:headerfile|/H:headerpath\headerfile] [/D:headerdate] [/T:headertime] [/C] [/A] [/R] Method 2: PACK listfile [packedfile] /L [/H:headerpath\|/H:headerfile|/H:headerpath\headerfile] [/D:headerdate] [/T:headertime] [/C] where: sourcefile Specifies the name of the file you want packed (compressed). This parameter is required. Include the drive and path if the file is not in the working directory. Global file-name characters are permitted. When the data is compressed, the name of the source file is placed in the header of the compressed file and is used as the destination file name during unpacking. listfile Specifies the name of the file that contains a list of files that are to be compressed. When naming a list file, do not use global file-name characters. For information about list files, see Creating a List File. packedfile Specifies the name of the file that will contain the compressed data. Files that contain compressed data can be recognized by the @ symbol as the last character in the file name. If you do not specify this parameter, PACK places the compressed data in sourcefile and modifies its name to contain the @ symbol. /H:headerpath\ or /H:headerfile or /H:headerpath\headerfile These parameters can be used separately or paired. /H:headerpath\ Specifies the destination path (drive letters are not permitted) to be placed in the header of the file that contains the compressed data. Unless this path is overridden with the UNPACK command, it will be the destination path when the file is uncompressed. Headerpath must end with a backslash (\). /H:headerfile Specifies the name of the file to be placed in the header of the compressed file. This file name will be used as the destination file for the uncompressed data and cannot be overridden. If a header file name is not specified, PACK automatically uses sourcefile as the name of the file that is placed in the header of the compressed file. /H:headerpath\headerfile Specifies that both a destination path and a destination file name are to be placed in the header of the file that has the compressed data. /D:headerdate Records the date in the header of the file that has the compressed data, and also in the destination file when it is uncompressed. The date must follow the format /D:MM-DD-YYYY. For example: /D:08-20-1991 and /D:12-30-2010. /T:headertime Records the time in the header of the file that has the compressed data, and also in the destination file when it is uncompressed. The time must follow the format /T:HH.MM. For example /T:02.06 and /T:14.54. Hour 00 represents 12 a.m. and hour 12 represents 12 p.m. /A Adds data from sourcefile to the data in packedfile. The source file can be either in a compressed or uncompressed state. If the source file is in an uncompressed state, the data is compressed before being added to the file containing the compressed data. /C Specifies that the current path be placed in the header of the file that contains the compressed data. When the UNPACK command is used, this path will be the destination path for the file that contains the uncompressed data. You cannot use /C when the headerpath is used. /L Indicates that listfile is a list file. A list file is not compressed; it simply contains a listing of the names of the files that are to be compressed. /R Removes the file specified by sourcefile from the file that contains only compressed data. The sourcefile parameter must specify the path and file name exactly as they appear in the header of the file with the compressed data; otherwise, the following error message appears on the screen: The specified file to remove was not found. The /R parameter is valid only when used in conjunction with sourcefile and packedfile. Note: The path and file-name information stored in the header of the file that contains the compressed data can be displayed by using the /SHOW option available with UNPACK. ═══ 7.3.1.10.2. Creating a List File ═══ To use a list file with PACK, you must first create a file that contains the names of the files you want to compress. You can give the list file any name. Following is an example of specifying a list file at the command line: PACK DEVICE.LST DEVICE.DRV /L The /L indicates that DEVICE.LST is a list file. If the list file is not in the working directory, you must specify the drive and path. Global file-name characters are not permitted in the list-file name. DEVICE.DRV is the destination file for the end-to-end-compressed data. (End-to-end compressed data is the data from each of the files contained in the list file. This data is stored in a contiguous format in the destination file.) The syntax used in the list file is similar to that used in the command line. The syntax for a single line in the list file follows: sourcefile [/H:headerpath\|/H:headerfile|/H:headerpath\ headerfile] [/D:headerdate] [/T:headertime] [/C] Remember, when using the list-file method (method 2), global file-name characters are not permitted in the source-file name. Notice also that "PACK" is excluded, and packedfile is not permitted in the list file, because they were specified on the command line. You can include comments or blank lines by entering a semicolon as the first character of the line. An example of a list file follows: ;This is a comment C:\OS2\COMMAND.COM CONFIG.SYS /H:CONFIG.BAK /C \OS2\INSTALL\DDINSTAL.EXE /H:\OS2\DDINSTAL.TMP /D:10-15-91 /T:11.45 ═══ 7.3.1.10.3. Starting UNPACK ═══ UNPACK restores a file of compressed data to its original size and copies it to a specified drive and path. To start the UNPACK command, type: UNPACK sourcefile [destinationdrive:][destinationpath] [/SHOW] [/N:singlefile] [/V] [/F] where: sourcefile Specifies the name of an existing file that contains compressed data. If this file contains one or more files of compressed data, UNPACK restores each file within the file. destinationdrive: Specifies the name of the drive to which you want UNPACK to copy one or more restored files. When you specify a destination drive, but not a path, UNPACK uses the path information stored in the header of the file that contains the compressed data. destinationpath Specifies the name of the directory (and its subdirectories) to which you want UNPACK to copy one or more restored files. When specified, the destination path overrides the path information stored in the header of the file that contains the compressed data. /SHOW Displays the destination path and file-name information that are saved in the header of each file containing compressed data. /N:singlefile Extracts and uncompresses one file from a file that contains multiple files of compressed data. /V Verifies that sectors written to the target disk are recorded properly. This parameter lets you know that critical data has been correctly recorded. This parameter causes UNPACK to run slower because a check is made for each entry recorded on the disk. /F Specifies that files with extended attributes should not be unpacked or copied if the destination file system does not support extended attributes. ═══ 7.3.1.11. PACK2 and UNPACK2 ═══ The algorithm used to compress files has been substantially enhanced. The use of this utility program is identical to the PACK and UNPACK utility, which is documented in the OS/2 Tools Reference. ═══ 7.3.2. Bidirectional (BIDI) Tools ═══ This section describes the BIDI tools. These help you develop programs for use on Bidirectional versions of OS/2. There is one tool available in this release: IPFCBIDI - Information Presentation Facility Compiler. ═══ 7.3.2.1. IPFCBIDI ═══ IPFCBIDI is a bidirectional version of the IPFC. Note: The Developer's Toolkit for OS/2 Warp on The Developer Connection for OS/2 includes two IPF compilers: IPFC.EXE and IPFCBIDI.EXE (the bidirectional version of IPFC.EXE). For this version of the Warp Toolkit, these programs are identical, as the bidirectional support has been integrated into the American version, IPFC.EXE. However, in a future release of the Warp Toolkit on The Developer Connection for OS/2, only IPFC.EXE will be included. Therefore, it will be necessary for you to modify any makefiles that reference IPFCBIDI.EXE to reference IPFC.EXE instead. ═══ 7.3.3. Multimedia Tools ═══ This section describes the Multimedia tools which help you develop multimedia programs. There is one multimedia tool available in this release: MIDICONV - MIDI Conversion Utility Note: The Wave Doctor, previously available with the OS/2 Multimedia Toolkit product, is not available with this version of the Warp Toolkit. ═══ 7.3.3.1. MIDICONV ═══ MIDICONV is a conversion utility program that lets you convert a MIDI format 1 file to a MIDI format 0 file through the use of an installable I/O procedure. Note: A MIDI format 0 file has only one track of music; a MIDI format 1 file has multiple tracks of music. ═══ 7.3.4. Presentation Manager (PM) Tools ═══ This section describes the Presentation Manager tools which help you develop Presentation Manager programs:  DLGEDIT - Dialog Editor  FONTEDIT - Font Editor  ICONEDIT - Icon Editor  IPFC - Information Presentation Facility Compiler  RC - Resource Script ═══ 7.3.4.1. DLGEDIT ═══ DLGEDIT (Dialog Editor) is used to create and modify dialog boxes and specify the controls and text within dialog boxes. As you create a dialog box and add controls, the dialog editor draws it to the screen. You can resize and reposition the dialog box, then test its controls before you incorporate it in your application. Although the dialog editor draws box outlines and controls to the screen so that you can view it from a user's perspective, the dialog editor does not save it as a graphic. Instead, the dialog editor stores a description of the dialog box and its controls in a text file that has a file-name extension of .DLG. It also creates a compiled form of the .DLG file into a resource file that has an extension of .RES. The dialog-box and resource files can each contain descriptions of more than one dialog box. The resource file can contain other application resources, such as icons, bit maps, and string tables. It is attached to the application's executable (.EXE) file after the compile and link processes. This version of the Dialog Editor is enhanced for use with Pen for OS/2. With this enhanced version, handwriting and sketch controls are available. ═══ 7.3.4.1.1. Starting DLGEDIT ═══ To start the dialog editor, select the PM Development Tools folder, then select the Dialog Editor object. The File Edit menu bar choices provide two ways to create a dialog box:  From the Edit menu, select the New Dialog item. The editor opens a new dialog in the current file. Notice that the dialog editor does not tell you that it has opened the resource files. You can open a new include file or an existing one.  From the File menu, select the New item. This opens new resource files with the extensions .RES and .DLG, as shown in the following figure:                       When you edit a dialog box, the names of the resource and include files are shown in the title bar of the dialog editor. If you are editing a new file that has not yet been named or saved, "Untitled" appears in the title bar in place of a name. ═══ 7.3.4.1.2. Replacing DLGEDIT ═══ IBM supports the version of DLGEDIT (Dialog Editor) in this release of the Warp Toolkit, but will not be enhancing or otherwise changing the Dialog Editor in future releases. URE (Universal Resource Editor) will become the editor of choice for creating and modifying dialogs and other resources. ═══ 7.3.4.2. FONTEDIT ═══ FONTEDIT (Font Editor) is used to design and save fonts for use in applications. A font is a set of alphanumeric characters, punctuation marks, and other symbols that share a common typeface design and line weight. When the font editor creates a font file, it supplies an .FNT file-name extension. The font file contains a header, which describes the font in general terms, and a section that contains bit maps of the characters themselves. ═══ 7.3.4.2.1. Starting FNTEDIT ═══ To start the font editor select the PM Development Tools folder, then select the Font Editor object. The following window appears: The quadrille to the left of the screen has within it an enlarged version of the character selected from the long, scrollable, horizontal box at the bottom of the screen. To edit the enlarged version of the character in the quadrille, use the mouse to switch the enlarged representation to black or white. You can change a series of pels by holding mouse button 1 down and moving the pointer through the pels. Several choices are available from the menu bar that enable you to tailor individual fonts. With these choices you can:  Create a font file or open an existing file  Edit a new or existing font  Define the characteristics of the font  Specify character spacing (fixed or proportional)  Name the typeface  Identify a type style (italic, underscored)  Change the width and weight of individual characters  Insert or delete a column in the character. ═══ 7.3.4.2.2. Font Resource Files ═══ All resources, except fonts, can be bound to the application's executable file or compiled into a dynamic link library (DLL). Fonts must be put in a separate .DLL using the RC. You then link the file at run time and load the resources into your application by using DosLoadModule or GpiLoadFonts. A .DLL containing font resources must have a file-name extension of .FON. The .FON file can be installed on the system. ═══ 7.3.4.3. ICONEDIT ═══ ICONEDIT (Icon Editor) is used to create icons, pointers, and bit maps. In the PM, an icon is a graphic symbol that identifies a data object, a system action, or a minimized application. A pointer is a small shape on the screen that reflects the movement of the mouse. Pointers have a hot spot that identifies their exact location on the screen. Icons, pointers, and bit maps produced by the Icon Editor are graphic symbols comprised of pels in any of the following display states:  Black  White  Color  Screen (background color)  Inverse screen (inverse of background color). Note: Mini-icons (also called small icons) are icons that are one-half the size of normal icons (also called large icons). Normal icons are 32x32 or 40x40 pels (depending on the monitor resolution). Mini-icons are 16x16 or 20x20 pels. They are used in areas where a normal icon is too large, for example, in toolbars. If you previously had OS/2 installed on your system, and if you did not update your icon profile when you installed this Warp Toolkit, then you need to run the Icon Editor once with its profile update options in order to use the mini-icon forms. To do this, enter: X:\TOOLKIT\BIN\ICONEDIT /t /i where: X Is the drive location for the installed Warp Toolkit. After the initial run of Icon Editor, the new mini-icons will be part of your profile and you will not need to use options /t /i again. ═══ 7.3.4.3.1. Starting ICONEDIT ═══ To start the Icon Editor, select the PM Development Tools folder, then select the Icon Editor object. The following window appears: Notice the information area at the top of the Icon Editor window; the items displayed from left to right include:  A two-button mouse, showing the color currently selected for each button  An actual-size image of the current figure that you are editing  A status area that provides: - Size (in pels using x and y coordinates) - Pen location - Pen size (from 1-by-1 to 9-by-9) - Hot spot (for icons and pointers, but not bit maps) - Figure type (icon, pointer, or bit map) - Form name. The palette window, in the lower-right corner, displays the colors that are available for use during editing. The colors currently selected are marked with frames. The editing window is the largest part of your working area. Use the mouse to paint the enlarged representation with the selected color. The menu-bar choices provide access to the many functions of the Icon Editor. These choices enable you to:  Create a new icon, pointer, or bit map  Edit an existing icon, pointer, or bit map  Test the new icon or pointer  Superimpose a grid over the editing window (for drawing a symmetrical figure)  Restrict a drawing to straight vertical or horizontal lines  Make transparent pels (for icons or pointers) visible  Change the shape and size of the pen  Select system preferences (to set prompts or suppress warnings)  Define hot spots (where the mouse pointer is directed). ═══ 7.3.4.4. IPFC ═══ IPF (Information Presentation Facility) is a set of tools used to create an online help facility for an application. IPF also is used to create online information that can be viewed independent of an application. It is a tool for both the information author and the application programmer. As an author of online information, you can define the windows in which information is displayed. For example, a window can be split so that scrollable text can be displayed beside a stationary illustration that the text describes. The following figure shows an IPF application-control-window. Note: A new, 32-bit version of the Information Presentation Facility Compiler (IPFC) is included in the Warp Toolkit. The new compiler provides the following enhancements: - Ability to specify output files - Expanded use of environment variables - Improved error messages - More sophisticated use of support files - New command-line interface - New tag (:hdref.) - Two new macros (.nameit and .ce) - Upgraded overall performance and increased limits ═══ 7.3.4.4.1. Developing Online Information ═══ IPF makes it possible for you to design your information in two types of formats:  An online document format for reference books  A help-window format for context-sensitive help for your application programs. To produce either format, you must create a text file using a text editor and two IPF elements:  The IPF tagging language - consists of instructions for formatting and displaying your document on the screen.  The IPFC - interprets the tags and converts the source file into an IPF format. ═══ 7.3.4.4.2. Starting IPFC ═══ You can start the IPFC and specify all input from the command line. An example of the syntax follows: IPFC [-switch] [-option] infile [outfile] where: -switch Performs the functions in the following list. They can be used either individually or combined. i Compiles the source file as an online document. s Suppresses the performance of the search function. x Generates and displays a cross-reference list. -option Performs the functions in the following list. They can be used either individually or combined. C Character code page. D DBCS range or country code. L Language ID. W Warning level. infile Specifies the name of your IPF source file. If you do not give a file-name extension, the IPFC uses .IPF by default. If your file has a file-name extension other than IPF, include that file-name extension in the command-line syntax. outfile Specifies the name of the output file. If this parameter is not used, the output file will have the same file name as the input file and an extension of either .INF (if used in conjunction with the i switch) or .HLP. If you need to store the outfile in a different location, a path can be specified. The interface from earlier levels of the compiler is still supported. An example of the syntax follows: IPFC filename [/INF] [/S] [/X] [/Wn] [> messageoutputfilename] where: filename Specifies the name of your IPF source file. If you do not give a file-name extension, the IPFC uses .IPF by default. If your file has a file-name extension other than IPF, include that file-name extension in the command line. /INF Compiles the source file as an online document. If this parameter is not included, the default is to compile the source file as a help library (with a file-name extension of .HLP). /S Suppresses the performance of the Search function. This parameter increases compression of compiled data by about 10% to further reduce the storage it requires. /X Generates and displays a cross-reference list. /Wn Generates and displays a list of error messages. The value of n indicates the level of error messages you want to receive. Values you can specify for n are 1, 2, or 3.  Warning Level 1 (the most severe)  Warning Level 2 (moderately severe)  Warning Level 3 (the least severe and is the default). messageoutputfilename Specifies the name of the file where error and cross reference messages are sent. If you do not specify this parameter, messages generated by /X and /Wn are sent to the display screen. ═══ 7.3.4.4.2.1. Compiling Help Files ═══ To compile a source file that is intended as a help-text window, use the IPFC command without the /INF option. For example: IPFC myhelp.hlp ═══ 7.3.4.4.2.2. Compiling with International Language Considerations ═══ The following parameters provide international language support: /COUNTRY = nnn (where nnn is the 3-digit country code) /CODEPAGE = nnnn (where nnnn is the 3 or 4-digit code page) /LANGUAGE = xxx (where xxx is a 3-letter identifier that indicates an international language file is to be used) An example of the command-line syntax follows: IPFC myfile.txt /INF /COUNTRY=033 /CODEPAGE=437 /LANGUAGE=FRA You can now add additional languages to IPFC by providing an IPFxxx.NLS file where xxx matches the name of the language supplied with the /LANGUAGE or -L switch. You can also add additional code pages by providing an APSYxxxx.APS file where xxxx matches the number of the code page. Four-digit code pages are supported. Three-digit code pages have a leading 0 in their APSYxxxx.APS file name, but the leading 0 does not have to be passed with the /CODEPAGE or -C switch. The underlying operating system must support the supplied code page. Note: When adding new language or code page files, be sure they are located in the same subdirectory where your IPFC program files are located. ═══ 7.3.4.4.2.3. IPFC Environment Variables ═══ There are four environment variables that can be used to specify the location of source files: IPFC Specifies the location of the .IPF support files (such as APSYMBOL.APS and IPF*.NLS). IPFCIMBED Searches for files imbedded with the .im macro. IPFCARTWORK Specifies the location of artwork files and artlink files. TMP Indicates where the compiler should store the temporary files it creates during the compilation. ═══ 7.3.4.4.2.4. Viewing an Online Document ═══ If you want to see your formatted online document, you can use the VIEW command to display it. An online document has an extension of .INF. It can be viewed by entering its name as a parameter to the VIEW command; for example: VIEW myfile You do not need to include the .INF file extension. Note: You cannot use VIEW to display help-text windows for application programs. However, for test viewing purposes, you can compile the help text as .INF files and use VIEW to look at the information. ═══ 7.3.4.5. RC ═══ RC (Resource Script) is a tool that lets you add application resources, such as message strings, pointers, menus, and dialog boxes, to your application's executable file. The primary purpose of RC is to prepare data for applications that use functions such as WinLoadString, WinLoadPointer, WinLoadMenu, and WinLoadDlg. These functions load resources from the application's executable file or another specified executable file. The application then can use the loaded resources as needed. RC and the resource functions let you define and modify application resources without recompiling the application itself. RC can modify the resources in an executable file at any time without affecting the rest of the file. You can create custom applications from a single executable file by using RC to add the custom resources you need to each application. RC is especially important for international language support because it lets you define all language-dependent data, such as message strings, as resources. Preparing the application for a new language is simply a matter of adding new resources to the existing executable file. The effective limit to the length of a string value of a macro to the RC preprocessor is 794 bytes. To count to the limit, count one for each byte interior to the string, one byte for the beginning and ending double quotation marks of each segment of the string as defined, plus one byte for the whitespace separating the ending and beginning double quotation marks of concatenated string segments. The RC program recognizes the accelerator flags (constants named like AF_*) when expressed in an ACCELTABLE statement. The flags may be expressed singly or in combination with the bitwise OR operator. The ID numbers of messages in MESSAGETABLE resources range from 0 to 65535 of any positive integer. This range is the same range as string IDs inside STRINGTABLE resources. The RC program can read from the INCLUDE environment variable any HPFS filenames containing embedded blanks, without the need to enclose such names inside quotation marks. RC uses the semicolon as a directory separator in the INCLUDE environment variable. The RC program offers two new switches with the Warp Toolkit: /nologo Suppresses display of the copyright banner each time the program starts. /? Displays the command-line syntax and options. A new option is available with the Warp Toolkit. -x[{1|2}] This option causes resources to be compressed. These resources will be automatically decompressed when the resource is accessed. ═══ 7.3.4.5.1. Creating an RC File ═══ All resources are defined in a resource script file. You use a text editor to create a resource script file that has an .RC extension. Resources are defined either explicitly in statements in the resource script file, or in other files (such as output files from the resource editors). The .RC file is the input file to the RC; the output has an .RES extension. The .RC file can contain statements that define resources and that include resources from other files. Text-based resources such as menus, accelerator keys, and text strings are defined in the .RC file. Non-text-based resources are specified in the .RC file as file names of the external files where these resources reside. Such resources include icons, pointers, and bit maps. The syntax for including external files in a resource script varies according to the nature of the resources defined or contained in the files. Fonts have a resource file to themselves. Make sure that none of the include files in your resource script file contain an end-of-file character. When the RC sees an end-of-file character, it assumes it to be the end of all input. For an example of a resource script file, see the sample program TEMPLATE. ═══ 7.3.4.5.2. Starting RC ═══ You can start RC in three ways:  Compile a resource script file and bind it to an executable file: To compile the resource script file EXAMPLE.RC and bind the resulting compiled resource (.RES) file to the executable file, EXAMPLE.EXE, use the following command: RC EXAMPLE You do not need to specify the .RC extension for EXAMPLE. The RC program creates the resource file EXAMPLE.RES and then adds the compiled resource to the executable file EXAMPLE.EXE.  Compile a resource script file but do not bind it to the executable file: To compile the resource script file, EXAMPLE.RC, into a resource file without binding the resources to an executable file, use the following command: RC -R EXAMPLE The compiler creates the resource file EXAMPLE.RES.  Compile a resource script file and put it in a DLL: Instead of binding a resource file to your application, you can put it in a dynamic link library. To add the compiled resources to a dynamic link library, use the following command: RC EXAMPLE.RES DYNALINK.DLL You can then link the file at run time and load the resources into your application by using DosLoadModule or GpiLoadFonts. However, you cannot switch from binding resources to putting resources into a dynamic link library without changing your application source code. ═══ 7.3.5. SOM Tools ═══ SOM tools help you develop SOM programs. This section describe the SOM tools:  CTOI  IRDUMP - Information Repository Dump  PDL - Public Definition Language  PREGIMPL - PM version of REGIMPL  REGIMPL - Implementation Registration  SC - SOM Compiler  SOMCORBA - SOM CORBA  SOMDCHK - SOM Check  SOMDD - SOM DSOM Daemon  SOMDSRV - SOM Server  SOMENV - SOM Environment  SOMSTARS  SOMXH - SOM .XH Header Files  WPIDL2XH - Workplace Shell .IDL To .XH Files ═══ 7.3.5.1. CTOI ═══ CTOI automates the conversion process from the SOM 1.0 format (.CSC files) to SOM 2.0 format (.IDL files). An example of the syntax follows: CTOI f1 where: f1 Is the name of the .CSC file to be converted. You may require some modifications to your environment and your existing code in order to use this tool successfully. For more information, see the article titled Using the SOM CTOI Tool in the online version of The Developer Connection News, Volume 5. This newsletter can be found by opening the following folders, starting with The Developer Connection folder: The Developer Connection Browser The Developer Connection for OS/2 References The Developer Connection News ═══ 7.3.5.2. IRDUMP ═══ IRDUMP (Information Repository Dump) verifies that a class exists in the Information Repository. An example of the syntax follows: IRDUMP [-o] [-w] [-?] [object] where: -o Includes file offset information. -w Follows dump with "within" operation. -? Shows this usage information. object Is a simple or fully-qualified name of an object in the Interface Repository. The default action is to dump all objects. ═══ 7.3.5.3. PDL ═══ PDL (Public Definition Language) is a separate program that performs the same function as the Public Definition Language (PDL) emitter used with the SOM Compiler. That emitter generates a copy of an .IDL file which has the portions designated as private removed. The file generated is the same as the .IDL file from which it is produced, except that it removes all items within the .IDL file that are marked as "private". An item is marked as private by surrounding it with #ifdef __PRIVATE__ and #endif directives. Thus, the PDL emitter can be used to generate a "public" version of an .IDL file. (Generally, client programs will need only the "public" methods and attributes.) The PDL program can be invoked independently of the SOM Compiler. In addition, the PDL program can remove any kind of items in the .IDL file that are preceded by a user-specified #ifdef directive and followed by an #endif directive. The PDL program is invoked as follows: PDL [-c] [-d] [-f] [-h] [-s] [-/] files where: -c cmd Specifies that, for each .IDL file, the PDL program is to run the specified system command. This command may contain a single occurrence of the string %s, which will be replaced with the source file name before the command is executed. For example the option -c sc -sh %s has the same effect as issuing the SC command with the -sh option. -d dir Specifies a directory in which the output files are to be placed. (The output files are given the same name as the input files). If no directory is specified, the output files are named .PDL (where fileStem is the file stem of the input file) and are placed in the current working directory. -h Requests this description of the PDL command syntax and options. -f Specifies that output files are to replace existing files with the same name, even if the existing files are read-only. By default, files are replaced only if they have write access. -s smemit Specifies the SMEMIT variable with which the PDL program is to invoke the SOM Compiler. -/ Specifies the #ifdef pattern for which the PDL program will strip out .IDL statements. The default value is #ifdef __PRIVATE__. files Specifies one or more .IDL files whose specified #ifdef sections are to be removed. Filenames must be completely specified (with the .IDL extension). If no #ifdef directive is specified (by including a -/ option), then the #ifdef __PRIVATE__ sections will be removed by default. Selected options can be specified individually, as a string of option characters, or as a combination of both. Any option that takes an argument either must be specified individually or must appear as the final option in a string of option characters. ═══ 7.3.5.4. PREGIMPL ═══ PREGIMPL is a Presentation Manager version of the REGIMPL tool. ═══ 7.3.5.5. REGIMPL ═══ Before an implementation (a server program and class libraries) can be used by client applications, it must be registered with DSOM by running the Implementation Registration utility, REGIMPL. This facility is available primarily for use in command (.CMD) files. During execution of REGIMPL, DSOM updates its database to include the new server implementation and the associated classes. This enables DSOM to find and, if necessary, to activate the server so that clients can invoke methods on it. Below are some examples on how you can use REGIMPL.  To enter interactive mode: REGIMPL  To add implementation: REGIMPL -A -i [-p ] [-v ] [-f ] [-b ] [-h ] [-m {on|off}] [-z ]  To update implementation: REGIMPL -U -i [-p ] [-v ] [-f ] [-b ] [-h ] [-m {on|off}]  To delete implementation: REGIMPL -D -i [-i ...]  To list implementation(s): REGIMPL -L [-i [-i ...]]  To list aliases: REGIMPL -S  To add class(es): REGIMPL -a -c [-c ...] -i [-i ...]  To delete class(es): REGIMPL -d -c [-c ...] [-i [-i ...]]  To list classes associated with implementation(s): REGIMPL -l [-i [-i ...]] where: -i Is the implementation alias name. -p Is the server program name. The default value is SOMDSVR.EXE. -v Is the server-class name. The default value is SOMDServer. -f Is the reference data file name. Use NULL to delete. -b Is the reference data backup file name. Use NULL to delete. -h Is the host machine name. The default value is localhost. -m {on|off} Enables multi-threaded server. -z Is the implementation ID. -c Is the class name. ═══ 7.3.5.6. SC ═══ The OS/2 operating system provides a programming interface that allows applications to implement Desktop objects. This programming interface enables you to create Desktop objects that conforms to the CUA architecture using basic object-oriented programming interface. The interface is implemented using the IBM SC (SOM Compiler). The SOM Compiler (SC) helps implementers build classes in which interface and implementation are decoupled. The SOM Compiler reads the IDL definition of a class interface and generates:  An implementation skeleton for the class  Bindings for implementors  Bindings for client programs Bindings are language-specific macros and procedures that make implementing and using SOM classes more convenient. These bindings offer a convenient interface to SOM that is tailored to a particular programming language. For instance, C programmers can invoke methods in the same way they make ordinary procedure calls. The C++ bindings "wrap" SOM objects as C++ objects, so that C++ programmers can invoke methods on SOM objects in the same way they invoke methods on C++ objects. In addition, SOM objects receive full C++ typechecking, just as C++ objects do. Currently, the SOM Compiler can generate both C and C++ language bindings for a class. ═══ 7.3.5.6.1. Starting SC ═══ The SOM compiler is actually a precompiler and a collection of code emitters that produce binding files from the output of the precompiler. The files have several forms, including C-header files, a C-implementation template, and the language-neutral version of the class definition file. To start the SOM precompiler from the command line, type: SC [-C] [-D] [-E] [-I] [-S] [-U] [-V] [-c] [-d] [-h] [-i] [-m] [-p] [-r] [-s] [-u] [-v] [-w] f1 f2 ... where: -C Is the size of the comment buffer. The default value is 49152. -D Is the same as the -D option for cpp. -E = Is the set environment variable. -I Is the same as the -I option for cpp. -S Is the size of the string buffer. The default is 49152. -U Is the same as the -U option for cpp. -V Shows the version number of the compiler. -c Ignores all comments. -d Is the output directory for each emitted file. -h Is this message. -i Uses this file name as supplied. -m Adds a global modifier. -p Is a shorthand for -D__PRIVATE__. -r Checks if the releaseorder entries exist. The default value is FALSE. -s Replaces the SMEMIT variable with a . -u Updates the interface repository. -v Verboses the debugging mode. The default value is FALSE. -w Does not display warnings. The default value is FALSE. file1, file2 Is the name of a file that contains an OIDL class definition. If you do not specify a file-name extension, the compiler uses .IDL by default. The options can be specified individually, as a string of option characters, or as a combination of these forms. Any option that takes an argument must be specified individually or be the final option in a string of option characters. The modifiers are as follows: addprefixes Adds functionprefix to method names in template file [no]addstar Does not add a * to C bindings for interface references. corba Checks the source for CORBA compliance. csc Forces running of the OIDL compiler. emitappend Appends the emitted files at the end of an existing file. noheader Does not add a header to the emitted file. noint Does not warn about int causing portability problems. nolock Does not lock the IR during update. nopp Does not run the source through the pre-processor. notc Does not use typecodes for emit information. nouseshort Does not generate short names for types. pp= Specifies a local pre-processor to use. tcconsts Generates CORBA type code constants. ═══ 7.3.5.6.2. SMEMIT Environment Variable ═══ SMEMIT is used to indicate which emitter programs should be executed. Like the SMINCLUDE environment variable it can consist of a list of items separated by semicolons. Each item designates a particular emitter by the name of the file extension the emitter produces. The syntax is as follows: SMEMIT=[h;ih;c;xh;xih;xc;def;ir;pdl] The default values are h and ih. For example: SET SMEMIT=H;IH;DEF; indicates that EMITH.EXE, EMITIH.EXE, and EMITDEF.EXE programs should be executed to produce .H, .IH, and .DEF files, respectively. By default all emitted output files are placed in the same directory as the input file. If the SMEMIT environment variable is not defined, the SOM compiler will perform a syntax check of your class definition but no output will be produced. Note: All command-line modifiers can be set in the environment by changing them to UPPERCASE and preappending SM to them. ═══ 7.3.5.6.3. SMINCLUDE Environment Variable ═══ The SOM compiler uses an environment variable called SMINCLUDE to locate included class definitions. SMINCLUDE specifies where to search for .IDL and .EFW files. Because every SOM class will have an include file for its parent class definition, you must set SMINCLUDE before running the SOM compiler. Its form is similar to the OS/2 PATH or DPATH environment variables, in that it can consist of one or more directory names, separated by a semicolon. Directory names can be specified with absolute or relative path names. The syntax is as follows: SMINCLUDE=[;]+ For example: SET SMINCLUDE=.;C:\TOOLKIT\SOM\INCLUDE;C:\TOOLKIT\IDL; Note: All command-line modifiers can be set in the environment by changing them to UPPERCASE and preappending SM to them. ═══ 7.3.5.6.4. SMKNOWNEXTS Environment Variable ═══ SMKNOWNEXTS add headers to user written emitters. The syntax is as follows: SMKNOWNEXTS=ext[;ext]+ Note: All command-line modifiers can be set in the environment by changing them to UPPERCASE and preappending SM to them. ═══ 7.3.5.6.5. SMTMP Environment Variable ═══ The SMTMP environment variable specifies the name of a directory that the SOM compiler uses to hold intermediate output files. The syntax is as follows: SMTMP= For example: SET SMTMP=%TMP% tells the SOM compiler to use the same directory for temporary files as given by the setting of the TMP environment variable. As a general rule, the directory indicated by SMTMP should never coincide with the directory used by the SOM compiler for its input or the emitted output files. Note: All command-line modifiers can be set in the environment by changing them to UPPERCASE and preappending SM to them. ═══ 7.3.5.6.6. SOMIR Environment Variable ═══ SOMIR provides a list of IRs to search for. The syntax is as follows: SOMIR=[;]+ Note: All command-line modifiers can be set in the environment by changing them to UPPERCASE and preappending SM to them. ═══ 7.3.5.6.7. #pragma Directives ═══ There are two pragma directives: #pragma somemittypes on Turns on the emission of global types. #pragma somemittypes off Turns off the emission of global types. #pragma modifier Used instead of modifier statement. ═══ 7.3.5.6.8. Running SOM Emitters ═══ You complete the SOM compilation process by running the emitters. You can control the output of the emitters from the command line by typing: COMMAND [-o filename] [-a name[=value]]* where: command Is one of the following:  EMITH  EMITIH  EMITC  EMITDEF -o Is an explicit name (including drive, path, and file-name extension) for the emitted output file. If this option is not specified, the output file is placed in the current directory, and the file-name extension defaults to a type appropriate to the selected emitter program. -a name[=value] Adds a global attribute. ═══ 7.3.5.7. SOMCORBA ═══ SOMCORBA is a command script to convert to implicit pointers (like CORBA) for interface references. ═══ 7.3.5.8. SOMDCHK ═══ SOMDCHK evaluates the environment to verify whether DSOM can operate correctly. The program generates messages that evaluate the DSOM environment. It determines whether the necessary SOM DLLs can be located, whether DSOM is enabled for workgroup (cross-machine) communication, whether Interface and Implementation Repositories can be located, and it displays the settings of important environment variables. In its "verbose" mode, SOMDCHK gives the default settings for DSOM environment variables and explains how DSOM uses them. The program is invoked from the command line using the syntax given below. The optional verbose setting can be turned on by including the -v option with the following command: SOMDCHK [-v] ═══ 7.3.5.9. SOMDD ═══ SOMDD is the DSOM daemon. It must be started prior to running a DSOM application. The daemon can be started manually from the command line, or it could be started automatically from a start-up script run at boot time. It may be run in the background with the following command: START SOMDD The SOMDD program requires no parameters. An optional -q parameters can be used to set "quiet" mode, to suppress messages. ═══ 7.3.5.10. SOMDSVR ═══ SOMDSVR is the "generic" server program. It can be started either from the command line or automatically upon demand. When starting SOMDSVR from the command line, the server's implementation ID or alias must be supplied as an argument. The command syntax for starting a generic SOM server is: SOMDSVR [impl_id | -a alias] ═══ 7.3.5.11. SOMENV ═══ SOMENV is a command script to set the environment variables required for SOM programming. This command script requires that the SOMBASE environment variable be set. ═══ 7.3.5.12. SOMSTARS ═══ SOMSTARS is a command script to convert to explicit pointers for interface references. ═══ 7.3.5.13. SOMXH ═══ SOMXH is a command script to create the .XH header files from the .IDL files located in the \TOOLKIT\SOM\INCLUDE subdirectory. ═══ 7.3.5.14. WPIDL2XH ═══ WPIDL2XH.CMD is a command file to emit .XH header files from Workplace Shell .IDL files. To re-generate the .XH headers for C++, invoke this command file on each Workplace Shell class .IDL file from the Toolkit. It is only necessary to do this when you upgrade to a new level of SOM. Invoking the SOMXH command script will create .XH files for you, as the Workplace Shell classes currently only maintain passthru sections for .H files for C. The syntax is as follows: WPIDL2XH ═══ 7.3.6. Workplace Shell Tools ═══ This section describes the Workplace Shell tools which help you develop Workplace Shell programs. There are two Workplace Shell tools in this release:  OBJUTIL - Object Utility/2  WPCLSLST - Workplace Class List ═══ 7.3.6.1. OBJUTIL ═══ OBJUTIL (Object Utility/2) is a new Workplace Shell tool that provides a facility for registering classes, and creating and modifying instances of classes. ═══ 7.3.6.2. WPCLSLST ═══ WPCLSLST (Workplace Class List) creates a workplace object class and an instance of a workplace object class. Workplace objects are constructed using the SOM protocol and are instances of one of the following workplace object classes: Predefined These classes are defined by the system. Examples of predefined workplace object classes are WPObject, WPFileSystem, and WPAbstract. Subclass These classes are derived from existing predefined workplace object classes. They add or remove function; however, they retain the basic behavior of that class. Replaced These classes replace the class being subclassed. They notify the behavior of an instance of a predefined workplace object class without the instance being aware of the new class. ═══ 7.3.6.2.1. Starting WPCLSLST ═══ To start the Workplace Class List, select the PM Development Tools folder, then select the WP Class List object. A window similar to the following appears: Using this window, you can:  Add, delete, and browse registered Workplace Class Objects  Create an instance of a Workplace Class Object  View the registered Workplace Class Object in the system. ═══ 7.4. Online Documentation ═══ The following list describes manuals available online that might be of interest to users who develop applications for OS/2 Warp, Version 3. The OS/2 Warp, Version 3 Technical Library provides both guidance and reference information and can be used for OS/2 Warp, Version 3 development. It also explains How to Use Online Documents. The library includes the following online books:  Bidirectional Language Support Dev. Guide and Reference  Control Program Guide and Reference  Debug Kernel Reference  Graphics Programming Guide and Reference  Information Presentation Facility Guide and Reference  Multimedia Application Programming Guide  Multimedia Programming Reference  Multimedia Subsystem Programming Guide  Presentation Manager Programming Guide and Reference  SOM Programmers Reference  SOM User's Guide  Tools Reference  Workplace Shell Programming Guide  Workplace Shell Programming Reference ═══ 7.4.1. Bidirectional Language Support Dev. Guide and Reference ═══ This book provides information about the interface (API) for the Arabic and Hebrew languages thus allowing programmers to create Arabic or Hebrew applications for this environment. The Bidirectional support in PM is provided in the Arabic and Hebrew language versions of the OS/2 operating system. The support is active/configured when the COUNTRY selection during OS/2 installation is Arabic or Hebrew in these versions. ═══ 7.4.2. Control Program Guide and Reference ═══ This book provides the C-language syntax for each of the base operating-system application programming interface (API), including input and output parameters, data structures, data types, return codes, and example codes. Guidance information is also provided to assist you in developing applications using these items. API functions (indicated by the prefix "Dos") are presented by component; such as Error Management, Exception Management, and File System. The API functions, within each of the components to which they apply, are listed in alphabetic order. API functions also are available from a single alphabetic list. The online Control Program Guide and Reference contains the information of the Control Program Programming Guide and the Control Program Programming Reference books. ═══ 7.4.3. Debug Kernel Reference ═══ This book provides details on the debug kernel, installation, debugging commands and syntax, and the debug PM interface. ═══ 7.4.4. Graphics Programming Guide and Reference ═══ This book describes the concepts associated with graphical output--presentation spaces, device contexts, graphic primitives, fonts--and how to prepare graphical output for display and printing. It provides the C-language syntax for all the graphical programming interface (GPI), including input and output parameters, data structures, data types, return codes, and example codes. Guidance information is also provided to assist you in developing applications using these items. GPI functions (indicated by the prefix "Gpi") are listed in alphabetic order. The online Graphics Programming Guide and Reference contains the information of the Graphics Programming Guide and the Graphics Programming Reference books. ═══ 7.4.5. Information Presentation Facility Guide and Reference ═══ This book describes the concepts--help windows, hypertext linking, author-controlled viewports, dynamic data formatting--and the functions used for implementing help in OS/2 applications. It describes how to create online help and information. It also contains an alphabetic list of IPF tags, symbols, and control words. The IPFC error messages, window functions, dynamic data formatting functions, and help manager messages and functions are included. ═══ 7.4.6. 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. ═══ 7.4.7. Multimedia Programming Reference ═══ This book describes the media control interface, PM graphic push buttons, secondary windows functions, multimedia I/O services, direct interface video extensions (DIVE), and subsystem services for synchronization and streaming. ═══ 7.4.8. Multimedia Subsystem Programming Guide ═══ This book describes the subsystem components--media control driver, stream handler, and I/O procedure--that support a multimedia device. ═══ 7.4.9. OS/2 Tools Reference ═══ This book describes the tools that are included in the IBM Developer's Toolkit for OS/2 Warp, Version 3. ═══ 7.4.10. Presentation Manager Programming Guide and Reference ═══ This book provides the C-language syntax for each of the base operating-system application programming interface (API), including input and output parameters, data structures, data types, return codes, and example codes. API function prefixes include Drg (dragdrop), Ddf (dynamic data format), Prf (profile), Spl (spooler), and Win (window). Also included are application hooks, and PM messages. The online Presentation Manager Programming Guide and Reference contains the information of the Presentation Manager Programming Guide and Presentation Manager Programming Reference books. ═══ 7.4.11. REXX Program Reference ═══ This book provides detailed descriptions of the REXX functions. ═══ 7.4.12. SOM Programmers Reference ═══ This book is a complete reference for each of the classes and methods used for the object-oriented programming environment. Also included are System Object Model (SOM) C-language and C++ bindings, the Object Interface Definition Language syntax, and the SOM compiler command syntax. ═══ 7.4.13. SOM User's Guide ═══ This book explains how programmers using C, C++, and other languages can:  Implement class libraries that exploit the SOM library-packaging technology  Develop client programs that use class libraries that were built using SOM  Develop applications that use the frameworks supplied with the SOMobjects Toolkit, class libraries that facilitate development of object-oriented applications. ═══ 7.4.14. Workplace Shell Programming Guide ═══ This book describes the concepts associated with object-oriented programming for the OS/2 operating system--SOM, Workplace Shell classes and methods--and how to create object-oriented applications for the OS/2 Desktop. ═══ 7.4.15. Workplace Shell Programming Reference ═══ This book provides the detailed descriptions of the Workplace Shell object-oriented programming interface. ═══ 7.4.16. How to Use Online Documents ═══ The online documents in the Warp Toolkit were developed with IPF. IPF displays information through a familiar user interface and lets you do the following:  View a table of contents from which you can quickly gain access to a category  View the category and select related topics from a menu  View multiple windows of related information for comparison values  Search for a topic throughout the document  Copy the contents of a topic to the system clipboard for editing with the OS/2 System Editor, the Enhanced Editor, or any other editor with this capability  Copy the contents of a topic to a temporary file for editing with a text editor. When installed, the online documents are added to the Toolkit Information folder. To access the online documents, double-click on the folder, then select the appropriate book. A window that has a table of contents (Contents window) will appear. When the Contents window first appears, some categories have a plus sign (+) beside them. The plus sign indicates that additional topics are available. Using mouse button 1, click on the plus sign to expand the category. For more information about using the Warp Toolkit online documents, refer to the How to Use the Using Your Toolkit Book section. ═══ 7.5. BETA ═══ The BETA component contains new tools, samples, online documentation and API support for function in future versions of the operating system. Execution of these pieces will typically require additional runtime support provided by a Beta version of OS/2 Warp. In general, Beta versions of the operating system are available on The Developer Connection for OS/2. However, there will be cases, as in this volume's entertainment samples and tools , where the runtime support is included with the Developer's Toolkit for OS/2 Warp. The content of this component can vary from volume to volume of The Developer Connection for OS/2. This component is not installed by default by the Developer's Toolkit for OS/2 installation program, but the component can be selected prior to installing. All files for installed via the BETA component are installed in the \TOOLKIT\BETA directory structure by default. In this release of the Warp Toolkit, the BETA component includes Entertainment Support and IBM Developer API Extensions for OS/2. Summer games are here! PC game developers have been asking for code, tools, and samples specifically related to their entertainment software and games requirements. So, we have created new entertainment samples and tools just for you--the entertainment software developer. In our very first Beta version, you will find audio, video, networking, and joystick functionality that has been created or enhanced with PC gamers in mind. If you have a question regarding any of the entertainment components, refer to the entertainment online documentation as a first step. If you still need assistance, call 1-800-553-1623 for technical support. ═══ 7.5.1. BRender Entertainment Samples ═══ There is one BRender sample in this release: ROBOT - Walking Robot ═══ 7.5.1.1. ROBOT ═══ Note: You must read the Argonaut Non-Commercial License before using this sample. ROBOT demonstrates how to use the new OS/2 version of Argonaut's BRender technology. The BRender technology allows for real-time, three-dimensional (3D) manipulation of actors. An actor can be the actual object model, a camera, or a light. The objects are composed of polygons. These polygons can be moved independently or in conjunction with each other. While BRender provides all the functions necessary for the 3D transformation of the scene, it requires that system-specific code be used for blitting to the screen. There are two parts to the design. One is the use of BRender to perform the 3D manipulations, and the other is the use of DIVE (DIVE provides a faster method of blitting) to allocate and display the image buffer and to do any palette manipulations. ROBOT does the following:  Performs initialization  Imports data for models, materials and textures  Renders the scene  Modifies object positions and orientations via user interface. This sample demonstrates a robot walking. The mouse can be used to zoom in and out and also to rotate the robot in 3D space. ═══ 7.5.1.1.1. Starting ROBOT ═══ You can start ROBOT in two ways:  From the command line, change to the TOOLKIT\BETA\BRENDER\SAMPLES\ROBOT subdirectory and type: ROBOT  From the Desktop, open the Toolkit folder and then: 1. Open the BETA folder. 2. Open the BRender folder. 3. Open the BRender Samples folder. 4. Double-click on Robot. ═══ 7.5.2. Entertainment Samples ═══ The entertainment samples provided with this release are all new Beta samples. They are categorized as follows:  Audio Samples  Input Device Sample  Network Sample  Video Sample ═══ 7.5.2.1. Audio Samples ═══ There are two audio samples in this release:  DAUDIO - Direct Audio  MIDISAMP - Real Time MIDI ═══ 7.5.2.1.1. DAUDIO ═══ DAUDIO (direct audio) demonstrates the use of the direct audio interface. This high speed audio interface allows an application to send audio data directly to the amp-mixer device. The sample demonstrates the steps required to set up and use this new interface for playing and recording digital audio data. Hardware requirements:  Computer capable of running OS/2 Warp  Sound Card  Speakers or Headphones. Software requirements:  OS/2 Warp  Multimedia support. ═══ 7.5.2.1.1.1. Installing DAUDIO ═══ This version of the entertainment samples and tools includes Beta versions of AMPMXMCD.DLL and AUDIOSH.DLL. The original versions of these files (located in MMOS2\DLL) must be replaced with the Beta files before any application utilizing the direct audio interface can work. The Beta versions of these .DLL files are located in the TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\DAUDIO subdirectory. To replace these .DLL files:  Double-click on Sound located in the Multimedia folder and ensure Enable system sound is not selected.  Shut down and restart your system. This will unlock the AMPMXMCD.DLL and AUDIOSH.DLL files.  Back up the AMPMXMCD.DLL and AUDIOSH.DLL files.  Copy the AMPMXMCD.DLL and AUDIOSH.DLL files (located in \TOOLKIT\BETA\DLL) to the MMOS2\DLL subdirectory.  Double-click on Sound located in the Multimedia folder and select Enable system sounds. ═══ 7.5.2.1.1.2. Starting DAUDIO ═══ You can start DAUDIO in two ways:  From the command line, change to the TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\DAUDIO subdirectory and type: DAUDIO  From the Desktop, open the Toolkit folder and then: 1. Open the BETA folder 2. Open the Beta Entertainment Samples folder. 3. Open the Audio Samples folder. 4. Double-click on Direct Audio. ═══ 7.5.2.1.2. MIDISAMP ═══ MIDISAMP illustrates the use of the real-time MIDI support programming concepts and usage of the new real-time MIDI API. This sample program illustrates the use of the new real-time MIDI API by initializing and setting up a small MIDI node network and subsequently sending a MIDI message from an application node to a hardware node, thereby demonstrating MIDI playback. Hardware requirements:  Computer capable of running OS/2 Warp  Speaker or headphones  Sound card Note: The README for MIDISAMP contains specific information regarding device driver installation for running MIDISAMP. (This README is located in the TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\MIDI subdirectory.) Software requirements: - OS/2 Warp - Multimedia support - Standard MIDI file. ═══ 7.5.2.1.2.1. Known Limitations ═══ Currently, MIDISAMP might halt when another process attempts to play a sound (including system sounds) while the sample is running. Therefore, you should disable system sound before running MIDISAMP. To disable system sound, double-click on Sound located in the Multimedia folder and ensure Enable system sound is not selected. ═══ 7.5.2.1.2.2. Starting MIDISAMP ═══ You can start MIDISAMP in two ways:  From the command line, change to the TOOLKIT\BETA\SAMPLES\ENTOOLKT\AUDIO\MIDI subdirectory and type: MIDISAMP filename.mid where: filename.mid is a MIDI file.  From the Desktop, open the Toolkit folder and then: 1. Open the BETA folder. 2. Open the Beta Entertainment Samples folder. 3. Open the Audio Samples folder. 4. Double-click on MIDI Samp. Sample MIDI files are located in the MMOS2\SOUNDS subdirectory. ═══ 7.5.2.2. Input Device Sample ═══ There is one input device sample in this release: JOYSTICK ═══ 7.5.2.2.1. JOYSTICK ═══ JOYSTICK (OS/2 Joystick device driver) allows an OS/2 Warp application to access the machine's game port. The driver provides an interface or a set of API function calls for reading the joysticks. The Joystick API is implemented within the OS/2 Joystick device driver. This sample code shows how to use the OS/2 Joystick API and supports any two standard joysticks or one joystick with an advanced feature, such as a hatch or throttle control. Currently, there are no high-level versions of access to these functions, except through the IOCtl interface. This sample issues DosDevIOCtl to request status or sends commands to the OS/2 Joystick device driver. The API function number, an input parameter to DosDevIOCtl, is defined by the OS/2 Joystick device driver. JOYSTICK registers with the OS/2 Joystick device driver via DosOpen, with the device name "GAME$". It sends commands to the Joystick device driver via DosDevIOCtl after opening the new GAME$ device. These commands or IOCtls are subfunctions that are issued through DosDevIOCtl. This sample passes proper parameters and required data buffers or data structures when calling the API. The returned data is examined and a proper message is displayed to the screen. If the call is unsuccessful, an error message will be displayed and the sample will be terminated. JOYSTICK shows how to interface with the OS/2 Joystick API via the following functions:  Get the version number of the driver, API function x'01'.  Get the device parameters, API function x'02'.  Set the device parameters, API function x'03'.  Get the calibration values, API function x'04'.  Get the current joystick status, API function x'10'.  Get the joystick status at next button press, API function x'11'.  Get the joystick status at next sample, API function x'12'. It also accesses other OS/2 functions such as:  DosOpen DosOpen function must be called first to open the device driver name (GAME$) prior to any API function call to the OS/2 Joystick device driver.  DosClose When the program terminates, DosClose must be called to end the program properly. Hardware Requirements:  Joystick device Software Requirements:  OS/2 Warp  IBM C Set ++ compiler 2.x or 3.x  Developer's Toolkit 3.0  GAMEDD.SYS driver Note: An error message will be displayed and the program will terminate if the driver is not installed. The design of this sample is based on the set of functions provided by the OS/2 Joystick device driver. The CONFIG.SYS should include the following statement: DEVICE=pathname\GAMEDD.SYS where: pathname is the path where GAMEDD.SYS is located. ═══ 7.5.2.2.1.1. Starting JOYSTICK ═══ You can start JOYSTICK in two ways:  From the command line, change to the TOOLKIT\BETA\SAMPLES\ENTOOLKT\INPUT\JOYSTICK subdirectory and type: JOYSTICK  From the Desktop, open the Toolkit folder and then: 1. Open the BETA folder. 2. Open the Beta Entertainment Samples folder. 3. Open the Input Samples folder. 4. Double-click on Joytest. ═══ 7.5.2.3. Network Sample ═══ There is one network sample in this release: TICTAC - TicTacToe ═══ 7.5.2.3.1. TICTAC ═══ TICTAC (TicTacToe) demonstrates how to use networking functions to develop a multiplayer, networked game. These networking support functions are referred to as OS/2 Warp networking functions. These functions support multiple transports such as TCP/IP, SPX/IPX, and OEM stacks. The current functions implement support for TCP/IP transport only. This sample uses the Warp networking functions to illustrate a 2-player TicTacToe game, where two players play against each other. Software Requirements:  WARPNET.DLL  OS/2 TCP/IP Version 2.x or higher  OS/2 Warp 3.0 or higher. ═══ 7.5.2.3.1.1. Starting TICTAC ═══ You can start TICTAC in two ways:  From the command line, change to the TOOLKIT\BETA\SAMPLES\ENTOOLKT\NETWORK\TICTAC subdirectory and type: TICTAC  From the Desktop, open the Toolkit folder and then: 1. Open the BETA folder. 2. Open the Beta Entertainment Samples folder. 3. Open the Network Samples folder. 4. Double-click on TicTac. ═══ 7.5.2.3.1.2. Warp Networking Functions ═══ The Warp networking functions represent a standard application layer interface to OS/2 entertainment software for networked multiplayer support. These networking functions support multiple transports such as TCP/IP, SPX/IPX, and OEM stacks. Warp networking functions enable creation of multiplayer networked entertainment software, such as games. This first implementation of the Warp networking functions uses TCP/IP. Warp networking functions define a well known UDP port just for entertainment software. The Warp networking game server or the daemon monitors the well-known game port and routes packets received at this port to the application. Note: The TCP/IP Services file (located in \TCPIP\ETC\SERVICES) must be modified to include the well known Game port entry. The modification would look similar to the following: GAMED 5022/UDP #Well Known UDP based Game Port. ═══ 7.5.2.3.1.3. Known Limitations ═══ Currently, the receive function (WarpnetPackRecv) for Warp networking can only receive header information with no packet data. ═══ 7.5.2.4. Video Sample ═══ There is one video sample in this release: FSDIVE - Full Screen DIVE ═══ 7.5.2.4.1. FSDIVE ═══ FSDIVE (full-screen DIVE) demonstrates the use of multimedia's direct interface video extensions (DIVE) by repeatedly displaying a short animation sequence. The animation is performed by sequentially displaying a series of up to 16 bit maps in a PM window. You can display the default bit maps, shipped with the sample, or specify the bit maps by passing the file names as command line parameters. After the application is started, you can move or resize the window and observe the effects on the frame rate of the animation (displayed on the title bar). The latest version of the DIVE interface has been enhanced to allow an application to take over the display and change the resolution. This allows an application to run in a full screen without paying the performance penalty of maintaining a high-resolution Desktop. Note: Before the full-screen DIVE sample can run in full-screen mode, full-screen support must be installed by running GSRVINST.EXE (located in \TOOLKIT\BETA\SAMPLES\ENTOOLKT\VIDEO\FSDIVE). See the GAMESRVR.DOC file in the same directory for more details. Once the game server DLL is installed, full-screen DIVE can be activated by using the Alt+Home hot key. ═══ 7.5.2.4.1.1. Starting FSDIVE ═══ You can start FSDIVE in two ways:  From the command line, change to the TOOLKIT\BETA\SAMPLES\ENTOOLKT\VIDEO\FSDIVE subdirectory and type: FSDIVE  From the Desktop, open the Toolkit folder and then: 1. Open the BETA folder. 2. Open the Beta Entertainment Samples folder. 3. Open the Video Samples folder. 4. Double-click on FS Dive. ═══ 7.5.3. Entertainment Tools ═══ The following Beta entertainment tool is available with this release: RINST2 - REXX Installation Aid for Games DOS Programs ═══ 7.5.3.1. RINST2 ═══ RINST2 is a REXX tool that assists you in installing any entertainment or DOS program. It creates a Workplace Shell program, associates an icon, and sets the DOS setting as appropriate. It also offers the chance to run a setup program as part of the installation. This tool can easily be used to install any type of program. Note: OS/2 REXX must be installed and loaded prior to running this program. ═══ 7.5.3.1.1. Starting RINST2 ═══ To start RINST2 from the command line, change to the TOOLKIT\BETA\BIN subdirectory and type: RINST2 ═══ 7.5.3.1.2. Using RINST2 ═══ To customize this tool, use a text editor and change the title, Raptor, and the program name, RAP.EXE, to meet your needs. title = "Raptor" rc = SysFileTree("RAP.EXE",fspec,"FO") ═══ 7.5.4. Entertainment Online Documentation ═══ There are five new entertainment online books, which are located in the \TOOLKIT\BETA\BOOK subdirectory.  BRender Concise Guide  BRender Technical Reference  Direct Audio Interface  Entertainment Programming Guide and Reference  Real Time MIDI You can also access these books from the Desktop by opening the Toolkit folder, then the BETA folder, and then the Beta Toolkit Information folder. ═══ 7.5.4.1. BRender Concise Guide ═══ This book describes the BRender Power Rendering System Application Programming Interface (API), shows how the components of the BRender system work as a whole, and gives some idea of the capabilities of this system. ═══ 7.5.4.2. BRender Technical Reference ═══ This book provides documentation support for the BRender Power Rendering System, a real-time, 3D graphics software by Argonaut Technologies Ltd. Argonaut's BRender 3D graphics API is only distributed under Argonaut's end-user license. The BRender Sample provides a limited license permitting you to evaluate the product. Should you wish to include the BRender Power Rendering System in your entertainment software, you need to contact Argonaut for a commercial license. ═══ 7.5.4.3. Direct Audio Interface ═══ This book provides an overview of the direct audio interface including descriptions of messages and associated data types. ═══ 7.5.4.4. Entertainment Programming Guide and Reference ═══ This book is written for the developer interested in writing entertainment software for OS/2 Warp. It contains information about video support, audio support, networking, and input devices used specifically in entertainment development, such as:  OS/2 Joystick device driver  Full-screen DIVE (Direct Interface Video Extensions)  Multiplayer networking API ═══ 7.5.4.5. Real Time MIDI ═══ This book provides a discussion of the new real-time MIDI architecture and introduces the real-time MIDI application programming interface (API) including detailed descriptions of the real-time MIDI functions and associated data types. ═══ 7.5.5. IBM Developer API Extensions for OS/2 Samples ═══ The following samples are included supporting the IBM Developer API Extensions for OS/2:  HiWorld  ToyBox  WinMain Wrapper Function (MAIN.C)  DLL Initialization Entry Point (DLLMAIN.C) ═══ 7.5.5.1. DLL Initialization Entry Point ═══ The DLLMAIN.C file (located in the \TOOLKIT\BETA\SAMPLES\DAPIE\DLLENTRY subdirectory) contains the DLL initialization/termination function, which is called when a process gains or loses access to the DLL. The .DEF file used to build the DLL needs to specify INITINSTANCE and TERMINSTANCE; otherwise, this function will only be called for the first process to gain access and the last process to free up the DLL. This implementation is for IBM C Set ++ and assumes that the C runtime library is being statically linked to the DLL and that the library uses C++ classes. ═══ 7.5.5.2. HiWorld ═══ HiWorld is a simple Windows 32-bit (Win32) application that displays the following text, centered in the client area of the main window: Hello, World There are two versions of the HiWorld sample. The Win32 version, located in the \TOOLKIT\BETA\SAMPLES\DAPIE\HIWORLD subdirectory, will build without source changes on a Win32 system with the appropriate development tools. (Win32 tools are not provided with the Warp Toolkit.) The OS/2 version of HiWorld is located in the \TOOLKIT\BETA\SAMPLES\DAPIE\HIWORLD2 subdirectory along with a README that briefly describes the steps that were taken to convert the Win32 version of HiWorld to this native OS/2 executable. ═══ 7.5.5.3. ToyBox ═══ ToyBox is a basic Win32 application that uses bit-block transfer (BitBlt) to display a large number of simple bit maps on the display screen and give them motion. It moves the objects around the client portion of the screen and makes the objects appear to change shape and rotate. There are two versions of the ToyBox sample. The Win32 version, located in the \TOOLKIT\BETA\SAMPLES\DAPIE\TOYBOX subdirectory, will build without source changes on a Win32 system with the appropriate development tools. (Win32 tools are not provided with the Warp Toolkit.) The OS/2 version of ToyBox is located in the \TOOLKIT\BETA\SAMPLES\DAPIE\TOYBOX2 subdirectory. ═══ 7.5.5.4. WinMain Wrapper Function ═══ The MAIN.C file (located in the \TOOLKIT\BETA\SAMPLES\DAPIE\WINMAIN subdirectory) is provided as a helper (stub) to demonstrate how to invoke the Windows WinMain function from OS/2. This is the "main" wrapper for an application based on the IBM Developer API Extensions for OS/2. It initializes the Alternative Windows Emulator (AWE) environment, calls the WinMain function, and upon completion, calls the WinTerm function to shut down the AWE environment. Note: To be able to use the Windows WinMain() function, use the OS/2 Warp main() function located in the MAIN.C file. MAIN.C gets compiled and linked with the module containing WinMain() and creates an OS/2 Warp executable. If you do not use the OS/2 Warp main() function, you will receive a link error stating that there is no starting address for your program. ═══ 7.5.6. IBM Developer API Extensions for OS/2 Documentation ═══ The IBM Developer API Extensions for OS/2 Programming Guide is a new online book included with this release of the Warp Toolkit. This book is located in the \TOOLKIT\BETA\BOOK subdirectory and provides information on the following topics:  What the IBM Developer API Extensions for OS/2 are and how they help you either: - Migrate Windows code to OS/2 code - Write common source code for OS/2 and Windows  How to use the SMART tool to analyze Windows code and see how much effort is involved to migrate it to OS/2 code.  Differences in behavior between some IBM Developer API Extensions for OS/2 functions and their Windows counterparts.  Changes to the Resource Compiler due to IBM Developer API Extensions for OS/2.  The functions supported by the IBM Developer API Extensions for OS/2. You can access this book from the Desktop by opening the Toolkit folder, then the BETA folder, and then the Beta Toolkit Information folder. ═══ 7.6. Try Me! ═══ The Try Me! component, formerly called NeatStuff, contains new tools and samples that execute on generally available versions of OS/2, such as OS/2 Warp Version 3. These tools and samples are provided to obtain feedback from you, our customers. We are considering adding these tools and samples to the Toolkit permanently. The content of this component can vary from volume to volume of The Developer Connection for OS/2. Try Me! is installed by default by the Developer's Toolkit for OS/2 installation program, but the component can be deselected prior to installing to save space on your hard disk. All files installed via the Try Me! component are installed in the \TOOLKIT\BETA directory structure by default. In this release of the Warp Toolkit, there are two new entries in the Try Me! component:  ALP - Assembly Language Processor  URE - Universal Resource Editor The P2String tool is also in the Try Me! component. Note: These utilities are pre-release and unsupported versions, and are provided on an "as is" basis for evaluation and demonstration. They are not intended for use with production code. IBM supports the version of Dialog Editor in this release of the Warp Toolkit, but will not be enhancing or otherwise changing Dialog Editor in future releases. URE (Universal Resource Editor) will become the editor of choice for creating and modifying dialogs and other resources. Take our Toolkit Survey and send it in! We are interested in your feedback! Please use any of the mechanisms listed below to give us your comments:  Internet tink@vnet.ibm.com  CompuServe 72410,624  Mail IBM Corporation Attn: Rick Timkovich Zip 1606 P.O. Box 1328 Boca Raton, FL 33429-1328 ═══ 7.6.1. Tools ═══ This section describes the new tools which help you develop OS/2 programs. There are three tools in this release:  ALP - Assembly Language Processor  P2STRING  URE - Universal Resource Editor ═══ 7.6.1.1. ALP ═══ ALP (Assembly Language Processor) is a macro assembler that runs under the 32-bit OS/2 operating system. In its initial form, ALP is designed as a functional replacement for the Microsoft Macro Assembler (MASM), Version 5.1. It accepts the full syntax of the Intel 80X86 architecture, and a subset of MASM's high-level directive language. ALP creates standard Object Module Format (.OMF) files that can be linked to produce DOS or OS/2 executables, and can generate line number debug information compatible with IBM's Presentation Manager Debugger. In addition, this tool offers a rich set of command line options, as well as a comprehensive listing file with user-tailored formatting, allowing a visual perspective not possible with other assemblers. ALP translates assembly language source files (typically having a filename extension of .ASM) into object (.OBJ) files. The LINK386 utility can then be used to combine multiple object files into a single executable file, dynamic link library, or device driver. While ALP is designed as a functional replacement for the Microsoft MASM assembler in terms of source code compatibility, it does not use the MASM command line syntax. ALP uses a free-form syntax, has a comprehensive set of options, and allows assembly of multiple input files with a single command line invocation. For each corresponding input source file, ALP can produce the following types of output files:  Object (.OBJ) files containing program data and executable code.  Listing (.LST) files which document the results of the assembly.  Message (.MSG) files which can contain all error, warning, and informational messages produced during the assembly. An online document, Assembly Language Processor Reference Guide, is available in the Beta Information folder. You can access this folder by opening the Toolkit folder and then opening the BETA folder. Online help is also available from the command line for all ALP options. ═══ 7.6.1.1.1. Starting ALP ═══ To start ALP from the command line, change to the TOOLKIT\BETA\BIN subdirectory and type: ALP Note: ALP cannot be started from the Desktop. ═══ 7.6.1.2. P2STRING ═══ P2STRING is used to test OS/2 multimedia subsystems through the media control interface string commands in OS/2 multimedia environment. This tool processes script files (containing string commands and tool directives) to test the behavior of subsystems in OS/2 multimedia. P2STRING extracts the strings from the script files and processes the commands through the mciSendString function. Messages and error conditions of the processes included in the scripts are logged to an output file and displayed in windows. P2STRING provides subsystem developers with an effective testing and because it alleviates the need for extensive test code to be written. Developers can write script files to test all relevant scenarios, and it also aids in debugging using log files. Note: Refer to the README file in the P2STRING subdirectory for information about how to use P2STRING and how to create script files that it can process. ═══ 7.6.1.3. URE ═══ URE (Universal Resource Editor) provides a graphical user interface by which you can design dialogs, menus, and other OS/2 program resources. You can create binary resource files, resource scripts, and symbol definition files. For any new resource design, URE allows you to:  Select the applicable operating environment, file names and formats from the New Design dialog.  Choose the type of presentation from the New Dialog/Window dialog.  Set the appearance of your window from the Window/Dialogue Styles dialog.  Select controls for your window from the Tools window.  Include multiple windows and file resources with any design.  Save your finished resource design to a binary file for later attachment to an executable program.  Edit an existing resource design and copy parts from one design to another. An online document, Universal Resource Editor for OS/2 User's Guide, is available in the TRYME folder. Online help is also available for menus, buttons, and dialogs you use while running URE and related samples. Note: URE will replace DLGEDIT (Dialog Editor) in a future release of the Warp Toolkit. ═══ 7.6.1.3.1. Starting URE ═══ You can start URE in two ways:  From the command line, change to the TOOLKIT\BETA\BIN subdirectory and type: URE URE has a number of sample programs that are installed into subdirectories below the TOOLKIT\BETA\SAMPLES\PM\URE subdirectory path.  From the Desktop, open the Toolkit folder and then: 1. Open the TRYME folder. 2. Double-click on Universal Resource Editor. ═══ 7.6.1.3.2. Replacing DLGEDIT ═══ IBM supports the version of DLGEDIT (Dialog Editor) in this release of the Warp Toolkit, but will not be enhancing or otherwise changing the Dialog Editor in future releases. URE (Universal Resource Editor) will become the editor of choice for creating and modifying dialogs and other resources. ═══ 7.6.2. Online Documentation ═══ This section describes the new online documentation (located in \TOOLKIT\BETA\BOOK) that might be of interest to users who develop applications for OS/2 Warp, Version 3. You can also access them through the TRYME folder, within the Toolkit folder. It also explains How to Use Online Documents. There are two new manuals in this release:  Assembly Language Processor Reference Guide  Universal Resource Editor User's Guide ═══ 7.6.2.1. Assembly Language Processor Reference Guide ═══ This book describes how to install and run the ALP assembler. It provides a complete description of the following:  Installation  Command line syntax  Environment variables  Assembler return codes  Message descriptions and recovery ═══ 7.6.2.2. Universal Resource Editor User's Guide ═══ This book provides information on the following URE features:  Using the tool bar, status window, and symbol definition window  Using all dialogs  Designing an application with URE  Adding backing code to a design  Running a prototype  Adding new elements to a process  Rebuilding an application  Using PM control extensions  Setting styles and CUA guidelines  Creating resource DLLs  Using accelerators in a resource design. ═══ 8. Programming Considerations ═══ Programming considerations apply for the following areas of the OS/2 Warp, Version 3 operating system:  Important Considerations  Kernel Debugger  Presentation Manager  SOM  VisualAge (C Set ++ Compiler)  Workplace Shell ═══ 8.1. Important Considerations ═══ Included in this section are important items that can affect your future development efforts when using the IBM Developer's Toolkit for OS/2 Warp, Version 3.  Compiling with IBM C/2  Compiling with VisualAge (C Set ++)  Known Limitations for DIVE  Known Limitations for MIDISAMP  Known Limitations for Warp Networking  Replacing DLGEDIT - Dialog Editor  Replacing IPFCBIDI - Bidirectional Information Presentation Facility Compiler ═══ 8.1.1. Compiling with IBM C/2 ═══ The Developer's Toolkit for OS/2 Warp, Version 3 is not intended to be used with the IBM C/2, Version 1.1 compiler. If you really want to use that compiler, you should use version 1.3 of the Toolkit. (An unsupported version of that Toolkit is available on The Developer Connection for OS/2 product.) The Warp Toolkit is intended to be used with the IBM C Set ++ compiler. You may be able to use the IBM C/2 compiler, but you will probably get some "unrecognized pragma" warnings during compilation. ═══ 8.1.2. Compiling with VisualAge (C Set ++) ═══ The next version of the C Set ++ compiler (now called VisualAge C++) has been released. VisualAge C++ is shipped with its own version of the Warp Toolkit which includes updated sample makefiles. Changes to the sample makefiles relate to the new linker (ILINK) and to the new library (CPPOM30.LIB). To compile any of the samples shipped with the IBM Developer's Toolkit for OS/2 Warp, Version 3 using ILINK, instead of LINK386, you need to do the following:  Replace LINK386.EXE with ILINK.EXE  Add the /nofree option to the ILINK.EXE step Note: This option must be the first one.  Insert spaces in between each ILINK flags. For example: LFLAGS = /MAP /CO /NOD Note: When using ILINK, the /batch switch is no longer supported and must be removed or linking will fail. There are several other link switches that have been dropped but they only cause link warnings. Only /batch causes linking to fail. If you have installed any of the samples shipped with the VisualAge product, you can compile those samples using LINK386 by changing any reference to CPPOM30.LIB to: DDE4MBS.LIB and changing any reference to ILINK to LINK386. Note that the /nofree option must be removed from the LINK386 statement. ═══ 8.1.3. Known Limitations for DIVE ═══ DIVE will not run in direct mode on some systems if the video card requires bank switching. To determine if your video card requires bank switching, select Query Caps from the Options menu of the DIVE sample. If the Screen access requires bank switch field is set to YES, setting a lower Desktop resolution in the System Setup may fix this. DIVE may not work on some systems when the Desktop is set to 16 million colors. If your system is set to 16 million colors and DIVE does not work properly, try setting the Desktop to fewer colors in the System Setup. ═══ 8.1.4. Known Limitations for MIDISAMP ═══ Currently, MIDISAMP might halt when another process attempts to play a sound (including system sounds) while the sample is running. Therefore, you should disable system sound before running MIDISAMP. To disable system sound, double-click on Sound located in the Multimedia folder and ensure Enable system sound is not selected. ═══ 8.1.5. Known Limitations for Warp Networking ═══ Currently, the receive function (WarpnetPackRecv) for Warp networking can only receive header information with no packet data. ═══ 8.1.6. Replacing DLGEDIT ═══ IBM supports the version of DLGEDIT (Dialog Editor) in this release of the Warp Toolkit, but will not be enhancing or otherwise changing the Dialog Editor in future releases. URE (Universal Resource Editor) will become the editor of choice for creating and modifying dialogs and other resources. ═══ 8.1.7. Replacing IPFCBIDI ═══ The Developer's Toolkit for OS/2 Warp on The Developer Connection for OS/2 includes two IPF compilers: IPFC.EXE and IPFCBIDI.EXE (the bidirectional version of IPFC.EXE). For this version of the Warp Toolkit, these programs are identical, as the bidirectional support has been integrated into the American version, IPFC.EXE. However, in the Warp Toolkit on the next release of The Developer Connection for OS/2, only IPFC.EXE will be included. Therefore, it will be necessary for you to modify any makefiles that reference IPFCBIDI.EXE to reference IPFC.EXE instead. ═══ 8.2. Kernel Debugger Considerations ═══ New kernel debug files are available. If you are installing the Warp Toolkit from The Developer's Connection for OS/2, you have two options:  Install the kernel debug files directly from the CD.  Create diskettes from which you can later install the kernel debug files. To install directly from the CD, choose the appropriate Kernel Debugger product in the Developer Connection for OS/2 Catalog and install it. This will run an installation program that installs the appropriate kernel debug files. To create kernel debug diskettes, choose the appropriate Kernel Debugger product in the Developer Connection for OS/2 Catalog and install it. This will bring up a utility that will create the kernel debug diskettes for you. Once you have created the diskettes, insert the first kernel debug diskette into a diskette drive, switch to that drive, and type INSTALL at an OS/2 command prompt. ═══ 8.3. Presentation Manager Considerations ═══ Making modifications to Microsoft Windows programs to enable dynamic data exchange (DDE) communications with PM programs helps facilitate a gradual migration of applications to PM. Not all data formats are automatically converted when using DDE between Windows programs and PM programs (DDE set public). The following formats are converted automatically by the OS/2 operating system: ┌──────────────────────┬──────────────────────┐ │ PM Application │ Windows Application │ │ Data Format │ Interpretation │ │══════════════════════│══════════════════════│ │ PM bit map │ Windows DIB │ │ PM private │ Windows private │ │ Text │ Text (codepage 819) │ │---------------------------------------------│ │ Windows Application │ PM Application │ │ Data Format │ Interpretation │ ├══════════════════════│══════════════════════┤ │ Text (codepage 819) │ Text │ │ Windows DIB │ PM Bit map │ │ Windows private │ PM Private │ └──────────────────────┴──────────────────────┘ Note: Code page translation (Windows 819 to/from current PM code page) is performed for topic name in all cases. When data conversion is not automatically performed, programs can still communicate using dynamic data exchange if the two programs are able to perform the data conversion and pass private data formats. ═══ 8.4. SOM Considerations ═══ This version of the Warp Toolkit contains a subset of the SOMobjects Developer's Toolkit. The following SOM programming considerations are briefly described:  Distributed SOM  SOM 1.0 OIDL  SOM Bindings  SOM Coding Styles  SOM Compiler  SOM DLLs ═══ 8.4.1. Distributed SOM (DSOM) ═══ New features, known limitations, and restrictions pertain to the Distributed SOM (DSOM). There are briefly described as follows:  DSOM now provides a PM version of the REGIMPL tool for registering servers in the implementation repository. It is called PREGIMPL and is similar in functionality to REGIMPL. To invoke the tool, type PREGIMPL on a command line. Remember to select File Save before exiting to commit any changes made.  You are now able to control the number of request threads created per server. The environment variable SOMDNUMTHREADS is used to indicate the maximum size of the thread pool. If this environment variable is not set, a separate thread will be created for each request.  The OUT_LIST_MEMORY, IN_COPY_VALUE, and DEPENDENT_LIST flags, used with the dynamic invocation interface, are not supported.  Concurrent updates to the implementation repository are currently not properly serialized, and can conflict.  The is_nil method of SOMDObject has been changed from a true method to a procedure, so that is_nil can be safely invoked on a NULL object pointer. As a result, the syntax for invoking is_nil from C++ client programs has changed. The new syntax is: obj->is_nil(obj,env); Rather than: obj->is_nil(env); where: obj Is an object pointer of type SOMDObject. env Is of type Environment. ═══ 8.4.2. SOM 1.0 OIDL Users ═══ If you need to recompile an OIDL class that overrides somDumpSelf or somDumpSelfInt, you will need to change the data type of the level parameter in the function definition in your C source program from INT to LONG. For example, if your original class source program had a somDumpSelfInt override procedure similar to: SOM_Scope void SOMLINK somDumpSelfInt( *somSelf, INT level) { ... } Change it to read: SOM_Scope void SOMLINK somDumpSelfInt( *somSelf, LONG level) { ... } Because both INT and LONG data types require 4 bytes on OS/2, this does not affect the binary interface of your class. ═══ 8.4.3. SOM Bindings ═══ The XH and H files shipped with this Warp Toolkit will only work with the IDL files shipped with this Toolkit. You will need to generate new SOM bindings if you install a new version of SOM. This means that the XH and H files will need to be re-emitted if new versions of the IDL files are made available. There are two steps that you will need to take. If you install version 'Y' of SOM on top of version 'X', you will need to generate SOM bindings for version 'Y'. The version 'X' SOM bindings are not guaranteed to be compatible with version 'Y'.  Use the SOMSTARS.CMD file to generate the SOMSTARS version of the bindings.  Use SOMCORBA.CMD to generate the SOMCORBA version of the bindings. This will upgrade your SOM bindings. The command file WPIDL2XH.CMD is provided to upgrade Workplace Shell bindings, for developers that upgrade their SOMobjects Toolkit in the future. This command file emits the .XH header files from the Workplace Shell .IDL files. The file should be invoked upon each of the .IDL files from the Warp Toolkit to regenerate the headers for C++. This is only necessary when you upgrade to a new level of the SOMobjects Toolkit. Invoking the SOM compiler's .XH emitter on the Workplace Shell .IDL will not emit .XH files for you, because the Workplace Shell classes currently only maintain passthru sections for .H files for C. ═══ 8.4.4. SOM Coding Styles ═══ There are two possible forms of C bindings for SOM programming: SOMCORBA The strict CORBA-compliant form in which pointer references ('*'s) are NOT exposed in object references. SOMSTARS The OIDL-compatible C++ form in which pointer references ('*'s) are visible in object references. The SOMSTARS form is more appropriate if you plan to move your class implementations from C to C++ at some future point. This choice will determine how object references will appear in all of your C programs. For example, to declare a reference to an instance of class Foo, you would code either: Foo afoo; /* Strict CORBA compliant form */ OR Foo *afoo; /* C++ migration or OIDL-compatible form */ If you later decide to switch from one SOM coding style to the other, you will have to convert any C code that you have already written in one style to the other style. The Workplace Shell uses the SOMSTARS version of the SOM header files. Therefore, the Warp Toolkit installs the SOMSTARS version of the header files. The Workplace Shell interface definition language (IDL) files (WP*.IDL) are the counterparts for the documented Workplace Shell classes' SC files provided with the OS/2 2.1 Toolkit. The WP*.H and WP*.XH files emitted from the Workplace Shell's IDL files by the SOM compiler are also provided. The OS/2 makefiles for the Workplace Shell Warp Toolkit samples are written assuming the SOMSTARS style of coding. If you have the SOMobjects Toolkit, the C samples provided with the SOMobjects Toolkit use the SOMCORBA style of coding (these samples are not part of the IBM Developer's Toolkit for OS/2). ═══ 8.4.5. SOM Compiler ═══ New features, known limitations, and restrictions pertain to the SOM compiler. There are briefly described as follows:  Mutually recursive IDL struct and union are not currently supported. The following is an example of unsupported mutual recursion: struct X; struct Y { sequence indirectSelf; }; struct X { sequence indirectSelf; };  The C bindings do not permit the use of multiple methods with the same name that also take an argument of data type VA_LIST within the same module. For example, the following legal IDL will result in incorrect C usage bindings: module X { interface Y { void Foo (in LONG f, in VA_LIST ap); }; interface Z { void Foo (in LONG f, in VA_LIST ap); }; };  The SOM C++ language bindings are built assuming use of the OS/2 C Set ++ compiler, but other C++ compilers should be able to use these bindings as well. For example, to use BCOS2 (the Borland C++ compiler for OS/2), use -DSOMLINK=_syscall on the compile line, and make sure that SOMobjects' include directory is consulted before BCOS2/include (because BCOS2/include contains older SOM.H include files).  If the SOM compiler is interrupted by the user (using Ctrl+C, for example), it sometimes leaves a temporary file with a .CTN extension in the temporary directory specified by the SMTMP environmental variable. These should be removed periodically.  When direct references to SOMFOREIGN types are made in an IDL struct or union, the C or C++ language bindings are generated incorrectly. To refer to a SOMFOREIGN type (for example, "somId") in a struct or union it is necessary to supply a secondary typedef for "somId". For example: #include struct S1 { somId badId; /* Generates incorrect */ }; /* C/C++ bindings */ #include typedef somId somId2; struct S1 { somId2 badId; /* OK */ }; ═══ 8.4.6. SOM Dynamic Link Libraries (DLLs) ═══ When SOMobjects 2.0 (NOT the version shipped with this Warp Toolkit) is installed on OS/2 Warp, Version 3, the LIBPATH, PATH, and DPATH environment variables in CONFIG.SYS are changed to place the SOMobjects directories before the operating system directories in the search order for DLLs, EXEs, and data files. This will cause the Workplace Shell to encounter an unrecoverable error the next time the system is restarted because it requires the SOM DLLs that are contained in the \OS2\DLL subdirectory. In order to allow SOMobjects 2.0 Workstation applications to run successfully, you must edit CONFIG.SYS and change the LIBPATH, PATH, and DPATH statements before restarting the system. These statements must be changed to place the operating system directories before the SOMobjects directories. Note: This only applies to SOMobjects Workstation applications, not Workgroup applications. The same problem will occur for any application that ships SOMobjects 2.0 DLLs if the application places its DLL directory first in the LIBPATH. Once again, the workaround is to assure that the \OS2\DLL subdirectory is before any other directory that contains earlier versions of the SOM DLLs. Any changes made to the PATH and DPATH environment variables by the application installation must also be reversed. ═══ 8.5. Workplace Shell Considerations ═══ When including an OBJECTID=<....> keyname=value pair in a setup string, you must specify it at the end of the setup string. ═══ 9. System Debug Support ═══ This section introduces you to the interface that installs the debug kernel, symbol files, and debug version of the PM. It also describes tools that support your debugging efforts. The tools are categorized as follows:  Communications  The Debug Files  Installing the Debug Installation Program  MAPSYM  T (Terminal Emulator) Additional details on the debug kernel can be found in the online Kernel Debug Reference in the Toolkit Information folder. ═══ 9.1. Communications ═══ Local and remote debugging are the same, except for the location of the system to be debugged (also known as the system under test). If the system to be debugged is close to the debug terminal, use a null modem cable to connect them. If the system is physically distant, use modems. The default setup for the communication port of the debug kernel is: Baud rate 9600 Parity none Data bits 8 Stop bits 1 ═══ 9.2. The Debug Files ═══ The files described in this section are referred to as either a retail or debug version. "Retail" refers to the files that came with your OS/2 operating system; "debug" refers to the files that are part of the Kernel Debugger product. Several versions of the Kernel Debugger product are available on The Developer Connection for OS/2. Look for the following in the Developer Connection for OS/2 Catalog under the Developer Toolkits category: Kernel Debugger for OS/2 2.x and Warp (IBM): CD Install Kernel Debugger for OS/2 for SMP v2.11 (IBM): CD Install Kernel Debugger for OS/2 for SMP v2.11 (IBM): Diskettes Kernel Debugger for OS/2 Japan 2.1 CSD BJC006 (IBM): CD Install Kernel Debugger for OS/2 Japan 2.11 (IBM): CD Install Kernel Debugger for OS/2 ServicePak XR06300 v2.1 (IBM): CD Install Kernel Debugger for OS/2 2.11 (IBM): Diskettes Kernel Debugger for OS/2 Warp with WIN-OS2 (IBM): Diskettes Kernel Debugger for OS/2 Warp, Version 3 (IBM): Diskettes ═══ 9.2.1. Debug Kernel ═══ The debug kernel, a special version of the OS/2 kernel, makes it possible to set breakpoints and trace programs. It also permits the use of symbolic addresses. You can interact with the debug kernel by using a modem or null modem and a second asynchronous debug terminal. Note: You can only use the debug kernel files with the version of the OS/2 operating system with which they are associated. ═══ 9.2.2. Debug Presentation Manager Interface ═══ The debug PM interface is a special version of the PM DLLs. The debugger detects errors in your PM application and issues messages to the terminal. This interface is not required to run the debug kernel. ═══ 9.3. Installing the Debug Installation Program ═══ The menu-based debug installation program installs debug replacement files for the kernel and the PM interface. Once the program is installed, you can install other debug files, or restore retail files, from an OS/2 command prompt. During initial installation, two files are copied to the root directory of your specified installation drive: DBINST.CMD A command file that can be executed separately. This file calls DBUGINST.EXE with the requested installation drive as a command-line argument. DBUGINST.EXE This executable file is the user interface. The user can choose which parts of the debug system to install, or which parts to restore to the retail version. ═══ 9.3.1. Selecting Installation Options ═══ The user interface consists of a menu that provides installation choices in three optional parts. It also provides the ability to restore two of those parts to their corresponding retail versions. The following is an illustration of the screen that appears: When prompted to enter a debug installation option, choose the options in the order they appear on the screen. Review Editing the CONFIG.SYS File after your selections are complete. ═══ 9.3.2. Editing the CONFIG.SYS File ═══ When you complete the debug installation procedure, you may need to edit your CONFIG.SYS file. The following paragraphs explain: For the Debug Kernel: If you installed only the debug kernel, shutdown and restart your system. Restoring the Kernel: To restore the retail kernel, run the debug installation program and select the Restore retail kernel option. For the Debug Presentation Manager Interface: If you have installed the debug version of the PM interface, modify the DEVICE statement with the PMDD.SYS line as follows: DEVICE=C:\OS2\DEBUG\DLL\PMDD.SYS /Cn The DEVICE statement includes the C drive as the installation drive and allows you to call the debug version of PMDD.SYS from the OS2\DEBUG\DLL subdirectory. The /C switch is set with n as the communication port for the debug output. Modify the LIBPATH statement by adding the DEBUG\DLL subdirectory as follows: LIBPATH=C:\OS2\DEBUG\DLL; ... Shut down and restart your system to have the changes take effect. Restoring the Presentation Manager Interface: To restore the retail PM, do the following: 1. Restore the device statement: DEVICE=C:\OS2\PMDD.SYS 2. Modify the LIBPATH statement by removing the DEBUG\DLL subdirectory. 3. Shut down and restart your system to have the changes take effect. ═══ 9.4. MAPSYM ═══ MAPSYM is used to generate binary files that the debug kernel uses to associate a symbolic name with an address in memory. ═══ 9.4.1. Starting MAPSYM ═══ MAPSYM creates public symbol (.SYM) files from map (.MAP) files. You must start MAPSYM from the directory in which the map file is located. An example of the syntax follows: MAPSYM filename [options] where: filename Is the name of the map file. You do not have to type the .MAP file-name extension. options Is the name of the MAPSYM option that modifies the action of MAPSYM. Note: Be sure the .SYM files are in the same subdirectory as their corresponding DLLs. ═══ 9.5. T (Terminal Emulator) ═══ T is a terminal emulator and is used by the debug kernel to communicate with the system to be debugged. You can use any ASCII terminal emulator; the Warp Toolkit provides T. A terminal emulator allows a device, such as a personal computer, to enter and receive data from a computer system as if it were a particular type of attached terminal. For example, you use T to send and receive ASCII files. Hardware Requirements: Make sure your system has a properly installed asynchronous-port and communication-port driver, and that your CONFIG.SYS file has the following line: DEVICE=C:\OS2\COM.SYS ═══ 9.5.1. Starting T ═══ You can start T at the command line by typing its executable name: T A blank screen appears. Press F1; a menu appears that allows you to:  Display function-key assignments  Set up communication-port parameters  Set the file name and start sending  View the text that has scrolled off the screen  Send the text that was written to a screen, to a file (capture mode)  Toggle to the capture mode  Set the file name or delete the current capture file  Exit from the terminal program. Note: Capture mode can be started automatically when T is executed by placing the line: Capture=yes in the initialization file. ═══ 10. Toolkit Support ═══ To ensure your success with the IBM Developer's Toolkit for OS/2 Warp, Version 3, IBM offers you not only excellent online and printed documentation but also a "Getting Started" period. What kind of support can I expect? The IBM Developer's Toolkit for OS/2 Warp, Version 3 Technical Support Team can assist you with the following kind of activities during a 60-day period that we call your "Getting Started" period:  Installing and using the IBM Developer's Toolkit for OS/2 Warp, Version 3  Reporting suspected system defects as a result of applying the IBM Developer's Toolkit for OS/2 Warp, Version 3. When should I call? As a first step, use the online or hardcopy guide and reference manuals. If you still need assistance several options are available to you:  CompuServe: The dedicated Developer Connection section is located in the IBM OS/2 Developer Forum 2. To obtain access to this section, please send a note with your order number to the Developer Connection Administrator at CompuServe user id 73423,2767. To access the forum: 1. Type GO OS2DF2 at the ! prompt 2. Select the Developer Connection section  Internet: Send questions or comments to devcon@vnet.ibm.com.  OS/2 BBS: The DEVCON CFORUM or OS2TLKIT CFORUM, under TalkLink, is a feature under the IBMLink Commercial Services.  If you do not have access to either CompuServe, Internet, or OS/2 BBS, then call us Monday through Friday between 8:00 a.m. and 5:00 p.m. your time, excluding U.S. national holidays. Here's how: - Locate your registration number for service entitlement on your Customer Service and Support brochure. - Dial 1-800-992-4777. You will be presented with pre-recorded help options. Request to speak to a service representative who will make a note of your needs and dispatch them to a technical support person. Your call will be returned before the end of the next business day. Your 60 days of "Getting Started" support begins with this call. Note: If you have a specific question regarding the Beta version entertainment components, you can call 1-800-553-1623 for technical support. ═══ 11. Hardcopy Documentation ═══ The following list describes books available in hardcopy that might be of interest to users who develop applications for OS/2 Warp, Version 3. The OS/2 Warp, Version 3 Technical Library provides both guidance and reference information and can be used for OS/2 Warp, Version 3 development. The library includes the following printed books:  Control Program Programming Guide  Control Program Programming Reference  Graphics Programming Interface Programming Guide  Graphics Programming Interface Programming Reference  Information Presentation Facility Programming Guide and Reference  Multimedia Application Programming Guide  Multimedia Programming Reference  Multimedia Subsystem Programming Guide  Presentation Manager Programming Guide - The Basics  Presentation Manager Programming Guide - Advanced Topics  Presentation Manager Programming Reference  REXX User's Guide  REXX Reference  Tools Reference  Workplace Shell Programming Guide  Workplace Shell Programming Reference Programming guide information is organized by topic and contains everything an application developer needs--function details, data structures, and message descriptions--to design, write, and build function into an OS/2 application. Programming reference information provides detailed descriptions of the application programming interface (API) and contains remarks and examples to assist application developers in implementing each function. Application developers can choose to order the complete set of books, or order individual books separately. The information available in hardcopy is basically the same as the information in the online books contained in this Warp Toolkit. ═══ 11.1. OS/2 Technical Library Publications ═══ The following figure presents you each book of the OS/2, Version 3 Technical Library with its associated part number. To order the full set use part number G25H-7116. ═══ 11.2. Control Program Programming Guide ═══ This book describes the components of the OS/2 Control Program--file systems, interprocess communication, program execution and control, memory management, exception and error management, device I/O--and how to create an OS/2 application using Dosxxx functions. A hardcopy version of this book is available separately with order part number G25H-7101. ═══ 11.3. Control Program Programming Reference ═══ This book provides the detailed descriptions for the Dosxxx functions of the OS/2 Control Program. A hardcopy version of this book is available separately with order part number G25H-7102. ═══ 11.4. Graphics Programming Interface Programming Guide ═══ This book describes the concepts associated with graphical output--presentation spaces, device contexts, graphic primitives, fonts--and how to prepare graphical output for display and printing, using Gpixxx functions. A hardcopy version of this book is available separately with order part number G25H-7106. ═══ 11.5. Graphics Programming Interface Programming Reference ═══ This book provides the detailed descriptions for the Gpixxx functions of the Graphics Programming Interface. A hardcopy version of this book is available separately with order part number G25H-7107. ═══ 11.6. Information Presentation Facility Programming Guide and Reference ═══ This book describes the concepts--help windows, hypertext linking, author-controlled viewports, dynamic data formatting--and the functions used for implementing help in OS/2 applications. It describes how to create online help and information. It also contains an alphabetic list of IPF tags, symbols, and control words. The IPFC error messages, window functions, dynamic data formatting functions, and help manager messages and functions are included. A hardcopy version of this book is available separately with order part number G25H-7110. ═══ 11.7. Multimedia Application Programming Guide ═══ This book describes the concepts associated with managing audio and video data and hardware using an extendable architecture that includes logical media devices (amplifier-mixer, waveform audio, MIDI sequencer, CD-audio, CD-XA, digital video, and videodisc) and I/O procedures for supporting various file formats. A hardcopy version of this book is available separately with order part number G25H-7112. ═══ 11.8. Multimedia Programming Reference ═══ This book describes the media control interface, PM graphic push buttons, secondary windows functions, multimedia I/O services, and subsystem services for synchronization and streaming. A hardcopy version of this book is available separately with order part number G25H-7114. ═══ 11.9. Multimedia Subsystem Programming Guide ═══ This book describes the subsystem components--media control driver, stream handler, and I/O procedure--that support a multimedia device. A hardcopy version of this book is available separately with order part number G25H-7113. ═══ 11.10. Presentation Manager Programming Guide - Advanced Topics ═══ This book describes the advanced features of a sophisticated OS/2 window application--font and file dialogs, containers, notebooks, hooks, dynamic data exchange, direct manipulation--and how to implement them, using Winxxx and other PM functions. A hardcopy version of this book is available separately with order part number G25H-7104. ═══ 11.11. Presentation Manager Programming Guide - The Basics ═══ This book describes the components of a basic OS/2 window application--windows and message queues, window controls such as scroll bars, title bars, and menus--and how to create them using Winxxx functions. A hardcopy version of this book is available separately with order part number G25H-7103. ═══ 11.12. Presentation Manager Programming Reference ═══ This book provides the detailed descriptions for Winxxx and other functions of the OS/2 PM. A hardcopy version of this book is available separately with order part number G25H-7105. ═══ 11.13. REXX Reference ═══ This book provides detailed descriptions of the REXX functions. A hardcopy version of this book is available separately with order part number S10G-6268. ═══ 11.14. REXX User's Guide ═══ This book describes the REXX programming language and provides examples for writing programs using REXX. A hardcopy version of this book is available separately with order part number S10G-6269. ═══ 11.15. Tools Reference ═══ This book describes the tools that are included in the IBM Developer's Toolkit for OS/2 Warp, Version 3. A hardcopy version of this book is available separately with order part number G25H-7111. ═══ 11.16. Workplace Shell Programming Guide ═══ This book describes the concepts associated with object-oriented programming for the OS/2 operating system--System Object Model (SOM), Workplace Shell classes and methods--and how to create object-oriented applications for the OS/2 Desktop. A hardcopy version of this book is available separately with order part number G25H-7108. ═══ 11.17. Workplace Shell Programming Reference ═══ This book provides the detailed descriptions of the Workplace Shell object-oriented programming interface. A hardcopy version of this book is available separately with order part number G25H-7109. ═══ 12. Hyperwise ═══ IBM has announced Hyperwise Version 2.0. Hyperwise is a WYSIWYG editor for development of OS/2 and Windows application helps and online books. Its drag and drop methods are far superior to the old tagging methods. Hyperwise Version 2.0 runs on OS/2 Warp and incorporates audio, video, graphics and animation files into its helps and books. The new features for version 2.0 are as follows:  Enhanced search  Enhanced performance and usability  HTML Export  RTF Import  Spellcheck  Tutor/2 (an interactive tutorial manager). To obtain the latest pricing information or to order Hyperwise Version 2.0, contact your IBM Authorized Remarketer, or IBM marketing representative. Upgrade paths from Hyperwise Version 1.0 are also available from some participating IBM Authorized Remarketers. Hyperwise Version 2.0 Product Order Number 30H1731 Phone Number 1-800-3IBMOS2 (1-800-342-6672) or Indelible Blue at 1-800-776-8284 ═══ 13. Ordering Information ═══ You can order the following:  Hardcopy documentation  The Developer Connection for OS/2 ═══ 13.1. Hardcopy Documentation ═══ The hardcopy books can be ordered weekdays between 8 a.m. and 8 p.m. (Eastern time). For Canada and the United States, the following telephone or fax numbers can be used for placing orders: Country Telephone Number Canada 1-800-465-4234 United States 1-800-IBM-PCTB (1-800-426-7282) For Asia/Pacific, Brazil, Europe, Japan, and Mexico mail your order to the following address: IBM Software Manufacturing Solutions (ISMS) Attn: Direct Services Sortemosevey 21 DK-3450 Alleroed Denmark When placing an order, please provide the part number (for books), quantity, and your credit card information ready. Charge your order to one of the following credit cards:  American Express  Diners Club  Discover  MasterCard  VISA Please allow one to two weeks for delivery of telephone orders. ═══ 13.2. The Developer Connection for OS/2 ═══ The following telephone or fax numbers can be used for placing orders. When placing an order, please have your credit card information ready. Charge your order to one of the following credit cards:  American Express  Diners Club  Discover  MasterCard  VISA Please allow one to two weeks for delivery of telephone orders. For more information double-click mouse button 2 anywhere on the map. ═══ 14. Toolkit Survey ═══ ═══ 15. Notices ═══ Second Edition (August 1995) The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country. Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative. ═══ 15.1. Copyright Notices ═══ (C)Copyright International Business Machines Corporation 1995. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. ═══ 15.2. Disclaimers ═══ References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 10594, U.S.A. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department RM1A, 1000 N.W. 51st Street, Boca Raton, FL 33431, U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. ═══ 15.3. Trademarks ═══ The following terms are trademarks of the IBM Corporation in the United States or other countries or both: AVC OS/2 C/2 Presentation Manager Common User Access SOMobjects C Set ++ Ultimotion CUA VisualAge Hyperwise WIN-OS2 IBM Workplace Shell The following terms are trademarks of other companies: Trademark Owner American Express American Express Incorporated Borland C++ Borland International, Inc. BRender Argonaut Technologies Limited C++ American Telephone and Telegraph Company CompuServe CompuServe Incorporated Diners Club Diners Club of America Discover Sears, Roebuck and Co. MASM Microsoft Corporation MasterCard MasterCard International, Incorporated Microsoft Microsoft Corporation VISA VISA International Services Association Win32 Microsoft Corporation Windows Microsoft Corporation WinTV Hauppauge Computer Works, Inc. Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others. ═══ Ordering Information - Supplement ═══ When calling from the following countries: The Developer Connection for OS/2 can be ordered from the following countries. For Asia/Pacific, please ensure that you dial the international access code applicable to your country before the listed phone number. Note that 61 is the country code for Australia. Country Telephone Number Asia/Pacific 61 2 3547684 Fax 61 2 3547766 Canada 1-800-561-5293 (Toll free) Germany 0 130 812177 (Toll free) United States 1-800-6DEVCON (Toll free: 1-800-633-8266) Fax 1-303-330-7655 In Central and South America: Country Telephone Number Argentina 01-313-0014 Bolivia 02-351840 Brazil 0800-111205 (Toll free) Fax 011-886-3222 Chile 02-633-4400 Colombia 01-257-0111 Costa Rica 223-6222 Dominican Republic 566-5161 Ecuador 02-565100 El Salvador 02-985011 Guatemala 02-315859 Honduras 32-2319 Mexico 91-800-00316 (Toll free) Mexico City (525) 627-1111 Panama 02-639977 Paraguay 021-444094 Peru 014-366345 Uruguay 02-923617 Venezuela 02-908-8901 In Europe: The Developer Connection for OS/2 can be ordered direct from IBM SPC in Denmark (45 is the country code) if you are calling outside the countries listed above. Please ensure that you dial the international access code applicable to your country before dialing the appropriate phone number. This applies to both telephone and fax orders. Operators speaking the following languages are available: Language Telephone Spoken Number Danish 45 4 8101300 Dutch 45 4 8101400 English 45 4 8101500 Finnish 45 4 8101650 French 45 4 8101200 German 45 4 8101000 Italian 45 4 8101600 Norwegian 45 4 8101250 Spanish 45 4 8101100 Swedish 45 4 8101150 Fax 45 4 8142207 ═══ \TOOLKIT\BETA Subdirectories ═══ BETA - Beta versions of new tools, │ samples, and online books ├─\BIN - Beta versions of new tools ├─\BOOK - Beta versions of new online books ├─\BRENDER - BRender samples and tools │ └─\SAMPLES - BRender samples │ └─\ROBOT - Robot Walking sample └─\SAMPLES - Beta versions of new samples ├─\DAPIE - IBM Developer API Extensions for OS/2 samples │ ├─\DLLENTRY - DLL initialization entry point │ ├─\HIWORLD - HiWorld sample (Windows version) │ ├─\HIWORLD2 - HiWorld sample (OS/2 version) │ ├─\TOYBOX - Bitmap Manipulation Sample (Windows version) │ ├─\TOYBOX2 - Bitmap Manipulation Sample (OS/2 version) │ └─\WINMAIN - WinMain wrapper function └─\ENTOOLKT - Entertainment samples ├─\AUDIO - Audio samples │ ├─\DAUDIO - Direct Audio sample │ └─\MIDI - Real Time MIDI sample ├─\INPUT - Input Device sample │ └─\JOYSTICK - Joystick sample ├─\NETWORK - Networking sample │ └─\TICTAC - TicTacToe sample └─\VIDEO - Video sample └─\FSDIVE - Full-Screen DIVE sample ═══ \TOOLKIT\SOM Subdirectories ═══ SOM - SOM subdirectories │ ├─\BIN - SOM executable (.EXE) files ├─\COMMON - SOM common-file subdirectories, │ │ which contains the runtime files │ ├─\DLL common with OS/2 Warp, Version 3 │ ├─\ETC │ ├─\INSTALL │ └─\SYSTEM ├─\INCLUDE - SOM .IDL, .SC, .H, .XH, .HC, .HS, │ and .EFW header files ├─\LIB - SOM library (.LIB & .DLL) files └─\MSG - SOM message (.MSG) file ═══ \TOOLKIT\SAMPLES Subdirectories ═══ SAMPLES - Contains common information for all │ samples, as well as SAMPLES.DOC │ ├─\BIDI - Contains the bidirectional (BIDI) samples ├─\MM - Contains the Multimedia samples ├─\OS2 - Contains the Control Program samples ├─\PM - Contains the Presentation Manager samples ├─\REXX - Contains common information for the │ C-language REXX samples └─\WPS - Contains the Workplace Shell samples ═══ \SAMPLES ═══ SAMPLES │ │ ├─\BIDI ├─\MM ├─\OS2 ├─\PM ├─\REXX └─\WPS ═══ \TOOLKIT\SAMPLES\BIDI Subdirectories ═══ BIDI - Contains the bidirectional (BIDI) samples ├─\ARABIC - Contains the Arabic-specific BIDI samples │ ├─\STYLE - Arabic Style sample │ └─\TELDIR - Arabic Telephone Directory sample └─\HEBREW - Contains the Hebrew-specific BIDI samples ├─\STYLE - Hebrew Style sample └─\TELDIR - Hebrew Telephone directory sample ═══ \TOOLKIT\SAMPLES\MM Subdirectories ═══ MM - Contains the Multimedia samples,templates, │ and command tables. ├─\ADMCT - Waveform Audio Media Control Driver sample ├─\ASYMREC - Asymmetric Recording sample ├─\AVCINST - AVC I/O Procedure Installation sample ├─\CAPDLL - Caption sample support files (DLL) ├─\CAPSAMP - Caption sample ├─\CAPTION - Caption Creation Utility program ├─\CASECONV - Case Converter I/O procedure sample ├─\CDMCIDRV - CD Audio Media Control Driver sample ├─\CF - Control File templates ├─\CLOCK - Memory Playlist sample ├─\CODEC - Compressor/Decompressor sample ├─\DIVE - Direct Interface Video Extensions sample ├─\DOUBPLAY - Double Buffering Playlist sample ├─\DUET1 - Streaming Device Duet sample ├─\DUET2 - Streaming and Non-Streaming Device Duet sample ├─\FSSHT - File System Stream Handler sample ├─\MCDTBL - Media Control Driver (MCD) command tables ├─\MCDTEMP - Media Control Driver (MCD) template ├─\MCISPY - Message Monitoring sample ├─\MCISTRNG - Media Control Interface String Test sample ├─\MMBROWSE - Image Browser sample ├─\MMIOPROC - M-Motion I/O procedure sample ├─\MOVIE - Movie sample ├─\RECORDER - Audio Recording sample ├─\SHORTCF - Control File templates (subset of the \CF directory) ├─\SHRCFILE - Stream Handler Resource File sample ├─\TUNER - TV Tuner sample ├─\ULTIEYES - Non-Linear Video sample └─\ULTIMOIO - Ultimotion I/O procedure sample ═══ \TOOLKIT\SAMPLES\OS2 Subdirectories ═══ OS2 - Contains the Control Program samples ├─\CONSOLIO - Console I/O sample (Worms) ├─\DLLAPI - Dynamic Link Library sample ├─\EAEDIT - Extended Attributes Editor sample (EAS) ├─\HANOI - Multithreaded sample (Towers of Hanoi) ├─\NPIPE - Named Pipes sample ├─\QUEUES - Interprocess Communication Queue sample ├─\SEMAPH - Semaphore sample ├─\SORT - Multithreaded sample (Sorting Algorithm) ├─\TIMESERV - Timer Services sample (Clock) └─\VMM - Virtual Memory Management sample ═══ \TOOLKIT\SAMPLES\PM Subdirectories ═══ PM - Contains the Presentation Manager samples ├─\BMPSAMP - Bit map Manipulation sample (Jigsaw) ├─\CLIPBRD - Clipboard sample ├─\CONTROLS - PM Controls sample (Style) ├─\DIALOG - Introductory Dialog Box sample ├─\DRAGDROP - Direct Manipulation (Dragdrop) sample ├─\GRAPHIC - Non-retained Graphic sample ├─\IPF - Information Presentation Facility sample ├─\PALETTE - Palette Manager sample ├─\PORTING - PM 16-bit to 32-bit Porting sample (Image32) ├─\PRINT - Printer sample ├─\STDWND - Standard Window sample (Hello) └─\TEMPLATE - Application Template sample ═══ \TOOLKIT\SAMPLES\REXX Subdirectories ═══ REXX - Contains common information for the │ C-language REXX samples └─\API - Contains the API 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 ═══ \TOOLKIT\SAMPLES\WPS Subdirectories ═══ WPS - Contains the Workplace Shell samples ├─\BROWSE - ASCII/Hex File Browser sample ├─\CAR - WPDataFile Subclass (C) sample ├─\CARPP - WPDataFile Subclass (C++) sample ├─\TEXTFLDR - Text Folder sample ├─\WPSTUTOR - Tutorial sample └─\WSFILE - Workplace File object sample