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