home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / famapi.zip / FAMAPI.1 < prev    next >
Text File  |  1993-06-13  |  8KB  |  198 lines
  1. >---L--------------------------------------------------------------------------R
  2. >>>
  3. >>> This is a PROFF document, and not part of the release.
  4. >>>
  5. >>> To format, use PROFF.EXE
  6. >>>
  7. >PL 58
  8. >SM 1
  9. >TM 0
  10. >BM 0
  11. >HM 1
  12. >FM 1
  13. >HE Documentation for C++ Library                                       Page %
  14. >FO Copyright (c) 1991-1993 JdeBP
  15.  
  16.            C++ Library Family API Documentation -- 13th June 1993
  17.  
  18.                             Package Version 1.00
  19.  
  20.             Package Copyright (c) 1993 Jonathan de Boyne Pollard
  21.              Licensed under General Public Licence version 1.00
  22.  
  23.                Jonathan de Boyne Pollard, c/o 1 Queen's Close
  24.                      KENILWORTH  CV8 1JR, United Kingdom
  25.                   Telephone +44 926 484512 (0900-1730 GMT)
  26.  
  27.            I am also available in the FIDO OS2PROG and OS2DOS echos,
  28.        and on the Mission Impossible BBS, Nottingham, United Kingdom on
  29.                      +44 602 655394/654329/654680/653247.
  30.  
  31.     This file is plain ANSI text with embedded tabs and form-feeds. It may be
  32.     viewed with an ANSI file viewer. This is preferable to printing it out,
  33.     because saving paper saves the environment.
  34.  
  35.     To view :    LIST FAMAPI.DOC        (Vernon Buerg's file viewer)
  36.     To print :   PRINT FAMAPI.DOC       (MDOS and OS/2 print utility)
  37.  
  38.     This file contains documentation for the Family API portion of the C++
  39.     library written for Borland C++ version 3.x by Jonathan de Boyne Pollard.
  40.     The library has been tested in programs compiled for real and protected
  41.     mode under OS/2 2.0 and DR-DOS 6.0.
  42.  
  43.     Although I have taken great pains to ensure that the library is
  44.     problem-free (or at least, any known problems are thoroughly documented),
  45.     if you do find a problem with it, please contact me in writing at the
  46.     address given and I will attempt to cure it. Please provide example source
  47.     code and makefiles where possible.
  48.  
  49. >PA
  50.  
  51.     Purpose
  52.     ───────
  53.  
  54.     You will need this Family API library to develop 16-bit dual mode
  55.     OS/2 programs using Borland C++ 3.x for DOS.
  56.  
  57.     Although it is not needed in protected mode, this provides support for
  58.     v8086 and real mode DOS equivalents for all OS/2 calls made by the
  59.     Cx.LIB libraries.
  60.  
  61.     This library can also be used as a separate product for those who wish
  62.     to use all of the functionality of OS/2's high-level-language API
  63.     instead of assembly language calls for PC-DOS.
  64.  
  65.     Full source is provided for your reference only. Note that COPYING.DOC
  66.     restricts you to only distributing the original library in the original
  67.     form that you obtained it. The MANIFEST document details what the
  68.     library should contain.
  69.  
  70. >PA
  71.  
  72.     Family API calls
  73.     ────────────────
  74.  
  75.     Full documentation of the Family API calls can be found in any good OS/2
  76.     1.x 16-bit reference. Most 16-bit OS/2 calls map directly from the
  77.     PC-DOS API, although the parameters and functions of some were tidied up
  78.     some.
  79.  
  80.     The PRCP.INF file is also available as shareware (not from me, though!)
  81.     for those who wish to have the 16-bit API in INF format. I use it myself
  82.     just to cross-check this library.
  83.  
  84.     It is interesting to note that the December 1992 beta release of OS/2
  85.     2.1 contained versions of Dos16SubSet/Dos16SubAlloc/Dos16SubFree that
  86.     would cause segmentation faults under certain conditions.
  87.  
  88.     The author linked the versions of those calls supplied here instead of
  89.     the DOSCALLS1.DLL versions, and the author's worked in protected mode.
  90.     At the time of writing it is unknown whether the 2.1 GA code has been
  91.     fixed (GA release is tomorrow would you believe ?).
  92.  
  93.     Source
  94.     ──────
  95.  
  96.     In order to recompile, you will need the <dos.h>, <os2.h>, and
  97.     <limits.h> headers from the shareware Borland C++ 3.x cross-development
  98.     kit for OS/2. This has not been released at the time of writing, so the
  99.     INCLUDE.ZIP file contains the current versions of the headers.
  100.  
  101. >PA
  102.  
  103.     Mou Calls
  104.     ─────────
  105.  
  106.     Note that the Mou calls have not been implemented. It is hoped that they
  107.     will be in a future version of this library.
  108.  
  109.     Vio Calls
  110.     ─────────
  111.  
  112.     The Vio routines will handle all text modes, and (to some extent)
  113.     graphics modes as well. However, background colours will not work in
  114.     graphics modes, and you may discover some oddities.
  115.  
  116.     It is not the intention of this library to provide a graphics library
  117.     for DOS programs. If you wish to pursue graphics programs, I suggest
  118.     that you move directly to Presentation Manager.
  119.  
  120.     The Vio mode changing routines will not handle dual monitors, although
  121.     this is of some inconvenience to the author, who is working on it for a
  122.     future release.
  123.  
  124.     Kbd Calls
  125.     ─────────
  126.  
  127.     The Kbd calls do not support some of the more esoteric features of the
  128.     Kbd interface, such as raw mode and reporting shift states. It is
  129.     suggested that anyone wishing to use such functionality switch to
  130.     Presentation Manager, which provides a much better keyboard interface.
  131.  
  132.     The Kbd subsystem implemented here only accomodates enough to implement
  133.     <conio.h> functionality in the Borland C++ 16-bit cross-development
  134.     library.
  135.  
  136.     Dos Calls
  137.     ─────────
  138.  
  139.     The more obscure calls Dos, such as DosDevIoctl, have not been
  140.     implemented either, for the same reason, and also because the 16-bit
  141.     interface is not out of date for OS/2.
  142.  
  143.     If you wish to tinker with the hardware directly, it is suggested that
  144.     you use the full 32-bit interface, which more fully supports CD-ROM and
  145.     Network file systems, as well as HPFS.
  146.  
  147. >PA
  148.  
  149.     Forthcoming developments
  150.     ────────────────────────
  151.  
  152.     As part of an effort to standardise cross-platform development on OS/2,
  153.     a future version of this library is planned that will link as a 16-bit
  154.     DLL under Microsoft Windows 3.x.
  155.  
  156.     It is the author's belief that the library will work as it stands under
  157.     Windows 3.x, although the Dos3Call can be changed to use the
  158.     undocumented KERNEL call of the same name instead of issuing an INT 21h
  159.     instruction.
  160.  
  161.     This allows the Borland C++ 16-bit conversion kit to link smaller
  162.     Windows 3.x programs with no change fo source code.
  163.  
  164.     We look forward to a shareware MIRRORS system ...
  165.  
  166. >PA
  167.  
  168.     Other products from Jonathan de Boyne Pollard
  169.     ─────────────────────────────────────────────
  170.  
  171.     Naturally, the Borland C++ for DOS 16-bit devlopment kit for OS/2 is
  172.     also available as BC3-OS2.ZIP.
  173.  
  174.     Also available as shareware are twin sets of command-line utilities for
  175.     DOS and OS/2 sessions (DOSCLUnn.ZIP and OS2CLUnn.ZIP), developed with
  176.     this library, including :
  177.  
  178.     ■ FF - File Finder ■ extended ATTRIB command ■
  179.     ■ extended XDIR and XDEL commands ■ WHICH file search utility ■
  180.     ■ TOUCH file date/time utility ■ Intelligent file DUMP ■
  181.     ■ MEM memory (XMS/DPMI) display for DOS ■
  182.     ■ And (as they say) many, many, more ...
  183.  
  184.     These will be available from all good BBSes. If they are not available
  185.     to you locally they are also available for downloading from Mission
  186.     Impossible BBS in the United Kingdom, on +44 602
  187.     655394/654329/654680/653247.
  188.  
  189.     Warranty and Licence
  190.     ────────────────────
  191.  
  192.     For warranty and licence conditions, see the file COPYING.DOC.
  193.  
  194.     Credits
  195.     ───────
  196.  
  197.     Many thanks to Russ Freeman for testing early versions of this library.
  198.