home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-386-Vol-2of3.iso / c / codebk11.zip / CODEBOOK.DOC < prev    next >
Text File  |  1990-12-21  |  9KB  |  143 lines
  1. Program CODEBOOK.BAS 1.1, 21 December 1990, by Jim Groeneveld.
  2.  
  3. PURPOSE
  4. -------
  5. This program unformats a fixed formatted ascii data file for (STATGRAPHICS)
  6. using a user created codebook file. STATGRAPHICS can not read ASCII data files
  7. with records longer than 640 bytes. Next, preparing to read suited ASCII files
  8. is time consuming and user-unfriendly: the user has to create a vector
  9. containing the information of the position of each variable in the data file.
  10. This means a lot of initial arithmetic and errors are difficult to correct.
  11. Besides, all fields will be read: the vector only specifies field widths of
  12. fields that are directly following the previous fields. The sum of all widths
  13. cannot exceed 640. So using standard STATGRAPHICS options in this case is
  14. clumsy, time consuming and error sensitive. This asked for the current replacing
  15. solution.
  16.  
  17. DESCRIPTION
  18. -----------
  19. CODEBOOK transforms any (fixed formatted) ASCII file with one record per case of
  20. any (unlimited) length into multiple Blank or Comma delimited (or eventually
  21. Fixed formatted or Report) data files (optionally) with STATGRAPHICS (or
  22. generally acceptable, e.g. Lotus) variable names on the first row, each
  23. containing a user specified number of variables. This has the advantage that
  24. all the necessary preparation can be done within any editor, creation of a
  25. codebook file, indicating for each variable to be transformed a.o. the field
  26. width, the starting and ending columns and the variable name. The resulting
  27. data files may then be read after each other into STATGRAPHICS (or used with
  28. any appropriate program). Completely blank fields (mostly representing missing
  29. values) in the original ASCII file may be replaced automatically by any (user-
  30. specified) numerical or character value in the resulting output data files.
  31. This makes reading ASCII data files much more efficient, less sensitive to
  32. errors, much quicker and more logical and surveyable.
  33.  
  34. (Unique) limit specifications:
  35. ------------------------------
  36. 1) maximum number of variables per single output file: 32767, default: 58
  37. 2) if not reserved enough space initially when specifying the current maximum
  38.    number of variables: optional automatic (but rather slow) adaptation to the
  39.    actually required number of variables (number of array elements) read from
  40.    the codebook file
  41. 3) maximum input record length (=number of columns per line): unlimited
  42. 4) maximum column specification (interpreted bytes/record):32767*255-1=8,355,584
  43.    (practically unlimited, practically limited by available memory in BASIC)
  44. 5) number of cases: unlimited (only hardware and software (BASIC) restrictions)
  45.  
  46. The resulting unformatted data file(s) contain default maximally 58 variables
  47. because of the STATGRAPHICS limits of 640 bytes max.line length and 10
  48. character variable names separated by delimiters; STATGRAPHICS, however, allows
  49. for a maximum of 64 variables to be edited at the same time within its data
  50. editor and even more (?) within any (STATGRAPHICS) data file.
  51.  
  52. The output records (generally unformatted values) are preceded by a first line
  53. with variable names. As many unformatted, blank or comma delimited (or fixed
  54. formatted or report) output files are generated as are necessary to contain the
  55. total number of variables as a multiple of the number of variables per output
  56. file. They are named automatically by the file name of the original formatted
  57. data file with their sequence number as the extension. All output files may be
  58. read by STATGRAPHICS.
  59.  
  60. USE
  61. ---
  62. A codebook file should be created using any editor in which on each line a
  63. variable should be described as follows:
  64. (all data descriptors, except for the first column, MUST be separated by
  65. COMMA's, only widths and columns may be ended with one or more spaces)
  66. FIRST column :─┬─ space: numeric or character variable to be output 'as is';
  67.  (WITHOUT      ├─ "    : character variable to be output within double quotes;
  68.   ending       ├─ '    : character variable to be output within single quotes;
  69.   delimiter)   └─ any other character (or empty line): comment line, no action.
  70. Missing Value:─┬─ any value to replace originally entirely blank fields, may
  71.  (END with     │  be a character value, optionally enclosed by double quotes;
  72.   a COMMA)     └─ if left empty it will take the value prompted for when run;
  73. Starting Column : integer positive value <=8,355,584 (end with comma or spaces);
  74. Ending Column   : integer positive value <=8,355,584 (end with comma or spaces);
  75. Field Width  :─┬─ integer positive value <=255, for double checking field
  76.  (end with com-│  correspondence with Starting and Ending Column;
  77.   ma or spaces)└─ if 0: disable checking with Starting and Ending Column;
  78. Variable Name:─┬─ any character value up to 255 (!) characters, not quoted;
  79.  (end with     └─ if omitted a default name, consisting of 'VarX' in which X is
  80.   comma/space/    the variable number, will be generated; the Variable Names are
  81.   /EOL:CRLF)      inserted as the first line of the output file(s);
  82. Comment         : optional, may be omitted, not interpreted.
  83.  
  84. Column specifications need not to be contiguous and sequential. Columns may be
  85. skipped or read multiple times (as part of different variables). This allows
  86. for extracting one or more data files with a restricted, specified number of any
  87. variables from the original database file.
  88.  
  89. MEMORY REQUIREMENTS
  90. -------------------
  91. Approximate needed memory space per variable to process:
  92.    1 byte  VAR.TYPE$ (first column of codebook file)
  93. ≈  2 bytes MISSING.VALUE$ (average 2 columns)
  94.    4 bytes BEGIN.COLUMN! (double precision)
  95.    4 bytes END.COLUMN! (double precision)
  96. ≈ 10 bytes VARIABLE.NAME$ (common max. variable name length)
  97. ≈  2 bytes VALUE$ in DATA.LINE$ (average 2 columns)
  98. ────────── +
  99. ≈ 23 bytes (say generally no more then 25) per variable altogether.
  100. E.g. for 1000 variables this requires a data space in BASIC memory of ≈25 Kb.
  101. So the programs own algorithmic limit of 32767 variables may not be reached
  102. far enough due to other limitations. (Maybe compiled BASIC allows for more
  103. data space). The same applies for the maximum column specification: this would
  104. assume a data file with at least one line of more than 8 Mb long, which has to
  105. fit in memory entirely.
  106.  
  107. Suggestion: if limits occur while processing a CODEBOOK file break it into
  108. smaller pieces (of about the number of variables per output file) and run
  109. CODEBOOK multiple times. This will not take more time in total. Beware of
  110. duplicate file names! Rename, if necessary in between.
  111.  
  112. Suggestion: if limits occur while processing a DATABASE file break it into
  113. smaller pieces using COPYFIX (specify record lengths of ≤80 and included and
  114. synchronized CRLF's) and SEPARATE (specify NO record numbers) and rerun CODEBOOK
  115. with adapted (variables and column specifications) parts of the original
  116. codebook file on each of the (renamed!: different FileNameS and no numeric
  117. extensions) generated files from SEPARATE.
  118.  
  119. GWBASIC-LINE INPUT
  120. ------------------
  121. In GWBASIC a LINE INPUT reads at most 255 characters within ONE line. If 255
  122. characters are read any following CRLF has not been encountered yet. Any
  123. succeeding LINE INPUT will start from the point where the previous LINE INPUT
  124. was left. If still more than 255 characters are to be read only 255 will be
  125. read, leaving the rest for the eventual next LINE INPUT. If less than 255
  126. characters on the SAME line are to be read, even if only a remaining CRLF, they
  127. are ALL read, INCLUDING the CRLF, but the CRLF are NOT part of the read STRING.
  128. Any following LINE INPUT starts with the NEXT line. If another BASIC (e.g.
  129. BASICA, according to its manual) processes LINE INPUT in a different way the
  130. course of this program may be unpredicted and erroneous, so BE AWARE of your
  131. BASIC version! The number of characters read by a LINE INPUT statement may be
  132. changed ONLY IF NECESSARY by redefining the BASIC variable MAX.LINE.INPUT.LENGTH
  133. in program line 70.
  134.  
  135. NOTE: (GW)BASIC performs Garbage Collection (or House Cleaning) regularly.
  136.  
  137. Centrum voor Medische Informatica TNO       <Email>              |  |  |\/|
  138. TNO Center for Medical Informatics | GROENEVELD@CMI.TNO.NL  |  \_/  |  |  |
  139. ( CMI-TNO )    | Y. Groeneveld     | GROENEVELD@CMIHP1.UUCP | Jim Groeneveld
  140. P.O.Box 124    | Wassenaarseweg 56 | GROENEVELD@TNO.NL      | Schoolweg 14
  141. 2300 AC Leiden | 2333 AL Leiden    | ...@HDETNO51.BITNET    | 8071 BC Nunspeet
  142. Nederland.     | (+31|0)71-181810  | Fax (+31|0)71-176382   | 03412-60413
  143.