home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_200 / 271_02 / smlibtc.doc < prev    next >
Text File  |  1987-08-20  |  45KB  |  1,255 lines

  1.          
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                             ==========================
  15.                             =    STEVE'S LIBRARY     =
  16.                             =      for Turbo C       =
  17.                             =        - by -          =
  18.                             =   Steven E. Margison   =
  19.                             =      Version 1.30      =
  20.                             ==========================
  21.  
  22.  
  23.                     Functions and Documentation Copyright 1987
  24.                    by Steven E. Margison -- All Rights Reserved
  25.  
  26.  
  27.                                 ISBN 0-944267-05-X
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.          
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.          
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.                       --------- TABLE OF CONTENTS ---------
  75.  
  76.  
  77.               Introduction ................................. 1
  78.               The Documentation ............................ 1
  79.               Installation ................................. 2
  80.               Linking ...................................... 3
  81.               Real Time Interrupt Handler .................. 4
  82.               Video Functions .............................. 5
  83.                  A.  Introduction .......................... 5
  84.                  B.  Initialization ........................ 5
  85.                  C.  De-Initialization ..................... 6
  86.                  D.  Cursor and Character Placement ........ 6
  87.                  E.  Writing Characters and Attributes ..... 7
  88.                  F.  Miscellaneous Operations .............. 7
  89.                  G.  Video Page Switching .................. 8
  90.                  H.  Reading from Video Memory ............. 9
  91.               Utilities ..... .............................. 10
  92.               Shareware .................................... 15
  93.               Warranty ..................................... 16
  94.               Registration Form ............................ --
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.          
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.          
  134.  
  135.  
  136.  
  137.  
  138.                       Steve's C Function Library for Turbo C
  139.  
  140.  
  141.          I. INTRODUCTION
  142.                  The heart  of  the  C  language  is  its  library.  Each
  143.          compiler has its own library of  functions,  which  is  complete
  144.          only  to  the degree that the compiler author wishes to make it.
  145.          The Turbo C Compiler is an excellent product, and comes  with  a
  146.          very   extensive  function  library  which  has  all  the  usual
  147.          "standard" functions, plus many DOS functions as well.  However,
  148.          the more functions a programmer has at his disposal, the shorter
  149.          the time from idea to complete program.  That's  where  "Steve's
  150.          Library" comes  in.    At  over 100 functions my library greatly
  151.          enhances program development with Turbo C.
  152.                  "Steve's Turbo-C Library" is the third  library  I  have
  153.          produced,  the other two being for the Datalight C compiler, and
  154.          the Lattice C compiler.  Many of the functions in  this  library
  155.          may also  be  found  in  the  other  two  libraries  as well.  A
  156.          significant exception is the direct video functions.   Datalight
  157.          C has an excellent (though incomplete) set of functions aimed at
  158.          providing direct access to screen memory.  Turbo-C does not have
  159.          these  functions, however, and I think the omission is a serious
  160.          flaw in any MS-DOS compiler.  I have corrected that situation in
  161.          my Turbo-C library by adding an entire package of  direct  video
  162.          access  functions, supporting standard IBM-type video boards and
  163.          modes.
  164.  
  165.  
  166.  
  167.  
  168.          II. THE DOCUMENTATION
  169.                  The documentation for the  library  is  contained  in  a
  170.          number of .DOC  files,  which  describe  each  function.    When
  171.          printed, these pages may be  placed  in  a  standard  three-ring
  172.          binder.  A utility program, PMAN.COM is provided to generate the
  173.          entire set  of documents.  PMAN requires the file LISTALL, which
  174.          may be edited to eliminate printing of certain files if desired.
  175.          (PMAN is copyrighted, but placed in the public domain.)
  176.                  To print the DOC files, you must be in a  directory  (or
  177.          on  a  floppy)  containing PMAN, LISTALL, and all the DOC files.
  178.          Just type "PMAN" at your system prompt and  the  files  will  be
  179.          printed to PRN:.
  180.                  This  documentation  is  not  intended  to be a complete
  181.          course on writing in "C", or on using the Turbo-C compiler.   It
  182.          is  assumed  that  if  you  have  this library, you already have
  183.          Turbo-C and have read Borland's fine manual.
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.                    Steve's Library for Turbo C          Page 1           
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.          
  200.  
  201.  
  202.          III. INSTALLATION
  203.                  "Steve's Turbo-C Library" is distributed as five library
  204.          files for each type of memory model. (Only the full registration
  205.          with source has all five libraries.) The filenames are:
  206.               SMTCS.LIB       Small Memory Model
  207.               SMTCC.LIB       Compact Memory Model
  208.               SMTCM.LIB       Medium Memory Model
  209.               SMTCH.LIB       Huge Memory Model
  210.               SMTCL.LIB       Large Memory Model
  211.          For  the remainder of this manual the libraries will be referred
  212.          to as SMTCx.LIB.
  213.          A typical hard disk installation  of  Turbo-C  will  consist  of
  214.          several directories, one of which will contain all the "include"
  215.          files  (those  with  ".H"  extensions)  and one with the library
  216.          files (those with ".LIB" extensions).   All  files  in  "Steve's
  217.          Library" with a ".H" extension should be placed in the directory
  218.          with the  Turbo-C  ".H" files.  Similarly, all "Steve's Library"
  219.          files with a ".LIB" extension should be placed with the  Turbo-C
  220.          ".LIB" files.   The documentation and source files from "Steve's
  221.          Library" do not need to be on the hard disk, as they  will  only
  222.          be  used  to  print  the  documentation  or  modify the function
  223.          source.  They are not used in the direct creation of  a  program
  224.          under  Turbo-C.  The executable utilities (*.EXE) files supplied
  225.          with "Steve's Library" may be optionally placed in any directory
  226.          specified in your PATH environment.    These  programs  are  all
  227.          examples  of  function  usage  and  C  programming,  and  do not
  228.          directly relate to program  development  for  Turbo-C.  However,
  229.          they are useful and should be placed on your system for access.
  230.                  The  files  with  "Steve's Library" with an extension of
  231.          ".SEM"  or  ".MAC"  are  required  only  for  re-assembling  the
  232.          assembly language  modules  from this library.  They do not need
  233.          to be placed on your hard disk unless you  plan  to  re-assemble
  234.          any ".ASM" source code files.
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.                     Steve's Library for Turbo C          Page 2          
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.          
  266.  
  267.  
  268.          IV. LINKING
  269.                  The SMTCx.LIB library must  be  linked  with  any  other
  270.          libraries whenever  a  function  is  used in your program.  Some
  271.          programs may not use  SMTCx.LIB  functions,  and  therefore  the
  272.          linking of  the  library  may  be  eliminated  to save time.  In
  273.          addition, if you have other third party libraries,  be  sure  to
  274.          include them after SMTCx.LIB.
  275.                  There  are several methods to invoke the SMTCx.LIBs when
  276.          linking under Turbo C. Refer to the Turbo C  manual,  chapter  3
  277.          (User's  Guide)  for  information  on  using  the libraries from
  278.          within the TC programming environment.   If  you  use  Borland's
  279.          "MAKE" utility with "TLINK", then include a link line similar to
  280.          this:
  281.          libs = \btc\lib\smtcs+\btc\lib\cs
  282.          
  283.          program: program
  284.                  tlink \btc\c0s+program, program,,$(libs) /M
  285.  
  286.          This  command  will link program.obj, c0s.obj, and the indicated
  287.          libraries.  Be sure to include the path if the libraries are NOT
  288.          in the directory in which the link tales place.
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.                    Steve's Library for Turbo C          Page 3           
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.          
  332.  
  333.  
  334.          V. REAL TIME INTERRUPT HANDLER
  335.                  A  special  feature of "Steve's Library" is the "ticker"
  336.          interrupt handler  function.    This   function   provides   the
  337.          programmer  with  the  ability  to  install a special routine to
  338.          intercept DOS interrupt 1CH. ticker()  is  a  pre-built  handler
  339.          which  allows  the  user  to  perform operations relative to the
  340.          system's clock.  A special variable may be loaded with  a  value
  341.          and then tested at intervals.  When the variable has hit zero, a
  342.          specific amount  of  time  has passed.  The variable counts 18.2
  343.          times per second, and is installed on INT 1CH.
  344.                  The usage of this interrupt  handler  forces  some  hard
  345.          rules on  the  programmer.    Since this is an interrupt routine
  346.          which is called asynchronously to your  program,  it  ABSOLUTELY
  347.          MUST  be  un-installed  BEFORE  your program exits to DOS. To do
  348.          otherwise will invariably cause the next program  run  to  crash
  349.          the  system,  since  the 1CH interrupt will then be invoked to a
  350.          section of code in the new program which is NOT intended  to  be
  351.          run  from  int 1CH. Therefore, it is imperative to control exits
  352.          from your program when using the ticker.  This means  that  your
  353.          program   should   exit   from   only  one  place,  which  calls
  354.          removetick() before performing  the  actual  exit.    With  good
  355.          program  design,  this  is easy to accomplish. (Watch out for my
  356.          error(), cant(), badext(), and eraok() functions, though,  since
  357.          they  will  exit  the  program all by themselves!) What isn't so
  358.          obvious is the manner in which a program may exit beyond control
  359.          of the program itself.   This  is  done  if  the  user  types  a
  360.          control-break, or responds with (A)bort to a DOS critical error.
  361.          To  avoid  exiting  the  program  under these circumstances, any
  362.          program which uses the ticker MUST ALSO use Turbo-C's  ctrlbrk()
  363.          AND  harderr()  functions  to trap and cleanly process a program
  364.          exit.  Refer to the Turbo-C manual for the proper use  of  these
  365.          two interrupt  handler functions.  Again, once installtick() has
  366.          been invoked, be sure that your program cannot possible exit  to
  367.          DOS unless removetick() has been called first.
  368.                  One  exception:  if  the program is a terminate and stay
  369.          resident (TSR) utility which needs interrupt  1CH  to  function,
  370.          then  removetick()  should  NOT  be  invoked  before  using  the
  371.          resident exit DOS command.  Since the program will still  reside
  372.          in  memory,  there  will  be  no conflict in having the ticker()
  373.          active.
  374.                  A file is included named  TESTINTS.C,  which  shows  the
  375.          usage of  the  ticker  functions.  This file may be compiled and
  376.          run. (Ignore any warnings about suspicious  pointer  conversions
  377.          -- it is really O.K.)
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.                     Steve's Library for Turbo C          Page 4          
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.          
  398.  
  399.  
  400.          VI. VIDEO FUNCTIONS
  401.                                  A. Introduction
  402.                  "Steve's  Library"  provides  a  complete  facility  for
  403.          direct writes  and  reads in video memory.  Direct video memory,
  404.          dvid for short, provides the programmer with a means of creating
  405.          extremely fast screen displays, with full  control  over  colors
  406.          and attributes.   Virtually all "real good" programs, commercial
  407.          or otherwise, make use of direct  video  access  to  create  the
  408.          rapid, "sparkling"  displays  that  attract users.  There is one
  409.          gotcha, though.  Direct video access works only on systems which
  410.          are truly IBM compatible.   Thankfully,  this  is  almost  every
  411.          PC-type system  nowadays.    However,  there  still  may  be the
  412.          occasional wierdo system which places video memory at an oddball
  413.          address.  With these systems, the direct video access package in
  414.          this library  will  fail.    However,  since  there  is  a  BIOS
  415.          override,  it should still be possible to configure a program to
  416.          operate using rom-bios services for those cases.
  417.                  Using dvid  is  very  simple,  but  carries  some  extra
  418.          responsibility  for  the  programmer,  especially if the program
  419.          being created is intended for public distribution.  Some  things
  420.          to consider are:
  421.               *  provision  for  forcing  black & white on a CGA, in
  422.               case the user has only a monochrome monitor
  423.               * provision for changing  the  default  colors.  (Just
  424.               because  YOU  like  magenta  text on a blue background
  425.               doesn't mean that everybody else is stupid!)
  426.               * provision for forcing bios routines in case the user
  427.               has an oddball video system.
  428.               * sensing a monochrome adapter card (MDA) and altering
  429.               the  program  accordingly;   i.e.,   no   video   page
  430.               switching, and an underline attribute.
  431.                  Of  course,  you  can  always  specify that your program
  432.          requires a CGA only, or an MDA only, but it is  better  to  have
  433.          the ability to work with both if possible.  For the remainder of
  434.          this  discussion  it  may  be handy to have a printout of DUMP.C
  435.          (one of the supplied utilities) for  reference.    This  program
  436.          does not take into consideration user configuration, since it is
  437.          supplied in source  form.    Don't  like  the  colors?  Edit the
  438.          source and re-compile it!  As a matter  of  fact,  this  program
  439.          serves as  a  good  "test  bed"  for  the  dvid functions.  Many
  440.          modifications are possible to demonstrate the use  of  the  dvid
  441.          functions.
  442.  
  443.                                 B. Initialization
  444.                  Before  the  dvid functions can be used, the dvid_init()
  445.          function must  be  invoked.    This  function  investigates  the
  446.          system's  resources  and  sets the base video address, number of
  447.          rows, and  columns,  into  its  private  memory  area.      This
  448.          information is  critical to proper dvid operation.  Using any of
  449.          the functions before invoking dvid_init()  will  probably  cause
  450.          problems  on  MONO boards, and definitely cause trouble with CGA
  451.          or EGA boards.  If the initialization procedure  encounters  any
  452.  
  453.  
  454.                     Steve's Library for Turbo C          Page 5          
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.          
  464.  
  465.  
  466.          type of video information which it  cannot  understand,  then  a
  467.          flag is set and all video access through the system will then be
  468.          done  through  rom-bios  video  services, instead of directly to
  469.          memory.  Generally, the only effect of  this  will  be  to  make
  470.          screen writing noticably slower, but still not as slow as normal
  471.          text writing.    In addition, it will NOT be possible to display
  472.          one CGA video page and write to a different one.   However,  the
  473.          occasions when  this would occur should be very rare.  There are
  474.          ways to insure that EGA cards will behave as MONO or CGA  cards.
  475.          By using the vmode() function you can set the video mode desired
  476.          before calling dvid_init().  Then, dvid_init() should obtain the
  477.          correct  mode from an EGA emulating a CGA, and avoid setting the
  478.          bios flag.
  479.                  dvid_init() has no effect  if  called  more  than  once,
  480.          since a  check is made on an initialization flag.  Therefore, it
  481.          is  not  possible  to  change  video  modes  and   then   recall
  482.          dvid_init().   In  order  for  dvid_init()  to re-initialize the
  483.          video   system,   dvid_done()   must   first   be   called    to
  484.          "de-initialize"  the  video  system  and  restore  all  internal
  485.          defaults.
  486.  
  487.                                C. De-Initialization
  488.                  There  is  really  no  overwhelming  need  to  call  the
  489.          dvid_done() function, unless you just happen to be a "neat-nik".
  490.          dvid_done()  updates the screen cursor position and restores the
  491.          cursor shape to what it was when dvid_init() was  invoked.    In
  492.          addition,  it  will  restore  all  of the dvid function internal
  493.          parameters to their default values and make possible the  recall
  494.          of dvid_init().    Normally,  dvid_done()  would  be called just
  495.          prior to exiting the program.
  496.  
  497.                         D. Cursor and Character Placement
  498.                  The  dvid  system  maintains  two  sets  of   row/column
  499.          parameters.   The  first indicates where the NEXT character will
  500.          be written in the video memory.  The second stores the  position
  501.          of the  REAL  onscreen cursor.  Since rom-bios routines are used
  502.          to change the  location  of  the  onscreen  cursor,  it  is  not
  503.          efficient to continually update the onscreen cursor for all dvid
  504.          write operations.    The  dvid_flush()  function  is provided to
  505.          perform that operation.  I will refer to the "internal"  cursor,
  506.          and the  "screen"  cursor  in  the  following  discussions.  The
  507.          internal cursor is the position which will be next written.  The
  508.          screen cursor is the  actual  onscreen  cursor,  whether  it  is
  509.          actually visible or not.
  510.                  All of the dvid functions which take a row/col value and
  511.          a   character   or   string  argument,  such  as  dvid_say()  or
  512.          dvid_char_at(),  will  call  dvid_flush()  at  the  end  of  the
  513.          operation  to  update  the  screen cursor to the internal cursor
  514.          position.   However,  the  lower   level   functions   such   as
  515.          dvid_putchr() will NOT automatically update the screen cursor to
  516.          the internal  cursor.    Normally,  dvid_flush()  is only called
  517.          after a block of  text  is  written  and  it  is  necessary  for
  518.  
  519.  
  520.                     Steve's Library for Turbo C          Page 6          
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.          
  530.  
  531.  
  532.          cosmetic reasons to show where the cursor "really" is.  Since it
  533.          uses  rom-bios  functions,  using  dvid_flush()  sparingly  will
  534.          increase overall screen display speed.
  535.                  The  function  dvid_move()  is  used to set the internal
  536.          cursor position to a new location.  Note that the screen  cursor
  537.          is NOT affected by a call to dvid_move().
  538.  
  539.                        E. Writing Characters and Attributes
  540.                  When  writing  with normal DOS functions to the standard
  541.          output channel, no concern is ever made about screen  attributes
  542.          or colors.    However, when writing directly to video memory, it
  543.          is actually necessary to write out two bytes for each character;
  544.          one is the character, the second is the  attribute.    The  dvid
  545.          system  saves  an  attribute  internally  which is automatically
  546.          written each time a character is written to video  memory.    At
  547.          initialization, the attribute defaults to normal white on black.
  548.          The  dvid_attrib()  function  is  used  to  change  the  default
  549.          attribute to any valid attribute for  the  video  mode  in  use.
  550.          Refer  to the file screen.h for a mnemonic list of screen colors
  551.          and attributes.
  552.                  The primary  function  for  placing  characters  to  the
  553.          screen  is  dvid_putchr(),  although  in practice dvid_say() and
  554.          dvid_char_at() may actually be more useful.  dvid_putchr()  will
  555.          properly  place  all  256  possible  character values with these
  556.          exceptions:
  557.                07H      Sounds Bell
  558.                08H      Backspaces unless internal cursor is in column 0
  559.                09H      moves internal cursor right to next mod-8 column
  560.                         (horizontal TAB)
  561.                0AH      moves internal cursor down 1 row
  562.                         (linefeed)
  563.                         If internal cursor is already at bottom of screen,
  564.                         screen scrolls up by 1 line
  565.                0DH      moves internal cursor to column 0 of current line
  566.                         (carriage return)
  567.                0BH      moves internal cursor up one line, unless cursor is
  568.                         already on line 0
  569.                         (vertical TAB)
  570.                7FH      (delete) is ignored
  571.                All other characters below 20H (space) are ignored
  572.  
  573.                            F.  Miscellaneous Operations
  574.                  There are a number of other functions to aid  in  screen
  575.          management.   As  noted above, a screen attribute can be set and
  576.          altered at will.  The function dvid_getattr()  will  return  the
  577.          value  of  the  current  attribute in use, and the current video
  578.          page selected for  writing.    In  order  to  erase  characters,
  579.          dvid_e2eol()  is  provided  to erase from cursor to end of line,
  580.          and dvid_e2eos() erases from cursor to end of screen.   In  each
  581.          case,  the  cursor position used is the internal cursor, and the
  582.          screen cursor is updated automatically to match.  To  clear  the
  583.          entire screen, do:
  584.  
  585.  
  586.                     Steve's Library for Turbo C          Page 7          
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.          
  596.  
  597.  
  598.             dvid_move(0,0);     /* cursor to upper left corner */
  599.             dvid_e2eos();       /* erase from 0,0 to end of screen */
  600.               - or -
  601.             dvid_cls();         /* performs a direct screen clear &
  602.                                    home cursor */
  603.  
  604.                  The CGA video card must be written  to  (or  read  from)
  605.          only at certain times to prevent video "snow".  Monochrome cards
  606.          do not  have  this  problem.   Normally, all dvid functions will
  607.          automatically synchronize with the CGA card  to  suppress  snow.
  608.          However,  it is possible to turn synchronization on and off with
  609.          the dvid_sync() function.  An argument of 0  (FALSE)  will  turn
  610.          sync  off,  and  a  non-zero  argument  (TRUE) will turn sync on
  611.          (default condition).  Why turn sync off?  Well, some  EGA  cards
  612.          do  not  produce  snow, so that sync is not needed when they are
  613.          used in CGA mode.  Or, in some cases, the extra speed of writing
  614.          without sync may be preferable to a  little  video  snow.    The
  615.          function is provided so that full flexibility is possible.
  616.                  dvid_scroll() is a function which uses rom-bios features
  617.          to scroll  a  region of the current screen up or down.  Refer to
  618.          the detailed description for this function for an explanation of
  619.          its arguments.
  620.                  If dvid_init() cannot  properly  initialize  itself,  it
  621.          sets  an  internal  flag which then forces the dvid functions to
  622.          use only rom-bios  video  functions.    This  slows  down  video
  623.          access, but  provides compatibility for oddball video cards.  As
  624.          a backup to this, the dvid_bios() function can be  called  AFTER
  625.          dvid_init() to  force the use of bios.  Note that once selected,
  626.          there is no way to turn bios off without calling dvid_done() and
  627.          re-initializing the entire video system.
  628.                  It is possible to change the attributes on a section  of
  629.          the screen  by  using  the dvid_chgattrib().  Parameters are the
  630.          starting row and column, the ending  row  and  column,  and  new
  631.          attribute.   If  using  a  CGA  card,  synchronization  will  be
  632.          performed unless it has been turned off  with  dvid_sync(FALSE).
  633.          Note  that  rom-bios  functions  will  NOT  be  used  with  this
  634.          function.  Therefore, this function MAY fail if used on  a  card
  635.          which  does  not  map video into the "normal" areas, even though
  636.          the use-bios flag has been set.
  637.  
  638.                              G.  Video Page Switching
  639.                  dvid_setpage() may be used to control the video page  in
  640.          use, if  a  CGA  card is being used.  Note that MDA cards do not
  641.          support video paging, and this function will have no effect.  If
  642.          a CGA card is used in 80 column mode, there are 4 video pages in
  643.          memory, numbered 0-3.  For 40 column mode, there  are  8  pages,
  644.          0-7. dvid_setpage() takes two arguments.  The first is the video
  645.          page to  select  for  all  write/read  operations.    The second
  646.          argument is FALSE to select the video page for write/read  only,
  647.          and TRUE  to  also  select  for  display.    Using this function
  648.          judiciously it  is  possible  to  write  to  a  video  page  not
  649.          currently   being  displayed,  and  then  switch  to  that  page
  650.  
  651.  
  652.                    Steve's Library for Turbo C          Page 8           
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.          
  662.  
  663.  
  664.          instantly.  This can be done as follows:
  665.            dvid_setpage(0, TRUE);   /* select page 0 for write and display */
  666.            dvid_setpage(1, FALSE);  /* select page 1 for writing, but do
  667.                                        not change currently displayed page */
  668.            dvid_say(10, 5, "Hello World");  /* write to page 1 */
  669.            dvid_setpage(1, TRUE);      /* make page 1 display now */
  670.          One caution  is  necessary  when  switching  video pages.  It is
  671.          HIGHLY recommended that you insure  a  full  return  to  page  0
  672.          before exiting  the  program.  Leaving the system on a different
  673.          page often prevents subsequent programs from working properly.
  674.  
  675.                           H.  Reading from Video Memory
  676.                  Although few programs will ever need to read what is  on
  677.          the  screen, there is support in "Steve's Library" to accomplish
  678.          this. dvid_getchr() will read the character and video  attribute
  679.          at a  specified  row/column  position.   Synchronization will be
  680.          active or inactive as for writing, and  the  page  selected  for
  681.          writing will be the page used for reading.
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.                     Steve's Library for Turbo C          Page 9          
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.          
  728.  
  729.  
  730.          VII. THE UTILITIES
  731.                  "Steve's  Library"   comes   with   several   utilities,
  732.          including the  C  source code.  Nothing earth shaking here, just
  733.          some convenient programs to make life a little easier.  All  the
  734.          programs use functions from "Steve's Library" , and can serve as
  735.          an example of proper usage.  Here is a short description of each
  736.          utility:
  737.  
  738.                                       INPATH
  739.  
  740.                  This  utility  searches for an EXECUTABLE program in the
  741.          current path.  Typing INPATH at the DOS prompt will display  the
  742.          version number and a short usage message.  To use, type:
  743.  
  744.                inpath <filename>
  745.  
  746.          where filename is the basename portion of the executable file to
  747.          find.   Note  that  an  extension  can  be  specified, but it is
  748.          ignored.  INPATH will first look for the  file  in  the  current
  749.          directory, and then look in the PATH environment variable (if it
  750.          is present)  in the order specified.  For each directory, INPATH
  751.          first tries to locate a .COM file, then a .EXE file, then a .BAT
  752.          file, since that is the order in which DOS searches  for  files.
  753.          On  the  first  match,  INPATH  reports  the  directory and full
  754.          filename of the program and then exits.  If none are found, that
  755.          fact is reported.
  756.  
  757.          INPATH demonstrates the use of newext() and error().
  758.  
  759.  
  760.                                         TC
  761.  
  762.                  This is a quick Text  Compare  program  to  compare  two
  763.          ASCII files.    Typing  TC  at  the  DOS prompt will display the
  764.          version number and a short usage message.  To use, type:
  765.  
  766.                tc file1 file2
  767.  
  768.          where file1 and file2 are the two files  to  compare.    If  the
  769.          files are  identical,  no more messages will appear.  Otherwise,
  770.          the program will report any lines which are different  with  the
  771.          filename, line  number,  and  a printout of the actual line.  If
  772.          one file ends before the other, the program reports  which  file
  773.          terminated first.
  774.  
  775.          TC demonstrates the use of error() and cant().
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.                    Steve's Library for Turbo C          Page 10          
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.          
  794.  
  795.  
  796.                                         WC
  797.  
  798.                  WC counts words, lines, characters, and checksums one or
  799.          more files.  Typing WC  at  the  DOS  prompt  will  display  the
  800.          version number and a short usage message.  To use, type:
  801.  
  802.                 wc filename [-wcls]
  803.  
  804.          where filename  is  the  name  of the file to act upon.  With no
  805.          options, the program will report words, characters, lines, and a
  806.          checksum, which is a simple binary  addition  of  all  character
  807.          values.   No,  it ain't a CRC, but it is a quick check to see if
  808.          it the same as another file under the same name.    The  options
  809.          [wcls] tell the program to report ONLY the items specified:
  810.  
  811.               -w     report only words
  812.               -l     report only lines
  813.               -c     report only characters
  814.               -s     report only checksum
  815.  
  816.          Note that giving all options is the same as giving no options.
  817.  
  818.          Since words, lines, and characters are meaningless in a non-text
  819.          file,  the  program examines the filename extension to determine
  820.          if the file is a binary or text file.    This  isn't  a  perfect
  821.          method, but  it  is good enough.  If the file extension is .COM,
  822.          .EXE, .OBJ, .REL, .PFS, .LIB, or .BIN, then only the checksum is
  823.          reported, overriding all other options.   The  program  supports
  824.          wildcards in the filename, as well as drives and directories.
  825.  
  826.          WC demonstrates the use of exttyp(), and cant().
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.                    Steve's Library for Turbo C          Page 11          
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.          
  860.  
  861.  
  862.                                       OKISET
  863.  
  864.                  This  program  is  used  to  set  the  printing  options
  865.          available  on  an Okidata ML84 (with IBM Plug 'n' Play), or most
  866.          other IBM compatible printers.  It may be easily customized  for
  867.          other printers.    This  is  a  menu driven program requiring no
  868.          options.  Just execute it and follow the directions!
  869.  
  870.  
  871.               F1    PITCH
  872.               Use the SPACE key to toggle between  normal  (10  cpi)
  873.               and condensed  (17.5 cpi) pitch.  Press RETURN to make
  874.               the selection.
  875.  
  876.               F2    STYLE Use the SPACE key to toggle between  draft
  877.               and letter quality style, and press RETURN to select.
  878.  
  879.               F3    LQ  SPACING  Enter  1  or  2 digits in the range
  880.               00-11 to select letter quality spacing.   ESCape  will
  881.               abort  this  entry,  BACKSPACE will allow you to start
  882.               the entry over, and RETURN selects the entered  value.
  883.               This selection assumes letter quality mode, and forces
  884.               the style to letter quality, and the pitch to 10 cpi.
  885.  
  886.               F4    LINES  PER PAGE Enter 1 or 2 digits in the range
  887.               01-99 to set  the  page  length  in  lines  per  page.
  888.               ESCape, BACKSPACE, and RETURN operate as for F3.
  889.  
  890.               F5    LINE  SPACING  Use SPACE key to toggle between 6
  891.               LPI and 8 LPI spacing, and press RETURN to select.
  892.  
  893.               F7    OUTPUT CHANNEL Use SPACE  key  to  step  through
  894.               output channels  PRN, LPT1, and LPT2.  Press RETURN to
  895.               select.
  896.  
  897.               F9    NORMAL OPTIONS This key sets all  other  options
  898.               as  follows:      pitch  >  10  CPI      style > Draft
  899.                   lines > 66     space > 6 LPI     output > PRN
  900.  
  901.               F10    SEND CONTROL CODES and EXIT  No  control  codes
  902.               are sent  until  this  key  is  pressed.  Only control
  903.               codes which have been selected are sent.  If the pitch
  904.               selection remains blank in the menu, for example,  the
  905.               pitch control code will not be sent.  This allows only
  906.               some  options  to  be  changed  without disturbing the
  907.               existing printer configuration.
  908.          Letter quality and  condensed  modes  cannot  be  mixed  on  the
  909.          printer.   Therefore,  if  a  conflicting selection is made, the
  910.          last entry will force correct options.
  911.  
  912.          OKISET will present various beeps for  invalid  keystrokes,  and
  913.          warning messages where appropriate.
  914.  
  915.  
  916.                    Steve's Library for Turbo C          Page 12          
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.          
  926.  
  927.  
  928.  
  929.          OKISET  will  demonstrate  cls(),  mkbox(),  d_say(),  getkey(),
  930.          d_pos(),  and  show  how  to  manage  a  non-scrolling  program.
  931.          Programming idea: re-write this program using the  direct  video
  932.          access routines.
  933.  
  934.  
  935.                                        GTOD
  936.  
  937.                  This  utility  will  report  the current system time and
  938.          date in a variety of formats.   GTOD  may  be  invoked  with  or
  939.          without options.  Options may be preceded by dash, fraction bar,
  940.          or nothing at all.
  941.  
  942.                 gtod <options>
  943.  
  944.               -d     report only date
  945.               -t     report only time
  946.               -e     report date in European format (DD/MM/YY)
  947.               -s     report seconds, if time reporting enabled
  948.               -r     reverse reporting order, with time first and date second
  949.               -l     spell out month in long format
  950.               -n     if option -l, then add name of weekday
  951.               -m     report time in 24 hour (military) format
  952.               -v     report version number
  953.               -?     usage message and exit
  954.               no options defaults to -dt
  955.          Output may be redirected to a file or another device, except for
  956.          error messages.
  957.  
  958.          GTOD  demonstrates  the  system  clock  interface,  as  well  as
  959.          error(),  monthis(),  wkdayname(),  i_dstr(),   and   weekday().
  960.          Program idea: allow calculation for other time zones.
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.                    Steve's Library for Turbo C          Page 13          
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.          
  992.  
  993.  
  994.  
  995.  
  996.                                        DUMP
  997.  
  998.                  (Oh!  No!  Not aNOTHer file dump  utility!)  Well,  yes,
  999.          and I apologize all to h*ll.  However, this one does some things
  1000.          that others do not.  First, it will be in **COLOR** if it senses
  1001.          a  CGA  card  installed, and will use blinks and highlights if a
  1002.          mono card is sensed.  The  direct  video  access  functions  are
  1003.          used.   Second,  it will highlight any selected byte whenever it
  1004.          is found!  Third, it displays only 20 lines at a time and  waits
  1005.          for a keypress to continue.  Invoke the program as follows:
  1006.  
  1007.                 dump filename <offset> <byte>
  1008.  
  1009.          where  filename  is  the  file to dump, offset is the hex offset
  1010.          value in which to index into the file before  dumping  (defaults
  1011.          is  0000), and byte is the hex value to highlight (default is no
  1012.          highlight).  The parameters MUST be in the order specified,  and
  1013.          the  offset  must  be  supplied  (as a place holder) if the byte
  1014.          option is desired.
  1015.  
  1016.          DUMP demonstrates the use of getkey(),  stuff(),  error(),  plus
  1017.          the direct video functions of this library, and the use of color
  1018.          attributes.    Programming  idea:  there  are  several  ways  to
  1019.          increase the speed of the program.  I haven't  implemented  them
  1020.          so that  you  can  have  the  fun(!!)  of  doing  it.  Hint: the
  1021.          overhead in printf() is horrendous.
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.                    Steve's Library for Turbo C          Page 14          
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.          
  1058.  
  1059.  
  1060.          VIII. SHAREWARE
  1061.                  ShareWare  is  "try-before-you-buy" software, reasonably
  1062.          priced and user-supported.  This simply means that you  can  get
  1063.          ShareWare software for free from anyone who has a copy, or often
  1064.          from bulletin  board  systems.  If you use and like the program,
  1065.          then the author asks that you register  (purchase)  the  program
  1066.          for a  stated  fee.   By registering you will often also receive
  1067.          notice of available upgrades or supplemental programs.   Payment
  1068.          under  shareware is on the "honor system", but if the program is
  1069.          useful and the price is right, then please play by the rules and
  1070.          purchase the program.  Also, keep in mind that the purchase of a
  1071.          program from a public domain distributor or payment to an online
  1072.          service (such as CompuServe) does NOT constitute registration of
  1073.          the program since the producer of the program does  not  receive
  1074.          one penny of that payment.
  1075.                  "Steve's Library"  is  shareware.  If you use it, please
  1076.          register your copy on the registration form enclosed at the  end
  1077.          of this  manual.  For a slightly higher charge, you may elect to
  1078.          obtain the source code for all  functions,  and  the  M, C, H, L
  1079.          libraries.   Please note that the extra libraries and the source
  1080.          code are NOT SHAREWARE, and should not be distributed.  Only the
  1081.          documentation, utilities, header files, and Small model  library
  1082.          may be passed on under the shareware concept.
  1083.                  Online    help    is    available   through   CompuServe
  1084.          (74435,1042), or GEnie mail  (S.MARGISON)  to  registered  users
  1085.          ONLY. Help  is also available by mail.  I will try to answer all
  1086.          letters within 48 hours.  Non-registered users  must  include  a
  1087.          SASE for   a   reply.      The   degree  of  help  available  to
  1088.          non-registered users is purely discretionary.  No  phone  calls,
  1089.          please.
  1090.                  "Steve's   Library"   may   be   used  in  a  commercial
  1091.          environment,  with  no  royalties  required  if  functions   are
  1092.          included in  a  program  for sale.  However, the library, source
  1093.          code, and all related documentation may not be  sold  under  any
  1094.          circumstances without  my  prior  approval.    Software  library
  1095.          services and Users Groups may charge a nominal fee  for  copying
  1096.          and distributing  those  files  which  are  shareware.    Please
  1097.          contact me for a complimentary  copy  to  insure  that  you  are
  1098.          offering the  most recent and complete release.  The source code
  1099.          may NOT be offered for sale  or  trade  by  other  than  myself.
  1100.          "Steve's  Library"  may  not  be  included or "bundled" with any
  1101.          other software without prior permission.
  1102.                  "Steve's Library"  and  its  documentation  may  not  be
  1103.          transferred nor  exchanged  in  any  modified form.  I cannot be
  1104.          expected to help others use these functions if they are not  the
  1105.          same as  distributed.   Under no circumstances may the copyright
  1106.          notices  be  altered  or   removed   from   the   functions   or
  1107.          documentation.
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.                    Steve's Library for Turbo C          Page 15          
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.          
  1124.  
  1125.  
  1126.          IX. WARRANTY
  1127.                  Oh,  this  shouldn't  be  necessary  among  friends  and
  1128.          gentlemen,  but  it's  really  the lawyers who run the world and
  1129.          they say we gotta do this:
  1130.  
  1131.  
  1132.               ** Steve's Library functions and all documentation are
  1133.               copyright 1987 by Steven E. Margison.
  1134.  
  1135.               ** These functions and documentation are provided  "as
  1136.               is"  without warranty of any kind, either expressed or
  1137.               implied, including but  not  limited  to  the  implied
  1138.               warranties   of  merchantability  and  fitness  for  a
  1139.               particular purpose.
  1140.  
  1141.               ** The user of these functions and documentation agree
  1142.               to hold  the  author  and/or  distributor(s)  of  this
  1143.               material  harmless  for  any  direct  or consequential
  1144.               damages resulting from  its  use.    In  other  words,
  1145.               "you're on your own!"
  1146.  
  1147.               **  IBM  is  a  registered  trademark of International
  1148.               Business Machines Corporation.
  1149.  
  1150.               ** MS-DOS is a trademark of MicroSoft Corporation.
  1151.  
  1152.               **  Turbo-C  is  a  registered  trademark  of  Borland
  1153.               International, Inc.
  1154.  
  1155.               ** Datalight C is a registered trademark of Datalight,
  1156.               Inc.
  1157.  
  1158.               ** Lattice is a registered trademark of Lattice, Inc.
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.                    Steve's Library for Turbo C          Page 16          
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.          
  1190.  
  1191.  
  1192.          =======================================================================
  1193.                       SOFTWARE REGISTRATION FORM AND ORDER
  1194.          =======================================================================
  1195.          A separate form must be filled out for each product ordered or
  1196.          registered.  This form may be photocopied, printed out, or
  1197.          edited to include all information and re-printed.
  1198.          
  1199.          PRODUCT: --------- STEVE'S TURBO-C LIBRARY VERSION 1.30 --------------
  1200.          
  1201.          QUANTITY:                                                Amount:
  1202.          
  1203.          _____  Standard registration                $10.00 ea    $______
  1204.          _____  Registration with Source code        $25.00 ea    $______
  1205.          
  1206.               Shipping outside U.S. or Canada                     $  3.00
  1207.          
  1208.                                   TOTAL DUE                       $______
  1209.               Payment must be made in U.S. Funds
  1210.          
  1211.          Source code is NOT SHAREWARE and is not to be transferred to other
  1212.          users.  Only the DOC files, header files, utilities,
  1213.          and S library are released into shareware.
  1214.          
  1215.          Corporations:  Write with your requirements for a quote on
  1216.                         multiple copies or site licensing.
  1217.          
  1218.          If you already have this library, where was it obtained?
  1219.          [ ]CompuServe  [ ]Friend  [ ]Employer  [ ]BBS:__________________
  1220.          Version_____ Serial No._________ 
  1221.          
  1222.          Payment is by check[ ] or money order[ ] (Sorry - no COD or charges)
  1223.          
  1224.          NAME _______________________________________________________
  1225.          
  1226.          COMPANY ____________________________________________________
  1227.          
  1228.          ADDRESS ____________________________________________________
  1229.          
  1230.          CITY _______________________________________________________
  1231.          
  1232.          STATE___________________________ ZIP _______________________
  1233.          
  1234.          =======================================================================
  1235.          Send completed form and payment to:
  1236.                              Steven E. Margison
  1237.                               124 Sixth Street
  1238.                           Downers Grove, IL, 60515
  1239.          =======================================================================
  1240.                        - do not write below this line -
  1241.          
  1242.          recd________   sent________ version_______ serial no.__________________
  1243.  
  1244.  
  1245.  
  1246.          
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.