home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v4.zip / OS2TK21 / READ.ME < prev    next >
Text File  |  1993-05-06  |  38KB  |  1,165 lines
  1.    Welcome to the IBM Developer's Toolkit for OS/2 2.1.
  2.    This information has been prepared to assist you
  3.    in your application development activities.
  4.  
  5.    The following major topics are discussed in this README:
  6.  
  7.       -  ADDITIONAL DEVELOPER INFORMATION
  8.       -  IBM DEVICE DRIVER SOURCE KIT FOR OS/2
  9.       -  VIRTUAL DEVICE DRIVER INFORMATION
  10.       -  USING SOM AND C++ TO CREATE WORKPLACE OBJECTS
  11.       -  METHOD MACROS
  12.       -  WP CAR SAMPLE
  13.       -  ONLINE IPF REFERENCE
  14.       -  OS/2 ENHANCED EDITOR (EPM)
  15.       -  TK21DESK.CMD
  16.       -  OS2DEF.H HEADER INFORMATION
  17.       -  BIDIRECTIONAL NATIONAL LANGUAGE SUPPORT
  18.       -  DEVICE DRIVER PROGRAMMING INTERFACES
  19.       -  DOS PROGRAMMING INTERFACE
  20.       -  WIN PROGRAMMING INTERFACE
  21.       -  DDE BETWEEN PM AND WINDOWS PROGRAMS
  22.       -  PM REFERENCE UPDATES
  23.       -  PROGRAMMING CONSIDERATIONS
  24.       -  NEW FUNCTIONS FOR THE OS/2 2.1 CONTAINER CONTROL
  25.       -  ADDENDUM TO PROGRAMMING GUIDE VOL. II, CHAPTER 33 (p. 22)
  26.       -  PMWIN LOCKUP API'S AND HK_LOCKUP HOOK
  27.       -  PROGRAMMING GUIDE VOLUME III
  28.       -  DOSSHUTDOWN API
  29.       -  DEVICE DRIVER INITIALIZATION
  30.       -  NEW BIT ADDED TO CAPABILITIES BIT STRIP
  31.       -  CHANGE TO DEVICE ATTRIBUTE FIELD
  32.       -  NEW HOOKS FOR VDHINSTALLUSERHOOK VIRTUAL DEVICE HELPER FUNCTION
  33.       -  ADDITION TO VMALLOC DEVHLP FUNCTION
  34.       -  DLL INITIALIZATION AND TERMINATION
  35.       -  CHANGES AND CLARIFICATIONS
  36.       -  NOTICES
  37.  
  38.  
  39.  
  40. ADDITIONAL DEVELOPER INFORMATION
  41. ________________________________
  42.  
  43.    IBM* participates in CompuServe forums.  If you
  44.    are logged onto CompuServe, simply type
  45.    "GO IBMOS2" at the ! prompt and you will be
  46.    provided with a menu of the available OS/2*
  47.    forums.
  48.  
  49.  
  50.  
  51.  
  52. IBM DEVICE DRIVER SOURCE KIT FOR OS/2
  53. _____________________________________
  54.  
  55.    The following publications are available for additional
  56.    device driver development references.  They can be
  57.    purchased separately at an additional charge through
  58.    your IBM dealer, or call 1-800-267-2338 (US only) for
  59.    information.
  60.  
  61.               Pub Title                    Part Num  Form Num
  62.               ---------                    --------  --------
  63.     Printer Device Driver Reference        71G1895   S71G-1895-00
  64.     Display Device Driver Reference        71G1896   S71G-1896-00
  65.     Storage Device Driver Reference        71G1897   S71G-1897-00
  66.     Input/Output Device Driver Reference   71G1898   S71G-1898-00
  67.     PenPM Device Driver Reference          71G1899   S71G-1899-00
  68.     MMPM/2 Device Driver Reference         71G3678   S71G-3678-00
  69.  
  70.  
  71.  
  72.  
  73. VIRTUAL DEVICE DRIVER INFORMATION
  74. _________________________________
  75.  
  76.    The VDD sample is now written in C language
  77.    and can be built using the IBM C/C ++
  78.    compiler.
  79.  
  80.    This Virtual Device Driver sample is intended
  81.    to demonstrate interdevice communication with
  82.    the Physical Device Driver sample.
  83.  
  84.    The VDD sample illustrates intercepting the
  85.    communication from a DOS Application which is
  86.    executing in a DOS session under OS/2, and
  87.    routing the appropriate information to the
  88.    corresponding Physical Device Driver sample
  89.    to complete the task.  The intent of this
  90.    sample is to provide source code demonstrating
  91.    this functionality in the C language.  Additional
  92.    software and hardware is required to fully
  93.    exercise the device drivers.
  94.  
  95.    Warning messages may be received when compiling
  96.    this sample.  The warning message is necessary
  97.    when building device drivers, and is required,
  98.    because DS = SS for ring 0.
  99.  
  100.    The VDD subdirectory contains header files that are
  101.    intended for writers of device drivers, and
  102.    should not be used in conjunction with application
  103.    header files contained in the OS2H subdirectory.
  104.  
  105.  
  106.  
  107.  
  108. USING SOM AND C++ TO CREATE WORKPLACE OBJECTS
  109. _____________________________________________
  110.  
  111.    SOM provides a language-neutral object-oriented
  112.    programming mechanism for OS/2.  This means that
  113.    classes of objects can be defined using SOM and
  114.    implemented using any programming language
  115.    supported by the SOM compiler (currently C and C++).
  116.  
  117.    The CAR Workplace object in the OS/2 Toolkit has
  118.    been modified to demonstrate a C++ implementation
  119.    of a SOM/Workplace object.  In the C implementation
  120.    of CAR in the OS/2 2.0 Toolkit, the CAR's brake,
  121.    horn, and speed are defined in terms of SOM
  122.    instance data and methods:
  123.  
  124.          Feature        Instance Data        Methods
  125.          -------------------------------------------------
  126.          Brake          BrakeFlag            QueryBrakes
  127.                                              SetBrakes
  128.          -------------------------------------------------
  129.          Horn           Duration             QueryDuration
  130.                                              Set Duration
  131.                         ----------------------------------
  132.                         HighTone             QueryHighTone
  133.                                              SetHighTone
  134.                         ----------------------------------
  135.                         LowTone              QueryLowTone
  136.                                              SetLowTone
  137.          -------------------------------------------------
  138.          Speed          Speed                QuerySpeed
  139.                                              SetSpeed
  140.          -------------------------------------------------
  141.  
  142.  
  143.    In the C++ implementation of CAR in the OS/2 2.1
  144.    Toolkit, the CAR's brake, horn, and speed are defined
  145.    in terms of three C++ classes:   BRAKE, HORN, and RPM.
  146.  
  147.    SOM and C++ objects have different class hierarchies.
  148.    SOM provides commonality across SOM objects implemented
  149.    in different languages and used by different applications.
  150.    C++ classes are local to an application.  As a rule, use
  151.    SOM to define classes if the class can be useful to other
  152.    applications.  Use C++ to define classes that are useful
  153.    only to your application.  As an example, suppose we have
  154.    a class of BOATs.  Just as a CAR has a HORN, a BOAT may
  155.    also have a HORN.  HORNs are useful to both CARs and
  156.    BOATs.  Therefore, defining HORN using SOM, instead of
  157.    C++, is advisable.
  158.  
  159.    SOM can also be used to "wrap" a C++ implementation of
  160.    a class if the class is useful to other applications
  161.    or must fit into the Workplace.  As an example, we can
  162.    define CAR as a C++ class.  To place a CAR in the
  163.    Workplace, we must define a SOM "wrapper" for the CAR
  164.    class.
  165.  
  166.  
  167.  
  168.  
  169. METHOD MACROS
  170. _____________
  171.  
  172.    To simplify conversion of C code to C++ code, if the
  173.    programmer #defines C_TRANSLATION_MACROS before
  174.    including the .XIH file, the method macros will be
  175.    defined differently to remove the need to change the
  176.    method calls to match the C++ convention.  One such
  177.    macro definition would be:
  178.  
  179.          #define_somGetClass(obj obj->somGetClass()
  180.  
  181.     vs. the normal definition:
  182.  
  183.          #define_somGetClass somSelf->somGetClass
  184.  
  185.  
  186.  
  187.  
  188. WP CAR SAMPLE
  189. _____________
  190.  
  191.    An additional CAR sample has been written in C++.
  192.    This sample should be installed to you hardfile
  193.    and NOT registered on your desktop.
  194.  
  195.  
  196.  
  197.  
  198. ONLINE IPF REFERENCE
  199. ___________________
  200.  
  201.    There is a dynamic link library (IPF.DLL)
  202.    associated with the compiled example of the
  203.    Application-Controlled Window Example.
  204.    However, IPF.DLL is installed with the Sample
  205.    Programs component of the Toolkit.  Therefore,
  206.    unless the Sample Programs component is
  207.    installed, you will be unable to view the
  208.    animation provided by the IPF.DLL in the
  209.    Application-Controlled Window Example in the
  210.    online IPF Reference.
  211.  
  212.  
  213.  
  214.  
  215. OS/2 ENHANCED EDITOR (EPM)
  216. __________________________
  217.  
  218.    If you attempt to access additional information
  219.    for a text string by pressing Ctrl+H, the
  220.    following message might appear:
  221.  
  222.             epmkwhlp.ndx file not found
  223.  
  224.    To avoid this message, add the following to the
  225.    DPATH statement in CONFIG.SYS:
  226.  
  227.             x:\toolkt21\book;
  228.  
  229.        where "x" is the drive location for the Toolkit.
  230.  
  231.  
  232.  
  233.  
  234. TK21DESK.CMD
  235. ____________
  236.  
  237.     A command file, TK21DESK.CMD, is located in TOOLKT21\OS2BIN.
  238.     TK21DESK.CMD is used to create a Toolkit folder and
  239.     subfolders and contains the installed Toolkit on the CD-ROM.
  240.     TK21DESK.CMD also updates CONFIG.SYS.  TK21DESK.CMD can be
  241.     used to re-create a Toolkit folder for a Toolkit installed on
  242.     a hardfile.
  243.  
  244.  
  245.  
  246.  
  247. OS2DEF.H HEADER INFORMATION
  248. ___________________________
  249.  
  250.     In the OS2DEF.H header file, the SELECTOROF macro is
  251.     incorrect.  It was intended to be used to get the
  252.     selector of a 16:16 address,  which it does not do.
  253.  
  254.     Either of the following two macros can be used to get
  255.     the selector of a 16:16 address:
  256.  
  257.        #define SELECTOROF(p)   (((PUSHORT)&(p))[1])
  258.        #define SELECTOROF(p)   ((ULONG)(p) >>16)
  259.  
  260.     If you use the selector returned from one of the above
  261.     macros with the OFFSETOF and MAKEP macros in the
  262.     OS2DEF.H header file, you can successfully convert a
  263.     16:16 address to a 0:32 address.
  264.  
  265.  
  266.  
  267.  
  268. BIDIRECTIONAL NATIONAL LANGUAGE SUPPORT
  269. _______________________________________
  270.  
  271.    Information on how to use the BIDI programming
  272.    interface can be found in
  273.    \TOOLKT21\C\SAMPLES\BIDI\READ.ME.
  274.  
  275.  
  276.  
  277.  
  278. DEVICE DRIVER PROGRAMMING INTERFACES
  279. ____________________________________
  280.  
  281.    The header files previously contained in the
  282.    \TOOLKT20\C\OS2H\DASD directory have been
  283.    removed.  These headers are now included in the
  284.    "IBM Device Driver Source Kit for OS/2", available
  285.    separately.
  286.  
  287.  
  288.  
  289.  
  290. DOS PROGRAMMING INTERFACE
  291. _________________________
  292.  
  293.    The DosSetDOSProperty() and
  294.    DosQueryDOSProperty() functions in BSEDOS.H are
  295.    not supported.  Do not use these application
  296.    programming interfaces.
  297.  
  298.  
  299.  
  300.  
  301. WIN PROGRAMMING INTERFACE
  302. _________________________
  303.  
  304.    The debug kernel version of PMGRE.DLL contained
  305.    in the Toolkit executes an INT 3 instruction,
  306.    causing a break-point to be hit in the debugger.
  307.    The INT 3 is executed only in 32-bit API parameter
  308.    validation on the debug version of PMGRE.DLL;
  309.    all other errors will not execute an INT 3.
  310.  
  311.    For the WinCreateWindow function, the first
  312.    USHORT pointed to by the control data parameter
  313.    is assumed to be the length of the data block.
  314.  
  315.  
  316.  
  317.  
  318. DDE BETWEEN PM AND WINDOWS PROGRAMS
  319. ___________________________________
  320.  
  321.    Making modifications to Microsoft Windows** programs
  322.    to enable dynamic data exchange (DDE) communications
  323.    with Presentation Manager*(PM) programs helps
  324.    facilitate a gradual migration of applications to PM.
  325.    Not all data formats are automatically converted when
  326.    using DDE between Windows programs and PM programs
  327.    (DDE set public).  The following formats are
  328.    converted automatically by OS/2 2.1:
  329.  
  330.  
  331.             PM Application               Windows Application
  332.             Data Format                  Interpretation
  333.             --------------------         --------------------
  334.             PM BITMAP                    Windows DIB
  335.             TEXT                         TEXT (codepage 819)
  336.             PM private                   Windows private
  337.  
  338.  
  339.             Windows Application          PM Application
  340.             Data Format                  Interpretation
  341.             --------------------         --------------------
  342.             Windows DIB                  PM BITMAP
  343.             TEXT (codepage 819)          TEXT
  344.             Windows private              PM Private
  345.  
  346.    Notes:
  347.  
  348.    1.  Code page translation (Windows 819 to/from
  349.        current PM code page) is performed for topic
  350.        name in all cases.
  351.  
  352.    2.  When data conversion is not automatically
  353.        performed, programs can still communicate via
  354.        DDE if the two programs are able to perform the
  355.        data conversion and pass private data formats.
  356.  
  357.  
  358.  
  359.  
  360. PM REFERENCE UPDATES
  361. ____________________
  362.  
  363.  
  364. PROGRAMMING CONSIDERATIONS
  365. __________________________
  366.  
  367.    When including an OBJECTID=<....> keyname/value pair
  368.    in a setup string, you must specify it at the end
  369.    of the setup string.
  370.  
  371.    Existing 16-bit applications (small and tiny models)
  372.    must have a 4KB stack available when they enter
  373.    system calls. If they do not have a 4KB stack
  374.    available, the stack can overflow into the data
  375.    area.  In testing, we found some 16-bit small/tiny
  376.    model applications have not followed the
  377.    guidelines and, therefore, have encountered
  378.    problems.
  379.  
  380.  
  381.  
  382.  
  383. NEW FUNCTIONS FOR THE OS/2 2.1 CONTAINER CONTROL
  384. ________________________________________________
  385.  
  386.    In response to user requests, the following
  387.    new functions have been added to the OS/2 2.1
  388.    container control.
  389.  
  390.  
  391. DETERMINING THE WIDTH OF A COLUMN IN THE DETAILS VIEW
  392.  
  393.    There are instances when you might want to determine
  394.    the width of a column in the details view, such
  395.    as to allow the user to tab the split bar
  396.    between columns.  A function has been added
  397.    to the container control to allow you to
  398.    determine the width of the data in a column.
  399.    You can then compute the width of the entire
  400.    column by adding the width of the data to the
  401.    left and right margins of the column.
  402.  
  403.    To determine the width of a column:
  404.  
  405.    1.  Define an attribute with a value of 0X0200
  406.        and give it a name such as CMA_DATAWIDTH.
  407.  
  408.    2.  Issue the CM_QUERYDETAILFIELDINFO message
  409.        with the following values:
  410.  
  411.        a.  Provide a pointer to the FIELDINFO
  412.            structure in param1.
  413.  
  414.        b.  Specify your attribute (see step 1) in
  415.            param2.
  416.  
  417.        c.  Request a return value with a type of
  418.            LONG, not PFIELDINFO, to retrieve the
  419.            width of the column in the FIELDINFO
  420.            structure to which you are pointing.
  421.            The value returned is the width of the
  422.            data (text, icon, or bit map) in this
  423.            column.
  424.  
  425.    3.  Use the GpiQueryFontMetrics function to
  426.        query the average character width of the
  427.        font used by the container.  This value
  428.        will be used to calculate the total column
  429.        width.
  430.  
  431.    4.  Multiply 3 by the average character
  432.        width and add this to the data width
  433.        returned from step 2 for all columns except
  434.        the following:
  435.  
  436.        The first and last columns in each
  437.        split window.  In these cases, multiply
  438.        2.5 by the average character width
  439.        and add the column data width returned
  440.        from step 2.
  441.  
  442.        The only other special case is where
  443.        there is only 1 column in either the
  444.        left or right split windows.  In this
  445.        case, you would multiply 2 by the
  446.        average character width and add the
  447.        column data width returned from step 2.
  448.  
  449.    5.  The value returned is the total width of
  450.        the column.
  451.  
  452.  
  453.  
  454. PROVIDING SOURCE EMPHASIS FOR CONTAINER ITEMS
  455.  
  456.    Source emphasis is the type of emphasis that
  457.    the Workplace Shell interface provides when a
  458.    context menu is displayed.  It appears as a
  459.    dotted box with rounded corners that surrounds
  460.    the item for which the context menu is requested
  461.    and the item that is being dragged.
  462.  
  463.    To provide source emphasis for container items:
  464.  
  465.    1.  Define an attribute with a value of
  466.        0X00004000L and give it a name such as
  467.        CRA_SOURCE.
  468.  
  469.    2.  Issue the CM_SETRECORDEMPHASIS message with
  470.        the following values:
  471.  
  472.        a.  Provide a pointer to the RECORDCORE or
  473.            MINIRECORDCORE structure in param1.
  474.  
  475.            You can provide source emphasis for the
  476.            entire container by setting param1 to
  477.            NULL.
  478.  
  479.        b.  Set the usChangeEmphasis parameter to
  480.            TRUE in param2.
  481.  
  482.        c.  Specify your attribute (see step 1) in
  483.            the fEmphasisAttribute parameter in
  484.            param2.
  485.  
  486.    To remove source emphasis follow the same
  487.    procedure outlined above, but set the
  488.    usChangeEmphasis parameter in param2 to FALSE
  489.    instead of TRUE.
  490.  
  491.  
  492.  
  493. SEARCHING FOR EXACT TEXT STRING MATCHES
  494.  
  495.    There might be times when you need to search the
  496.    container for a text string that is an exact
  497.    match of your search string argument.
  498.  
  499.    To find an exact match:
  500.  
  501.    1.  Define an attribute with a value of
  502.        0X10000000L and give it a name such as
  503.        CV_EXACTMATCH.
  504.  
  505.    2.  In the SEARCHSTRING data structure, specify
  506.        values for the fields as you normally
  507.        would, with the following exception:
  508.  
  509.        Specify your attribute (see step 1),
  510.        along with an attribute for the type of
  511.        view being displayed in the container,
  512.        in the usView field.  For example:
  513.  
  514.             CV_EXACTMATCH | CV_ICON
  515.  
  516.         Note:  In the "OS/2 2.0 Programming
  517.                Reference, Vol. III", the field for
  518.                specifying the exact match attribute
  519.                and the type of view is usView.  The
  520.                type associated with the field,
  521.                however, is ULONG.  You must specify
  522.                usView to match the information in
  523.                the header file.
  524.  
  525.  
  526.  
  527. CHAPTER 34. CODE PAGES
  528.  
  529.    The following are corrections to code pages
  530.    in Chapter 34:
  531.  
  532. CODE  HEX    GCGID      NAME      CORRECT    NAME
  533. PAGE  VALUE  GIVEN                GCGID
  534.  
  535. 037    6A    SP05000  apostrophe  SM650000 vertical line, broken
  536. 285    6A    SP05000  apostrophe  SM650000 vertical line, broken
  537. 500    6A    SP05000  apostrophe  SM650000 vertical line, broken
  538. 277    70    SP05000  apostrophe  SM650000 vertical line, broken
  539.  
  540.  
  541.  
  542.  
  543. ADDENDUM TO PROGRAMMING GUIDE VOL. II, CHAPTER 33 (p. 22)
  544. __________________________________________________________
  545.  
  546.  
  547. WORKPLACE RENDERING MECHANISM:
  548.  
  549.    The Workplace shell interface uses the rendering
  550.    mechanism of <DRM_OBJECT,DRF_OBJECT> to communicate
  551.    information about the workplace objects involved
  552.    in a direct manipulation.
  553.  
  554.    For the <DRM_OBJECT,DRF_OBJECT> rendering mechanism,
  555.    pdraginfo->hwndSource is expected to be the window
  556.    handle of the container holding objects which were
  557.    inserted via the _wpCnrInsertObject method.
  558.  
  559.    For each dragitem, pdragitem->ulItemID is the
  560.    PMINIRECORDCORE pointer associated with the
  561.    object.  The object can be retrieved using
  562.    OBJECT_FROM_PREC on pdragitem->ulItemID.
  563.  
  564.    As soon as the target object has completed
  565.    processing, a DM_ENDCONVERSATION message is
  566.    sent to the window handle in pdragitem->hwndItem.
  567.  
  568.  
  569.  
  570. DM_PRINT CHANGED TO DM_PRINTOBJECT
  571.  
  572.    DM_PRINT is a message used in direct
  573.    manipulation to ask a source object to print
  574.    the current view of the object.  DM_PRINT is
  575.    documented in the "OS/2 2.0 Programming Guide
  576.    Volume II" on page 33-20 and 33-23.
  577.  
  578.    DM_PRINT has been changed to DM_PRINTOBJECT.
  579.    The changes that need to be made in the book
  580.    are:
  581.  
  582.    o   On page 22-20, under the heading "Print
  583.        Rendering Mechanism", in the sub-section
  584.        titled "Messages":
  585.  
  586.            In the first sentence, change DM_PRINT
  587.            to DM_PRINTOBJECT.  Additionally, in
  588.            the last sentence, remove "queue, which
  589.            is also identified in the message" from
  590.            the end of the sentence and add a new
  591.            sentence after "printer":
  592.  
  593.                The second message parameter (of
  594.                type PRINTDEST) gives all the
  595.                parameters necessary to call
  596.                DevPostDeviceModes and DevOpenDC.
  597.  
  598.  
  599.    o   On page 33-23, in the table of Direct
  600.        Manipulation Messages, change DM_PRINT to
  601.        DM_PRINTOBJECT.  There is no change to the
  602.        description.
  603.  
  604.  
  605.  
  606.  
  607. PMWIN LOCKUP API'S AND HK_LOCKUP HOOK
  608. _____________________________________
  609.  
  610.    WinLockupSystem
  611.    WinUnlockSystem
  612.  
  613.       These two API's will allow a PM application to
  614.       lock and unlock the system from within the
  615.       application.
  616.  
  617.       In order for the WinUnlockSystem API to execute
  618.       after the WinLockupSystem has been called, the
  619.       WinUnlockSystem must be called from a separate
  620.       thread.
  621.  
  622.       The HK_LOCKUP hook will allow a PM application
  623.       to customize system lockup from within their
  624.       application.
  625.  
  626.       In order for your window to appear as the top
  627.       most window on the lockup screen you must use
  628.       the WS_CLIPSIBLINGS flag in your WinCreateWindow
  629.       or WinCreateStdWindow call.
  630.  
  631.  
  632.  
  633.  
  634. PROGRAMMING GUIDE VOLUME III
  635. ____________________________
  636.  
  637.  
  638. GPIERASE CHANGES
  639.  
  640.    In the "OS/2 2.0 Programming Guide Volume III"
  641.    the graphics programming interface is
  642.    described.
  643.  
  644.    In the Summary Tables on pages 13-18 and 14-12
  645.    change the description of GpiErase to:
  646.  
  647.        Clears a window, identified by a screen
  648.        device context, and paints the window using
  649.        the color identified by index 0 in the
  650.        color table, or by the first color in the
  651.        presentation space's palette.
  652.  
  653.  
  654.  
  655.  
  656. DOSSHUTDOWN API
  657. _______________
  658.  
  659.    The DosShutDown API is documented in the "OS/2
  660.    2.0 Control Program Programming Reference" 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
  673.                    and file system lock.
  674.  
  675.          1         Perform buffer and cache flushing
  676.                    to make the system quiescent.
  677.  
  678.      All other values are reserved.
  679.  
  680.    The Remarks section of the DosShutDown API
  681.    is updated to qualify the existing text as
  682.    applicable to the ShutDownValue parameter
  683.    value of 0.  The Remarks for the ShutDownValue
  684.    parameter value equal to 1 indicates the system
  685.    has 0 threads of execution active upon the
  686.    completion of this function request.  The
  687.    file systems will not be locked and processing
  688.    can resume again at a later time.
  689.  
  690.    Information on the new Power Management
  691.    features located in "IBM Device Driver
  692.    Source Kit for OS/2", available separately.
  693.  
  694.  
  695.  
  696.  
  697. DEVICE DRIVER INITIALIZATION
  698. ____________________________
  699.  
  700.    There are two new options available to device
  701.    drivers during initialization.
  702.  
  703.  
  704. DEVICE DRIVER INITIALIZATION QUIET FAILURE FLAG
  705.  
  706.    This interface is documented in the "OS/2 2.0
  707.    Physical Device Driver Reference".  Several
  708.    pages have changes for the new device driver
  709.    Quiet Failure Flag.  The changes are:
  710.  
  711.    o   Page 15-3.  Add the following information
  712.        after "Invalid Parameter (13H)":
  713.  
  714.            Initialization Failed (noncritical)
  715.            (15H):  Returned when the device driver
  716.            initialization fails, but a message
  717.            will not be displayed indicating a
  718.            failure.
  719.  
  720.    o   Page 15-6.  Remove the following sentence
  721.        from the last paragraph:
  722.  
  723.            If none of the devices in the device
  724.            driver header chain pass
  725.            initialization, the physical device
  726.            driver does not remain loaded.
  727.  
  728.        and add a new paragraph at the end:
  729.  
  730.            If none of the devices in the device
  731.            driver header chain pass
  732.            initialization, and the device driver
  733.            returns Initialization Failed
  734.            (noncritical) (15H) for all devices in
  735.            the device driver header chain, a
  736.            failure message will not be displayed
  737.            to the user and the physical device
  738.            driver does not remain loaded.
  739.  
  740.            If none of the devices in the device
  741.            driver header chain pass
  742.            initialization, and the device driver
  743.            returns an error code other than
  744.            Initialization Failed (noncritical)
  745.            (15H) for at least one device in the
  746.            device driver header chain, a failure
  747.            message will be displayed to the user
  748.            and the physical device driver will not
  749.            remain loaded.  If at least one of the
  750.            devices in the device driver header
  751.            chain passes initialization, a failure
  752.            message will not be displayed to the
  753.            user and the physical device driver
  754.            will remain loaded.
  755.  
  756.  
  757.  
  758. DEVICE DRIVER INITIALIZATION COMPLETE COMMAND
  759.  
  760.    This interface is documented in the "OS/2 2.0
  761.    Physical Device Driver Reference".  Several
  762.    pages have changes for the new device driver
  763.    Initialization Complete Command.  The changes
  764.    are:
  765.  
  766.    o   Page 4-3.  Add the following to list of
  767.        packets supported by character devices:
  768.  
  769.            31 - Init Complete
  770.  
  771.    o   Page 15-4.  Add the following to the table of
  772.        physical device driver strategy commands:
  773.  
  774.            1F - Initialization Complete
  775.  
  776.    o   After Page 15-24.  Add the following for the
  777.        new strategy command description:
  778.  
  779.            1FH/ Initialization Complete
  780.            ----------------------------
  781.            This command informs the physical device driver
  782.            that all physical device drivers have been loaded.
  783.  
  784.            Request Block Format
  785.            +----------------------------------+
  786.            | Field                Length      |
  787.            |----------------------------------|
  788.            | Request Header       13 bytes    |
  789.            +----------------------------------+
  790.  
  791.  
  792.            Remarks:  When a device driver receives this command,
  793.            all physical device drivers have been loaded and
  794.            initialized.  Virtual device drivers have not been
  795.            loaded and initialized.  The device driver can now
  796.            establish links to other physical device drivers.
  797.  
  798.            This command is sent to the device driver only if it
  799.            is a level-3 device driver and if Bit 4 is set in the
  800.            Capabilities Bit Strip in the device driver header
  801.            (see the section on the Capabilities Bit Strip later in this file).
  802.  
  803.  
  804.  
  805.  
  806. NEW BIT ADDED TO CAPABILITIES BIT STRIP
  807. _______________________________________
  808.  
  809.    The Capabilities Bit Strip is a part of the
  810.    device driver header and is described on pages
  811.    3-4 and 3-5 of the "Physical Device Driver
  812.    Reference".
  813.  
  814.    A new bit has been added to the Capabilities
  815.    Bit Strip.  On page 3-5, after "Bit 2" add a
  816.    new entry to the list:
  817.  
  818.    Bit 4     If set to 1, the new "Initialization
  819.              Complete" command (1FH) is supported.
  820.  
  821.              (The new "Initialization Complete"
  822.              command is documented in an earlier
  823.              section of this file.)
  824.  
  825.  
  826.  
  827.  
  828. CHANGE TO DEVICE ATTRIBUTE FIELD
  829. ________________________________
  830.  
  831.    The Device Attribute Field is a part of the
  832.    device driver header and is described on pages
  833.    3-3 and 3-4 of the "Physical Device Driver
  834.    Reference".
  835.  
  836.    On page 3-3, in the text describing "Bit 13",
  837.    delete the second sentence:
  838.  
  839.        "Set for output-until-busy support
  840.        (character device drivers only)."
  841.  
  842.  
  843.  
  844.  
  845. NEW HOOKS FOR VDHINSTALLUSERHOOK VIRTUAL DEVICE HELPER FUNCTION
  846. _______________________________________________________________
  847.  
  848.    VDHInstallUserHook is documented in the "OS/2
  849.    2.0 Virtual Device Driver Reference" on page
  850.    5-70.
  851.  
  852.    Two new user hooks for virtual device drivers
  853.    (VDDs) have been added for use with
  854.    VDHInstallUserHook.  These hooks support an
  855.    enhancement to the DOS Protect Mode Interface
  856.    (DPMI) support for DOS sessions.
  857.  
  858.  
  859.  
  860. BACKGROUND -- A DOS SESSION DPMI ENHANCEMENT
  861.  
  862.    The OS/2 operating system has been enhanced to
  863.    support multiple local descriptor tables (LDT)
  864.    and interrupt descriptor tables (IDT) in each
  865.    DOS session, as specified in the DPMI 1.0
  866.    specification.
  867.  
  868.    The OS/2 operating system now allocates a new
  869.    IDT and LDT each time a DPMI application
  870.    initially enters protect mode.  The original
  871.    DPMI implementation for the OS/2 operating
  872.    system supported DPMI 0.9, which defined a
  873.    single-LDT, single-IDT mechanism; all DPMI
  874.    applications used the same LDT and IDT.  This
  875.    implementation meant that multiple DPMI
  876.    applications could run in a DOS session, but
  877.    that all the DPMI applications within a single
  878.    DOS session had to be either 16-bit or 32-bit.
  879.  
  880.    The OS/2 operating system now creates a new LDT
  881.    and IDT for each DPMI application when the
  882.    application initially enters protect mode.
  883.    Protect mode exceptions and interrupts are
  884.    routed to the primary DPMI client in the DOS
  885.    session, which is defined to be the last
  886.    application to enter protect mode.  With this
  887.    enhancement, 16-bit and 32-bit DPMI
  888.    applications can be run in the same DOS
  889.    session.
  890.  
  891.    This support conforms with the DPMI 1.0
  892.    specification.
  893.  
  894.    The primary DPMI client's IDT is used to call
  895.    the appropriate interrupt and exception
  896.    handlers.  The virtual Programmable Interrupt
  897.    Controller (VPIC) simulates hardware interrupts
  898.    using the primary DPMI client's IDT.  The DOS
  899.    session switches to the primary client's IDT so
  900.    that the interrupt is routed to the correct
  901.    handler, and then restores the current task (if
  902.    necessary) after the interrupt has been
  903.    simulated.
  904.  
  905.    Two new hooks for virtual device drivers (VDDs)
  906.    have been added to VDHInstallUserHook to support
  907.    this enhancement.
  908.  
  909.  
  910.  
  911. NEW VDHINSTALLUSERHOOK HOOKS
  912.  
  913.    The two new user hooks enable VDDs to be notified
  914.    when a DPMI task begins and ends execution, so
  915.    the VDD is able to hook any events in protect
  916.    mode that are required.
  917.  
  918.    The new hooks are VDM_BEGIN_VPM_TASK, and
  919.    VDM_END_VPM_TASK (VPM means Virtual Protect
  920.    Mode).  Each time a new DPMI application/task
  921.    starts in a DOS Session, all VDM_BEGIN_VPM_TASK
  922.    hooks are called.  Each time a DPMI
  923.    application/task exits, all VDM_END_VPM_TASK
  924.    hooks are called.
  925.  
  926.    The constants are defined as follows:
  927.  
  928.        #define VDM_BEGIN_VPM_TASK   13   /* VPM task initially started */
  929.        #define VDM_END_VPM_TASK     14   /* VPM task terminated        */
  930.  
  931.    The routines registered to receive control when
  932.    a task starts or stops are passed the handle to
  933.    the DOS session, but the DPMI application that
  934.    is starting or stopping will have its IDT and
  935.    LDT active.
  936.  
  937.  
  938.  
  939.  
  940. ADDITION TO VMALLOC DEVHLP FUNCTION
  941. ___________________________________
  942.  
  943.    VMAlloc is documented in the "OS/2 2.0 Physical
  944.    Device Driver Reference" on page 17-98.
  945.  
  946.    A new bit has been added to the VMAlloc DevHlp
  947.    function that tells the operating system to
  948.    allocate memory above the 16MB limit.  This bit
  949.    is:
  950.  
  951.        0x800 - VMDHA_USEHIGHMEM
  952.  
  953.    If memory above 16MB exists but there is not
  954.    enough to satisfy the request, memory above 16MB
  955.    will be used first and the remaining amount will
  956.    be taken from memory below 16MB.  If no memory
  957.    above 16 MB exists, the allocation will be taken
  958.    from existing memory.  The memory is freed by
  959.    calling the VMFree DevHlp function.
  960.  
  961.    This bit is only valid during device driver
  962.    initialization.  If this bit is used at any
  963.    other time, VMAlloc will return an error
  964.    (ERROR_INVALID_PARAMETER).
  965.  
  966.  
  967.  
  968.  
  969. DLL INITIALIZATION AND TERMINATION
  970. __________________________________
  971.  
  972.    The TERMGLOBAL option of the  _DLL_InitTerm
  973.    function as described on pages 5-9 and 5-13
  974.    within the "OS/2 2.0 Application Design Guide"
  975.    is not supported.
  976.  
  977.  
  978.  
  979.  
  980. CHANGES AND CLARIFICATIONS
  981. __________________________
  982.  
  983.    This section contains some additions, changes,
  984.    and clarifications to the "OS/2 2.0 Programming
  985.    Guide Volume I:  Control Program", and for the
  986.    "OS/2 2.0 Physical Device Driver Reference".
  987.  
  988.  
  989.  
  990. ADDENDUM TO FILE MANAGEMENT CODING EXAMPLES
  991.  
  992.    File management is described in Chapter 4 of
  993.    the "OS/2 2.0 Programming Guide Volume I:
  994.    Control Program".  In the sample code on pages
  995.    4-20 and 4-21, under the line:
  996.  
  997.        #define INCL_DOSFILEMGR
  998.  
  999.    add the line:
  1000.  
  1001.        #define INCL_DOSMISC
  1002.  
  1003.    The "#define INCL_DOSMISC" is required to
  1004.    include the header file support (function
  1005.    prototypes, and so on) for DosScanEnv and
  1006.    DosSearchPath.  The DosQuerySysInfo function
  1007.    also requires the "#define INCL_DOSMISC", but
  1008.    this function is not used in any of the samples
  1009.    in the Programming Guide.
  1010.  
  1011.  
  1012.  
  1013. PROGRAM EXECUTION CONTROL
  1014.  
  1015.    Sessions, processes, and threads are documented
  1016.    in Chapter 7 of the "OS/2 2.0 Programming Guide
  1017.    Volume I: Control Program".  In Figure 7-1 on
  1018.    page 7-2, in the center box of the figure,
  1019.    change the word "Sessions" to "Processes".
  1020.  
  1021.  
  1022.  
  1023. USER-DEFINED EXCEPTIONS
  1024.  
  1025.    Exception management is documented in Chapter 13 of
  1026.    the "OS/2 2.0 Programming Guide Volume I: Control
  1027.    Program".  On page 2-339, under the heading
  1028.    "User-Defined Exceptions", change the example for
  1029.    raising exceptions from:
  1030.  
  1031.        DosRaiseException(XCPT_YOUR_EXCEPTION);
  1032.  
  1033.    to the following:
  1034.  
  1035.        EXCEPTIONREPORTRECORD  ERepRec;
  1036.  
  1037.        ERepRec.ExceptionNum                = XCPT_YOUR_EXCEPTION;
  1038.        ERepRec.fHandlerFlags               = 0;
  1039.        ERepRec.NestedExceptionReportRecord = NULL;
  1040.        ERepRec.ExceptionAddress            = NULL;
  1041.        ERepRec.cParameters                 = 0;
  1042.  
  1043.        DosRaiseException(&ERepRec);
  1044.  
  1045.  
  1046.  
  1047. ADDENDUM TO PHYSICAL DEVICE DRIVER REQUEST PACKET DOCUMENTATION
  1048.  
  1049.    The format of the physical device driver's
  1050.    Request Packet Status WORD is described on page
  1051.    15-2 of the "OS/2 2.0 Physical Device Driver
  1052.    Reference".  This addendum relates to bit 15
  1053.    (the Error bit), bit 8 (the Done bit), and bits
  1054.    7-0 (Error Code).
  1055.  
  1056.        Bit 8 (the Done bit) MUST be set, even when
  1057.        bit 15 (the Error bit) is set.  That is,
  1058.        whenever you return with the Error bit set,
  1059.        you must also set the Done bit.
  1060.  
  1061.  
  1062.  
  1063. CHANGE TO DOCUMENTATION FOR PHYSICAL MOUSE DEVICE DRIVER IDC
  1064.  
  1065.    The physical Mouse device driver's inter-device-driver
  1066.    communication (IDC) interface is documented in the
  1067.    "OS/2 2.0 Physical Device Driver Reference", in
  1068.    Chapter 12, "Physical Mouse Device Driver".  In the
  1069.    section headed "MOUSE.SYS IDC Interface", under the
  1070.    information on the Process_Absolute IDC request, at
  1071.    bottom of page 12-3 and top of page 12-4, there is
  1072.    a reference to the "event" field that must be changed.
  1073.    Remove the following sentences:
  1074.  
  1075.        The event field should never indicate that
  1076.        motion was associated with the event.
  1077.        MOUSE$ determines if motion occurs.
  1078.  
  1079.  
  1080.  
  1081. ADDENDUM TO DOCUMENTATION FOR THE LOCK DEVHLP
  1082.  
  1083.    The Lock DevHlp is described on pages 17-43 and
  1084.    17-44 of the "OS/2 2.0 Physical Device Driver
  1085.    Reference".  On page 17-44, at the end of the
  1086.    Remarks for Lock, add the following paragraph:
  1087.  
  1088.        By default, when DosDevIOCtl passes an
  1089.        address to a device driver, it passes the
  1090.        address in the form of a temporary
  1091.        selector.  This selector is only valid for
  1092.        the duration of the call and cannot be used
  1093.        to lock the memory using the Lock DevHlp.
  1094.        If you need to lock this memory, the
  1095.        calling program must use the DosAllocMem
  1096.        function with the object tile (OBJ_TILE)
  1097.        bit set.  If you pass a pointer to this
  1098.        memory in the call to DosDevIOCtl, the
  1099.        device driver can use the Lock DevHlp to
  1100.        lock this memory.
  1101.  
  1102.  
  1103.  
  1104.  
  1105. NOTICES
  1106. _______
  1107.  
  1108.    References in this publication to IBM products,
  1109.    programs, or services do not imply that IBM
  1110.    intends to make these available in all
  1111.    countries in which IBM operates.  Any reference
  1112.    to an IBM product, program or service is not
  1113.    intended to state or imply that only IBM's
  1114.    product, program, or service may be used.  Any
  1115.    functionally equivalent product, program, or
  1116.    service that does not infringe any of IBM's
  1117.    intellectual property rights or other legally
  1118.    projectable rights may be used instead of the
  1119.    IBM product, program, or service.  Evaluation
  1120.    and verification of operation in conjunction
  1121.    with other products, programs, or services,
  1122.    except those expressly designated by IBM, are
  1123.    the user's responsibility.
  1124.  
  1125.    IBM may have patents or pending patent
  1126.    applications covering subject matter in this
  1127.    document.  The furnishing of this document does
  1128.    not give you any license to these patents.  You
  1129.    can send license inquiries, in writing, to the
  1130.    IBM Director of Commercial Relations, IBM
  1131.    Corporation, Purchase, NY 10577.
  1132.  
  1133.  
  1134.  
  1135. TRADEMARKS AND SERVICE MARKS
  1136.  
  1137.    The following terms denoted by an asterisk
  1138.    (*) used in this publication are trademarks,
  1139.    or service marks of the IBM Corporation in the
  1140.    United States or other countries:
  1141.  
  1142.    IBM
  1143.    OS/2
  1144.    Presentation Manager
  1145.    Workplace Shell
  1146.  
  1147.  
  1148.    The following terms denoted by double asterisks
  1149.    (**) used in this publication are trademarks,
  1150.    or service marks of non-IBM Corporations in
  1151.    the United States or other countries:
  1152.  
  1153.    Microsoft Windows
  1154.  
  1155.    IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED
  1156.    OR IMPLIED, INCLUDING WITHOUT LIMITATION,
  1157.    WARRANTIES OF FITNESS AND MERCHANTABILITY WITH
  1158.    RESPECT TO THE INFORMATION IN THIS DOCUMENT.
  1159.    BY FURNISHING THIS DOCUMENT, IBM GRANTS NO
  1160.    LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS.
  1161.  
  1162.  
  1163.    Copyright International Business Machines Corporation, 1993.
  1164.    All Rights Reserved.
  1165.