home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / o / os2tk1.zip / DISK1.DSK / READ.ME < prev    next >
Text File  |  1992-12-15  |  36KB  |  1,098 lines

  1.    Welcome to the IBM Developer's Toolkit for OS/2
  2.    2.1.  This information has been prepared to
  3.    assist you in your application development
  4.    activities.
  5.  
  6.  
  7.  
  8. ADDITIONAL DEVELOPER INFORMATION
  9. ________________________________
  10.  
  11.    IBM participates in CompuServe forums.  If you
  12.    are online as a CompuServe member, simply type
  13.    "GO IBMOS2" at the ! prompt and you will be
  14.    provided with a menu of the available OS/2
  15.    forums.
  16.  
  17.  
  18. TOOLKIT INSTALLATION
  19. ____________________
  20.  
  21.    The toolkit installation program has been
  22.    updated to take advantage of new features in
  23.    the Workplace Shell.  The Toolkit folder on the
  24.    desktop, illustrated by the toolbox icon,
  25.    contains three other folders.  These folders
  26.    are:
  27.  
  28.    o   PM Development Tools
  29.    o   Toolkit Information
  30.    o   Sample Programs
  31.  
  32.    You may install the Toolkit for OS/2 2.1 on a
  33.    1.3 system.  The installation program will
  34.    transfer your files and update the environment
  35.    variables; however, no programs will be
  36.    registered on the desktop.
  37.  
  38.  
  39. KWIKINF UTILITY
  40. _______________
  41.  
  42.    KwikINF provides a convenient method of
  43.    accessing information in OS/2 2.1 online
  44.    documents.  Once KwikINF starts, pressing a
  45.    hot-key sequence causes the program to pop up
  46.    and search for a text string of your choice.
  47.  
  48.    You can specify three KwikINF options from the
  49.    command line.  An example of the command line
  50.    syntax follows:
  51.  
  52.             KwikINF [/C] [/T] [/?]
  53.  
  54.    where:
  55.  
  56.  
  57. KWIKINF
  58.  
  59.    Entering KwikINF at the command prompt with no
  60.    options starts KwikINF.  After entering this
  61.    command, the default hot-key sequence (ALT + Q)
  62.    is enabled.
  63.  
  64.    /T        Entering the /T option will terminate
  65.              KwikINF and disable the hot-key
  66.              sequence.  KwikINF will be terminated
  67.              for all active sessions.
  68.    /C        Entering the /C option will display
  69.              the "Configure KwikINF" window.  Use
  70.              the "Configure KwikINF" window to
  71.              customize KwikINF values.
  72.    /?        entering the /? will display the
  73.              following information.
  74.  
  75.                       Usage: KwikINF [Option]
  76.                        Option    Description
  77.                          /C      Configure KwikINF
  78.                          /T      Terminate KwikINF
  79.                          /?      This short help list
  80.  
  81.  
  82.    Pressing the hot-key sequence brings to the
  83.    foreground KwikINF's "Search" window.  KwikINF
  84.    will work in any of the OS/2 sessions types:
  85.    full screen, AVIO window, and PM window.  If
  86.    your application is running in a full-screen
  87.    session, an AVIO window, or an active PM window
  88.    is a multi-line entry (MLE) field, KwikINF will
  89.    retrieve the word the cursor is on and
  90.    automatically place it in the entry field of
  91.    the "Search" window.  In PM windows, you can
  92.    use the hot-key sequence to display the search
  93.    window; however, you must enter the search
  94.    string manually.  KwikINF does not pre-fill the
  95.    search string field for PM windows.  KwikINF
  96.    cannot determine the word under the cursor in
  97.    these types of sessions because they are
  98.    graphics sessions and the characters are stored
  99.    as bit maps rather than as characters.
  100.  
  101.    To find information on a string, do the
  102.    following:
  103.  
  104.    o   If you are in a full-screen session, an
  105.        AVIO window, or MLE window, position the
  106.        cursor on the string you want to search
  107.        for, then press the hot-key sequence.
  108.        KwikINF retrieves the word at the cursor
  109.        and places it in the entry field of the
  110.        "Search" window.
  111.    o   If you are in a PM window or an AVIO
  112.        session, press the hot-key sequence, then
  113.        type the word to search for in the entry
  114.        field of the "Search" window.
  115.  
  116.    KwikINF then takes you to the entry for the
  117.    search string in the online document.
  118.  
  119.    NOTE: You should not add KwikINF to your
  120.    STARTUP.CMD if it is followed by an EXIT
  121.    statement.  Instead, create a KwikINF program
  122.    object.
  123.  
  124.  
  125. LINK386 UTILITY
  126. _______________
  127.  
  128.    It is recommended that the ALIGN, BASE, and
  129.    EXEPACK options be used when linking all
  130.    executables.  This will compress them in size
  131.    and improve their performance.
  132.  
  133.    Use /ALIGN:4 for 32-bit applications, /ALIGN:16
  134.    for 16-bit applications.  For .EXE files,
  135.    /BASE:0x10000 option must be used.  Any other
  136.    value produces a warning.  For .DLL files, use
  137.    /BASE:0x12000000 (or a lesser value).
  138.  
  139.  
  140. ONLINE IPF REFERENCE
  141. ____________________
  142.  
  143.    There is a dynamic link library (IPF.DLL)
  144.    associated with the compiled example of
  145.    "Application-Controlled Window Example."
  146.    However, IPF.DLL is installed with the Sample
  147.    Programs component of the Toolkit.  Therefore,
  148.    unless the Sample Programs component is
  149.    installed, you will be unable to view the
  150.    animation provided by the IPF.DLL in the
  151.    Application-Controlled Window Example in the
  152.    online IPF Reference.
  153.  
  154.  
  155. OS/2 2.0 ENHANCED EDITOR
  156. ________________________
  157.  
  158.    If you attempt to access additional information
  159.    for a text string by pressing Ctrl+H, the
  160.    following message might appear:
  161.  
  162.             epmkwhlp.ndx file not found
  163.  
  164.    To avoid this message, add the following to the
  165.    DPATH statement in CONFIG.SYS:
  166.  
  167.             x:\toolkt20\book;
  168.  
  169.        where "x" is the drive location for the Toolkit.
  170.  
  171.  
  172. SAMPLE PROGRAMS
  173. _______________
  174.  
  175.    The following sample programs are new or
  176.    enhanced for this Toolkit update.
  177.  
  178.  
  179. PALETTE MANAGER SAMPLE PROGRAM
  180.  
  181.    PALETTE MANAGER is new and demonstrates 32-bit
  182.    graphics functions including:
  183.  
  184.    o   Creating a window using a custom palette
  185.        and animation.
  186.    o   Using menus with switches, and modifying
  187.        the menu text.
  188.    o   Using multiple threads and semaphores in
  189.        the PM environment.
  190.    o   Displaying graphics on the screen using
  191.        outline fonts and clip paths.
  192.    o   On-line help.
  193.  
  194.    Requirements are a XGA adapter card fully
  195.    populated with 1 megabyte of RAM and the 32-bit
  196.    Graphics Engine.
  197.  
  198.    When started, PALETTE displays a standard
  199.    window with a large IBM logo in the foreground.
  200.    The user has the ability to change the IBM logo
  201.    to the OS/2 logo.  If the user resizes the
  202.    window, the logo is scaled and redrawn to fit
  203.    the new window size.  The user can also control
  204.    the animation speed from the PALETTE menu.
  205.  
  206.    The animation is performed by creating a clip
  207.    path which represents the outline of the logo
  208.    characters (which are displayed using an
  209.    outline font); setting the clip path to the
  210.    presentation space; and then drawing a series
  211.    of lines to the presentation space.  Each line
  212.    is drawn with an incrementing color index.
  213.    Palette animation is performed using the 32-bit
  214.    GpiAnimatePalette function call.
  215.  
  216.    In order for PALETTE to remain responsive to
  217.    system and user messages, no animation is
  218.    performed on the main window procedure thread.
  219.    A second thread is created from which all
  220.    animation is performed.
  221.  
  222.  
  223. STYLE SAMPLE PROGRAM
  224.  
  225.    STYLE has new function that demonstrates the
  226.    detection of a font that does not conform to
  227.    the International Standards Organization (ISO
  228.    9241).  When the user selects a non-compliant
  229.    font in the standard font dialog, a message box
  230.    is displayed to inform the user.
  231.  
  232.    The fsSelection field in the FONTMETRICS
  233.    structure can be tested with the following bit
  234.    to determine if the current font has been
  235.    tested for ISO conformance:
  236.  
  237.        FM_SEL_ISO9241_TESTED
  238.  
  239.    The panose.fbFailedISO field in the FONTMETRICS
  240.    structure can be tested with the following bits
  241.    to determine if the current font fails to
  242.    conform to ISO 9241 standards on specific
  243.    displays that are known to comply:
  244.  
  245.        FM_ISO_9518_640
  246.        FM_ISO_9515_640
  247.        FM_ISO_9515_1024
  248.        FM_ISO_9517_640
  249.        FM_ISO_9517_1024
  250.  
  251.    These defines and additional information can be
  252.    found in OS2DEF.H which is shipped with this
  253.    product.The path to get to the OS2DEF.H defines
  254.    is:
  255.  
  256.      x:\TOOLKT20\C\OS2H
  257.  
  258.  
  259. WPCAR SAMPLE PROGRAM
  260.  
  261.    WPCAR is the sample program that demonstrates
  262.    how to create a Workplace Shell object.   New
  263.    to WPCAR is its ability to set an exception
  264.    handler for memory access violations.  To
  265.    demonstrate this, a new menu item was added to
  266.    WPCAR that calls a function that causes an
  267.    exception.  A message indicates the program's
  268.    exception handler is returning control to the
  269.    cleanup code.
  270.  
  271.    Additional README files concerning sample
  272.    programs are available in these
  273.    directories:\TOOLKT20\C\SAMPLES\IMAGE and
  274.    \TOOLKT20\C\SAMPLES\TEMPLATE.
  275.  
  276.  
  277. WORKFRAME/2
  278. ___________
  279.  
  280.    The IBM WorkFrame/2 allows you to integrate
  281.    various tools into your application development
  282.    environment.  Tools, such as the Dialog Editor,
  283.    Font Editor, Icon Editor, Information
  284.    Presentation Facility Compiler, and Resource
  285.    Compiler, can then be selected from the "Tools"
  286.    pull-down menu of WorkFrame/2.
  287.  
  288.    This toolkit integration is optional.  To help
  289.    you add the tools into the WorkFrame
  290.    environment easily, a special file
  291.    (TOOLKT20.INI) is provided in the
  292.    \TOOLKT20\OS2BIN directory.
  293.  
  294.    To integrate the toolkit tools into the
  295.    WorkFrame/2, do the following:
  296.  
  297.    1.  After completing Toolkit installation,
  298.        install the IBM WorkFrame/2.  Make sure the
  299.        CONFIG.SYS file is updated for the
  300.        WorkFrame/2, either by selecting the
  301.        "Update CONFIG.SYS" checkbox or by updating
  302.        it manually.
  303.    2.  Reboot your computer, as specified in the
  304.        WorkFrame/2 installation procedure.
  305.    3.  At the OS/2 command line, type:
  306.  
  307.                    addtool \toolkt20\os2bin\toolkt20.ini
  308.  
  309.  
  310.    When you start WorkFrame/2 and select "Tools"
  311.    from the menu bar, entries for the five Toolkit
  312.    tools appear in a pull-down menu.
  313.  
  314.  
  315. BIDIRECTIONAL NATIONAL LANGUAGE SUPPORT
  316. _______________________________________
  317.  
  318.     Information on how to use the BIDI programming
  319.    interface can be found in
  320.    \TOOLKT20\C\SAMPLES\BIDI\READ.ME.
  321.  
  322.  
  323. DEVICE DRIVER PROGRAMMING INTERFACES
  324. ____________________________________
  325.  
  326.    The header files contained in the
  327.    \TOOLKT20\C\OS2H\DASD directory define the data
  328.    structures used in the layered DASD/SCSI device
  329.    driver interface.  Documentation is available
  330.    from IBM for constructing device drivers that
  331.    work with this interface.  This document is
  332.    primarily targeted for development
  333.    organizations that:
  334.  
  335.    o   Develop device drivers for SCSI adapters
  336.    o   Develop device drivers for non-standard
  337.        DASD hardware interfaces
  338.    o   Develop OS/2 kernel extensions that add
  339.        value to existing DASD or SCSI subsystems
  340.        DASD data encryption packages, Redundant
  341.        Array of Inexpensive Disks (RAID) packages,
  342.        and other data striping packages fall into
  343.        this category.
  344.  
  345.    Until the SCSI Device Driver Reference is
  346.    published, you can acquire this document by
  347.    contacting: IBM BTIG (Zip 1424), P.O. Box 1328,
  348.    Boca Raton, FL 33432.
  349.  
  350.  
  351. DOS PROGRAMMING INTERFACE
  352. _________________________
  353.  
  354.    The DosSetDOSProperty() and
  355.    DosQueryDOSProperty() functions in BSEDOS.H are
  356.    not supported.  Do not use these application
  357.    programming interfaces.
  358.  
  359.  
  360. GRAPHICS PROGRAMMING INTERFACE
  361. ______________________________
  362.  
  363.    The GpiFloodFill function may produce incorrect
  364.    results if another window is visible on top of
  365.    any of the area being filled.  You will get
  366.    correct results if your application is in the
  367.    foreground, and no windows or dialogs owned by
  368.    your application are visible during flood-fill
  369.    operations.
  370.  
  371.  
  372. WORKPLACE PROGRAMMING INTERFACE
  373. _______________________________
  374.  
  375.  
  376.  
  377. WORKPLACE CLASSES, INSTANCE METHODS, AND CLASS METHODS
  378.  
  379.    wpFindViewItem - Do not use method, it may be
  380.    removed from the header files in the future.
  381.    Use wpFindUseItem to find VIEWITEM structures
  382.    to achieve the same functionality.
  383.  
  384.    wpclsQueryObject now locks the object before
  385.    returning it. If you are using this method,
  386.    make sure you unlock the object after you are
  387.    done with it.
  388.  
  389.  
  390. WIN PROGRAMMING INTERFACE
  391. _________________________
  392.  
  393.    The kernel debug version of PMWIN.DLL contained
  394.    in the Toolkit executes an INT 3 instruction,
  395.    causing a break in the debugger.  The INT 3 is
  396.    executed only in 32-bit API parameter
  397.    validation on the debug version of PMWIN.DLL;
  398.    all other errors will not execute an INT 3.
  399.  
  400.    For the WinCreateWindow function, the first
  401.    USHORT the control data parameter points to is
  402.    assumed to be the length of the data block.
  403.  
  404.  
  405. DEBUGGING PROGRAMS
  406. __________________
  407.  
  408.    In this release, the DosDebug API will not
  409.    permit the debugging of code that is in use by
  410.    more than one process.
  411.  
  412.  
  413. DDE BETWEEN PM AND WINDOWS PROGRAMS
  414. ___________________________________
  415.  
  416.    Making modifications to Windows programs in
  417.    order to use dynamic data exchange (DDE)
  418.    communications with PM programs helps
  419.    facilitate a gradual migration of applications
  420.    to PM.  Not all data formats are automatically
  421.    converted when doing DDE between Windows
  422.    programs and PM programs  (DDE set PUBLIC).
  423.    The following formats are converted
  424.    automatically by OS/2 2.1:
  425.  
  426.             PM Application               Windows Application
  427.             Data Format                  Interpretation
  428.             --------------------         --------------------
  429.             PM BITMAP                    Windows DIB
  430.             TEXT                         TEXT (codepage 819)
  431.             PM private                   Windows private
  432.  
  433.  
  434.             Windows Application          PM Application
  435.             Data Format                  Interpretation
  436.             --------------------         --------------------
  437.             Windows DIB                  PM BITMAP
  438.             TEXT (codepage 819)          TEXT
  439.             Windows private              PM Private
  440.  
  441.    Notes:
  442.  
  443.    1.  Code page translation (Windows 819 to/from
  444.        current PM codepage) is done for topic name
  445.        in all cases.
  446.  
  447.    2.  When data conversion is not automatically
  448.        done, programs can still communicate via
  449.        DDE if the two programs are able to do the
  450.        data conversion and pass private data
  451.        formats.
  452.  
  453.  
  454. PM REFERENCE UPDATES
  455. ____________________
  456.  
  457.  
  458.  
  459. RESOURCE COMPILER
  460.  
  461.    See the Tools Reference for updated resource
  462.    compiler information.
  463.  
  464.  
  465. DATA TYPES
  466.  
  467.    o   The following structures are found in the
  468.        Bit-Map File Format section, they should be
  469.        in the datatype section also.
  470.  
  471.        -   BITMAPARRAYFILEHEADER
  472.        -   BITMAPARRAYFILEHEADER2
  473.        -   BITMAPFILEHEADER
  474.        -   BITMAPFILEHEADER2.
  475.  
  476.    o   The following structures are found in the
  477.        Font-File Format section, they should be in
  478.        the datatype section.
  479.  
  480.        -   ADDITIONALMETRICS
  481.        -   FOCAFONT
  482.        -   FOCAMETRICS
  483.        -   FONTDEFINITIONHDR
  484.        -   FONTFILEMETRICS
  485.        -   FONTSIGNATURE
  486.  
  487.  
  488. PROGRAMMING CONSIDERATIONS
  489. __________________________
  490.  
  491.    Existing applications (small and tiny model)
  492.    must have a 4K stack available when they enter
  493.    system calls. If they do not have a 4K stack
  494.    available, the stack can overflow into the data
  495.    area.  We have found in our testing, that some
  496.    16-bit small and tiny model applications have
  497.    not followed the guidelines and encountered
  498.    problems.
  499.  
  500.  
  501. NEW FUNCTIONS FOR THE OS/2 2.1 CONTAINER CONTROL
  502. ________________________________________________
  503.  
  504.    In response to requests from our users, the
  505.    following new functions have been added to the
  506.    OS/2 2.1 container control.
  507.  
  508.  
  509. DETERMINING THE WIDTH OF A COLUMN IN THE DETAILS VIEW
  510.  
  511.    There are times when you may want to determine
  512.    the width of a column in the details view, such
  513.    as to allow the user to tab the split bar
  514.    between columns.  New function has been added
  515.    to the container control to allow you to
  516.    determine the width of the data in a column.
  517.    You can then compute the width of the entire
  518.    column by adding the width of the data to the
  519.    left and right margins of the column.
  520.  
  521.    To determine the width of a column:
  522.  
  523.    1.  Define an attribute with a value of 0X0200
  524.        and give it a name such as CMA_DATAWIDTH.
  525.    2.  Issue the CM_QUERYDETAILFIELDINFO message
  526.        with the following values:
  527.        a.  Provide a pointer to the FIELDINFO
  528.            structure in param1.
  529.        b.  Specify your attribute (see Step 1) in
  530.            param2.
  531.        c.  Request a return value with a type of
  532.            LONG, not PFIELDINFO, to retrieve the
  533.            width of the column in the FIELDINFO
  534.            structure to which you are pointing.
  535.            The value returned is the width of the
  536.            data (text, icon, or bit map) in this
  537.            column.
  538.    3.  Use the GpiQueryFontMetrics function to
  539.        query the average character width of the
  540.        font used by the container.  This value
  541.        will be used to calculate the total column
  542.        width.
  543.    4.  Multiply 3 times the average character
  544.        width and add this to the data width
  545.        returned from step 2 for all columns except
  546.        the following:
  547.        a.  The first and last columns in each
  548.            split window.  In these cases, multiply
  549.            2.5 times the average character width
  550.            and add the column data width returned
  551.            from step 2.
  552.        b.  The only other special case is where
  553.            there is only 1 column in either the
  554.            left or right split windows.  In this
  555.            case you would multiply 2 times the
  556.            average character width and add the
  557.            column data width returned from step 2.
  558.    5.  The value returned is the total width of
  559.        the column.
  560.  
  561.  
  562. PROVIDING SOURCE EMPHASIS FOR CONTAINER ITEMS
  563.  
  564.    Source emphasis is the type of emphasis that
  565.    the Workplace Shell provides when a context
  566.    menu is displayed.  It appears as a dotted box
  567.    with rounded corners that surrounds the item
  568.    for which the context menu is requested and an
  569.    item that is being dragged.
  570.  
  571.    To provide source emphasis for container items:
  572.  
  573.    1.  Define an attribute with a value of
  574.        0X00004000L and give it a name such as
  575.        CRA_SOURCE.
  576.    2.  Issue the CM_SETRECORDEMPHASIS message with
  577.        the following values:
  578.        a.  Provide a pointer to the RECORDCORE or
  579.            MINIRECORDCORE structure in param1.
  580.  
  581.            You can provide source emphasis for the
  582.            entire container by setting param1 to
  583.            NULL.
  584.        b.  Set the usChangeEmphasis parameter to
  585.            TRUE in param2.
  586.        c.  Specify your attribute (see Step 1) in
  587.            the fEmphasisAttribute parameter in
  588.            param2.
  589.  
  590.    To remove source emphasis, follow the same
  591.    procedure outlined above, but set the
  592.    usChangeEmphasis parameter in param2 to FALSE
  593.    instead of TRUE.
  594.  
  595.  
  596. SEARCHING FOR EXACT TEXT STRING MATCHES
  597.  
  598.    There may be times when you need to search the
  599.    container for a text string that is an exact
  600.    match of your search string argument.
  601.  
  602.    To find an exact match:
  603.  
  604.    1.  Define an attribute with a value of
  605.        0X10000000L and give it a name such as
  606.        CV_EXACTMATCH.
  607.    2.  In the SEARCHSTRING data structure, specify
  608.        values for the fields as you normally
  609.        would, with the following exception:
  610.        a.  Specify your attribute (see Step 1),
  611.            along with an attribute for the type of
  612.            view being displayed in the container,
  613.            in the usView field.  For example:
  614.  
  615.                        CV_EXACTMATCH | CV_ICON
  616.  
  617.            NOTE: In the OS/2 2.0 Programming
  618.            Reference, Vol. III, the field for
  619.            specifying the exact match attribute
  620.            and the type of view should be usView,
  621.            not ulView.  The type associated with
  622.            the field, however, is ULONG.  You must
  623.            specify usView to match the information
  624.            in the header file.
  625.  
  626.  
  627. ADDENDUM TO PROGRAMMING GUIDE VOL. II, CHAPTER 33 (PG. 22)
  628. __________________________________________________________
  629.  
  630.  
  631.  
  632. WORKPLACE RENDERING MECHANISM:
  633.  
  634.    Workplace shell uses the rendering mechanism of
  635.    <DRM_OBJECT,DRF_OBJECT> to communicate
  636.    information about the workplace objects
  637.    involved in a direct manipulation.
  638.  
  639.    For the <DRM_OBJECT,DRF_OBJECT> rendering
  640.    mechanism, pdraginfo->hwndSource is expected to
  641.    be the window handle of the container holding
  642.    objects which were inserted via the
  643.    _wpCnrInsertObject method.
  644.  
  645.    For each dragitem, pdragitem->ulItemID is the
  646.    PMINIRECORDCORE pointer associated with the
  647.    object.  The object can be retrieved using
  648.    OBJECT_FROM_PREC on pdragitem->ulItemID.
  649.  
  650.    Once the target object has completed
  651.    processing, it should send a DM_ENDCONVERSATION
  652.    message to the window handle in
  653.    pdragitem->hwndItem.
  654.  
  655.  
  656. DOSSHUTDOWN API
  657. _______________
  658.  
  659.    The DosShutDown API is documented in the OS/2
  660.    2.0 Control Program ProgrammingReference on
  661.    page 2-339.  This API has been enhanced to
  662.    assist in the Power Management activities
  663.    within the operating system.
  664.  
  665.    The primary change is to rename the ulReserved
  666.    parameter to ShutDownValue.  In addition, the
  667.    valid ShutDownValue parameter values are
  668.    defined as:
  669.  
  670.        Value       Definition
  671.        -----       ----------------------------------------------------
  672.          0         Perform full system shut down and file system lock.
  673.          1         Perform buffer and cache flushing to make the system
  674.                    quiescent.
  675.  
  676.      All other values are reserved.
  677.  
  678.    The Remarks section of the DosShutDown API
  679.    should be updated to qualify the existing text
  680.    as applicable to the ShutDownValue parameter
  681.    value of 0.  Also, the Remarks for the
  682.    ShutDownValue parameter value of 1 should
  683.    indicate that the system should be quiescent
  684.    (that is, no threads of execution will be
  685.    active) at the end of this function request,
  686.    but that the file systems will not be locked
  687.    and processing can resume again at a later
  688.    time.
  689.  
  690.    For more information on the new Power
  691.    Management features, see the Power Management
  692.    TXT (text) file.
  693.  
  694.  
  695. DEVICE DRIVER INITIALIZATION
  696. ____________________________
  697.  
  698.    There are two new options available to device
  699.    drivers during initialization.
  700.  
  701.  
  702. DEVICE DRIVER INITIALIZATION QUIET FAILURE FLAG
  703.  
  704.    This interface is documented in the OS/2 2.0
  705.    Physical Device Driver Reference.  Several
  706.    pages have changes for the new device driver
  707.    Quiet Failure Flag.  The changes are:
  708.  
  709.    o   Page 15-3 add the following information
  710.        after "Invalid Parameter (13H)":
  711.  
  712.            Initialization Failed (noncritical)
  713.            (15H):  Returned when the device driver
  714.            initialization fails, but a message
  715.            should not be displayed indicating a
  716.            failure.
  717.  
  718.    o   Page 15-6 remove the following sentence
  719.        from the last paragraph:
  720.  
  721.            If none of the devices in the device
  722.            driver header chain pass
  723.            initialization, the physical device
  724.            driver does not remain loaded.
  725.  
  726.        and add a new paragraph at the end:
  727.  
  728.            If none of the devices in the device
  729.            driver header chain pass
  730.            initialization, and the device driver
  731.            returns Initialization Failed
  732.            (noncritical) (15H) for all devices in
  733.            the device driver header chain, a
  734.            failure message will not be displayed
  735.            to the user and the physical device
  736.            driver does not remain loaded.
  737.  
  738.            If none of the devices in the device
  739.            driver header chain pass
  740.            initialization, and the device driver
  741.            returns an error code other than
  742.            Initialization Failed (noncritical)
  743.            (15H) for at least one device in the
  744.            device driver header chain, a failure
  745.            message will be displayed to the user
  746.            and the physical device driver will not
  747.            remain loaded.  If at least one of the
  748.            devices in the device driver header
  749.            chain passes initialization, a failure
  750.            message will not be displayed to the
  751.            user and the physical device driver
  752.            will remain loaded.
  753.  
  754.  
  755. DEVICE DRIVER INITIALIZATION COMPLETE COMMAND
  756.  
  757.    This interface is documented in the OS/2 2.0
  758.    Physical Device Driver Reference.  Several
  759.    pages have changes for the new device driver
  760.    Initialization Complete Command.  The changes
  761.    are:
  762.  
  763.    o   Page 4-3 add the following to list of
  764.        packets supported by character devices:
  765.  
  766.            31 - Init Complete
  767.  
  768.    o   Page 15-4 add the following to the table of
  769.        physical device driver strategy commands:
  770.  
  771.            1F - Initialization Complete
  772.  
  773.    o   After Page 15-24 add the following for the
  774.        new strategy command description:
  775.  
  776.            1FH/ Initialization Complete
  777.            ________________________________________________________
  778.            This command informs the physical device driver that all
  779.            physical device drivers have been loaded.
  780.  
  781.            Request Block Format
  782.            +----------------------------------+
  783.            | Field                Length      |
  784.            |----------------------------------|
  785.            | Request Header       13 bytes    |
  786.            +----------------------------------+
  787.  
  788.  
  789.            Remarks:  When a device driver receives this command, all physical
  790.            device drivers have been loaded and initialized.  Virtual device
  791.            drivers have not been loaded and initialized.  The device driver
  792.            can now establish links to other physical device drivers.
  793.  
  794.  
  795. NEW IOCTLS
  796. __________
  797.  
  798.    New IOCtls have been provided for two
  799.    categories of device management:  lockable
  800.    drives and power management.
  801.  
  802.    For lockable drives there are 3 new IOCtls in
  803.    Category 8:
  804.  
  805.    o   Category 8, Function 40H  -- Unlock, Lock,
  806.        and Eject Media
  807.    o   Category 8, Function 5DH -- Diskette
  808.        Control
  809.    o   Category 8, Function 66H  -- Query Lock
  810.        Status
  811.  
  812.    For power management there are 5 new IOCtls in
  813.    a new category, Category 12 IOCtls.  The IOCtls
  814.    in this category are:
  815.  
  816.    o   Category 12, Function 40H -- Send Power
  817.        Event
  818.    o   Category 12, Function 41H -- Set Power
  819.        Event Resource
  820.    o   Category 12, Function 60H -- Query Power
  821.        Status
  822.    o   Category 12, Function 61H -- Query Power
  823.        Event
  824.    o   Category 12, Function 62H -- Query Power
  825.        Info
  826.  
  827.    These IOCtls are documented in the online
  828.    Control Program Reference.  In addition, there
  829.    is a separate TXT (text) file devoted to Power
  830.    Management.
  831.  
  832.  
  833. NEW HOOKS FOR VDHINSTALLUSERHOOK VIRTUAL DEVICE HELPER FUNCTION
  834. _______________________________________________________________
  835.  
  836.    VDHInstallUserHook is documented in the OS/2
  837.    2.0 Virtual Device Driver Reference on page
  838.    5-70.
  839.  
  840.    Two new user hooks for virtual device drivers
  841.    (VDDs) have been added for use with
  842.    VDHInstallUserHook.  These hooks support an
  843.    enhancement to the DPMI support for DOS
  844.    Sessions.
  845.  
  846.  
  847. BACKGROUND -- A DOS SESSION DPMI ENHANCEMENT
  848.  
  849.    The OS/2 operating system has been enhanced to
  850.    support multiple local descriptor tables (LDT)
  851.    and interrupt descriptor tables (IDT) in each
  852.    DOS Session, as specified in the DPMI 1.0
  853.    specification.
  854.  
  855.    The OS/2 operating system now allocates a new
  856.    IDT and LDT each time a DPMI application
  857.    initially enters protect mode.  The original
  858.    DPMI implementation for the OS/2 operating
  859.    system supported DPMI 0.9, which defined a
  860.    single-LDT, single-IDT mechanism; all DPMI
  861.    applications used the same LDT and IDT.  This
  862.    implementation meant that multiple DPMI
  863.    applications could run in a DOS Session, but
  864.    that all the DPMI applications within a single
  865.    DOS Session had to be either 16-bit or 32-bit.
  866.  
  867.    The OS/2 operating system now creates a new LDT
  868.    and IDT for each DPMI application when the
  869.    application initially enters protect mode.
  870.    Protect mode exceptions and interrupts are
  871.    routed to the primary DPMI client in the DOS
  872.    Session, which is defined to be the last
  873.    application to enter protect mode.  With this
  874.    enhancement, 16-bit and 32-bit DPMI
  875.    applications can be run in the same DOS
  876.    Session.
  877.  
  878.    This support conforms with the DPMI 1.0
  879.    specification.
  880.  
  881.    The primary DPMI client's IDT is used to call
  882.    the appropriate interrupt and exception
  883.    handlers.  The virtual Programmable Interrupt
  884.    Controller (VPIC) simulates hardware interrupts
  885.    using the primary DPMI client's IDT.  The DOS
  886.    Session switches to the primary client's IDT so
  887.    that the interrupt is routed to the correct
  888.    handler, then restores the current task (if
  889.    necessary) after the interrupt has been
  890.    simulated.
  891.  
  892.    Two new hooks have been added to
  893.    VDHInstallUserHook to support this enhancement.
  894.  
  895.  
  896. NEW VDHINSTALLUSERHOOK HOOKS
  897.  
  898.    Two new user hooks for virtual device drivers
  899.    (VDDs) have been added for use with
  900.    VDHInstallUserHook.  The two new user hooks
  901.    enable VDDs to be notified when a DPMI task
  902.    begins and ends execution, so the VDD is able
  903.    to hook any events in protect mode that are
  904.    required.
  905.  
  906.    The new hooks are VDM_BEGIN_VPM_TASK, and
  907.    VDM_END_VPM_TASK (VPM means Virtual Protect
  908.    Mode).  Each time a new DPMI application/task
  909.    starts in a DOS Session, all VDM_BEGIN_VPM_TASK
  910.    hooks are called.  Each time a DPMI
  911.    application/task exits, all VDM_END_VPM_TASK
  912.    hooks are called.
  913.  
  914.    The constants are defined as follows:
  915.  
  916.        #define VDM_BEGIN_VPM_TASK   13   /* VPM task initially started */
  917.        #define VDM_END_VPM_TASK     14   /* VPM task terminated        */
  918.  
  919.    The routines registered to receive control when
  920.    a task starts or stops are passed the handle to
  921.    the DOS Session, but the DPMI application that
  922.    is starting or stopping will have its IDT and
  923.    LDT active.
  924.  
  925.  
  926. ADDITION TO VMALLOC DEVHLP FUNCTION
  927. ___________________________________
  928.  
  929.    VMAlloc is documented in the OS/2 2.0 Physical
  930.    Device Driver Reference on page 17-98.
  931.  
  932.    A new bit has been added to the VMAlloc DevHlp
  933.    function that tells the operating system to
  934.    allocate memory above the 16 MB line.  This bit
  935.    is:
  936.  
  937.        0x800 - VMDHA_USEHIGHMEM
  938.  
  939.    If memory above 16 MB exists, but there is not
  940.    enough to satisfy the request, memory above 16
  941.    MB will be used first and the remaining amount
  942.    will be taken from memory below 16 MB.  If no
  943.    memory above 16 MB exists, the allocation will
  944.    be taken from existing memory.  The memory is
  945.    freed by calling the VMFree DevHlp function.
  946.  
  947.    This bit is only valid during device driver
  948.    initialization.  If this bit is used at any
  949.    other time, VMAlloc will return an error
  950.    (ERROR_INVALID_PARAMETER).
  951.  
  952.  
  953. CHANGES AND CLARIFICATIONS
  954. __________________________
  955.  
  956.    This section contains some additions, changes,
  957.    and clarifications for the OS/2 2.0 Programming
  958.    Guide Volume I:  Control Program, and for the
  959.    OS/2 2.0 Physical Device Driver Reference.
  960.  
  961.  
  962. ADDENDUM TO FILE MANAGEMENT CODING EXAMPLES
  963.  
  964.    File management is described in Chapter 4 of
  965.    the OS/2 2.0 Programming Guide Volume I:
  966.    Control Program.  In the sample code on pages
  967.    4-20 and 4-21, under the line:
  968.  
  969.        #define INCL_DOSFILEMGR
  970.  
  971.    add the line:
  972.  
  973.        #define INCL_DOSMISC
  974.  
  975.    The "#define INCL_DOSMISC" is required to
  976.    include the header file support (function
  977.    prototypes, and so on) for DosScanEnv and
  978.    DosSearchPath.  The DosQuerySysInfo function
  979.    also requires the "#define INCL_DOSMISC", but
  980.    this function is not used in any of the samples
  981.    in the Programming Guide.
  982.  
  983.  
  984. PROGRAM EXECUTION CONTROL
  985.  
  986.    Sessions, processes, and threads are documented
  987.    in Chapter 7 in the OS/2 2.0 Programming Guide
  988.    Volume I: Control Program.  In Figure 7-1 on
  989.    page 7-2, in the center box of the figure,
  990.    change the word "Sessions" to "Processes".
  991.  
  992.  
  993. USER-DEFINED EXCEPTIONS
  994.  
  995.    Exception management is documented in the OS/2
  996.    2.0 Programming Guide Volume I: Control
  997.    Program, in Chapter 13.  On page 2-339, under
  998.    the heading "User-Defined Exceptions", change
  999.    the example for raising exceptions from:
  1000.  
  1001.        DosRaiseException(XCPT_YOUR_EXCEPTION);
  1002.  
  1003.    to the following:
  1004.  
  1005.        EXCEPTIONREPORTRECORD  ERepRec;
  1006.  
  1007.        ERepRec.ExceptionNum                = XCPT_YOUR_EXCEPTION;
  1008.        ERepRec.fHandlerFlags               = 0;
  1009.        ERepRec.NestedExceptionReportRecord = NULL;
  1010.        ERepRec.ExceptionAddress            = NULL;
  1011.        ERepRec.cParameters                 = 0;
  1012.  
  1013.        DosRaiseException(&ERepRec);
  1014.  
  1015.  
  1016. ADDENDUM TO PHYSICAL DEVICE DRIVER REQUEST PACKET DOCUMENTATION
  1017.  
  1018.    The format of the physical device driver's
  1019.    Request Packet Status WORD is described on page
  1020.    15-2 of the OS/2 2.0 Physical Device Driver
  1021.    Reference.  This addendum relates to bit 15
  1022.    (the Error bit) and bit 8 (the Done bit).
  1023.  
  1024.        Bit 8 (the Done bit) MUST be set, even when
  1025.        bit 15 (the Error bit) is set.  That is,
  1026.        whenever you return with the Error bit set,
  1027.        you must also set the Done bit.
  1028.  
  1029.  
  1030. CHANGE TO DOCUMENTATION FOR PHYSICAL MOUSE DEVICE DRIVER IDC
  1031.  
  1032.    The physical Mouse device driver's Inter-Device
  1033.    Communication (IDC) interface is documented in
  1034.    the OS/2 2.0 Physical Device Driver Reference,
  1035.    in chapter 12, "Physical Mouse Device Driver".
  1036.    In the section headed "MOUSE.SYS IDC
  1037.    Interface", under the information on the
  1038.    Process_Absolute IDC request, at the bottom of
  1039.    page 12-3 and top of page 12-4, there is a
  1040.    reference to the "event" field that has
  1041.    changed.  Remove the following sentences:
  1042.  
  1043.        The event field should never indicate that
  1044.        motion was associated with the event.
  1045.        MOUSE$ determines if motion occurs.
  1046.  
  1047.  
  1048. NOTICES
  1049. _______
  1050.  
  1051.    References in this publication to IBM products,
  1052.    programs, or services do not imply that IBM
  1053.    intends to make these available in all
  1054.    countries in which IBM operates.  Any reference
  1055.    to an IBM product, program or service is not
  1056.    intended to state or imply that only IBM's
  1057.    product, program, or service may be used.  Any
  1058.    functionally equivalent product, program, or
  1059.    service that does not infringe any of IBM's
  1060.    intellectual property rights or other legally
  1061.    projectable rights may be used instead of the
  1062.    IBM product, program, or service.  Evaluation
  1063.    and verification of operation in conjunction
  1064.    with other products, programs, or services,
  1065.    except those expressly designated by IBM, are
  1066.    the user's responsibility.
  1067.  
  1068.    IBM may have patents or pending patent
  1069.    applications covering subject matter in this
  1070.    document.  The furnishing of this document does
  1071.    not give you any license to these patents.  You
  1072.    can send license inquiries, in writing, to the
  1073.    IBM Director of Commercial Relations, IBM
  1074.    Corporation, Purchase, NY 10577.
  1075.  
  1076.  
  1077. TRADEMARKS AND SERVICE MARKS
  1078.  
  1079.    The following terms, denoted by an asterisk
  1080.    (*), used in this publication, are trademarks
  1081.    or service marks of the IBM Corporation in the
  1082.    United States or other countries:
  1083.  
  1084.    IBM
  1085.    OS/2
  1086.    OS/2 2.0
  1087.    OS/2 2.1
  1088.  
  1089.    IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED
  1090.    OR IMPLIED, INCLUDING WITHOUT LIMITATION,
  1091.    WARRANTIES OF FITNESS AND MERCHANTABILITY WITH
  1092.    RESPECT TO THE INFORMATION IN THIS DOCUMENT.
  1093.    BY FURNISHING THIS DOCUMENT, IBM GRANTS NO
  1094.    LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS.
  1095.  
  1096.    Copyright IBM Corporation, 1992, all rights
  1097.    reserved.
  1098.