home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / recio213.zip / tips.txt < prev    next >
Text File  |  1995-09-05  |  10KB  |  298 lines
  1.     Title: RECIO TIPS
  2. Copyright: (C) 1994-1995, William Pierpoint
  3.   Version: 2.13
  4.      Date: September 4, 1995
  5.  
  6.  
  7.  
  8. 1.0 COMMON PROGRAMMING ERRORS
  9.  
  10. 1.1 Inadvertently typing a stdio function instead of a recio function
  11.  
  12. Many functions in recio and stdio have similar names and similar uses.  
  13. This makes it easier to learn the recio functions, but it also makes it 
  14. easier to unintentionally type in a stdio function when you really want a 
  15. recio function.  When compiling it is best to have all warnings turned on.  
  16. A mistyped function will give a "suspicious pointer conversion" warning; 
  17. a mistyped macro will give an "undefined symbol" error.  Exceptions: 
  18. no error or warning if you use the fcloseall function instead of the 
  19. rcloseall function, or strerror instead of rstrerror.  Hint: in most 
  20. cases you can use the rerrstr function instead of rstrerror.
  21.  
  22. 1.2 Inadvertently typing the wrong symbolic name for an error constant
  23.  
  24. Symbolic names for error constants are similar between recio and those 
  25. supported by the compiler.  You may have typed ENOMEM when you meant 
  26. R_ENOMEM.  Check to make sure that for valid record pointers, symbolic 
  27. error constants start with "R_"; for invalid record pointers, symbolic 
  28. error constants start with "E".
  29.  
  30.  
  31.  
  32. 2.0 ERROR HANDLING
  33.  
  34. 2.1 Callback Error Function
  35.  
  36. The first use of any recio function should be rseterrfn() to register 
  37. your callback error function for your application.
  38.  
  39.  
  40. 2.2 Explicit Conditions Not Reported to Callback Error Function
  41.  
  42. There are two conditions that your code must explicitly handle as 
  43. these are not reported as errors to the callback error function:
  44.  
  45. 1)  Test ropen() for NULL return and, if true, test errno for ENOENT.  
  46. This indicates that the file could not be opened since it does not exist.  
  47. Any other errors are reported to the callback error function (if registered); 
  48. your code can handle them there.
  49.  
  50.     REC *rp = ropen("file", "r");
  51.     if (!rp) {
  52.         if (errno == ENOENT) {
  53.         /* file does not exist */
  54.         ...
  55.         }
  56.     }
  57.  
  58. 2)  Test the return value from rgetrec().  If it is a NULL return, then 
  59. either end-of-file reached or an error occurred.  You need to follow up on 
  60. the NULL return value to determine which one happened.  You can use either 
  61. the reof or the rerror function.  Any errors would have been reported to the 
  62. callback error function; be careful that you don't report the same error 
  63. twice.
  64.  
  65.     /* loop through all records in file */
  66.     while (rgetrec(rp)) {
  67.         ...
  68.     }
  69.     if (!reof(rp)) {
  70.         /* error occurred before all records read */
  71.         ...
  72.     }
  73.  
  74.  
  75. 2.3 Make an Error Check Just Prior to the rclose Function
  76.  
  77. Check for errors just before closing any record stream.  This is a good 
  78. safety check since (1) you might have forgotten to install your callback 
  79. error function or (2) your callback error function failed to catch and 
  80. correct all the errors.
  81.  
  82.     if (rerror(rp)) {
  83.         /* file not completely read in */
  84.         ...
  85.     }
  86.     rclose(rp);
  87.  
  88. If you use recin in your program, check for errors after your last use of 
  89. recin or just before you exit your program.
  90.  
  91.     if (rerror(recin)) {
  92.         /* error occurred on recin stream */
  93.         ...
  94.         exit(EXIT_FAILURE);
  95.     }
  96.     exit(EXIT_SUCCESS);
  97.  
  98.  
  99. 2.4 The rsetfldstr Function Clears Error and End-of-File Indicators
  100.  
  101. The rsetfldstr function has a side effect in that it internally calls 
  102. the rclearerr function, which clears the error and end-of-file indicators.  
  103. The rationale for this is as follows:  
  104.  
  105.     1. The rsetfldstr function is used in the callback error function to 
  106.        correct data errors.  Even if used elsewhere it's purpose is to 
  107.        force-feed a data value to the program.
  108.        
  109.     2. When the callback error function returns, the recio library 
  110.        functions will only read the replacement value if the error 
  111.        and end-of-file indicators are clear.
  112.     
  113.  
  114. 2.5 The rsetrecstr Function Clears Error and End-of-File Indicators
  115.  
  116. Rationale is similar to rsetfldstr function, section 2.4 above.
  117.  
  118.  
  119.  
  120. 3.0 FIELDS
  121.  
  122. 3.1 Field and Text Delimiters
  123.  
  124. Field and text delimiter characters must be ASCII and are used only with 
  125. character delimited fields.
  126.  
  127. If the null character '\0' is used as a delimiter on an output stream, that 
  128. delimiter is not written to the stream.  This can be sometimes be useful if 
  129. you just want to write some data to the screen.
  130.  
  131. If a delimiter is set to the space character, it is taken to mean any
  132. white space: space, tab, etc.  See the documentation that comes with your 
  133. compiler for the isspace() function.
  134.  
  135. Delimiters around text are optional; no error is generated if they are 
  136. missing.  However text delimiters are needed if the string contains a 
  137. field separator character.  Also no harm is done if text delimiters 
  138. are put around non-text fields.
  139.  
  140.  
  141. 3.2 String Fields
  142.  
  143. Empty strings are legal; no error is generated if there is nothing in a 
  144. string field.  All other types of fields must have something in them or 
  145. a missing data error is generated.
  146.  
  147. If you do this:
  148.  
  149.     /* usually bad */
  150.     char *strptr = rgets(rp);
  151.  
  152. strptr points to the string buffer which changes every time a new field 
  153. is read.  Instead copy the data into your string.  But the method below 
  154. could truncate your data if the field buffer has expanded.
  155.  
  156.     char str[FLDBUFSIZ+1];
  157.     
  158.     /* could lose data if field buffer has expanded */
  159.     strncpy(str, rgets(rp), FLDBUFSIZ);
  160.     str[FLDBUFSIZ] = '\0';
  161.  
  162. Instead you will need to dynamically allocate memory space for your strings.  
  163. The macros scpys and scats allow you to dynamically copy and concatenate 
  164. strings.  To use the scpys and scats macros, you will need to (1) set all 
  165. string pointers to NULL when declaring them, and (2) free your strings when 
  166. finished with them.
  167.  
  168.     char *str=NULL;
  169.     ...
  170.     scpys(str, rgets(rp));
  171.     ...
  172.     free(str);
  173.  
  174.  
  175.  
  176. 4.0 FINE TUNING
  177.  
  178. 4.1 Better Use of Heap Space
  179.  
  180. If you are tight on memory, you can fine tune recio for your application 
  181. by doing the following:
  182.  
  183. 1. Set ROPEN_MAX to the minimum number of files you need open simultaneously.
  184.    Note that recin is always open and must be included in the count.
  185.  
  186. 2. Use rsetfldsiz() and rsetrecsiz() functions to set the maximum size 
  187.    record and field needed for that record stream.  Use these functions 
  188.    before the first field or record is read from the file.  To determine 
  189.    the maximum size record buffer, determine the number of characters in 
  190.    the longest line of the file to be read, including the newline.  To 
  191.    determine the maximum size field buffer, determine the number of 
  192.    characters in the longest field in the record.  If the longest field 
  193.    contains text delimiters, a trailing field delimiter, or white space 
  194.    between the trailing text delimiter and the trailing field delimiter, 
  195.    include these as part of the size.
  196.  
  197.  
  198.  
  199. 5.0 IDEAS FOR EXPANDED CAPABILITIES
  200.  
  201.  
  202. 5.1 Additional Types of Input Functions
  203.  
  204. The macros rget_fn, rcget_fn, etc are used to define functions that get 
  205. numerical input.  By developing the appropriate conversion functions, 
  206. one could expand recio to get other types of data.
  207.  
  208.  
  209. 5.2 Wrapper Functions and Macros
  210.  
  211. If you define wrapper functions or macros that supply a default value 
  212. when the record pointer is NULL, then you can combine reading the file or 
  213. reading a set of default values with the same section of code.
  214.  
  215. REC *rp = ropen("file", "r");
  216. if (rp || (!rp && errno==ENOENT)) {
  217.     /* read data using wrapper functions with default value */
  218.     ...
  219.     if (rp) rclose(rp);
  220. }
  221.  
  222.  
  223. 5.2.1 Default Value
  224.  
  225. If your application cannot find a data file, you may want to use a set of
  226. built-in default values.  This could be a good strategy if your application
  227. uses configuration files.  Note that wrappers will be needed on almost every 
  228. recio function that occurs after the ropen function, including rclose, 
  229. rsetrecsiz, rsetfldsiz, rsetfldch, and rsettxtch, to prevent reporting a
  230. null record pointer to your callback error function (or you will first have 
  231. to test for a null record pointer, such as "if (rp) rclose(rp)").
  232.  
  233. Example Function
  234.  
  235. The rdgeti function gets an integer from an opened data file or gets the
  236. default value if the data file has not been opened (NULL pointer).
  237.  
  238. /* if file open, read value from file; else use default value */
  239. int rdgeti(REC *rp, int default) {
  240.     return (rp ? rgeti(rp) : default);
  241. }
  242.  
  243. Example Macro
  244.  
  245. You can easily rewrite the rdgeti function as a macro.
  246.  
  247. #define rdgeti(rp, default) ((rp) ? rgeti(rp) : (default))
  248.  
  249.  
  250. 5.2.2 Validated Range
  251.  
  252. In order to validate data, you need to make certain that the value read
  253. from the file is within established limits.  You may want to add functions 
  254. that post the range values to an internal data clipboard which your callback 
  255. error function can access.  If you are letting users correct data on the 
  256. fly, convert the minimum and maximum values to strings, and post pointers 
  257. to the strings.
  258.  
  259. Example Function
  260.  
  261. The rrgeti function gets a integer and validates that the integer is within
  262. the established range.
  263.  
  264. int rrgeti(REC *rp, int min, int max) {
  265.     int result;
  266.     
  267.     result = rgeti(rp);
  268.     if (result < min || result > max) {
  269.         rseterr(rp, R_ERANGE);
  270.     }
  271.     return result;
  272. }
  273.  
  274.  
  275. 5.2.3 Default and Range
  276.  
  277. You may want to combine default value and range validation into one function.
  278.  
  279. Example Function
  280.  
  281. The rdrgeti function gets an integer from an opened data file or gets the
  282. default value if the data file has not been opened.  The function validates 
  283. that the integer is within the established range.
  284.  
  285. int rdrgeti(REC *rp, int default, int min, int max) {
  286.     int result;
  287.  
  288.     if (!rp) {
  289.         result = default;
  290.     } else {
  291.         result = rgeti(rp);
  292.     }
  293.     if (result < min || result > max) {
  294.         rseterr(rp, R_ERANGE);
  295.     }
  296.     return result;
  297. }
  298.