... TIMER.DOC ...................... coolTimer 1.21a Documentation File
Document no.: M-0030.96.95M01.05     Copyright(c) 1995,96 by B-coolWare.
                                                     Written by Bobby Z.

 What's in this document.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This file contains the only available documentation on coolTimer
 library.
 Please read it carefully before making use of the coolTimer.
 It contains all necessary information and describes all functions
 found in the library.

 What is coolTimer.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 coolTimer is the collection of routines for PC timer programming
 for use in Pascal and C/C++. It allows up to 50* timer handlers
 to be installed, each with different rate, with resolutions from
 18.2 times per second up to 22000 times per second. It uses no
 floating point operations thus being really small and fast while
 providing impressive accuracy. It doesn't interfere with system
 clock keeping DOS working as if timer was not reprogrammed. With
 coolTimer you'll be able to add up to 50* "concurrent"
 time-dependant processes to your programs as easily as adding new
 procedures.

* By default, the number of concurrent handlers is limited to 5,
  but it can be set to any number within 1 and 255. Though we do
  not recommend to use values greater than 50. You will have to
  edit the source code to change the number of concurrent handlers
  supported and recompile the library.

 Software Legal Status.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 coolTimer library is copyrighted free software. This means that
 it can be distributed freely at no charge and used freely in
 non-commercial software provided that you keep the copyright
 notices unchanged. Usage of the library in commercial software
 (including shareware) requires prior written consent from the
 author. Here goes all the legal stuff:

 You are hereby granted the right to distribute the coolTimer
 library ("the library") provided that no fee is charged from
 recipient(s) exceeding your expences arising from distribution
 (uploading to a commercial network, for example) but not exceeding
 $5 in total. You are also granted the right to use the library
 in non-commercial software provided that you keep the original
 copyright notice unchanged. Use of the library in commercial
 software (including shareware) requires prior written consent from
 the author. You may not change the library source code or object
 files(*). If you break any of the terms mentioned you'll be liable
 for violation of Russian Copyright Law in Computer Programs and
 Databases as well as other national or international laws,
 treaties or provisions.

 Author disclaims all warranties, whether express or implied,
 regarding the library, including but not limited to, any implied
 warranties of code quality, reliability, errorlessness or fitness
 for a particular purpose. The library is distributed on "as is"
 basis and author shall not be liable for any damages, losses of
 data or profits or any similar troubles. The whole risk is with you.

 Author reserves the right to change software legal status in
 subsequent releases (for example, to shareware) as he sees fit.
 If he will change the software status, all previous releases will
 remain free and publicly available.

 Author provides no support of any kind for this software.
 But all letters regarding it will be processed and answered
 within reasonable time and found bugs will hopefully be
 eliminated ASAP.

(*)you may change the number of supported channels if your software
   needs more than five concurrent channels, but you may not
   distribute changed code.


 Some Theory.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * if you know how hardware timer works, you can skip this chapter.

 The PC hardware timer is a relatively simple counter chip that
 has a special register called "latch" that holds some number.
 At the rate of 1193181 Hz the counter decreases the latch and when
 its value reaches zero, the chip generates hardware interrupt,
 then reloads the latch from another special register. Both registers
 are word-sized, thus the maximum value for latch is 0 and minimum
 is 1 (this is a bit tricky: the chip first decreases the latch value,
 and only after that compares it to zero. Keeping in mind the fact,
 that after decreasing 0 we get -1 and -1 is effectively the same as
 unsigned 65535 (all bits set to 1), it appears that the counter will
 have to run down to zero through all 65536 possible positions if we
 start with 0). By default, the latch is set to 0, resulting in
 hardware interrupt being generated approximately 18.2
 (1193181/65536) times per second. If we reduce the latch value,
 the timer will generate interrupt more often. Thus the latch acts
 like a delay value for interrupt generator: the less is delay,
 the more often interrupt is generated. What's more important,
 is that we are able to compute and set the delay so that the timer
 will generate the interrupt at any rate we might need and it's quite
 precise. The equation is
    [times per second] = 1193181/[delay]
 and if we reverse it we'll achieve the equation used in this library:
  [delay] = 1193181/[needed times per second] !
 Luckily the chip was designed so that it allows to change the latch
 initial value from software. Both special registers can be read and
 the one that holds initial value also can be written using I/O ports
 40h through 43h.
 You can read more about actual timer chip programming in any book or
 manual that covers PC hardware programming. Robert Jourdain's
 "Inside the IBM PC/AT" is a good starting point for a dummy
 (regrettably, I don't remember it's ISBN).


 Support
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The coolTimer library is NOT supported by its author, nor by anyone
 else. Although if you spot a bug in it or would like to talk about
 it or suggest some improvements, you can contact author at

 internet: loki@cnit.uniyar.ac.ru
  FIDOnet: 2:5028/52.6, Vladimir M. Zakharychev aka Bobby Z.

 I am always answering all letters regarding my products, whether
 supported or not and all bugs are fixed asap.

 Latest version can be obtained at
  http://cnit2.uniyar.ac.ru/user/BobbyZ/ctimer.htm
  ftp://cnit2.uniyar.ac.ru/local/BobbyZ/pubfiles/

 If you made use of the library, I'd like you to let me know. Send me
 a postcard with a view of the place where you live or whatever you
 prefer to the following address:

 Vladimir M. Zakharychev
 150031, 10-4-13,
 Dobrynina Str.,
 Yaroslavl,
 Russia

 and write a word "coolTimer" on it along with your opinion
 (GREAT!!!, COOL!, NICE, FAIR, WORTHY, LAME, etc.).

 Thanx for yer attention, good bye.

*** AND DON'T FORGET TO CHECK OUT MY HOMEPAGE ON THE WEB AT THE URL: ***
            http://cnit2.uniyar.ac.ru/user/BobbyZ/Homepage.htm