CVBD - Convert to Base and Dump (version 2.00)
==============================================

TABLE OF CONTENTS
-----------------

     1. Overview
     2. Free Software
     3. Portability
     4. Installation
     5. What's New in Version 2.00
     6. Manual
     7. Programming Issues
     8. Contact and Links


1. OVERVIEW
   --------

       CVDB (Convert to Base and Dump) is a program that reads
   a file or a series of files and displays (dumps) their contents
   as a formatted series of values in either octal, decimal or
   hexadecimal format.
       It can be used for dumping and printing contents of binary
   files or even to add contents of binary files into your C (or
   other language) programs.
       If for example you have a picture in a file MYPIC.BMP and
   you wish to embed your picture into your C program so that it
   displays it every time it starts, you can use CVBD to convert
   MYPIC.BMP into a series of hex values separated by commas, and
   then add it into your program (into an array).


2. FREE SOFTWARE
   -------------

       CVBD is classified as "FREE SOFTWARE" as described in the
   GNU web page (visit http://www.gnu.org/philosophy/categories.html
   for more information). This means that it can be used (modified
   or not) by anyone and for any reason. However, I would appreciate
   any reference to my name.


3. PORTABILITY
   -----------

       Though an MS-DOS executable version is provided, there has been
    extensive efford to keep the source code highly portable. The program
    has been successfully compiled and tested on IBM AIX systems. *IX users
    can simply compile the source code in order to use the program on their
    systems (see below).


4. INSTALLATION
   ------------

       MS-DOS systems do not require any installation steps in order to
    use the software. An MS-DOS executable file is already provided.
       However, *IX users have to recompile the source-code in order
    to use it. In version 2.00 the source code has been broken into
    four files:

           cvdb.c  -  The main program's source-code
           cvdb.h  -  Header file with typedefs, defines and prototypes
           misc.c  -  Miscellaneous assisting functions
           misc.h  -  Header file for misc.c (with function prototypes)

       *IX users will have to put these four files into a directory and
    then use the C/C++ compiler to produce a binary executable file.
       A *IX user would probably use the following command:

          $cc -o cvdb cvdb.c misc.c

       This will (hopefully) produce the binary file cvdb which can be
    probably be executed by issuing the command:

          $cvdb

       Or in some other cases:

          $./cvdb


5. WHAT'S NEW IN VERSION 2.00
   --------------------------

   [ 27-JUN-2000 01:00am (GMT+2) ]

       a.  CVDB now uses buffered I/O for file reading instead of single
           character input (as was version 1.00). The buffer size can be
           adjusted by modifying the IOBUFSIZE definition in CVDB.H. The
           default size is 4096 bytes. Buffering increases the speed with
           which data are read from the file(s).
       b.  Fixed a serious error that forced hexadecimal values to be
           displayed always in C/C++ style.
       c.  Added an option to pause before each conversion.
       d.  The source-code has been separated in four files.
       e.  Minor modifications and enhancements.


6. MANUAL
   ------

       CVBD receives numerous command-line arguments. In the
   following description this notation is used:

       a.  Brackets ( [] ) denote an OPTIONAL argument.
       b.  Greater and less-than ( < and > ) denote an obligatory
           argument.
       c.  Pipe ( | ) between numerous items implies that ONLY ONE
           of the items may be used.
       d.  Comma ( , ) between numerous items implies that one or
           more of the items may be used together.   

       CVBD uses the following command-line syntax:

           <file1>..[fileN]  [/O] [/D] [/H[[L|U],C]] [/L[+|-]] [/E[+|-]]
                             [/F[+|-]] [/0[+|-]] [/P[+|-]] [/!] [/?]
                             [/S[:c|nnn]] [/W[nnn|A]] [/C[nnn]]

       Here is an explanation of every option:

       /O        Display values in octal.
       /D        Display values in decimal.
       /H        Display values in hexadecimal (uppercase letters).
                 /HL   Use lowercase letters.
                 /HU   Use UPPERCASE letters.
                 /HC   Use C/C++ hexadecimal style.
                       (C/C++ adds the prefix "0x" to hex. values)
                       This flag can be combined with one of the two above.
       /L[+|-]   Turns on (/L or /L+) or off (/L-) left-justification of
                 displayed values.
       /E[+|-]   Turns on (/E or /E+) or off (/E-) the display (echoing) of
                 user options at program startup. This flag can be useful
                 for debugging and development purposes.
       /F[+|-]   Turns on (/F or /F+) or off (/F-) the display of each
                 filename before every conversion.
       /P[+|-]   Turns on (/P or /P+) or off (/P-) pausing before every
                 conversion. Please note that if used with the /F(+) switch
                 the pause prompt is displayed after the filename is shown.
       /0[+|-]   Enables (/0 or /0+) or disables (/0-) the display of
                 leading zeros where required.
       /? and    Display command-line help. The /! switch was added because
       /!        some *IX shells use the question mark (?) for special
                 purposes.
       /Snnn     Set separation character to ASCII nnn, where nnn is
                 a decimal value. For example /S32 will set the
                 separation character to ASCII 32 (which is space).
       /S:c      An alternative to the above option, sets separation
                 character to c, where c is an actual character. Please
                 note that this cannot be space, as space is used
                 to separate the command-line arguments by the operating
                 system.
       /S and    Don't use a separation character. Values will be
       /S0       displayed side-by-side without any separation character
                 between.
       /Wnnn     Set formatting width to nnn characters, where nnn is
                 a decimal value. For example, /W5 will display all
                 values using a width of 5 characters (unless /L or /0
                 was used, the values will be 0-padded to the left when
                 required).
       /W and    Instructs the program NOT to use a formatting width.
       /W0       CVBD will use as much space required to display each
                 value (therefore no zeros will be added to the left).
       /WA       Instructs the program to use the internally predefined
                 widths which are specific for each conversion base:
                 3 for octal, 3 for decimal and 2 for hexadecimal.
       /Cnnn     Shows nnn values in each line, where nnn is a decimal
                 value. This is handy and allows the creation of nicely
                 formed blocks.
       /C and    Instructs the program NOT to split the values in every
       /C0       line.


           Please note that the flags are NOT case sensitive, and that both
       '-' (UNIX-style flags) and '/' (DOS-style switches) can be used.


       Defaults:
       ---------

       /HCU      Show in C/C++ hexadecimal format using UPPERCASE letters.
       /WA       Auto-width (3 characters for hexadecimal).
       /S:,      Separation character is comma.
       /C10      Show 10 values in every line.
       /0+       Show leading zeros.
       /L-       Right justification.
       /P-       No pause before every conversion.
       /E-       No user option echoing,
       /F-       No file name display.


6. PROGRAMMING ISSUES
   ------------------

       CVBD is not an advanced C program. However, it is an excellent way
   for novice or even intermediate programmers to get a taste of how to
   handle command-line arguments or perform buffered I/O.
       Furthermore, by examining the source-code one can notice these
   two functions:

           char *ce_strrev(char *l)              (in MISC.C)
           char *ce_itoa(int n,char *s)          (in MISC.C)

       The first one reverses the string *l, and the second one converts
   the integer n into a string placing it into *s.
       Though many compilers already provide such library routines, ANSI-C
   does not and so I have chosen to implement my own ones. This way the
   program's portability is further extended.
       Please note that the cryptic "ce" in front of the actual names are
   my initials; it is considered by some people (including myself) a good
   practise to prefix your initials on any existing function(s) that you
   wish to redefine or replace.


7. CONTACT AND LINKS
   -----------------

       Please feel free to contact me via e-mail for any suggestions,
   questions and requests you may have regarding the program.
       Here's my personal information:

            Christos Evaggelou
            E-mail: christos.e@cytanet.com.cy

       I would also be extremely grateful if you visited the following
   WWW links in order to get acquainted with the Cyprus Issue and learn
   about our 1616 Missing Persons.

            http://www.pio.gov.cy/cyissue/index.htm
            http://kypros.org/Cyprus_Problem/
            http://www.hri.org/Cyprus/Cyprus_Problem/missing.html
