home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warptlk3.zip / TOOLKIT / README next >
Text File  |  1995-10-24  |  23KB  |  604 lines
  1. ________________________________________________________________
  2.  
  3. IBM DEVELOPER'S TOOLKIT FOR OS/2 WARP, VERSION 3 README FILE
  4. ________________________________________________________________
  5.  
  6. Welcome to the IBM* Developer's Toolkit for OS/2* Warp, Version 3 (Toolkit).
  7. In addition to this README file, the book--"Using Your Toolkit"--is included
  8. to help you:
  9.  
  10.    -  See what is new and what has changed in the Toolkit
  11.    -  Become familiar with the Toolkit
  12.    -  Access information about the Toolkit more easily and quickly
  13.  
  14. This READ.ME file is a supplement to that book and provides information
  15. about Toolkit installation.  Use a non-proportional font to view this file.
  16. This README file contains:
  17.  
  18.    1. Introduction to the Toolkit
  19.    2. Installing the Toolkit
  20.    3. Updates to CONFIG.SYS
  21.    4. Known limitations and restrictions
  22.  
  23.  
  24. INTRODUCTION TO THE TOOLKIT
  25. ________________________________________________________________
  26.  
  27. The Toolkit is a collection of sample application programs, programming tools,
  28. library files, header files, and online documents that help you develop
  29. applications for OS/2.  The Toolkit can be installed from CD-ROM or from
  30. diskettes created from diskette images on the CD-ROM.
  31.  
  32.  
  33. INSTALLING THE TOOLKIT
  34. ________________________________________________________________
  35.  
  36. This section provides a step-by-step procedure for installing the Toolkit.
  37.  
  38.  
  39. System Requirements
  40. ________________________________________________________________
  41.  
  42. You can install the Toolkit for OS/2 Warp, Version 3 on any of the 
  43. following systems:
  44.  
  45.    -  OS/2 2.1
  46.    -  OS/2 2.11
  47.    -  OS/2 Warp, Version 3
  48.    -  OS/2 Warp with WIN-OS/2, Version 3
  49.    -  OS/2 Warp Connect
  50.    -  OS/2 Warp Connect with WIN-OS/2
  51.  
  52. The IBM Developer API Extensions for OS/2 Beta which can be found on this 
  53. version of The Developer Connection can be installed on the 4 versions of 
  54. OS/2 Warp listed above. However, The FixPak Beta, which can also be found 
  55. on this version of the Developer Connection must first be installed.
  56.  
  57. Only the functions available in the operating system you have installed
  58. will be available in the Toolkit.
  59.  
  60. Before you install the Toolkit, make sure you have:
  61.  
  62.    -  A personal computer that has an Intel386** (or higher) 
  63.       microprocessor with the OS/2 operating system installed
  64.  
  65.    -  A minimum of 4MB of memory (8MB or more is recommended)
  66.  
  67.    -  A high capacity 3.5-inch diskette drive or CD-ROM drive
  68.  
  69.    -  A hard disk drive with 80MB of free disk space 
  70.       (to install the entire Toolkit)
  71.  
  72. We recommend that you install a mouse.
  73.  
  74.  
  75. Installation Program
  76. ________________________________________________________________
  77.  
  78. You install the Toolkit through a Presentation Manager/2* application:  the
  79. Toolkit Installation Program.  This program is available through the CD-ROM
  80. or through diskettes made from diskette images on the CD-ROM. Through the
  81. Toolkit Installation Program, you can install:
  82.  
  83.    -  Development tools
  84.    -  Headers and libraries
  85.    -  Toolkit information
  86.    -  Sample programs
  87.  
  88. You can install the entire Toolkit or selected components of the Toolkit
  89. through the Toolkit Installation Program.  By default, the Toolkit
  90. installation will copy chosen files to your machine and update 
  91. CONFIG.SYS with respect to the locally installed files.
  92.  
  93.  
  94. Installation Help
  95. ________________________________________________________________
  96.  
  97. When installing the Toolkit, to get online help for installation, do one
  98. of the following:
  99.  
  100.    -  Press the F1 key
  101.    -  Select the Help push button
  102.    -  Choose one of the help choices from the Help menu
  103.  
  104.  
  105. Installing from Diskette Images
  106. ________________________________________________________________
  107.  
  108. You can install the Toolkit from the CD-ROM or from diskettes made from
  109. diskette images on the CD-ROM. To install from CD-ROM, go to the next
  110. section "Installing the Toolkit." 
  111.  
  112. You can create diskettes using The Developer Connection for OS/2 
  113. Catalog program as follows:
  114.  
  115.    1. Open The Developer Connection folder on your desktop.
  116.  
  117.    2. Open The Developer Connection for OS/2 folder from The Developer
  118.       Connection folder.
  119.  
  120.    3. Open The Developer Connection Catalog program from The Developer
  121.       Connection for OS/2 folder.
  122.  
  123.    4. Find the product entitled:
  124.  
  125.          IBM: The Developer's Toolkit for OS/2 Warp, Version 3: 3.5" Diskettes
  126.  
  127.       Note:  This product is located in the Developer Toolkits category.
  128.  
  129.    5. Start the diskette creation process by selecting the "Install product"
  130.       pop-up menu item.  By default, all diskettes will be created.
  131.  
  132.    6. Select the "Proceed" button to start the diskette creation, and
  133.       follow the instructions presented.
  134.  
  135. If you prefer to create the diskettes without using The Developer
  136. Connection for OS/2 Catalog program, you create the diskettes as 
  137. follows:
  138.  
  139.    1. Start an OS/2 Window or OS/2 Full Screen session.
  140.  
  141.    2. Change to the following directory on the compact disk drive:
  142.  
  143.          TOOLKITS\WARPTLKT\IMAGES
  144.  
  145.    3. Insert a blank diskette in drive A.  At the command prompt, type:
  146.  
  147.          LOADDSKF TK03401.IMG  A:/f
  148.  
  149.       This will create diskette one.
  150.  
  151.    4. Repeat step 3 for TK03402.IMG through TK03424.IMG.
  152.  
  153.    5. Once you have made all the diskettes, follow the steps in the next
  154.       section "Installing the Toolkit."
  155.  
  156.  
  157. Installing the Toolkit
  158. ________________________________________________________________
  159.  
  160. To install the Toolkit, do the following:
  161.  
  162.    1. Start the Toolkit Installation Program from the CD-ROM or diskettes
  163.       as follows:
  164.  
  165.       -  CD-ROM: 
  166.          From The Developer Connection for OS/2 Catalog, find
  167.          the product entitled:
  168.  
  169.             IBM: The Developer's Toolkit for OS/2 Warp, Version 3: CD Install
  170.  
  171.          Note:  This product is located in the Developer Toolkits
  172.          category.  Install the product by selecting the "Install product" 
  173.          pop-up menu item.  This action will bring up the Toolkit 
  174.          Installation program.
  175.  
  176.          If you prefer to install the Toolkit without using
  177.          The Developer Connection for OS/2 Catalog, start an OS/2 Window
  178.          or OS/2 Full Screen session.  Put the CD-ROM containing the
  179.          Toolkit in the CD-ROM drive and change directories as follows:
  180.  
  181.             CD TOOLKITS\WARPTLKT
  182.  
  183.          Type the following and press Enter:
  184.  
  185.             TKINSTAL
  186.  
  187.       -  DISKETTES: 
  188.          Put the first diskette into the a: drive (or other drive)
  189.          and type the following:
  190.  
  191.             a:\TKINSTAL
  192.  
  193.    2. The system displays the "IBM Developer's Toolkit for OS/2 Warp
  194.       Installation" window.  Select each component you want to install.
  195.       Depending on the components you select for installation, additional
  196.       components might be automatically selected for installation.
  197.       A plus (+) sign in a box in front of a component indicates that
  198.       the component has at least one level of subcomponents from which
  199.       you can select.  Select the plus sign in front of the component to
  200.       expand the list of components.
  201.  
  202.       Note:  The IBM Developer API Extensions for OS/2 Beta are not
  203.       preselected by default.  To install this Beta, expand the BETA
  204.       component and select the "Beta Developer API Extensions Support" 
  205.       component.
  206.  
  207.    3. If desired, change the default destination for the selected 
  208.       components by editing the "Destination" entry field.
  209.  
  210.    4. Select the "Options" push button to specify what updates to your
  211.       system are required.  You can choose to:
  212.  
  213.          -  Install the selected files
  214.          -  Register Workplace Shell* classes
  215.          -  Create Workplace Shell objects
  216.          -  Select the file where any CONFIG.SYS updates are to be made,
  217.             or deselect the "Write CONFIG.SYS updates to:" check box to
  218.             prevent the Toolkit Installation program from updating
  219.             CONFIG.SYS.
  220.  
  221.    5. To install all selected components of the Toolkit:
  222.  
  223.          a. Select the "Install" push button.
  224.          b. Follow the prompts in the message boxes to complete the installation.
  225.  
  226.    6. During installation, you may encounter a problem copying the file
  227.       SOM.IR because the file is in use.  This file has not changed from 
  228.       the last release, so you can select the "Ignore" push button on the
  229.       "Installation Status" dialog box and continue with the installation.
  230.  
  231.    7. The system displays a message box indicating successful completion of
  232.       the installation.
  233.  
  234.    8. To make the changes effective and have the Toolkit folder appear 
  235.       on the Desktop, shut down and restart your system.  After the Toolkit
  236.       is installed, the Toolkit folder appears on the desktop, represented
  237.       by the toolbox icon.  If you installed the entire Toolkit, the folder
  238.       will contain the following subfolders for the installed components:
  239.  
  240.          -  Beta
  241.          -  C REXX Samples
  242.          -  Development Tools
  243.          -  Multimedia Bitmaps
  244.          -  Multimedia Sample Programs
  245.          -  OS/2 Samples
  246.          -  Presentation Manager/2 Samples
  247.          -  Toolkit Information
  248.          -  Try Me!
  249.          -  Workplace Shell Samples
  250.  
  251. Note:  If the entire Toolkit is not required, components may still be
  252. deselected in the usual manner.  However, it is important that the 
  253. paths are ot changed from their defaults for all components other than 
  254. the root, because the directory structure on the CD cannot be changed.
  255.  
  256.  
  257. UPDATES TO CONFIG.SYS
  258. ________________________________________________________________
  259.  
  260. The Toolkit Installation Program adds the paths of all needed environment
  261. variables with the appropriate Toolkit path.  These variables include,
  262. but are not limited to:
  263.  
  264.    -  BOOKSHELF
  265.    -  DPATH
  266.    -  HELP
  267.    -  INCLUDE
  268.    -  LIB
  269.    -  LIBPATH
  270.    -  PATH
  271.    -  SMEMIT
  272.    -  SMINCLUDE
  273.    -  SOMBASE
  274.    -  SOMIR
  275.    -  TMP
  276.  
  277.  
  278. KNOWN LIMITATIONS AND RESTRICTIONS
  279. ________________________________________________________________
  280.  
  281. This section provides up-to-the-minute testing information on:
  282.  
  283.    -  IBM Developer API Extensions for OS/2
  284.    -  Real-time MIDI support and networking limitations
  285.    -  File conflicts with the IBM VisualAge* C++ for OS/2 product
  286.  
  287.  
  288. IBM Developer API Extensions for OS/2
  289. ________________________________________________________________
  290.  
  291. "IBM Developer API Extensions for OS/2 Guide" Changes:  Although 
  292. documented in the Guide, these APIs are not supported:
  293.  
  294.    -  lstrcmp
  295.    -  lstrcmpi
  296.    -  GetTextExtentPoint32
  297.    -  MapVirtualKey
  298.  
  299. WinMain Function:  To be able to use the Windows** WinMain function,
  300. use the OS/2 Warp main function located in the following subdirectory:
  301.  
  302.    TOOLKIT\BETA\SAMPLES\DAPIE\WINMAIN\MAIN.C
  303.  
  304. You can also use the main function, a DLL, in the following subdirectory:
  305.  
  306.    TOOLKIT\BETA\SAMPLES\DAPIE\DLLMAIN\DLLMAIN.C
  307.  
  308. MAIN.C gets compiled and linked with the module containing WinMain and
  309. creates an OS/2 Warp executable.  If you do not use the OS/2 Warp main
  310. function, you will receive a link error stating that there is no starting
  311. address for your program.
  312.  
  313. Recommended C Set++* Compiler Options:  Because the calling convention
  314. for IBM Developer API Extensions for OS/2 APIs is always _System in OS/2
  315. (the default calling convention for the C Set++ Compiler is _Optlink),
  316. it is recommended that applications use the C Set ++ /Ms and /Wpro+
  317. compiler options.
  318.  
  319. Resource Compiler Changes:  As an enhancement for IBM Developer API 
  320. Extensions for OS/2, the Resource Compiler now supports string ids for 
  321. resources in addition to integers.  The Resource Translator in SMART 
  322. allows the choice to convert resources in one of the following formats:
  323.  
  324.    1. String id:  Use the "Supports String ID" check box choice when
  325.       using the IBM Developer API Extensions for OS/2 APIs for resources.
  326.       The .HHH file is not required. The Resource Compiler accepts the
  327.       resources with ids specified as quoted strings.
  328.  
  329.    2. Integer id:  Ensure the check box for "Support String ID" is not
  330.       selected in order to generate the required .HHH file.  This file
  331.       defines the resource ids for use with the OS/2 native APIs.
  332.  
  333. Testing Items:  The following items, found during testing, will be fixed
  334. for the GM product:
  335.  
  336.     Functions:
  337.  
  338.       CheckDlgButton:  Does not check the button.
  339.  
  340.       CheckMenuItem:  If a NULL handle is passed into this function, 
  341.       the return code should be -1, but it is 0 (MF_UNCHECKED).
  342.  
  343.       CreateRoundRectRgn:  See SetWorldTransform.
  344.  
  345.       DlgDirList:  Does not sort the contents of the list box.
  346.  
  347.       DPtoLP:  When called with valid parameters, this call returns 0, 
  348.       but should return 1.
  349.  
  350.       DragQueryPoint:  Returns a negative y value.
  351.  
  352.       EnableScrollBar:
  353.  
  354.         1. When calling this function as follows, it should return FALSE,
  355.            but it returns TRUE:
  356.  
  357.               EnableScrollBar(hWndParent, SB_BOTH, ESB_DISABLE_BOTH);
  358.  
  359.         2. When calling this function as follows, it always returns FALSE:
  360.  
  361.               EnableScrollBar(hWndParent, SB_VERT, ESB_ENABLE_BOTH);
  362.  
  363.       EnumFontFamilies:  When this function is passed valid parameters,
  364.       it returns FALSE.
  365.  
  366.       FindResource:  When calling this function passing a valid resource 
  367.       ID and resource type to DosQueryResourceSize, FindResource 
  368.       returns 87 (indicating an invalid parameter).
  369.  
  370.       FlashWindow:  When this function is called and passed the handle 
  371.       of an inactive window, this function should return FALSE.  
  372.       However, it returns TRUE.
  373.  
  374.       GetClassLong:  For GCL_STYLE, returns 0 for edit controls.
  375.  
  376.       GetMenuState:  When this function is called as follows, 
  377.       it returns -1:
  378.  
  379.          nRet = GetMenuState(hMenuSave, 2, MF_BYPOSITION);
  380.  
  381.       However, this call is valid and should return a value other than -1.
  382.  
  383.       FrameRgn:  See SetWorldTransform.
  384.  
  385.       GetDeviceCaps:  This function returns rather large numbers for 
  386.       aspect x and y.  Overflow is possible if you multiply using these 
  387.       numbers.
  388.  
  389.       GetExitCodeProcess:  Does not return the value passed to ExitProcess
  390.       by the process in question when that process is not a child process.
  391.  
  392.       MessageBox:  Using Close from the system menu to dismiss a message 
  393.       box that specifies MB_YESNO gives you an incorrect return code from 
  394.       the MessageBox function.
  395.  
  396.       NameConvertUnicodeToPath:  Sporadically, when IBM Developer API 
  397.       Extensions for OS/2 code tries to access the NameConvertUnicodeToPath 
  398.       function, an access violation occurs.  Once this problem occurs, 
  399.       none of the Registry functions can be used successfully.  To recover 
  400.       from this problem, see the "IBM Developer API Extensions for OS/2 
  401.       Guide."
  402.  
  403.       PrintDlg:  If you are using the PrintDlg dialog, and if you are 
  404.       creating your own printer DC, and if your target printer has 
  405.       "print to file" selected, then you will be presented with two 
  406.       "Print to a file" dialogs.  Do the following:
  407.  
  408.          a. Cancel the first one
  409.          b. Type the name of the file into the second one
  410.  
  411.       If you use the first one, a zero length file will be created.
  412.  
  413.       ScrollDC:  This function does not redraw the blank area left due to
  414.       the scrolling of a rectangle of bits.
  415.  
  416.       ScrollWindow:  This function repaints the screen after bits are s
  417.       crolled.
  418.  
  419.       ScrollWindowEx:  This function returns FALSE when it should return 
  420.       TRUE.
  421.  
  422.       SendMessage:  For WM_CUT, WM_COPY, WM_PASTE and WM_CLEAR 
  423.       messages to an edit control, this function does not work.  The 
  424.       keyboard equivalents, however, do work.
  425.  
  426.       SetClassLong:  For GCL_BACKGROUND, this function does not work.
  427.  
  428.       SetParent:  This function returns 0 rather than the handle to the
  429.       previous parent when a child window is created under hWnd 
  430.       ownership.
  431.  
  432.       SetWorldTransform:  If this function is used to set a new world 
  433.       space transformation matrix then regions may not be displayed 
  434.       correctly with regards to the transformation.
  435.  
  436.       StretchBlt:  With negative values for x and y, this function does not
  437.       invert in the y direction.
  438.  
  439.       TrackPopupMenu:  Menus created with this function are not visible;
  440.       they blink but do not stay on the screen.
  441.  
  442.       WinExec:  If you are using this API to run a program, you may find
  443.       that the program never runs or appears to hang. If this happens, 
  444.       shut down and restart your system to clear the condition.
  445.  
  446.     Messages:
  447.  
  448.       WM_CHAR:  Not sent to dialog procedures or subclassed window 
  449.       procedures.
  450.  
  451.       WM_DESTROY:  If you close an application by pressing ALT+F4, this
  452.       message is not sent.
  453.  
  454.       WM_MDISETMENU:  Does not append the name to the title bar.
  455.  
  456.       WM_NC:  Non-client messages (WM_NC) are not functional.
  457.  
  458.       WM_SYSCHAR:  Not sent for menu items.
  459.  
  460.     Miscellaneous:
  461.  
  462.       1. Large pen sizes tend to distort shapes.
  463.  
  464.       2. Combination box lists may not collapse after selecting an item.
  465.  
  466.       3. Clipping the cursor to a window causes the cursor to disappear
  467.          when the window is minimized.
  468.  
  469.       4. MDI child windows disappear when minimized--that is, no icons 
  470.          are available and the WINDOW menu item does not have an entry 
  471.          for the minimized window. Retrieve the windows by pressing 
  472.          CTRL+F4.
  473.  
  474.          Also, a MDI child window should accept CTRL+F4 to exit the
  475.          MDI child window and CTRL+F6 to move from one to another of
  476.          the open MDI child windows.  These key sequences are not
  477.          implemented at this time.  Both ALT+F4 and CTRL+F4 send a
  478.          WM_CLOSE message to the frame window and therefore may cause
  479.          your application to end prematurely.
  480.  
  481.       5. Using a control item's mnemonic in a dialog box does not change
  482.          focus to that item.
  483.  
  484.       6. There is a memory leak in DDE when running a large number of
  485.          transactions.
  486.  
  487.       7. The ESC key does not dismiss a dialog box.
  488.  
  489.       8. The default push buttons do not work:  You have to click on 
  490.          the button.
  491.  
  492.       9. The owner drawn variable height list boxes and combination boxes
  493.          are not functional in this Beta.  However, the styles are located
  494.          in the header file OS2CTLWX.H to allow you to compile.
  495.  
  496.      10. The tab key does not change focus between dialog controls.  You
  497.          must use your mouse.
  498.  
  499.      11. When using two SMART tables--W16DAPIE.TBL and DAPIE16.TBL--to
  500.          calculate migration effort, the report that identifies 
  501.          non-supported keywords provides an incorrect migration effort 
  502.          calculation.
  503.  
  504.  
  505. Tested Sound Cards for New Real-Time MIDI Support
  506. ________________________________________________________________
  507.  
  508. The real-time MIDI support that is being introduced in the BETA component
  509. of the Toolkit has been successfully tested with the following sound cards:
  510.  
  511.    -  SoundBlaster** 16
  512.    -  Jazz16
  513.    -  SoundBlaster AWE32 (works with external MIDI synthesizer only)
  514.  
  515. Currently, the new real-time MIDI support does not work with the following
  516. sound cards:
  517.  
  518.    -  Pro AudioSpectrum 16**
  519.    -  SoundBlaster AWE32 (does not work with internal wave synthesizer)
  520.  
  521.  
  522. Network Functions Limitations
  523. ________________________________________________________________
  524.  
  525. Currently, the receive function used for networking (WarpNetPackRecv) can
  526. only receive header information without packet data.
  527.  
  528.  
  529. IBM VisualAge C++ for OS/2
  530. ________________________________________________________________
  531.  
  532. This version of the Toolkit supports the C Set ++ Version 2.1 Compiler.
  533.  
  534. A version of the Toolkit ships with the IBM VisualAge C++ for OS/2 product.
  535. The SOM files that ship with IBM VisualAge C++ for OS/2, including IDL and
  536. DLL files, are more recent than those shipped with this version of the
  537. Toolkit.  If you are using IBM VisualAge C++ for OS/2, be sure to use the
  538. SOM files shipped with that product instead of those shipped with this
  539. version of the Toolkit.
  540.  
  541. However, the Warp Toolkit Development Tools, such as the Resource Compiler,
  542. shipped with this version of the Toolkit are more recent than those
  543. shipped with IBM VisualAge C++ for OS/2.  Therefore, be sure to use the
  544. development tools shipped with this version of the Toolkit for your OS/2
  545. development.
  546.  
  547. Do not install the Toolkit samples shipped with this version of the Toolkit
  548. if you are using the VisualAge C++ compiler.  Use instead the sample programs
  549. shipped with the VisualAge C++ compiler; they are more recent than those
  550. shipped with this version of the Toolkit.  If you use the samples shipped
  551. with this version of the Toolkit and compile them with the VisualAge C++
  552. compiler, the compiler will generate link errors.
  553.  
  554. ________________________________________________________________
  555.  
  556. Thank you for your continued interest in the OS/2 Operating System.
  557. ________________________________________________________________
  558.  
  559.  
  560. TRADEMARK INFORMATION
  561. _____________________
  562.  
  563.  
  564. The following terms, denoted by an asterisk (*) in this file, are trademarks or
  565. registered trademarks of the IBM Corporation in the United States or other
  566. countries:
  567.  
  568.    -------------------------------------------------------
  569.    C Set ++
  570.    -------------------------------------------------------
  571.    IBM
  572.    -------------------------------------------------------
  573.    OS/2
  574.    -------------------------------------------------------
  575.    Presentation Manager/2
  576.    -------------------------------------------------------
  577.    VisualAge
  578.    -------------------------------------------------------
  579.    Workplace Shell
  580.    -------------------------------------------------------
  581.  
  582.  
  583. The following terms, denoted by a double asterisk (**) in this publication, are
  584. trademarks of other companies:
  585.  
  586.    -------------------------------------------------------
  587.    Intel386                    Intel
  588.    Pro AudioSpectrum 16        Media Vision, Inc.
  589.    Sound Blaster               Creative Technology, Ltd.
  590.    Windows                     Microsoft Corporation
  591.    -------------------------------------------------------
  592.  
  593. IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING WITHOUT
  594. LIMITATION, WARRANTIES OF FITNESS AND MERCHANTABILITY WITH RESPECT TO THE
  595. INFORMATION IN THIS DOCUMENT.  BY FURNISHING THIS DOCUMENT, IBM GRANTS NO
  596. LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS.
  597.  
  598. Copyright IBM Corporation, 1995, all rights reserved.
  599.  
  600. ________________________________________________________________
  601.  
  602. END-OF-README-FILE
  603. ________________________________________________________________
  604.