home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / APIEXT.ZIP / README < prev   
Text File  |  1988-04-18  |  6KB  |  147 lines
  1.  
  2.  *  Description:
  3.  *  ----------------------------------------------------------------------
  4.  *  APIEXT is an M extension written by Byron Dazey to help developers
  5.  *  convert from the all uppercase OS/2 API convention using the include
  6.  *  file "doscalls.h" used by C 4.5 to the mixed case API convention using
  7.  *  "os2.h" used in the newer C 5.1 product.
  8.  *
  9.  *  By default,  these functions assume the existence of the file
  10.  *  "os2api.lst" in the current directory.  This file contains the API's
  11.  *  in their mixed case form and is sectioned off in groups by the #define
  12.  *  names that need to be defined to include them (called INCL's).
  13.  *  Lines in this file that start with a semi-colon are comments,
  14.  *  lines that start with a "#" are INCL's. Other lines are assumed to
  15.  *  be OS/2 API's in their mixed case form.  For example:
  16.  *
  17.  *  ----------os2api.lst------------
  18.  *  ;comments here            <- This is a comment line
  19.  *  #INCL_DOSPROCESS            <- This is a #define
  20.  *  DosExecPgm                <-
  21.  *  DosExit                <- These are API's for INCL_DOSPROCESS
  22.  *
  23.  *  If required, the text switch "apilist" can be set to the path and
  24.  *  file name of the file that contains the API's.  If used, this switch
  25.  *  must contain at least the file name portion of the location of this
  26.  *  list.  For instance:
  27.  *
  28.  *  apilist:c:\init\apilist.txt      or
  29.  *  apilist:apilist.txt
  30.  *
  31.  *  would be valid, but not:
  32.  *
  33.  *  apilist:c:\init
  34.  *
  35.  *
  36.  *  This extension needs to be "loaded" into the editor to be used.  This
  37.  *  can be done in the TOOLS.INI file by adding the following lines:
  38.  *
  39.  *  [mep]
  40.  *    load:apiext
  41.  *
  42.  *  for OS/2 or:
  43.  *
  44.  *  [m]
  45.  *    load:apiext.exe
  46.  *
  47.  *  for DOS.
  48.  *
  49.  *  To use in OS/2, copy the file APIEXT.DLL to somewhere on your LIBPATH
  50.  *  and edit your TOOLS.INI file as described above.  Invoke MEP on the
  51.  *  file to convert and press alt+2 or alt+1 (unless you have re-assigned
  52.  *  these keys).
  53.  *
  54.  *  To use in DOS, copy the file APIEXT.EXE to somewhere on your PATH and
  55.  *  edit your TOOLS.INI file as described above.  Invoke M on the file to
  56.  *  convert and press alt+2 or alt+1 (unless you have re-assigned these
  57.  *  keys).  I had trouble with my version of M not finding the apiext.exe
  58.  *  file on the path.  If this happens, copy apiext.exe to your current
  59.  *  directory or fully qualify the pathname in the "load:" statement in
  60.  *  TOOLS.INI (ex. load:c:\tools\bin\apiext.exe).
  61.  *
  62.  *
  63.  *  Extension: convertapi
  64.  *
  65.  *  Description
  66.  *  ----------------------------------------------------------------------
  67.  *  This extension is used to convert all the occurances of an OS/2 API
  68.  *  to its mixed case equivalent.  The os2api.lst file is read and all the
  69.  *  API's listed are searched for without regard for case and globally
  70.  *  replaced with the case as found in the os2api.lst file.  Because the
  71.  *  length of the API is not changing, comments should not need to be
  72.  *  lined up again.
  73.  *
  74.  *  This extension will search through the current file for where the
  75.  *  include file "doscalls.h" is being included and replace it with a
  76.  *  line including "os2.h".  If "doscalls.h" is not found then it will
  77.  *  add the include for "os2.h" at the beginning of the file.
  78.  *
  79.  *  This line can be in any of the following forms, with the case of
  80.  *  "doscalls.h" and the number of spaces after "include" not being
  81.  *  important:
  82.  *
  83.  *  #include <doscalls.h>
  84.  *  #include "doscalls.h"
  85.  *  #include        <DOSCALLS.H>
  86.  *
  87.  *
  88.  *  These will be replaced with:
  89.  *
  90.  *  #include <os2.h>
  91.  *
  92.  *
  93.  *  A line including "subcalls.h" will also be searched for in a similiar
  94.  *  manner and will be deleted if found.
  95.  *
  96.  *  This extension will then search for the API's in each group in the
  97.  *  os2api.lst file and if an API for a certain "INCL" is found, it will
  98.  *  insert an appropriate #define statement for it before the include for
  99.  *  "os2.h".  For example, if "DosExecPgm" is found in the file, the
  100.  *  following will be added to the file:
  101.  *
  102.  *  #define INCL_DOSPROCESS
  103.  *  #include <os2.h>
  104.  *
  105.  *  WARNING!
  106.  *  API's that appear in comments and conditionally compiled sections of
  107.  *  code will be converted.  In addition, if any function or variable has
  108.  *  been named with part of an API's name, it will be converted to mixed
  109.  *  case also.    For instance, the user function "xDOSEXIT" would be
  110.  *  converted to "xDosExit".  This could also result in more #define
  111.  *  statements than are strictly necessary.  This is not a C preprocessor!
  112.  *
  113.  *  This function is not blinding fast.  It must invoke a global search
  114.  *  and replace on each OS/2 API and this can take a while for large
  115.  *  source files.  It is, however, much faster than doing it by hand and
  116.  *  should only need to be done once.
  117.  *
  118.  *
  119.  *
  120.  *  Extension: insertapiincl
  121.  *
  122.  *  Description
  123.  *  ----------------------------------------------------------------------
  124.  *  This extension will search for the API's in each group in the
  125.  *  os2api.lst file and if an API for a certain "INCL" is found, it will
  126.  *  insert an appropriate #define statement for it at the top of the file.
  127.  *  For example, if "DosExecPgm" is found in the file, the following will
  128.  *  be added to the top of the file:
  129.  *
  130.  *  #define INCL_DOSPROCESS
  131.  *
  132.  *  This functionality is also included in the convertapi function.  It is
  133.  *  repeated in this function so that a programmer can find all the names
  134.  *  of the INCL's that must be defined for a converted program that has
  135.  *  undergone some development/maintenance since being converted.  In some
  136.  *  cases it would be useful to know if all the INCL's being defined still
  137.  *  need to be.
  138.  *
  139.  *  WARNING:
  140.  *  API's that appear in comments or in conditional sections of code will
  141.  *  still be considered when searching.  In addition, if any function or
  142.  *  variable has been named with part of an OS/2 API's name, it will be
  143.  *  considered a match.  For instance, if there is a function named
  144.  *  xDosExecPgm then INCL_DOSPROCESS will be included.    This could result
  145.  *  in more #defines than are strictly necessary.
  146.  *
  147.