home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / dbase / convr304.zip / CONVERT.DOC < prev    next >
Text File  |  1993-03-02  |  11KB  |  253 lines
  1. CONVERT.DOC
  2. 03/02/93
  3.  
  4. Program written by:
  5.                         Bruce Guthrie
  6.                         Room H-4885
  7.                         U.S. Dept of Commerce/ESA/OBA/BSISD
  8.                         Washington, D.C. 20230
  9.  
  10.                         (202) 482-3234
  11.  
  12. This program was written in support of the National Trade Data Bank project and,
  13. as a government program, is basically in the public domain.
  14.  
  15.  
  16. Introduction:
  17.  
  18. This program converts data files from one format to another.  Specifically, it
  19. can take the following input file types:
  20.  
  21.         ASCII-delimited file
  22.         Fixed-field file
  23.         dBaseIII (.DBF) file
  24.  
  25. and create the following files:
  26.  
  27.         ASCII-delimited file
  28.         Fixed-field file
  29.         Lotus 1-2-3 worksheet (.WKS)
  30.         dBaseIII (.DBF) file
  31.  
  32. An ASCII-delimited file is one which has double quotes around each character
  33. field and typically commas between fields.  Leading and trailing spaces are
  34. removed from character as well as all other values.
  35.  
  36. A fixed-field file places each field in the same column positions on each
  37. record.  The lengths of the fields are the same from record to record.
  38.  
  39. As an example, these might be an ASCII-delimited records:
  40.  
  41.         "Economic Bulletin Board","202 482-3870",35
  42.         "EBB High-Speed","202 482-2584",100
  43.  
  44. Fixed-field file records might look like this for the same data:
  45.  
  46.         Economic Bulletin Board 202 482-3870  35
  47.         EBB High-Speed          202 482-2584 100
  48.  
  49. WKS files are supported directly by Lotus 1-2-3 (all versions) as well as most
  50. other spreadsheet programs.  DBF files are supported by dBaseIII, dBaseIII+,
  51. dBaseIV, and most other data base management programs.
  52.  
  53.  
  54.  
  55. Field definition file:
  56.  
  57. Unless you are reading a dBase file, the CONVERT program requires a field
  58. definition file to figure out the characteristics for each field and also to set
  59. certain file characteristics.  The definition file can be created with any text
  60. editor.  The definition file consists of several records with the following
  61. fields separated by spaces.  Except for the record type indicator (which must
  62. begin in column 1), all other fields can be placed in any columns:
  63.  
  64.         (1) record type (see below)
  65.         (2) length of field on input
  66.         (3) number of decimal places for numeric data (if you don't know,
  67.             put a "?" here; for non-numeric data, a "0" is fine) on output
  68.         (4) length of field on output
  69.  
  70. Any characters after the field length are treated as comment fields.  You would
  71. typically use this to enter the field name or column position or any other
  72. information of use to you.
  73.  
  74. The data record types accepted by CONVERT are as follows:
  75.  
  76.         type C = character data
  77.              N = numeric
  78.              L = logical (T or F)
  79.              D = date (in yyyymmdd format)
  80.  
  81. Other records accepted in the field definition file are as follows:
  82.  
  83.         type ; = comment (anything after semi-colon is ignored)
  84.              X = lines to ignore; specify "X=string" and any records
  85.                  which begin with the "string" characters will be ignored;
  86.                  defaults to X="_
  87.              Z = delimiter between fields; defaults to Z=,
  88.  
  89. The data fields (types C, N, L, and D) should be in the order the fields are
  90. found in the source file.
  91.  
  92.  
  93.  
  94. Note that for fixed field files, you have to account for every byte in the file.
  95. If you have something like this:
  96.  
  97.         12345678_1_2345678_2_2345678_3      (column positions)
  98.         APPLE    X Y    12 BANANAS
  99.  
  100. Even though you may think you only have five fields, the following .DEF file
  101. will NOT work:
  102.  
  103.         ; Bad .DEF file:  Note does not account for blank spaces
  104.         C   8 0   8 Fruit1
  105.         C   1 0   1 Class1
  106.         C   1 0   1 Class2
  107.         N   5 0   5 Value
  108.         C  11 0  11 Fruit2
  109.  
  110. You may want the Fruit1 field to be in columns 1 through 8 and Class1 to be in
  111. column 10 but CONVERT will not know to skip column 9 so it will start reading
  112. Class1 beginning in column 9, Class2 beginning in column 10, etc.  To drop the
  113. blank positions, you have to add dummy fields on input and ask for them to be
  114. dropped on output:
  115.  
  116.         ; Good .DEF file:  Spaces between fields are accounted for
  117.         C   8 0   8 Fruit1
  118.         C   1 0   0 Filler
  119.         C   1 0   1 Class1
  120.         C   1 0   0 Filler
  121.         C   1 0   1 Class2
  122.         C   1 0   0 Filler
  123.         N   5 0   5 Value
  124.         C   1 0   0 Filler
  125.         C  11 0  11 Fruit2
  126.  
  127. You can also use the input field length and output field lengths to either drop
  128. fields using other formats (by specifying a zero length for the output field
  129. length) or for creating fields on output (by specifying a zero length for the
  130. input field length).  You can also use this to expand on contract a field.  For
  131. example, if Fruit1 is 8 characters long but you only want it to occupy 4
  132. characters on output (thus the field would be truncated), specify 8 for the
  133. input field length and 4 for the output field length.
  134.  
  135.  
  136.  
  137. Running the program:
  138.  
  139. Some of the default values for this routine can be set using the CONFIGWS.EXE
  140. program.
  141.  
  142. To run the program, you must specify at least one parameter (the name of the
  143. input file).  There are also some optional parameters which can be left off if
  144. you want:
  145.  
  146.     CONVERT infile [ outfile [ deffile ] ]
  147.       [ /OVERWRITE | /-OVERWRITE | /APPEND | /OVERASK ]
  148.       [ /DEF=deffile ] [ /FROM { FIXED | ASCII | ASCII=char | DBF } ]
  149.       [ /FIXED | /ASCII | /ASCII=char | /DBF ] [ /USEDEF | /NODEF ]
  150.       [ /TO { FIXED | ASCII | ASCII=char | WKS | DBF } ] [ /HEADER | /-HEADER ]
  151.       [ /SKIP | /MISSING | /ABORT ] [ /SAS ] [ /BEEP | /-BEEP ] [ /Q ] [ /? ]
  152.  
  153. "infile" is the file specification for the ASCII-delimited or fixed-field file
  154. you want converted.  You can specify a drive and path specification if
  155. necessary.  This parameter is required.
  156.  
  157. "outfile" is the file specification of the file you want to create.  You can
  158. specify a drive and path specification if necessary.  If no outfile is provided,
  159. the routine will presume you want the output file called the same thing as the
  160. infile but you want the extension to be ".FIX" (if the output file is a
  161. fixed-field file), ".PRN" (if the output file is ASCII-delimited), or ".WKS" (if
  162. the output file is to be in a WKS format).
  163.  
  164. "deffile" is the file specification for the field definition file.  You can
  165. specify a drive and path specification if necessary.  If no deffile is provided,
  166. the routine will presume it is called the same thing as the infile but it has
  167. the extension of ".DEF".  Note that the deffile can only be provided if you also
  168. specify the outfile name.
  169.  
  170. "/OVERWRITE" says to overwrite the output file if it exists already.
  171.  
  172. "/-OVERWRITE" says to abort if the output file exists already.
  173.  
  174. "/APPEND" says to append (add) to the output file if it exists already.  This
  175. option is only available if you're creating either a fixed-field or ASCII-
  176. delimited output file.
  177.  
  178. "/OVERASK" says to ask if the output file exists already.  This is typically
  179. the default but it's CONFIGWS-able.
  180.  
  181. "/FROM FIXED", "/FROM ASCII", "/FROM ASCII=char", and "/FROM DBF" specifies the
  182. format for the input file.  The routine will typically read the file and guess
  183. its format for you.  The "/FROM ASCII=char" form allows you to specify the
  184. ASCII-delimiting character (usually a comma) instead of specifying it in the
  185. definition file.
  186.  
  187. "/FIXED", "/ASCII", "/ASCII=char", and "/DBF" specifies the format for the input
  188. file.  This is a short for of the "/FROM format" specification.
  189.  
  190.  
  191. "/USEDEF" is specified for dBase input files if you want CONVERT to read an
  192. existing field-definition file.  Since dBase files contain all of the field
  193. information in the data base itself, CONVERT will normally pick up all field
  194. information from there and simply ignore any field-definition file.
  195.  
  196. "/NODEF" is specified for ASCII-delimited input files if you want CONVERT to
  197. figure out the field-definition file for you.  There are some risks in this and
  198. the operation takes longer than you may desire.  Note that CONVERT will
  199. automatically write out the field-definition file for you if you select this
  200. option.
  201.  
  202. "/TO FIXED", "/TO ASCII", "/TO ASCII=char", "/TO WKS", and "/TO DBF" tells the
  203. routine what sort of output file you'd like to create.  Typically defaults to
  204. "/TO WKS" although you can change this using the CONFIGWS.EXE program.
  205.  
  206. "/HEADER" is used in conjunction with WKS output files.  If /HEADER is in
  207. effect, the first row of the spreadsheet will contain the variable name for the
  208. cell as provided in your control file.  If none are provided, the field names
  209. will be FIELD_01 onward.  /-HEADER turns this off and is the default.  Note that
  210. the header line (if any) will show up in the output counts.
  211.  
  212. "/SKIP" says to skip records with bad data values; otherwise the routine
  213. aborts when it runs into any.  /SKIP, /MISSING, and /ABORT are mutually
  214. exclusive.
  215.  
  216. "/MISSING" says to presume any missing fields in an ASCII-delimited record
  217. should be filled in with blanks (for character fields) and 0 for numeric fields.
  218. Incomplete records are written out (unlike in /SKIP).  /SKIP, /MISSING, and
  219. /ABORT are mutually exclusive.  Note that the program will only print out the
  220. first "bad" record.  There may be others that show up after this one.
  221.  
  222. "/ABORT" says to abort when you run into bad records.  This is typically the
  223. default although you can change this using the CONFIGWS.EXE program.  /SKIP,
  224. /MISSING, and /ABORT are mutually exclusive.
  225.  
  226. "/SAS" tells the program to accept single decimal points as valid numeric data
  227. and to convert them to zeroes.  The decimal point convention is used in the SAS
  228. language to designate missing data.
  229.  
  230. "/BEEP" beeps when the program is finished.
  231.  
  232. "/-BEEP" reverses /BEEP and is typically the default.  You can change the
  233. default with the CONFIGWS.EXE program.
  234.  
  235. "/Q" turns off the line-by-line status report.
  236.  
  237. "/?" (or "/HELP" or "HELP" ) gives you the syntax for the command.
  238.  
  239.  
  240.  
  241. Restrictions and Caveats:
  242.  
  243. The program cannot handle dBase files with Memo fields.
  244.  
  245. Most spreadsheet programs restrict a given field length to being 240 characters
  246. or less.
  247.  
  248. Date fields which are in the form "yy-mm-dd" (instead of "yyyymmdd") should be
  249. declared as character fields instead of date fields.
  250.  
  251. Date fields converted for WKS files are changed into strings of the "yy-mm-dd"
  252. format.
  253.