The Developer Connection - Device Driver Kit for OS/2 3

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

/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / devtools / toolkt21 / read.me < prev next >

Wrap

Text File | 1993-03-11 | 40.1 KB | 1,268 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. ADDITIONAL DEVELOPER INFORMATION ________________________________ IBM participates in CompuServe forums. If you are online as a CompuServe member, simply type "GO IBMOS2" at the ! prompt and you will be provided with a menu of the available OS/2 forums. TOOLKIT INSTALLATION ____________________ The toolkit installation program has been updated to take advantage of new features in the Workplace Shell. The Toolkit folder on the desktop, illustrated by the toolbox icon, contains three other folders. These folders are: o PM Development Tools o Toolkit Information o Sample Programs You may install the Toolkit for OS/2 2.1 on a 1.3 system. The installation program will transfer your files and update the environment variables; however, no programs will be registered on the desktop. KWIKINF UTILITY _______________ KwikINF provides a convenient method of accessing information in OS/2 2.1 online documents. Once KwikINF starts, pressing a hot-key sequence causes the program to pop up and search for a text string of your choice. You can specify three KwikINF options from the command line. An example of the command line syntax follows: KwikINF [/C] [/T] [/?] where: Entering KwikINF at the command prompt with no options starts KwikINF. After entering this command, the default hot-key sequence (ALT + Q) is enabled. /T Entering the /T option will terminate KwikINF and disable the hot-key sequence. KwikINF will be terminated for all active sessions. /C Entering the /C option will display the "Configure KwikINF" window. Use the "Configure KwikINF" window to customize KwikINF values. /? entering the /? will display the following information. Usage: KwikINF [Option] Option Description /C Configure KwikINF /T Terminate KwikINF /? This short help list Pressing the hot-key sequence brings to the foreground KwikINF's "Search" window. KwikINF will work in any of the OS/2 sessions types: full screen, AVIO window, and PM window. If your application is running in a full-screen session, an AVIO window, or an active PM window is a multi-line entry (MLE) field, KwikINF will retrieve the word the cursor is on and automatically place it in the entry field of the "Search" window. In PM windows, you can use the hot-key sequence to display the search window; however, you must enter the search string manually. KwikINF does not pre-fill the search string field for PM windows. KwikINF cannot determine the word under the cursor in this session because it is a graphics session and the characters are stored as bit maps rather than as characters. To find information on a string, do the following: o If you are in a full-screen session, an AVIO window, or MLE window, position the cursor on the string you want to search for, then press the hot-key sequence. KwikINF retrieves the word at the cursor and places it in the entry field of the "Search" window. o If you are in a PM window or an AVIO session, press the hot-key sequence, then type the word to search for in the entry field of the "Search" window. KwikINF then takes you to the entry for the search string in the online document. NOTE: You should not add KwikINF to your STARTUP.CMD if it is followed by an EXIT statement. Instead, create a KwikINF program object. LINK386 UTILITY _______________ It is recommended that the ALIGN, BASE, and EXEPACK options be used when linking all executables. This will compress them in size and improve their performance. Use /ALIGN:4 for 32-bit applications, /ALIGN:16 for 16-bit applications. For .EXE files, /BASE:0x10000 option must be used. Any other value produces a warning. For .DLL files, use /BASE:0x12000000 (or a lesser value). C/C++ INFORMATION _________________ A subset of the OS/2 header files have been C++ enabled and will be installed in the \TOOLKT21\CPLUS\OS2H subdirectory. If you have the IBM C/C++ Compiler installed they may be used to compile C and/or C++ programs. To use them, you will have to modify the CONFIG.SYS file as follows: SET INCLUDE=x:\TOOLKT21\CPLUS\OS2H;%include% where x is the correct disk drive and %include% is the existing INCLUDE= value If you want to use the OS/2 C++ headers to compile the toolkit samples, you may need to copy remaining headers that aren't C++ enabled from the \TOOLKT21\C\OS2H directory into \TOOLKT21\CPLUS\OS2H. VDD INFORMATION _________________ The VDD sample is now written in C language. You may receive error/warning messages when compiling this sample. If you include the following headers with the OS2.H header file, you may receive warnings regarding duplicate definitions in the following files: BASEMAC.H BASEMID.H MI.H MVDM.H VDMA.H VDMBIOS.H VDMM.H VDOS.H VFDPFD.H VKBD.H VKBDPDD.H VLPT.H VMDPMD.H VPIC.H VPMXPORT.H VVD.H The above header files are intended for building and accessing virtual device drivers. They should not be used to build applications other than device drivers. ONLINE IPF REFERENCE ____________________ There is a dynamic link library (IPF.DLL) associated with the compiled example of "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 2.0 ENHANCED EDITOR ________________________ 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:\toolkt20\book; where "x" is the drive location for the Toolkit. SAMPLE PROGRAMS _______________ The following sample programs are new or enhanced for this Toolkit update. PALETTE MANAGER SAMPLE PROGRAM PALETTE MANAGER is new and demonstrates 32-bit graphics functions including: o Creating a window using a custom palette and animation. o Using menus with switches, and modifying the menu text. o Using multiple threads and semaphores in the PM environment. o Displaying graphics on the screen using outline fonts and clip paths. o On-line help. Requirements are a XGA adapter card fully populated with 1 megabyte of RAM and the 32-bit Graphics Engine. When started, PALETTE displays a standard window with a large IBM logo in the foreground. The user has the ability to change the IBM logo to the OS/2 logo. If the user resizes the window, the logo is scaled and redrawn to fit the new window size. The user 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; and then drawing a series of lines to the presentation space. Each line is drawn with an incrementing color index. Palette animation is performed using the 32-bit GpiAnimatePalette function call. In order for 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. STYLE SAMPLE PROGRAM STYLE has new function that demonstrates the detection of a font that does not conform to the International Standards Organization (ISO 9241). When the user selects a non-compliant font in the standard font dialog, a message box is displayed to inform the user. The fsSelection field in the FONTMETRICS structure can be tested with the following bit to determine if the current font has been tested for ISO conformance: FM_SEL_ISO9241_TESTED The panose.fbFailedISO field in the FONTMETRICS structure can be tested with the following bits to determine if the current font fails to conform to ISO 9241 standards on specific displays that are known to comply: FM_ISO_9518_640 FM_ISO_9515_640 FM_ISO_9515_1024 FM_ISO_9517_640 FM_ISO_9517_1024 These defines and additional information can be found in OS2DEF.H which is shipped with this product.The path to get to the OS2DEF.H defines is: x:\TOOLKT21\C\OS2H WPCAR SAMPLE PROGRAM WPCAR is the sample program that demonstrates how to create a Workplace Shell object. New to WPCAR is its ability to set an exception handler for memory access violations. To demonstrate this, a new menu item was added to WPCAR that calls a function that causes an exception. A message indicates the program's exception handler is returning control to the cleanup code. Additional README files concerning sample programs are available in these directories:\TOOLKT21\C\SAMPLES\IMAGE and \TOOLKT21\C\SAMPLES\TEMPLATE. WORKFRAME/2 ___________ The IBM WorkFrame/2 allows you to integrate various tools into your application development environment. Tools, such as the Dialog Editor, Font Editor, Icon Editor, Information Presentation Facility Compiler, and Resource Compiler, can then be selected from the "Tools" pull-down menu of WorkFrame/2. This toolkit integration is optional. To help you add the tools into the WorkFrame environment easily, a special file (TOOLKT20.INI) is provided in the \TOOLKT21\OS2BIN directory. To integrate the toolkit tools into the WorkFrame/2, do the following: 1. After completing Toolkit installation, install the IBM WorkFrame/2. Make sure the CONFIG.SYS file is updated for the WorkFrame/2, either by selecting the "Update CONFIG.SYS" checkbox or by updating it manually. 2. Reboot your computer, as specified in the WorkFrame/2 installation procedure. 3. At the OS/2 command line, type: addtool \toolkt20\os2bin\toolkt20.ini When you start WorkFrame/2 and select "Tools" from the menu bar, entries for the five Toolkit tools appear in a pull-down menu. 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 OS/2 Device Driver Development Kit which can be obtained by calling 1-800-3-IBMOS2. CONTROL PROGRAM REFERENCE UPDATES FOR V2.1 __________________________________________ The following are new APIs were added: Control Program DosProtectClose DosProtectEnumAttribute DosProtectOpen DosProtectQueryFHState DosProtectQueryFileInfo DosProtectRead DosProtectSetFHState DosProtectSetFileInfo DosProtectSetFileLocks DosProtectSetFilePtr DosProtectSetFileSize DosProtectWrite Presentation Manager WinCheckInput WinLockPointerUpdate WinLockupSystem WinQuerySysPointerData WinQueryVisibleRegion WinSetPointerOwner WinSetSysPointerData WinSetVisibleRegionNotify WinUnlockSystem Workplace Shell methods/Classes wpAddPowerPage wpAddPowerViewPage WPBitmap wpChangePowerState WPCommandFile wpEjectDisk WPIcon wpLockDrive WPPointer WPPower (class) wpQueryAssociatedProgram wpQueryAutoRefresh wpQueryConcurrentView wpQueryDefStatusView wpQueryDriveLockStatus wpQueryPowerConfirmation wpQueryPowerManagement wpQueryRefreshRate wpSetAssociatedFileIcon wpSetAutoRefresh wpSetConcurrentView wpSetDefStatusView wpSetPowerConfirmation wpSetPowerManagement wpSetRefreshRate wpViewObject MESSAGES WM_VRNENABLED WM_VRNDISABLED WM_MOUSEMAP DOS PROGRAMMING INTERFACE _________________________ The DosSetDOSProperty() and DosQueryDOSProperty() functions in BSEDOS.H are not supported. Do not use these application programming interfaces. GRAPHICS PROGRAMMING INTERFACE ______________________________ The GpiFloodFill function may produce incorrect results if another window is visible on top of any of the area being filled. You will get correct results if your application is in the foreground, and no windows or dialogs owned by your application are visible during flood-fill operations. WORKPLACE PROGRAMMING INTERFACE _______________________________ WORKPLACE CLASSES, INSTANCE METHODS, AND CLASS METHODS wpFindViewItem - Do not use method, it may be removed from the header files in the future. Use wpFindUseItem to find VIEWITEM structures to achieve the same functionality. wpclsQueryObject now locks the object before returning it. If you are using this method, make sure you unlock the object after you are done with it. WIN PROGRAMMING INTERFACE _________________________ The kernel debug version of PMWIN.DLL contained in the Toolkit executes an INT 3 instruction, causing a break in the debugger. The INT 3 is executed only in 32-bit API parameter validation on the debug version of PMWIN.DLL; all other errors will not execute an INT 3. For the WinCreateWindow function, the first USHORT the control data parameter points to is assumed to be the length of the data block. SEAMLESS XGA OR SEAMLESS SVGA ----------------------------- When the debug kernel is installed and a application is run in seamless xga or seamless svga,when the application exits,it will cause the system to halt. It is recommended the debug kernel not be used with seamless xga or seamless svga. DDE BETWEEN PM AND WINDOWS PROGRAMS ___________________________________ Making modifications to Windows programs in order to use 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 doing 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 codepage) is done for topic name in all cases. 2. When data conversion is not automatically done, programs can still communicate via DDE if the two programs are able to do the data conversion and pass private data formats. PM REFERENCE UPDATES ____________________ RESOURCE COMPILER See the Tools Reference for updated resource compiler information. DATA TYPES o The following structures are found in the Bit-Map File Format section, they should be in the datatype section also. - BITMAPARRAYFILEHEADER - BITMAPARRAYFILEHEADER2 - BITMAPFILEHEADER - BITMAPFILEHEADER2. o The following structures are found in the Font-File Format section, they should be in the datatype section. - ADDITIONALMETRICS - FOCAFONT - FOCAMETRICS - FONTDEFINITIONHDR - FONTFILEMETRICS - FONTSIGNATURE PROGRAMMING CONSIDERATIONS __________________________ Existing applications (small and tiny model) must have a 4K stack available when they enter system calls. If they do not have a 4K stack available, the stack can overflow into the data area. We have found in our testing, that some 16-bit small and tiny model applications have not followed the guidelines and encountered problems. NEW FUNCTIONS FOR THE OS/2 2.1 CONTAINER CONTROL ________________________________________________ In response to requests from our users, 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 times when you may 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. New 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 times the average character width and add this to the data width returned from step 2 for all columns except the following: a. The first and last columns in each split window. In these cases, multiply 2.5 times the average character width and add the column data width returned from step 2. b. 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 times 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 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 an 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 may 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: a. 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 should be usView, not ulView. The type associated with the field, however, is ULONG. You must specify usView to match the information in the header file. ADDENDUM TO PROGRAMMING GUIDE VOL. II, CHAPTER 33 (PG. 22) __________________________________________________________ WORKPLACE RENDERING MECHANISM: Workplace shell 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. Once the target object has completed processing, it should send a DM_ENDCONVERSATION message to the window handle in pdragitem->hwndItem. 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 should be updated to qualify the existing text as applicable to the ShutDownValue parameter value of 0. Also, the Remarks for the ShutDownValue parameter value of 1 should indicate that the system should be quiescent (that is, no threads of execution will be active) at the end of this function request, but that the file systems will not be locked and processing can resume again at a later time. For more information on the new Power Management features, see the Power Management TXT (text) file. 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 should 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 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 IOCTLS __________ New IOCtls have been provided for two categories of device management: lockable drives and power management. For lockable drives there are 3 new IOCtls in Category 8: o Category 8, Function 40H -- Unlock, Lock, and Eject Media o Category 8, Function 5DH -- Diskette Control o Category 8, Function 66H -- Query Lock Status For power management there are 5 new IOCtls in a new category, Category 12 IOCtls. The IOCtls in this category are: o Category 12, Function 40H -- Send Power Event o Category 12, Function 41H -- Set Power Event Resource o Category 12, Function 60H -- Query Power Status o Category 12, Function 61H -- Query Power Event o Category 12, Function 62H -- Query Power Info These IOCtls are documented in the online Control Program Reference. In addition, there is a separate TXT (text) file devoted to Power Management. 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 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, then restores the current task (if necessary) after the interrupt has been simulated. Two new hooks have been added to VDHInstallUserHook to support this enhancement. NEW VDHINSTALLUSERHOOK HOOKS Two new user hooks for virtual device drivers (VDDs) have been added for use with VDHInstallUserHook. 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 16 MB line. This bit is: 0x800 - VMDHA_USEHIGHMEM If memory above 16 MB exists, but there is not enough to satisfy the request, memory above 16 MB will be used first and the remaining amount will be taken from memory below 16 MB. 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). CHANGES AND CLARIFICATIONS __________________________ This section contains some additions, changes, and clarifications for 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 in 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 the OS/2 2.0 Programming Guide Volume I: Control Program, in Chapter 13. 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 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 the bottom of page 12-3 and top of page 12-4, there is a reference to the "event" field that has 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 OS/2 2.0 OS/2 2.1 IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION, WARRANTIES OF FITNESS AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS. Copyright IBM Corporation, 1992, all rights reserved.