OS/2 Professional Developers Kit 1992 November

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

/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / os2tk20 / read.me < prev next >

Wrap

Text File | 1992-10-22 | 23.2 KB | 726 lines

Welcome to the IBM Developer's Toolkit for OS/2 2.0. 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.0 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. The toolkit installation program has the following problems: o If you install this version of the Toolkit on top of a previous version of the OS/2 2.0 Toolkit, duplicate program objects may appear in the Toolkit folder. To avoid this, remove the toolkit folder and all of its contents from the desktop. NOTE: You may not be able to remove the Car Sample or the Class Lister objects. If not, just remove all other toolkit objects. o The jigsaw sammple and the clock sample do may not appear in the Samples folder, but the source code will be installed. KWIKINF UTILITY _______________ KwikINF provides a convenient method of accessing information in OS/2 2.0 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: KWIKINF 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 these types of sessions because they are graphics sessions 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). 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 _______________ WORMS SAMPLE PROGRAM The WORMS sample will not compile with the version of C Set/2 on this release. You can compile WORMS with C Set/2 Version 1.0, or use the WORMS.EXE file supplied with this release. The WORMS sample might cause video corruption if executed. If you encounter problems executing WORMS, press Ctrl+Esc and close from the Window List. 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. The 32-bit Graphics Engine is available in these versions of OS/2: o OS/2 2.00.1 o OS/2 2.00.1 Backup Diskette Package for Preinstalled Systems o OS/2 2.0 Service Pak. 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. 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:\TOOLKT20\C\SAMPLES\IMAGE and \TOOLKT20\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 \TOOLKT20\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 \TOOLKT20\C\SAMPLES\BIDI\READ.ME. DEVICE DRIVER PROGRAMMING INTERFACES ____________________________________ In order to use text capability enhancements, the following statement must be added to certain header files: o Add the following line to the PMDEV.H header file: #define CAPS_ENHANCED_TEXT 16384 The header files contained in the \TOOLKT20\C\OS2H\DASD directory define the data structures used in the layered DASD/SCSI device driver interface. Documentation is available from IBM for constructing device drivers that work with this interface. This document is primarily targeted for development organizations that: o Develop device drivers for SCSI adapters o Develop device drivers for non-standard DASD hardware interfaces o Develop OS/2 kernel extensions that add value to existing DASD or SCSI subsystems DASD data encryption packages, Redundant Array of Inexpensive Disks (RAID) packages, and other data striping packages fall into this category. Until the SCSI Device Driver Reference is published, you can acquire this document by contacting: IBM BTIG (Zip 1424), P.O. Box 1328, Boca Raton, FL 33432. DOS PROGRAMMING INTERFACE _________________________ The DosSetDOSProperty() and DosQueryDOSProperty() functions in BSEDOS.H are not supported. Do not use these application programming interfaces. GRAPHICS PROGRAMMING INTERFACE ______________________________ OS/2 2.0 introduces several new graphics features not available on previous versions. In particular, OS/2 2.0 supports new bit map formats, polygons, and flood-fill operations. Metafiles and print spool files generated by new 32-bit applications that use these functions will generate incorrect or incomplete output when processed by earlier OS/2 versions, for example 1.3. The GpiDestroyPS will destroy a presentation space even it if is currently associated to a device context. This function will attempt to disassociate the presentation space from the device context and, if successful, continue to destroy the presentation space as normal. The current value set, on VN_SELECT and VN_ENTER notifications (both part of WM_CONTROL), returns the value set window handle instead of the selected row and column as documented. (The value set does return row and column information on VN_HELP, as documented.) Developers writing applications that require a particular font need to be aware that the OS/2 2.0 Installation program will copy only those fonts required by the displays attached to the computer. In previous OS/2 releases, all fonts were copied. 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 o 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. 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. DEBUGGING PROGRAMS __________________ In this release, the DosDebug API will not permit the debugging of code that is in use by more than one process. 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.0: 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. KERNEL DEBUG SUPPORT ____________________ In order for the debug version of OS2KRNL to boot on systems containing future Intel processors, two instructions must be modified. Future Intel processors might not recognize the TR6 and TR7 registers, and both registers are referenced once in the debug version of OS2KRNL with the following instructions: MOV EAX,TR6 and MOV EAX,TR7. These instructions must be replaced using a binary editor. 1. Search for the opcode 0F24F0h (MOV EAX,TR6) and replace with 909090h (3 NOPs). 2. Search for the opcode 0F24F8h (MOV EAX,TR7) and replace with 909090h (3 NOPs). The debug commands "R TR6" and "R TR7" might produce unpredictable results. If you require the use of the kernel debugger on a later version of OS/2, please check the OS2DEV forum on CompuServe for details on how to obtain the necessary code. To join CompuServe, call (800) 524-3388 and ask for representative 239 for a free introductory membership, complete with user ID, plus $15. worth of free connect time. 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 NEW FUNCTIONS FOR THE OS/2 2.0 CONTAINER CONTROL ________________________________________________ In response to requests from our users, the following new functions have been added to the OS/2 2.0 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.