Documentation for Squares.c  
             Source and Documentation by Michael S. Franzyshen
                               May 8, 1989

This simple program takes TWO arguments from the CLI (integer values), and
outputs the specified range of squared values for the numbers.  The two
arguments are the 'Start' and 'End' points of the output range.

SYNTAX: Squares <Start> <End>

Start is the beginning of the range of squares to output and End is the last
number in the output range. The values for Start and End must fall in the 
range:  -32,768 to +32767. This is the acceptable range for C integer values.
For the correct syntax type:  Squares by itself on the command line. You may 
also terminate the  program by typing Control-C.

NOTE:  The function of this program is an example of HOW to pass arguments 
from the CLI to the main() function of your program, not in its utility. When
passing arguments from the CLI to a C main() function, there are several
points that must be kept in mind:

  1) The main() definition itself takes ONLY two arguments.

  2) One argument is 'argc' which is an integer value specifying the
     number of entries typed at the CLI prompt.  This INCLUDES the 
     program name itself. 

                   e.g.  test_program  VAL_1 VAL_2 VAL_3

                   In the example above,  argc = 4.
         
                   e.g.  test_program  VAL_1 
      
                   In the example above,  argc = 2.

  3) The second argument in the main() function is argv (Argument Vector).
     This is a character array which will hold the arguments entered from
     the CLI.  Using one of the examples from above, suppose we typed from
     the CLI prompt:

                      test_program  VAL_1 VAL_2 VAL_3
        
     When the program actually runs, the following assignments are made:
          
                          argv[0] = test_program
                          argv[1] = VAL_1
                          argv[2] = VAL_2
                          argv[3] = VAL_3

     NOTE: A common mistake is forgetting that the first element of argv[]
           actually holds the program's name.  
  
  4) Don't  forget that argv is a character array.  If you need to need to
     pass numbers to main(), you must convert the characters to integers,
     floats, or longs (as in this example).  This is done using the C 
     functions atoi() (ASCII to integer), atol() (ASCII to long), or atof()
     (ASCII to float).   

  5) As the programmer, you MUST insure the arguments the user types in at
     the CLI, are ones that allow the program to execute properly.  If the
     arguments do not meet the program's criteria, terminate execution, 
     stating WHY the program failed to run.   You will notice in Squares.c
     that a majority of the program is devoted to error checking.
 
     NOTE: Under Manx 3.6a, you must declare the TYPE of value (int,long,
           float, etc), that atol(), atoi(), or atof() are returning, if
           other than an int value.  This is somewhat counter-intuitive for
           beginning C programmers. For example, nowhere is it defined that
           the atol() function is going to return a long int.  If you need 
           the use of a long integer value,  declare it  in the beginning
           of your program the following:

                               long     atol();

           The same rules apply to atof(), and atoi().

  6) Testing for Zero as an argument.  When your program accepts numbers,
     how can you tell if the user types 0 (Zero), or a string of ASCII 
     characters?  The atol() function will return zero in both cases.  For
     example, if the user types:

                             Squares  abc  10  

     the following result is: atol(argv[1]) = 0.  This is unacceptable, and 
     we want to generate an error.  On the other hand, if the user types:

                             Squares  0  10  

     In this case atol(argv[1]) = 0 also, but the input is very different.   
     We want to continue program execution, because the VALUE 0 (Zero) is
     acceptable. 
    
     The best way to determine if argv[1] is holding a Zero, or a string of
     random characters, is to test for the ASCII value of Zero (decimal 48)
     pointed to by  *argv[1].  Now if atol(argv[1])  yields Zero, but
     *argv[1] != 48 we know that the  user typed in a string of ASCII
     characters.  If this explanation is not clear, insert printf() in 
     the appropriate sections of code to see the actual values stored by
     *argv[1].  Better yet, if you have SDB from Manx, examine the 
     values of the variables with that.  It is far more dynamic than 
     printf().
     
This program was written using Manx Aztec 3.6a. It was compiled and linked
with these two commands:
   
                               CC Squares.c
                               Ln Squares.o -lc

I hope that others can make use of this file, since the conventional 
documentation on this subject is somewhat confusing, and often incomplete. 

If you have any questions or comments, please feel free to contact me at the
following:

                        COMPUSERVE:     71210,2522
                        GENIE:          xth42864
                        PLINK:          SRU541
 
                          DynaSoft Technologies
                          23 Mercury Street
                          Somerset, NJ  08873

The source, executable, and documentation  are public domain, and freely
distributable, as long as this ARC file contains: Squares, Squares.c, and
Squares.doc in its original form.  Feel free to  modify the source to suit
whatever needs you may have while programming your own applications.