===============================================================================
                                README.TXT
              For the VIN Check Digit Function (Vin.prg attached)
                                 11/04/92
                        Ferdinand Trauttmansdorff
                              ID: 73607,1443
===============================================================================

BACKGROUND INFORMATION:

      If you have ever tried to transcribe a 17-character Vehicle
Identification Number (VIN), then you know how easy it is to get it wrong.  For
example, try retyping this VIN: "1FTCR10A9NTA00294".  If you're like me, and
can't type without watching your fingers, you will find this exercise tedious.

      It's bad enough when you have a printed VIN to work from, but if you are
trying to inkey a list of handwritten VINs, you will almost certainly get some
of them wrong.  Since the VIN is a fairly critical detail to agencies such as
vehicle registration bureaus, insurance companies, warranty services etc., an
inadvertently mistyped VIN will ultimately cause grief for somebody.

      For the purpose of verifying its transcription, each VIN contains a Check
Digit (the ninth character) that is calculated depending on the position and
values of the other characters contained in the VIN.  The attached Vin()
function performs the Check Digit calculation and compares the calculated value
to the Check Digit contained in your VIN.  If the Check Digits do NOT match,
then the VIN -CANNOT- be correct as entered.

      However, and please NOTE this is IMPORTANT, if the Check Digits DO match,
do NOT take this as an absolute guarantee that the VIN is valid.  It is only a
confirmation that you have copied it correctly.  It is highly unlikely, but
still theoretically possible, that you could accidentally stumble onto a random
combination of mistyped characters whose calculated Check Digit matches up
correctly.  For example, an obviously invalid VIN of "11111111111111111" would
have a calculated Check Digit of "1" which correctly matches the ninth
character of the VIN.  The Vin() function would thus report this VIN as being
transcribed correctly.

      In addition to verifying the Check Digit, the Vin() function looks to see
if the VIN contains the required number of 17 characters, and that it contains
only allowable characters.  For instance the letters "I" and "O" are not
allowed because they are too easily confused with the numbers "1" and "0". 
Strangely enough, the letters "S" and "Z" are allowed despite the fact that
they are just as easily confused with the numbers "5" and "2".  Strange but
true.

USING THE Vin() FUNCTION:

Usage: lResult = Vin(<cVin>,<lDetail>)

      The Vin() function accepts two parameters, a VIN text string and a
logical .T. or .F. flag which enables or disables the display of messages.  If
the flag is omitted, the function will operate the same as if a logical .F. was
passed to the function.

      The Vin() function returns a logical .T. if:
            - the length of the VIN text string is correct;
            - no invalid characters are included in the VIN text string; and
            - the calculated Check Digit matches the ninth character of the VIN
              text string.

      Otherwise, the Vin() function returns a logical .F. value.  A logical .T.
or .F. value will be returned by the function regardless of which setting is
passed in the lDetail flag.

      If the lDetail flag is omitted or passed as .F., the Vin() function will
only return the .T. or .F. result.

      However, if the lDetail flag is set to .T., the Vin() function will pause
and display error messages in a window if any errors are detected in the VIN. 
Or, if no errors are detected, the Vin() function will pause and display a
message informing you that the Check Digit is correct.

ENVIRONMENT SETTINGS:

      The Vin() function should be called with "TALK" set to "OFF".  If TALK is
ON, lots of confusing numbers will scroll up your screen.

      In addition, "ESCAPE" should be set to "OFF".  The Vin() function
displays error messages in a window and waits for any key to be pressed before
continuing.  If the ESC key is pressed at this point, the function will cancel
without closing the window.  This will leave your display trapped in the
window.  If you find yourself in this situation, type "release window wMsg" to
clear the window.

VIN DECODING:

      This Vin() function will NOT decode the information contained within the
VIN.  This would be a huge task to accomplish since the coding scheme typically
changes each model year, is different for every manufacturer, and within any
particular manufacturer's coding scheme is usually different for passenger
cars, light trucks and vans, etc.

      However, it is relatively simple to extract the Model Year designator
from the VIN since that is one of the very few items that is standardized. 
Therefore, if the lDetail flag is set to .T. and the VIN Check Digit matches
correctly, the Vin() function will pause and display the decoded Model Year. 
The Model Year coding scheme is currently valid only for model years 1980 to
2009.  If you're still using this function in 2009, let me know and if I'm
still around I'll try to send you an upgrade.

WORDPERFECT 5.1 MACRO:

      If it interests you, this function has been previously posted as a
WordPerfect 5.1 Macro.  It can be found as VIN.ARC in Lib4 of the WordPerfect
Users Forum (GO WPUSERS).