IBM CD Showcase

home *** CD-ROM | disk | FTP | other *** search

/ IBM CD Showcase / OS2_CD_ROM.iso / smce0001 / cfirst11 / os2tk11 / read.me < prev next >

Wrap

Text File | 1993-05-06 | 37.0 KB | 1,165 lines

Welcome to the IBM Developer's Toolkit for OS/2 2.1. This information has been prepared to assist you in your application development activities. The following major topics are discussed in this README: - ADDITIONAL DEVELOPER INFORMATION - IBM DEVICE DRIVER SOURCE KIT FOR OS/2 - VIRTUAL DEVICE DRIVER INFORMATION - USING SOM AND C++ TO CREATE WORKPLACE OBJECTS - METHOD MACROS - WP CAR SAMPLE - ONLINE IPF REFERENCE - OS/2 ENHANCED EDITOR (EPM) - TK21DESK.CMD - OS2DEF.H HEADER INFORMATION - BIDIRECTIONAL NATIONAL LANGUAGE SUPPORT - DEVICE DRIVER PROGRAMMING INTERFACES - DOS PROGRAMMING INTERFACE - WIN PROGRAMMING INTERFACE - DDE BETWEEN PM AND WINDOWS PROGRAMS - PM REFERENCE UPDATES - PROGRAMMING CONSIDERATIONS - NEW FUNCTIONS FOR THE OS/2 2.1 CONTAINER CONTROL - ADDENDUM TO PROGRAMMING GUIDE VOL. II, CHAPTER 33 (p. 22) - PMWIN LOCKUP API'S AND HK_LOCKUP HOOK - PROGRAMMING GUIDE VOLUME III - DOSSHUTDOWN API - DEVICE DRIVER INITIALIZATION - NEW BIT ADDED TO CAPABILITIES BIT STRIP - CHANGE TO DEVICE ATTRIBUTE FIELD - NEW HOOKS FOR VDHINSTALLUSERHOOK VIRTUAL DEVICE HELPER FUNCTION - ADDITION TO VMALLOC DEVHLP FUNCTION - DLL INITIALIZATION AND TERMINATION - CHANGES AND CLARIFICATIONS - NOTICES ADDITIONAL DEVELOPER INFORMATION ________________________________ IBM* participates in CompuServe forums. If you are logged onto CompuServe, simply type "GO IBMOS2" at the ! prompt and you will be provided with a menu of the available OS/2* forums. IBM DEVICE DRIVER SOURCE KIT FOR OS/2 _____________________________________ The following publications are available for additional device driver development references. They can be purchased separately at an additional charge through your IBM dealer, or call 1-800-267-2338 (US only) for information. Pub Title Part Num Form Num --------- -------- -------- Printer Device Driver Reference 71G1895 S71G-1895-00 Display Device Driver Reference 71G1896 S71G-1896-00 Storage Device Driver Reference 71G1897 S71G-1897-00 Input/Output Device Driver Reference 71G1898 S71G-1898-00 PenPM Device Driver Reference 71G1899 S71G-1899-00 MMPM/2 Device Driver Reference 71G3678 S71G-3678-00 VIRTUAL DEVICE DRIVER INFORMATION _________________________________ The VDD sample is now written in C language and can be built using the IBM C/C ++ compiler. This Virtual Device Driver sample is intended to demonstrate interdevice communication with the Physical Device Driver sample. The VDD sample illustrates intercepting the communication from a DOS Application which is executing in a DOS session under OS/2, and routing the appropriate information to the corresponding Physical Device Driver sample to complete the task. The intent of this sample is to provide source code demonstrating this functionality in the C language. Additional software and hardware is required to fully exercise the device drivers. Warning messages may be received when compiling this sample. The warning message is necessary when building device drivers, and is required, because DS = SS for ring 0. The VDD subdirectory contains header files that are intended for writers of device drivers, and should not be used in conjunction with application header files contained in the OS2H subdirectory. USING SOM AND C++ TO CREATE WORKPLACE OBJECTS _____________________________________________ SOM provides a language-neutral object-oriented programming mechanism for OS/2. This means that classes of objects can be defined using SOM and implemented using any programming language supported by the SOM compiler (currently C and C++). The CAR Workplace object in the OS/2 Toolkit has been modified to demonstrate a C++ implementation of a SOM/Workplace object. In the C implementation of CAR in the OS/2 2.0 Toolkit, the CAR's brake, horn, and speed are defined in terms of SOM instance data and methods: Feature Instance Data Methods ------------------------------------------------- Brake BrakeFlag QueryBrakes SetBrakes ------------------------------------------------- Horn Duration QueryDuration Set Duration ---------------------------------- HighTone QueryHighTone SetHighTone ---------------------------------- LowTone QueryLowTone SetLowTone ------------------------------------------------- Speed Speed QuerySpeed SetSpeed ------------------------------------------------- In the C++ implementation of CAR in the OS/2 2.1 Toolkit, the CAR's brake, horn, and speed are defined in terms of three C++ classes: BRAKE, HORN, and RPM. SOM and C++ objects have different class hierarchies. SOM provides commonality across SOM objects implemented in different languages and used by different applications. C++ classes are local to an application. As a rule, use SOM to define classes if the class can be useful to other applications. Use C++ to define classes that are useful only to your application. As an example, suppose we have a class of BOATs. Just as a CAR has a HORN, a BOAT may also have a HORN. HORNs are useful to both CARs and BOATs. Therefore, defining HORN using SOM, instead of C++, is advisable. SOM can also be used to "wrap" a C++ implementation of a class if the class is useful to other applications or must fit into the Workplace. As an example, we can define CAR as a C++ class. To place a CAR in the Workplace, we must define a SOM "wrapper" for the CAR class. METHOD MACROS _____________ To simplify conversion of C code to C++ code, if the programmer #defines C_TRANSLATION_MACROS before including the .XIH file, the method macros will be defined differently to remove the need to change the method calls to match the C++ convention. One such macro definition would be: #define_somGetClass(obj obj->somGetClass() vs. the normal definition: #define_somGetClass somSelf->somGetClass WP CAR SAMPLE _____________ An additional CAR sample has been written in C++. This sample should be installed to you hardfile and NOT registered on your desktop. ONLINE IPF REFERENCE ___________________ There is a dynamic link library (IPF.DLL) associated with the compiled example of the Application-Controlled Window Example. However, IPF.DLL is installed with the Sample Programs component of the Toolkit. Therefore, unless the Sample Programs component is installed, you will be unable to view the animation provided by the IPF.DLL in the Application-Controlled Window Example in the online IPF Reference. OS/2 ENHANCED EDITOR (EPM) __________________________ If you attempt to access additional information for a text string by pressing Ctrl+H, the following message might appear: epmkwhlp.ndx file not found To avoid this message, add the following to the DPATH statement in CONFIG.SYS: x:\toolkt21\book; where "x" is the drive location for the Toolkit. TK21DESK.CMD ____________ A command file, TK21DESK.CMD, is located in TOOLKT21\OS2BIN. TK21DESK.CMD is used to create a Toolkit folder and subfolders and contains the installed Toolkit on the CD-ROM. TK21DESK.CMD also updates CONFIG.SYS. TK21DESK.CMD can be used to re-create a Toolkit folder for a Toolkit installed on a hardfile. OS2DEF.H HEADER INFORMATION ___________________________ In the OS2DEF.H header file, the SELECTOROF macro is incorrect. It was intended to be used to get the selector of a 16:16 address, which it does not do. Either of the following two macros can be used to get the selector of a 16:16 address: #define SELECTOROF(p) (((PUSHORT)&(p))[1]) #define SELECTOROF(p) ((ULONG)(p) >>16) If you use the selector returned from one of the above macros with the OFFSETOF and MAKEP macros in the OS2DEF.H header file, you can successfully convert a 16:16 address to a 0:32 address. BIDIRECTIONAL NATIONAL LANGUAGE SUPPORT _______________________________________ Information on how to use the BIDI programming interface can be found in \TOOLKT21\C\SAMPLES\BIDI\READ.ME. DEVICE DRIVER PROGRAMMING INTERFACES ____________________________________ The header files previously contained in the \TOOLKT20\C\OS2H\DASD directory have been removed. These headers are now included in the "IBM Device Driver Source Kit for OS/2", available separately. DOS PROGRAMMING INTERFACE _________________________ The DosSetDOSProperty() and DosQueryDOSProperty() functions in BSEDOS.H are not supported. Do not use these application programming interfaces. WIN PROGRAMMING INTERFACE _________________________ The debug kernel version of PMGRE.DLL contained in the Toolkit executes an INT 3 instruction, causing a break-point to be hit in the debugger. The INT 3 is executed only in 32-bit API parameter validation on the debug version of PMGRE.DLL; all other errors will not execute an INT 3. For the WinCreateWindow function, the first USHORT pointed to by the control data parameter is assumed to be the length of the data block. DDE BETWEEN PM AND WINDOWS PROGRAMS ___________________________________ Making modifications to Microsoft Windows** programs to enable dynamic data exchange (DDE) communications with Presentation Manager*(PM) programs helps facilitate a gradual migration of applications to PM. Not all data formats are automatically converted when using DDE between Windows programs and PM programs (DDE set public). The following formats are converted automatically by OS/2 2.1: PM Application Windows Application Data Format Interpretation -------------------- -------------------- PM BITMAP Windows DIB TEXT TEXT (codepage 819) PM private Windows private Windows Application PM Application Data Format Interpretation -------------------- -------------------- Windows DIB PM BITMAP TEXT (codepage 819) TEXT Windows private PM Private Notes: 1. Code page translation (Windows 819 to/from current PM code page) is performed for topic name in all cases. 2. When data conversion is not automatically performed, programs can still communicate via DDE if the two programs are able to perform the data conversion and pass private data formats. PM REFERENCE UPDATES ____________________ PROGRAMMING CONSIDERATIONS __________________________ When including an OBJECTID=<....> keyname/value pair in a setup string, you must specify it at the end of the setup string. Existing 16-bit applications (small and tiny models) must have a 4KB stack available when they enter system calls. If they do not have a 4KB stack available, the stack can overflow into the data area. In testing, we found some 16-bit small/tiny model applications have not followed the guidelines and, therefore, have encountered problems. NEW FUNCTIONS FOR THE OS/2 2.1 CONTAINER CONTROL ________________________________________________ In response to user requests, the following new functions have been added to the OS/2 2.1 container control. DETERMINING THE WIDTH OF A COLUMN IN THE DETAILS VIEW There are instances when you might want to determine the width of a column in the details view, such as to allow the user to tab the split bar between columns. A function has been added to the container control to allow you to determine the width of the data in a column. You can then compute the width of the entire column by adding the width of the data to the left and right margins of the column. To determine the width of a column: 1. Define an attribute with a value of 0X0200 and give it a name such as CMA_DATAWIDTH. 2. Issue the CM_QUERYDETAILFIELDINFO message with the following values: a. Provide a pointer to the FIELDINFO structure in param1. b. Specify your attribute (see step 1) in param2. c. Request a return value with a type of LONG, not PFIELDINFO, to retrieve the width of the column in the FIELDINFO structure to which you are pointing. The value returned is the width of the data (text, icon, or bit map) in this column. 3. Use the GpiQueryFontMetrics function to query the average character width of the font used by the container. This value will be used to calculate the total column width. 4. Multiply 3 by the average character width and add this to the data width returned from step 2 for all columns except the following: The first and last columns in each split window. In these cases, multiply 2.5 by the average character width and add the column data width returned from step 2. The only other special case is where there is only 1 column in either the left or right split windows. In this case, you would multiply 2 by the average character width and add the column data width returned from step 2. 5. The value returned is the total width of the column. PROVIDING SOURCE EMPHASIS FOR CONTAINER ITEMS Source emphasis is the type of emphasis that the Workplace Shell interface provides when a context menu is displayed. It appears as a dotted box with rounded corners that surrounds the item for which the context menu is requested and the item that is being dragged. To provide source emphasis for container items: 1. Define an attribute with a value of 0X00004000L and give it a name such as CRA_SOURCE. 2. Issue the CM_SETRECORDEMPHASIS message with the following values: a. Provide a pointer to the RECORDCORE or MINIRECORDCORE structure in param1. You can provide source emphasis for the entire container by setting param1 to NULL. b. Set the usChangeEmphasis parameter to TRUE in param2. c. Specify your attribute (see step 1) in the fEmphasisAttribute parameter in param2. To remove source emphasis follow the same procedure outlined above, but set the usChangeEmphasis parameter in param2 to FALSE instead of TRUE. SEARCHING FOR EXACT TEXT STRING MATCHES There might be times when you need to search the container for a text string that is an exact match of your search string argument. To find an exact match: 1. Define an attribute with a value of 0X10000000L and give it a name such as CV_EXACTMATCH. 2. In the SEARCHSTRING data structure, specify values for the fields as you normally would, with the following exception: Specify your attribute (see step 1), along with an attribute for the type of view being displayed in the container, in the usView field. For example: CV_EXACTMATCH | CV_ICON Note: In the "OS/2 2.0 Programming Reference, Vol. III", the field for specifying the exact match attribute and the type of view is usView. The type associated with the field, however, is ULONG. You must specify usView to match the information in the header file. CHAPTER 34. CODE PAGES The following are corrections to code pages in Chapter 34: CODE HEX GCGID NAME CORRECT NAME PAGE VALUE GIVEN GCGID 037 6A SP05000 apostrophe SM650000 vertical line, broken 285 6A SP05000 apostrophe SM650000 vertical line, broken 500 6A SP05000 apostrophe SM650000 vertical line, broken 277 70 SP05000 apostrophe SM650000 vertical line, broken ADDENDUM TO PROGRAMMING GUIDE VOL. II, CHAPTER 33 (p. 22) __________________________________________________________ WORKPLACE RENDERING MECHANISM: The Workplace shell interface uses the rendering mechanism of <DRM_OBJECT,DRF_OBJECT> to communicate information about the workplace objects involved in a direct manipulation. For the <DRM_OBJECT,DRF_OBJECT> rendering mechanism, pdraginfo->hwndSource is expected to be the window handle of the container holding objects which were inserted via the _wpCnrInsertObject method. For each dragitem, pdragitem->ulItemID is the PMINIRECORDCORE pointer associated with the object. The object can be retrieved using OBJECT_FROM_PREC on pdragitem->ulItemID. As soon as the target object has completed processing, a DM_ENDCONVERSATION message is sent to the window handle in pdragitem->hwndItem. DM_PRINT CHANGED TO DM_PRINTOBJECT DM_PRINT is a message used in direct manipulation to ask a source object to print the current view of the object. DM_PRINT is documented in the "OS/2 2.0 Programming Guide Volume II" on page 33-20 and 33-23. DM_PRINT has been changed to DM_PRINTOBJECT. The changes that need to be made in the book are: o On page 22-20, under the heading "Print Rendering Mechanism", in the sub-section titled "Messages": In the first sentence, change DM_PRINT to DM_PRINTOBJECT. Additionally, in the last sentence, remove "queue, which is also identified in the message" from the end of the sentence and add a new sentence after "printer": The second message parameter (of type PRINTDEST) gives all the parameters necessary to call DevPostDeviceModes and DevOpenDC. o On page 33-23, in the table of Direct Manipulation Messages, change DM_PRINT to DM_PRINTOBJECT. There is no change to the description. PMWIN LOCKUP API'S AND HK_LOCKUP HOOK _____________________________________ WinLockupSystem WinUnlockSystem These two API's will allow a PM application to lock and unlock the system from within the application. In order for the WinUnlockSystem API to execute after the WinLockupSystem has been called, the WinUnlockSystem must be called from a separate thread. The HK_LOCKUP hook will allow a PM application to customize system lockup from within their application. In order for your window to appear as the top most window on the lockup screen you must use the WS_CLIPSIBLINGS flag in your WinCreateWindow or WinCreateStdWindow call. PROGRAMMING GUIDE VOLUME III ____________________________ GPIERASE CHANGES In the "OS/2 2.0 Programming Guide Volume III" the graphics programming interface is described. In the Summary Tables on pages 13-18 and 14-12 change the description of GpiErase to: Clears a window, identified by a screen device context, and paints the window using the color identified by index 0 in the color table, or by the first color in the presentation space's palette. DOSSHUTDOWN API _______________ The DosShutDown API is documented in the "OS/2 2.0 Control Program Programming Reference" on page 2-339. This API has been enhanced to assist in the Power Management activities within the operating system. The primary change is to rename the ulReserved parameter to ShutDownValue. In addition, the valid ShutDownValue parameter values are defined as: Value Definition ----- --------------------------------- 0 Perform full system shut down and file system lock. 1 Perform buffer and cache flushing to make the system quiescent. All other values are reserved. The Remarks section of the DosShutDown API is updated to qualify the existing text as applicable to the ShutDownValue parameter value of 0. The Remarks for the ShutDownValue parameter value equal to 1 indicates the system has 0 threads of execution active upon the completion of this function request. The file systems will not be locked and processing can resume again at a later time. Information on the new Power Management features located in "IBM Device Driver Source Kit for OS/2", available separately. DEVICE DRIVER INITIALIZATION ____________________________ There are two new options available to device drivers during initialization. DEVICE DRIVER INITIALIZATION QUIET FAILURE FLAG This interface is documented in the "OS/2 2.0 Physical Device Driver Reference". Several pages have changes for the new device driver Quiet Failure Flag. The changes are: o Page 15-3. Add the following information after "Invalid Parameter (13H)": Initialization Failed (noncritical) (15H): Returned when the device driver initialization fails, but a message will not be displayed indicating a failure. o Page 15-6. Remove the following sentence from the last paragraph: If none of the devices in the device driver header chain pass initialization, the physical device driver does not remain loaded. and add a new paragraph at the end: If none of the devices in the device driver header chain pass initialization, and the device driver returns Initialization Failed (noncritical) (15H) for all devices in the device driver header chain, a failure message will not be displayed to the user and the physical device driver does not remain loaded. If none of the devices in the device driver header chain pass initialization, and the device driver returns an error code other than Initialization Failed (noncritical) (15H) for at least one device in the device driver header chain, a failure message will be displayed to the user and the physical device driver will not remain loaded. If at least one of the devices in the device driver header chain passes initialization, a failure message will not be displayed to the user and the physical device driver will remain loaded. DEVICE DRIVER INITIALIZATION COMPLETE COMMAND This interface is documented in the "OS/2 2.0 Physical Device Driver Reference". Several pages have changes for the new device driver Initialization Complete Command. The changes are: o Page 4-3. Add the following to list of packets supported by character devices: 31 - Init Complete o Page 15-4. Add the following to the table of physical device driver strategy commands: 1F - Initialization Complete o After Page 15-24. Add the following for the new strategy command description: 1FH/ Initialization Complete ---------------------------- This command informs the physical device driver that all physical device drivers have been loaded. Request Block Format +----------------------------------+ | Field Length | |----------------------------------| | Request Header 13 bytes | +----------------------------------+ Remarks: When a device driver receives this command, all physical device drivers have been loaded and initialized. Virtual device drivers have not been loaded and initialized. The device driver can now establish links to other physical device drivers. This command is sent to the device driver only if it is a level-3 device driver and if Bit 4 is set in the Capabilities Bit Strip in the device driver header (see the section on the Capabilities Bit Strip later in this file). NEW BIT ADDED TO CAPABILITIES BIT STRIP _______________________________________ The Capabilities Bit Strip is a part of the device driver header and is described on pages 3-4 and 3-5 of the "Physical Device Driver Reference". A new bit has been added to the Capabilities Bit Strip. On page 3-5, after "Bit 2" add a new entry to the list: Bit 4 If set to 1, the new "Initialization Complete" command (1FH) is supported. (The new "Initialization Complete" command is documented in an earlier section of this file.) CHANGE TO DEVICE ATTRIBUTE FIELD ________________________________ The Device Attribute Field is a part of the device driver header and is described on pages 3-3 and 3-4 of the "Physical Device Driver Reference". On page 3-3, in the text describing "Bit 13", delete the second sentence: "Set for output-until-busy support (character device drivers only)." NEW HOOKS FOR VDHINSTALLUSERHOOK VIRTUAL DEVICE HELPER FUNCTION _______________________________________________________________ VDHInstallUserHook is documented in the "OS/2 2.0 Virtual Device Driver Reference" on page 5-70. Two new user hooks for virtual device drivers (VDDs) have been added for use with VDHInstallUserHook. These hooks support an enhancement to the DOS Protect Mode Interface (DPMI) support for DOS sessions. BACKGROUND -- A DOS SESSION DPMI ENHANCEMENT The OS/2 operating system has been enhanced to support multiple local descriptor tables (LDT) and interrupt descriptor tables (IDT) in each DOS session, as specified in the DPMI 1.0 specification. The OS/2 operating system now allocates a new IDT and LDT each time a DPMI application initially enters protect mode. The original DPMI implementation for the OS/2 operating system supported DPMI 0.9, which defined a single-LDT, single-IDT mechanism; all DPMI applications used the same LDT and IDT. This implementation meant that multiple DPMI applications could run in a DOS session, but that all the DPMI applications within a single DOS session had to be either 16-bit or 32-bit. The OS/2 operating system now creates a new LDT and IDT for each DPMI application when the application initially enters protect mode. Protect mode exceptions and interrupts are routed to the primary DPMI client in the DOS session, which is defined to be the last application to enter protect mode. With this enhancement, 16-bit and 32-bit DPMI applications can be run in the same DOS session. This support conforms with the DPMI 1.0 specification. The primary DPMI client's IDT is used to call the appropriate interrupt and exception handlers. The virtual Programmable Interrupt Controller (VPIC) simulates hardware interrupts using the primary DPMI client's IDT. The DOS session switches to the primary client's IDT so that the interrupt is routed to the correct handler, and then restores the current task (if necessary) after the interrupt has been simulated. Two new hooks for virtual device drivers (VDDs) have been added to VDHInstallUserHook to support this enhancement. NEW VDHINSTALLUSERHOOK HOOKS The two new user hooks enable VDDs to be notified when a DPMI task begins and ends execution, so the VDD is able to hook any events in protect mode that are required. The new hooks are VDM_BEGIN_VPM_TASK, and VDM_END_VPM_TASK (VPM means Virtual Protect Mode). Each time a new DPMI application/task starts in a DOS Session, all VDM_BEGIN_VPM_TASK hooks are called. Each time a DPMI application/task exits, all VDM_END_VPM_TASK hooks are called. The constants are defined as follows: #define VDM_BEGIN_VPM_TASK 13 /* VPM task initially started */ #define VDM_END_VPM_TASK 14 /* VPM task terminated */ The routines registered to receive control when a task starts or stops are passed the handle to the DOS session, but the DPMI application that is starting or stopping will have its IDT and LDT active. ADDITION TO VMALLOC DEVHLP FUNCTION ___________________________________ VMAlloc is documented in the "OS/2 2.0 Physical Device Driver Reference" on page 17-98. A new bit has been added to the VMAlloc DevHlp function that tells the operating system to allocate memory above the 16MB limit. This bit is: 0x800 - VMDHA_USEHIGHMEM If memory above 16MB exists but there is not enough to satisfy the request, memory above 16MB will be used first and the remaining amount will be taken from memory below 16MB. If no memory above 16 MB exists, the allocation will be taken from existing memory. The memory is freed by calling the VMFree DevHlp function. This bit is only valid during device driver initialization. If this bit is used at any other time, VMAlloc will return an error (ERROR_INVALID_PARAMETER). DLL INITIALIZATION AND TERMINATION __________________________________ The TERMGLOBAL option of the _DLL_InitTerm function as described on pages 5-9 and 5-13 within the "OS/2 2.0 Application Design Guide" is not supported. CHANGES AND CLARIFICATIONS __________________________ This section contains some additions, changes, and clarifications to the "OS/2 2.0 Programming Guide Volume I: Control Program", and for the "OS/2 2.0 Physical Device Driver Reference". ADDENDUM TO FILE MANAGEMENT CODING EXAMPLES File management is described in Chapter 4 of the "OS/2 2.0 Programming Guide Volume I: Control Program". In the sample code on pages 4-20 and 4-21, under the line: #define INCL_DOSFILEMGR add the line: #define INCL_DOSMISC The "#define INCL_DOSMISC" is required to include the header file support (function prototypes, and so on) for DosScanEnv and DosSearchPath. The DosQuerySysInfo function also requires the "#define INCL_DOSMISC", but this function is not used in any of the samples in the Programming Guide. PROGRAM EXECUTION CONTROL Sessions, processes, and threads are documented in Chapter 7 of the "OS/2 2.0 Programming Guide Volume I: Control Program". In Figure 7-1 on page 7-2, in the center box of the figure, change the word "Sessions" to "Processes". USER-DEFINED EXCEPTIONS Exception management is documented in Chapter 13 of the "OS/2 2.0 Programming Guide Volume I: Control Program". On page 2-339, under the heading "User-Defined Exceptions", change the example for raising exceptions from: DosRaiseException(XCPT_YOUR_EXCEPTION); to the following: EXCEPTIONREPORTRECORD ERepRec; ERepRec.ExceptionNum = XCPT_YOUR_EXCEPTION; ERepRec.fHandlerFlags = 0; ERepRec.NestedExceptionReportRecord = NULL; ERepRec.ExceptionAddress = NULL; ERepRec.cParameters = 0; DosRaiseException(&ERepRec); ADDENDUM TO PHYSICAL DEVICE DRIVER REQUEST PACKET DOCUMENTATION The format of the physical device driver's Request Packet Status WORD is described on page 15-2 of the "OS/2 2.0 Physical Device Driver Reference". This addendum relates to bit 15 (the Error bit), bit 8 (the Done bit), and bits 7-0 (Error Code). Bit 8 (the Done bit) MUST be set, even when bit 15 (the Error bit) is set. That is, whenever you return with the Error bit set, you must also set the Done bit. CHANGE TO DOCUMENTATION FOR PHYSICAL MOUSE DEVICE DRIVER IDC The physical Mouse device driver's inter-device-driver communication (IDC) interface is documented in the "OS/2 2.0 Physical Device Driver Reference", in Chapter 12, "Physical Mouse Device Driver". In the section headed "MOUSE.SYS IDC Interface", under the information on the Process_Absolute IDC request, at bottom of page 12-3 and top of page 12-4, there is a reference to the "event" field that must be changed. Remove the following sentences: The event field should never indicate that motion was associated with the event. MOUSE$ determines if motion occurs. ADDENDUM TO DOCUMENTATION FOR THE LOCK DEVHLP The Lock DevHlp is described on pages 17-43 and 17-44 of the "OS/2 2.0 Physical Device Driver Reference". On page 17-44, at the end of the Remarks for Lock, add the following paragraph: By default, when DosDevIOCtl passes an address to a device driver, it passes the address in the form of a temporary selector. This selector is only valid for the duration of the call and cannot be used to lock the memory using the Lock DevHlp. If you need to lock this memory, the calling program must use the DosAllocMem function with the object tile (OBJ_TILE) bit set. If you pass a pointer to this memory in the call to DosDevIOCtl, the device driver can use the Lock DevHlp to lock this memory. NOTICES _______ 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. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally projectable rights 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 Commercial Relations, IBM Corporation, Purchase, NY 10577. TRADEMARKS AND SERVICE MARKS The following terms denoted by an asterisk (*) used in this publication are trademarks, or service marks of the IBM Corporation in the United States or other countries: IBM OS/2 Presentation Manager Workplace Shell The following terms denoted by double asterisks (**) used in this publication are trademarks, or service marks of non-IBM Corporations in the United States or other countries: Microsoft Windows IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION, WARRANTIES OF FITNESS AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS. Copyright International Business Machines Corporation, 1993. All Rights Reserved.