home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 15 / CD_ASCQ_15_070894.iso / news / 683 / recio120 / spec.txt < prev    next >
Text File  |  1994-04-08  |  51KB  |  1,572 lines
  1.     Title: SPECIFICATION OF C LANGUAGE RECIO LIBRARY
  2. Copyright: (C) 1994 William Pierpoint
  3.   Version: 1.20
  4.      Date: April 8, 1994
  5.  
  6.  
  7.  
  8. 1.0 RECORD INPUT/OUTPUT <recio.h>
  9.  
  10.  
  11. 1.1 Introduction
  12.  
  13. The header <recio.h> declares one type, several macros, and many functions
  14. for performing line oriented input.  
  15.  
  16. Note: This specification only covers input; output might be developed at a 
  17. later date if there is a perceived need.  Generally the functions available 
  18. in <stdio.h> are adequate for output.
  19.  
  20.  
  21. 1.1.1 Record Streams
  22.  
  23. Input is mapped into logical data record streams.  A record stream is an
  24. ordered sequence of characters composed into records, each record consisting
  25. of zero or more characters plus a terminating record delimiter character.
  26. The terminating record delimiter for a file is the newline character.
  27.  
  28. Each record consists of zero or more fields.  The record may be broken 
  29. into fields in two different ways: (1) character delimited and (2) column 
  30. delimited.  For character delimited fields, each field consists of zero or 
  31. more characters plus a terminating field delimiter character or, for the 
  32. last field in the record, the record delimiter character.  For column 
  33. delimited fields, each field consists of one or more characters delimited 
  34. by a single column position for fields consisting of one character, or by 
  35. beginning and ending column positions for fields consisting of one or more 
  36. characters.
  37.  
  38. Three types of fields are defined: (1) character, (2) text, and (3) 
  39. numeric.  A character field consists of a single character.  A text 
  40. field consists of a sequence of zero or more characters delimited at 
  41. each end by an optional text delimiter character.  A numeric field 
  42. consists of a sequence of one or more characters from the set of valid 
  43. characters for the number type (integral or floating point) and radix.
  44.  
  45.  
  46. 1.1.2 Type
  47.  
  48. The type is
  49.  
  50.     REC
  51.  
  52. which is an object type capable of recording all information needed to 
  53. control a record stream used for line oriented input, including its 
  54. file pointer, pointers to its associated record and field buffers, field 
  55. and text delimiting characters, an error indicator that records whether 
  56. an error has occurred, and an end-of-file indicator that records whether 
  57. the end of the file has been reached.
  58.  
  59.  
  60. 1.1.3 Macros
  61.  
  62. The macros are
  63.  
  64.     RECBUFSIZ
  65.     FLDBUFSIZ
  66.     
  67. which expand to integral constant expressions, which are the initial 
  68. sizes of the record buffer and the field buffer;
  69.     
  70.     RECFLDCH
  71.     RECTXTCH
  72.     
  73. which expand to integral constant expressions, which are the default 
  74. values of the characters used to separate the fields and delimit text 
  75. in a record and whose default value shall correspond to the value of
  76. the space character;
  77.  
  78.     ROPEN_MAX
  79.     
  80. which expands to an integral constant expression that is the maximum 
  81. number of files that can be open simultaneously;
  82.  
  83.     RECIN
  84.     
  85. which expands to an integral constant expression that is the context
  86. number for the recin record stream that gets it's input from the <stdio.h> 
  87. standard input stream stdin.
  88.  
  89.  
  90. 1.1.4 Expressions
  91.  
  92. The one expression is
  93.  
  94.     recin
  95.  
  96. which is of type "pointer to REC" that points to the REC object associated 
  97. with the <stdio.h> FILE object stdin (standard input stream).  The recin 
  98. record stream is always open and is included in the count of ROPEN_MAX.
  99.  
  100.  
  101. 1.2 Record Access Functions
  102.  
  103. 1.2.1 The rclose Function
  104.  
  105. Synopsis
  106.  
  107.      #include <recio.h>
  108.      int rclose(REC *rp);
  109.  
  110. Description
  111.  
  112. The rclose function causes the record stream pointed to by rp and the 
  113. associated file to be closed.  Any unread data is discarded.  The record 
  114. stream is disassociated from the file.  If associated buffers were 
  115. automatically allocated, they are deallocated.
  116.  
  117. If an error occurs, the error indicator for the record stream is set, 
  118. the callback error function is called (if registered), and the rclose 
  119. function returns EOF.
  120.  
  121. Returns
  122.  
  123. The rclose function returns zero if the record stream is successfully 
  124. closed, or EOF if any errors were detected.
  125.  
  126.  
  127. 1.2.2 The rcloseall Function
  128.  
  129. Synopsis
  130.  
  131.      #include <recio.h>
  132.      int rcloseall(void);
  133.  
  134. Description
  135.  
  136. The rcloseall function causes all the open record streams, and all the
  137. files associated with the open record streams, to be closed.  Any unread
  138. data is discarded.  Each record stream is disassociated from its file.
  139. If associated buffers were automatically allocated, they are deallocated.
  140.  
  141. If an error occurs, the rcloseall function returns EOF.
  142.  
  143. Returns
  144.  
  145. The rcloseall function returns the number of record streams successfully 
  146. closed, or EOF if any errors were detected.
  147.  
  148.  
  149. 1.2.3 The ropen Function
  150.  
  151. Synopsis
  152.  
  153.      #include <recio.h>
  154.      REC *ropen(const char *filename, const char *mode);
  155.  
  156. Description
  157.  
  158. The ropen function opens the file whose name is the string pointed to by
  159. filename, and associates a record stream with it.  The argument mode 
  160. points to a string containing:
  161.  
  162.        "r" - open text file for input
  163.  
  164. Note: This specification does not cover output modes at this time.
  165.  
  166. When successfully opened, the error and end-of-file indicators for the 
  167. record stream are clear.  If an error occurs, errno is set to one of the 
  168. error reporting macros as defined in <errno.h>, the callback error function 
  169. is called (except when the file associated with filename is not able to be 
  170. opened), and a null pointer is returned.
  171.  
  172. Returns
  173.  
  174. The ropen function returns a pointer to the object controlling the record 
  175. stream.  If the open operation fails, ropen returns a null pointer.
  176.  
  177.  
  178. 1.2.4 The rsetfldsiz Function
  179.  
  180. Synopsis
  181.  
  182.      #include <recio.h>
  183.      int rsetfldsiz(REC *rp, size_t fldsize);
  184.  
  185. Description
  186.  
  187. The rsetfldsiz function reallocates the field buffer associated with the 
  188. record stream pointed to by rp to the new size of fldsize.
  189.  
  190. The rsetfldsiz function may be used only after the record stream pointed 
  191. to by rp has been opened and before any data is read into the record 
  192. buffer.  Data is read into the record buffer by the function rgetrec,
  193. or by calling a function that either skips a field or gets data from a
  194. field.  If rsetfldsiz is not used, the initial size of the field buffer 
  195. is set by the value of the macro FLDBUFSIZ.
  196.  
  197. If an error occurs, the error indicator for the record stream is set, 
  198. the callback error function is called (if registered), and the rsetfldsiz 
  199. function returns EOF.
  200.  
  201. Returns
  202.  
  203. The rsetfldsiz function returns zero if the field buffer is successfully 
  204. reallocated, or EOF if any errors were detected.
  205.  
  206.  
  207. 1.2.5 The rsetrecsiz Function
  208.  
  209. Synopsis
  210.  
  211.      #include <recio.h>
  212.      int rsetrecsiz(REC *rp, size_t recsize);
  213.  
  214. Description
  215.  
  216. The rsetrecsiz function reallocates the record buffer associated with the 
  217. record stream pointed to by rp to the new size of recsize.
  218.  
  219. The rsetrecsiz function may be used only after the record stream pointed 
  220. to by rp has been opened and before any data is read into the record 
  221. buffer.  Data is read into the record buffer by the function rgetrec,
  222. or by calling a function that either skips a field or gets data from a
  223. field.  If rsetrecsiz is not used, the initial size of the field buffer 
  224. is set by the value of the macro RECBUFSIZ.
  225.  
  226. If an error occurs, the error indicator for the record stream is set, 
  227. the callback error function is called (if registered), and the rsetrecsiz 
  228. function returns EOF.
  229.  
  230. Returns
  231.  
  232. The rsetrecsiz function returns zero if the record buffer is successfully 
  233. reallocated, or EOF if any errors were detected.
  234.  
  235.  
  236. 1.3 Character Delimited Field Input Functions
  237.  
  238. 1.3.1 The rbgeti Function
  239.  
  240. Synopsis
  241.  
  242.      #include <recio.h>
  243.      int rbgeti(REC *rp, int base);
  244.  
  245. Description
  246.  
  247. The rbgeti function reads a field consisting of one integral number 
  248. represented by the radix determined by the value of base from the input 
  249. record stream pointed to by rp.  Any leading or trailing white space 
  250. in the field is ignored.
  251.  
  252. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  253. base is zero, the expected form of the integral number is described by
  254. section 3.1.3.2 of ANSI X3.159-1989.
  255.  
  256. If an error occurs, the error indicator for the record stream is set, 
  257. the callback error function is called (if registered), and the rbgeti 
  258. function returns zero.
  259.  
  260. Returns
  261.  
  262. The rbgeti function returns a signed integer from the input record 
  263. stream pointed to by rp.  If an attempt is made to read beyond the 
  264. end-of-record, if the field is empty, or if there is an illegal character 
  265. in the field, the error indicator for the record stream is set, and rbgeti 
  266. returns zero.  If the record stream is at end-of-file (end-of-file indicator 
  267. set), rbgeti returns zero.  If a previous error has occurred on the record 
  268. stream that has not been cleared (error indicator set), rbgeti returns zero.  
  269.  
  270.  
  271. 1.3.2 The rbgetl Function
  272.  
  273. Synopsis
  274.  
  275.      #include <recio.h>
  276.      long rbgetl(REC *rp, int base);
  277.  
  278. Description
  279.  
  280. The rbgetl function reads a field consisting of one integral number 
  281. represented by the radix determined by the value of base from the input 
  282. record stream pointed to by rp.  Any leading or trailing white space 
  283. in the field is ignored.
  284.  
  285. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  286. base is zero, the expected form of the integral number is described by
  287. section 3.1.3.2 of ANSI X3.159-1989.
  288.  
  289. If an error occurs, the error indicator for the record stream is set, 
  290. the callback error function is called (if registered), and the rbgetl 
  291. function returns zero (0L).
  292.  
  293. Returns
  294.  
  295. The rbgetl function returns a signed long from the input record stream 
  296. pointed to by rp.  If an attempt is made to read beyond the end-of-record, 
  297. if the field is empty, or if there is an illegal character in the field, 
  298. the error indicator for the record stream is set, and rbgetl returns zero 
  299. (0L).  If the record stream is at end-of-file (end-of-file indicator set), 
  300. rbgetl returns zero (0L).  If a previous error has occurred on the record 
  301. stream that has not been cleared (error indicator set), rbgetl returns 
  302. zero (0L).  
  303.  
  304.  
  305. 1.3.3 The rbgetui Function
  306.  
  307. Synopsis
  308.  
  309.      #include <recio.h>
  310.      unsigned int rbgetui(REC *rp, int base);
  311.  
  312. Description
  313.  
  314. The rbgetui function reads a field consisting of one non-negative integral 
  315. number represented by the radix determined by the value of base from the 
  316. input record stream pointed to by rp.  Any leading or trailing white space 
  317. in the field is ignored.
  318.  
  319. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  320. base is zero, the expected form of the integral number is described by
  321. section 3.1.3.2 of ANSI X3.159-1989.
  322.  
  323. If an error occurs, the error indicator for the record stream is set, 
  324. the callback error function is called (if registered), and the rbgetui 
  325. function returns zero.
  326.  
  327. Returns
  328.  
  329. The rbgetui function returns an unsigned integer from the input record 
  330. stream pointed to by rp.  If an attempt is made to read beyond the 
  331. end-of-record, if the field is empty, or if there is an illegal character 
  332. in the field, the error indicator for the record stream is set, and rbgetui 
  333. returns zero.  If the record stream is at end-of-file (end-of-file indicator 
  334. set), rbgetui returns zero.  If a previous error has occurred on the record 
  335. stream that has not been cleared (error indicator set), rbgetui returns zero.  
  336.  
  337.  
  338. 1.3.4 The rbgetul Function
  339.  
  340. Synopsis
  341.  
  342.      #include <recio.h>
  343.      unsigned long rbgetul(REC *rp, int base);
  344.  
  345. Description
  346.  
  347. The rbgetul function reads a field consisting of one non-negative integral 
  348. number represented by the radix determined by the value of base from the 
  349. input record stream pointed to by rp.  Any leading or trailing white space 
  350. in the field is ignored.
  351.  
  352. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  353. base is zero, the expected form of the integral number is described by
  354. section 3.1.3.2 of ANSI X3.159-1989.
  355.  
  356. If an error occurs, the error indicator for the record stream is set, 
  357. the callback error function is called (if registered), and the rbgetul 
  358. function returns zero (0L).
  359.  
  360. Returns
  361.  
  362. The rbgetul function returns an unsigned long from the input record stream 
  363. pointed to by rp.  If an attempt is made to read beyond the end-of-record, 
  364. if the field is empty, or if there is an illegal character in the field, 
  365. the error indicator for the record stream is set, and rbgetul returns zero 
  366. (0L).  If the record stream is at end-of-file (end-of-file indicator set), 
  367. rbgetul returns zero (0L).  If a previous error has occurred on the record 
  368. stream that has not been cleared (error indicator set), rbgetul returns 
  369. zero (0L).  
  370.  
  371.  
  372. 1.3.5 The rgetc Function
  373.  
  374. Synopsis
  375.  
  376.      #include <recio.h>
  377.      int rgetc(REC *rp);
  378.  
  379. Description
  380.  
  381. The rgetc function reads a field consisting of one non-white space 
  382. character from the input record stream pointed to by rp.  Any leading 
  383. or trailing white space in the field is ignored.
  384.  
  385. If an error occurs, the error indicator for the record stream is set, 
  386. the callback error function is called (if registered), and the rgetc 
  387. function returns EOF.
  388.  
  389. Returns
  390.  
  391. The rgetc function returns a character from a single non-white
  392. space character field in the input record stream pointed to by rp.  
  393. If an attempt is made to read beyond the end-of-record, or if there
  394. is more than or less than one non-white character in the field, the 
  395. error indicator for the record stream is set, and rgetc returns EOF.  If the 
  396. record stream is at end-of-file (end-of-file indicator set), rgetc returns 
  397. EOF.  If a previous error has occurred on the record stream that has not been 
  398. cleared (error indicator set), rgetc returns EOF.  
  399.  
  400.  
  401. 1.3.6 The rgetd Function
  402.  
  403. Synopsis
  404.  
  405.      #include <recio.h>
  406.      double rgetd(REC *rp);
  407.  
  408. Description
  409.  
  410. The rgetd function reads a field consisting of one floating point
  411. number from the input record stream pointed to by rp.  Any leading 
  412. or trailing white space in the field is ignored.
  413.  
  414. If an error occurs, the error indicator for the record stream is set, 
  415. the callback error function is called (if registered), and the rgetd 
  416. function returns zero (0.0).
  417.  
  418. Returns
  419.  
  420. The rgetd function returns a double precision floating point number 
  421. from the input record stream pointed to by rp.  If an attempt is made 
  422. to read beyond the end-of-record, if the field is empty, or if there
  423. is an illegal character in the field, the error indicator for the 
  424. record stream is set, and rgetd returns zero (0.0).  If the record stream is 
  425. at end-of-file (end-of-file indicator set), rgetd returns zero (0.0).  If a 
  426. previous error has occurred on the record stream that has not been cleared 
  427. (error indicator set), rgetd returns zero (0.0).
  428.  
  429.  
  430. 1.3.7 The rgetf Function
  431.  
  432. Synopsis
  433.  
  434.      #include <recio.h>
  435.      float rgetf(REC *rp);
  436.  
  437. Description
  438.  
  439. The rgetf function reads a field consisting of one floating point
  440. number from the input record stream pointed to by rp.  Any leading 
  441. or trailing white space in the field is ignored.
  442.  
  443. If an error occurs, the error indicator for the record stream is set, 
  444. the callback error function is called (if registered), and the rgetf 
  445. function returns zero (0.0).
  446.  
  447. Returns
  448.  
  449. The rgetf function returns a single precision floating point number 
  450. from the input record stream pointed to by rp.  If an attempt is made 
  451. to read beyond the end-of-record, if the field is empty, or if there
  452. is an illegal character in the field, the error indicator for the 
  453. record stream is set, and rgetf returns zero (0.0).  If the record stream is 
  454. at end-of-file (end-of-file indicator set), rgetf returns zero (0.0).  If a 
  455. previous error has occurred on the record stream that has not been cleared 
  456. (error indicator set), rgetf returns zero (0.0).
  457.  
  458.  
  459. 1.3.8 The rgeti Function
  460.  
  461. Synopsis
  462.  
  463.      #include <recio.h>
  464.      int rgeti(REC *rp);
  465.  
  466. Description
  467.  
  468. The rgeti function reads a field consisting of one integral
  469. number from the input record stream pointed to by rp.  Any leading 
  470. or trailing white space in the field is ignored.
  471.  
  472. If an error occurs, the error indicator for the record stream is set, 
  473. the callback error function is called (if registered), and the rgeti 
  474. function returns zero.
  475.  
  476. Returns
  477.  
  478. The rgeti function returns a signed integer from the input record 
  479. stream pointed to by rp.  If an attempt is made to read beyond the 
  480. end-of-record, if the field is empty, or if there is an illegal character 
  481. in the field, the error indicator for the record stream is set, and rgeti 
  482. returns zero.  If the record stream is at end-of-file (end-of-file indicator 
  483. set), rgeti returns zero.  If a previous error has occurred on the record 
  484. stream that has not been cleared (error indicator set), rgeti returns zero.  
  485.  
  486.  
  487. 1.3.9 The rgetl Function
  488.  
  489. Synopsis
  490.  
  491.      #include <recio.h>
  492.      long rgetl(REC *rp);
  493.  
  494. Description
  495.  
  496. The rgetl function reads a field consisting of one integral number 
  497. from the input record stream pointed to by rp.  Any leading or trailing 
  498. white space in the field is ignored.
  499.  
  500. If an error occurs, the error indicator for the record stream is set, 
  501. the callback error function is called (if registered), and the rgetl 
  502. function returns zero (0L).
  503.  
  504. Returns
  505.  
  506. The rgetl function returns a signed long from the input record stream 
  507. pointed to by rp.  If an attempt is made to read beyond the end-of-record, 
  508. if the field is empty, or if there is an illegal character in the field, 
  509. the error indicator for the record stream is set, and rgetl returns zero 
  510. (0L).  If the record stream is at end-of-file (end-of-file indicator set), 
  511. rgetl returns zero (0L).  If a previous error has occurred on the record 
  512. stream that has not been cleared (error indicator set), rgetl returns zero 
  513. (0L).  
  514.  
  515.  
  516. 1.3.10 The rgets Function
  517.  
  518. Synopsis
  519.  
  520.      #include <recio.h>
  521.      char *rgets(REC *rp);
  522.  
  523. Description
  524.  
  525. The rgets function reads a field consisting of one text string from the 
  526. input record stream pointed to by rp.  Any leading white space before the 
  527. text delimiter and any trailing white space after the text delimiter in 
  528. the field is ignored.  The text delimiters are not returned as part of 
  529. the string.
  530.  
  531. If an error occurs, the error indicator for the record stream is set, 
  532. the callback error function is called (if registered), and the rgets 
  533. function returns a pointer to an empty string.
  534.  
  535. Returns
  536.  
  537. The rgets function returns a pointer to a character array from the input 
  538. record stream pointed to by rp.  If an attempt is made to read beyond the 
  539. end-of-record, the error indicator for the record stream is set, and rgets 
  540. returns a pointer to an empty string.  If the record stream is at end-of-file 
  541. (end-of-file indicator set), rgets returns a pointer to an empty string.  If 
  542. a previous error has occurred on the record stream that has not been cleared 
  543. (error indicator set), rgets returns a pointer to an empty string.
  544.  
  545.  
  546. 1.3.11 The rgetui Function
  547.  
  548. Synopsis
  549.  
  550.      #include <recio.h>
  551.      unsigned int rgetui(REC *rp);
  552.  
  553. Description
  554.  
  555. The rgetui function reads a field consisting of one non-negative 
  556. integral number from the input record stream pointed to by rp.  Any 
  557. leading or trailing white space in the field is ignored.
  558.  
  559. If an error occurs, the error indicator for the record stream is set, 
  560. the callback error function is called (if registered), and the rgetui 
  561. function returns zero.
  562.  
  563. Returns
  564.  
  565. The rgetui function returns an unsigned integer from the input record 
  566. stream pointed to by rp.  If an attempt is made to read beyond the 
  567. end-of-record, if the field is empty, or if there is an illegal character 
  568. in the field, the error indicator for the record stream is set, and rgetui 
  569. returns zero.  If the record stream is at end-of-file (end-of-file indicator 
  570. set), rgetui returns zero.  If a previous error has occurred on the record 
  571. stream that has not been cleared (error indicator set), rgetui returns zero.  
  572.  
  573.  
  574. 1.3.12 The rgetul Function
  575.  
  576. Synopsis
  577.  
  578.      #include <recio.h>
  579.      unsigned long rgetul(REC *rp);
  580.  
  581. Description
  582.  
  583. The rgetul function reads a field consisting of one non-negative 
  584. integral number from the input record stream pointed to by rp.  Any 
  585. leading or trailing white space in the field is ignored.
  586.  
  587. If an error occurs, the error indicator for the record stream is set, 
  588. the callback error function is called (if registered), and the rgetul 
  589. function returns zero (0L).
  590.  
  591. Returns
  592.  
  593. The rgetul function returns an unsigned long from the input record stream 
  594. pointed to by rp.  If an attempt is made to read beyond the end-of-record, 
  595. if the field is empty, or if there is an illegal character in the field, 
  596. the error indicator for the record stream is set, and rgetul returns zero 
  597. (0L).  If the record stream is at end-of-file (end-of-file indicator set), 
  598. rgetul returns zero (0L).  If a previous error has occurred on the record 
  599. stream that has not been cleared (error indicator set), rgetul returns zero 
  600. (0L).  
  601.  
  602.  
  603. 1.3.13 The rsetfldch Function
  604.  
  605. Synopsis
  606.  
  607.      #include <recio.h>
  608.      int rsetfldch(REC *rp, int ch);
  609.  
  610. Description
  611.  
  612. The rsetfldch function sets the field delimiter to the character ch
  613. for the record stream pointed to by rp.  If the character ch is the 
  614. space character ' ', then the field is delimited by any white-space, 
  615. and multiple contiguous white space characters are treated as a single 
  616. delimiter.  If the character ch is other than the space character, then 
  617. multiple contiguous field delimiters are treated as a series of empty
  618. fields.
  619.  
  620. If rsetfldch is not called, the field delimiter is set by the value of 
  621. the macro RECFLDCH.
  622.  
  623. If an error occurs, the error indicator for the record stream is set, 
  624. the callback error function is called (if registered), and the rsetfldch 
  625. function returns EOF.
  626.  
  627. Returns
  628.  
  629. The rsetfldch function returns zero if the field delimiter character was
  630. successfully set for the record stream, or EOF if any errors were detected.
  631.  
  632.  
  633. 1.3.14 The rsettxtch Function
  634.  
  635. Synopsis
  636.  
  637.      #include <recio.h>
  638.      int rsettxtch(REC *rp, int ch);
  639.  
  640. Description
  641.  
  642. The rsettxtch function sets the text delimiter to the character ch for 
  643. the record stream pointed to by rp.
  644.  
  645. If rsettxtch is not called, the text delimiter is set by the value of 
  646. the macro RECTXTCH.
  647.  
  648. If an error occurs, the error indicator for the record stream is set, 
  649. the callback error function is called (if registered), and the rsettxtch 
  650. function returns EOF.
  651.  
  652. Returns
  653.  
  654. The rsettxtch function returns zero if the text delimiter character was
  655. successfully set for the record stream, or EOF if any errors were detected.
  656.  
  657.  
  658. 1.3.15 The rskipfld Function
  659.  
  660. Synopsis
  661.  
  662.      #include <recio.h>
  663.      int rskipfld(REC *rp);
  664.  
  665. Description
  666.  
  667. The rskipfld function skips to the next field for the record stream
  668. pointed to by rp.
  669.  
  670. If an error occurs, the error indicator for the record stream is set, 
  671. the callback error function is called (if registered), and the rskipfld 
  672. function returns EOF.
  673.  
  674. Returns
  675.  
  676. The rskipfld function returns one if the field was successfully skipped, 
  677. zero if the field could not be skipped (end of record), or EOF if any 
  678. errors were detected.
  679.  
  680.  
  681. 1.3.16 The rskipnfld Function
  682.  
  683. Synopsis
  684.  
  685.      #include <recio.h>
  686.      int rskipnfld(REC *rp, size_t num);
  687.  
  688. Description
  689.  
  690. The rskipnfld function skips over num number of fields for the record
  691. stream pointed to by rp.
  692.  
  693. If an error occurs, the error indicator for the record stream is set, 
  694. the callback error function is called (if registered), and the rskipnfld 
  695. function returns EOF.
  696.  
  697. Returns
  698.  
  699. The rskipfld function returns the actual number of fields skipped, or EOF 
  700. if any errors were detected.
  701.  
  702.  
  703. 1.4 Column Delimited Field Input Functions
  704.  
  705. 1.4.1 The rcbgeti Function
  706.  
  707. Synopsis
  708.  
  709.      #include <recio.h>
  710.      int rcbgeti(REC *rp, size_t begcol, size_t endcol, int base);
  711.  
  712. Description
  713.  
  714. The rcbgeti function gets one integral number represented by the radix 
  715. determined by the value of base and contained inclusively from column 
  716. begcol to column endcol for the input record stream pointed to by rp.  
  717. Any leading or trailing white space in the field is ignored.
  718.  
  719. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  720. base is zero, the expected form of the integral number is described by
  721. section 3.1.3.2 of ANSI X3.159-1989.
  722.  
  723. If an error occurs, the error indicator for the record stream is set, 
  724. the callback error function is called (if registered), and the rgeti 
  725. function returns zero.
  726.  
  727. Returns
  728.  
  729. The rcbgeti function returns a signed integer from the input record stream 
  730. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  731. empty, or if there is an illegal character in the field, the error indicator 
  732. for the record stream is set, and rcbgeti returns zero.  If the record stream 
  733. is at end-of-file (end-of-file indicator set), rcbgeti returns zero.  If a 
  734. previous error has occurred on the record stream that has not been cleared 
  735. (error indicator set), rcbgeti returns zero.  
  736.  
  737.  
  738. 1.4.2 The rcbgetl Function
  739.  
  740. Synopsis
  741.  
  742.      #include <recio.h>
  743.      long rcbgetl(REC *rp, size_t begcol, size_t endcol, int base);
  744.  
  745. Description
  746.  
  747. The rcbgetl function gets one integral number represented by the radix 
  748. determined by the value of base and contained inclusively from column 
  749. begcol to column endcol for the input record stream pointed to by rp.  
  750. Any leading or trailing white space in the field is ignored.
  751.  
  752. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  753. base is zero, the expected form of the integral number is described by
  754. section 3.1.3.2 of ANSI X3.159-1989.
  755.  
  756. If an error occurs, the error indicator for the record stream is set, 
  757. the callback error function is called (if registered), and the rgetl 
  758. function returns zero (0L).
  759.  
  760. Returns
  761.  
  762. The rcbgetl function returns a signed long from the input record stream 
  763. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  764. empty, or if there is an illegal character in the field, the error indicator 
  765. for the record stream is set, and rcbgetl returns zero (0L).  If the record 
  766. stream is at end-of-file (end-of-file indicator set), rcbgetl returns zero 
  767. (0L).  If a previous error has occurred on the record stream that has not been 
  768. cleared (error indicator set), rcbgetl returns zero (0L).  
  769.  
  770.  
  771. 1.4.3 The rcbgetui Function
  772.  
  773. Synopsis
  774.  
  775.      #include <recio.h>
  776.      unsigned int rcbgetui(REC *rp, size_t begcol, size_t endcol, 
  777.           int base);
  778.  
  779. Description
  780.  
  781. The rcbgetui function gets one non-negative integral number represented 
  782. by the radix determined by the value of base and contained inclusively 
  783. from column begcol to column endcol for the input record stream pointed 
  784. to by rp.  Any leading or trailing white space in the field is ignored.
  785.  
  786. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  787. base is zero, the expected form of the integral number is described by
  788. section 3.1.3.2 of ANSI X3.159-1989.
  789.  
  790. If an error occurs, the error indicator for the record stream is set, 
  791. the callback error function is called (if registered), and the rgetui 
  792. function returns zero.
  793.  
  794. Returns
  795.  
  796. The rcbgetui function returns an unsigned integer from the input record 
  797. stream pointed to by rp.  If begcol is beyond the end-of-record, if the 
  798. field is empty, or if there is an illegal character in the field, the 
  799. error indicator for the record stream is set, and rcbgetui returns zero.  If 
  800. the record stream is at end-of-file (end-of-file indicator set), rcbgetui 
  801. returns zero.  If a previous error has occurred on the record stream that has 
  802. not been cleared (error indicator set), rcbgetui returns zero.  
  803.  
  804.  
  805. 1.4.4 The rcbgetul Function
  806.  
  807. Synopsis
  808.  
  809.      #include <recio.h>
  810.      unsigned long rcbgetul(REC *rp, size_t begcol, size_t endcol, 
  811.           int base);
  812.  
  813. Description
  814.  
  815. The rcbgetul function gets one non-negative integral number represented 
  816. by the radix determined by the value of base and contained inclusively 
  817. from column begcol to column endcol for the input record stream pointed 
  818. to by rp.  Any leading or trailing white space in the field is ignored.
  819.  
  820. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  821. base is zero, the expected form of the integral number is described by
  822. section 3.1.3.2 of ANSI X3.159-1989.
  823.  
  824. If an error occurs, the error indicator for the record stream is set, 
  825. the callback error function is called (if registered), and the rgetul 
  826. function returns zero (0L).
  827.  
  828. Returns
  829.  
  830. The rcbgetul function returns an unsigned long from the input record stream 
  831. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  832. empty, or if there is an illegal character in the field, the error indicator 
  833. for the record stream is set, and rcbgetul returns zero (0L).  If the record 
  834. stream is at end-of-file (end-of-file indicator set), rcbgetul returns zero 
  835. (0L).  If a previous error has occurred on the record stream that has not been 
  836. cleared (error indicator set), rcbgetul returns zero (0L).  
  837.  
  838.  
  839. 1.4.5 The rcgetc Function
  840.  
  841. Synopsis
  842.  
  843.      #include <recio.h>
  844.      int rcgetc(REC *rp, size_t col);
  845.  
  846. Description
  847.  
  848. The rcgetc function obtains from column position col the unsigned char
  849. converted to an int from the input record stream pointed to by rp.
  850.  
  851. If an error occurs, the error indicator for the record stream is set, 
  852. the callback error function is called (if registered), and the rcgetc 
  853. function returns EOF.
  854.  
  855. Returns
  856.  
  857. The rcgetc function returns a character from column position col from 
  858. the input record stream pointed to by rp.  If an attempt is made to read 
  859. beyond the end-of-record, the error indicator for the record stream is set, 
  860. and rcgetc returns EOF.  If the record stream is at end-of-file (end-of-file 
  861. indicator set), rcgetc returns EOF.  If a previous error has occurred on the 
  862. record stream that has not been cleared (error indicator set), rcgetc returns 
  863. EOF.  
  864.  
  865.  
  866. 1.4.6 The rcgetd Function
  867.  
  868. Synopsis
  869.  
  870.      #include <recio.h>
  871.      double rcgetd(REC *rp, size_t begcol, size_t endcol);
  872.  
  873. Description
  874.  
  875. The rcgetd function gets one floating point number contained inclusively
  876. from column begcol to column endcol for the input record stream pointed to 
  877. by rp.  Any leading or trailing white space in the field is ignored.
  878.  
  879. If an error occurs, the error indicator for the record stream is set, 
  880. the callback error function is called (if registered), and the rcgetd 
  881. function returns zero (0.0).
  882.  
  883. Returns
  884.  
  885. The rcgetd function returns a double precision floating point number from the 
  886. input record stream pointed to by rp.  If begcol is beyond the end-of-record, 
  887. if the field is empty, or if there is an illegal character in the field, the 
  888. error indicator for the record stream is set, and rcgetd returns zero (0.0).  
  889. If the record stream is at end-of-file (end-of-file indicator set), rcgetd 
  890. returns zero (0.0).  If a previous error has occurred on the record stream 
  891. that has not been cleared (error indicator set), rcgetd returns zero (0.0).
  892.  
  893.  
  894. 1.4.7 The rcgetf Function
  895.  
  896. Synopsis
  897.  
  898.      #include <recio.h>
  899.      float rcgetf(REC *rp, size_t begcol, size_t endcol);
  900.  
  901. Description
  902.  
  903. The rcgetd function gets one floating point number contained inclusively
  904. from column begcol to column endcol for the input record stream pointed to 
  905. by rp.  Any leading or trailing white space in the field is ignored.
  906.  
  907. If an error occurs, the error indicator for the record stream is set, 
  908. the callback error function is called (if registered), and the rcgetf 
  909. function returns zero (0.0).
  910.  
  911. Returns
  912.  
  913. The rcgetf function returns a single precision floating point number from the 
  914. input record stream pointed to by rp.  If begcol is beyond the end-of-record, 
  915. if the field is empty, or if there is an illegal character in the field, the 
  916. error indicator for the record stream is set, and rcgetf returns zero (0.0).  
  917. If the record stream is at end-of-file (end-of-file indicator set), rcgetf 
  918. returns zero (0.0).  If a previous error has occurred on the record stream 
  919. that has not been cleared (error indicator set), rcgetf returns zero (0.0).
  920.  
  921.  
  922. 1.4.8 The rcgeti Function
  923.  
  924. Synopsis
  925.  
  926.      #include <recio.h>
  927.      int rcgeti(REC *rp, size_t begcol, size_t endcol);
  928.  
  929. Description
  930.  
  931. The rcgeti function gets one integral number contained inclusively from 
  932. column begcol to column endcol for the input record stream pointed to by 
  933. rp.  Any leading or trailing white space in the field is ignored.
  934.  
  935. If an error occurs, the error indicator for the record stream is set, 
  936. the callback error function is called (if registered), and the rgeti 
  937. function returns zero.
  938.  
  939. Returns
  940.  
  941. The rcgeti function returns a signed integer from the input record stream 
  942. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  943. empty, or if there is an illegal character in the field, the error indicator 
  944. for the record stream is set, and rcgeti returns zero.  If the record stream 
  945. is at end-of-file (end-of-file indicator set), rcgeti returns zero.  If a 
  946. previous error has occurred on the record stream that has not been cleared 
  947. (error indicator set), rcgeti returns zero.  
  948.  
  949.  
  950. 1.4.9 The rcgetl Function
  951.  
  952. Synopsis
  953.  
  954.      #include <recio.h>
  955.      long rcgetl(REC *rp, size_t begcol, size_t endcol);
  956.  
  957. Description
  958.  
  959. The rcgetl function gets one integral number contained inclusively from 
  960. column begcol to column endcol for the input record stream pointed to by 
  961. rp.  Any leading or trailing white space in the field is ignored.
  962.  
  963. If an error occurs, the error indicator for the record stream is set, 
  964. the callback error function is called (if registered), and the rgetl 
  965. function returns zero (0L).
  966.  
  967. Returns
  968.  
  969. The rcgetl function returns a signed long from the input record stream 
  970. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  971. empty, or if there is an illegal character in the field, the error indicator 
  972. for the record stream is set, and rcgetl returns zero (0L).  If the record 
  973. stream is at end-of-file (end-of-file indicator set), rcgetl returns zero 
  974. (0L).  If a previous error has occurred on the record stream that has not 
  975. been cleared (error indicator set), rcgetl returns zero (0L).  
  976.  
  977.  
  978. 1.4.10 The rcgets Function
  979.  
  980. Synopsis
  981.  
  982.      #include <recio.h>
  983.      char *rcgets(REC *rp, size_t begcol, size_t endcol);
  984.  
  985. Description
  986.  
  987. The rcgets function gets a string contained inclusively from column 
  988. begcol to column endcol for the input record stream pointed to by 
  989. rp.  The rcgets function does not remove any leading or trailing
  990. white space, nor does it remove any text delimiter characters.
  991.  
  992. If an error occurs, the error indicator for the record stream is set, 
  993. the callback error function is called (if registered), and the rgets 
  994. function returns a pointer to an empty string.
  995.  
  996. Returns
  997.  
  998. The rcgets function returns a pointer to a character array from the input 
  999. record stream pointed to by rp.  If begcol is beyond the end-of-record, the 
  1000. error indicator for the record stream is set, and rcgets returns a pointer to 
  1001. an empty string.  If the record stream is at end-of-file (eof indicator set), 
  1002. rcgets returns a pointer to an empty string.  If a previous error has occurred 
  1003. on the record stream that has not been cleared (error indicator set), rcgets 
  1004. returns a pointer to an empty string.
  1005.  
  1006.  
  1007. 1.4.11 The rcgetui Function
  1008.  
  1009. Synopsis
  1010.  
  1011.      #include <recio.h>
  1012.      unsigned int rcgetui(REC *rp, size_t begcol, size_t endcol);
  1013.  
  1014. Description
  1015.  
  1016. The rcgetui function gets one non-negative integral number contained 
  1017. inclusively from column begcol to column endcol for the input record 
  1018. stream pointed to by rp.  Any leading or trailing white space in the 
  1019. field is ignored.
  1020.  
  1021. If an error occurs, the error indicator for the record stream is set, 
  1022. the callback error function is called (if registered), and the rgetui 
  1023. function returns zero.
  1024.  
  1025. Returns
  1026.  
  1027. The rcgetui function returns an unsigned integer from the input record 
  1028. stream pointed to by rp.  If begcol is beyond the end-of-record, if the 
  1029. field is empty, or if there is an illegal character in the field, the 
  1030. error indicator for the record stream is set, and rcgetui returns zero.  If 
  1031. the record stream is at end-of-file (end-of-file indicator set), rcgetui 
  1032. returns zero.  If a previous error has occurred on the record stream that has 
  1033. not been cleared (error indicator set), rcgetui returns zero.  
  1034.  
  1035.  
  1036. 1.4.12 The rcgetul Function
  1037.  
  1038. Synopsis
  1039.  
  1040.      #include <recio.h>
  1041.      unsigned long rcgetul(REC *rp, size_t begcol, size_t endcol);
  1042.  
  1043. Description
  1044.  
  1045. The rcgetul function gets one non-negative integral number contained 
  1046. inclusively from column begcol to column endcol for the input record 
  1047. stream pointed to by rp.  Any leading or trailing white space in the 
  1048. field is ignored.
  1049.  
  1050. If an error occurs, the error indicator for the record stream is set, 
  1051. the callback error function is called (if registered), and the rgetul 
  1052. function returns zero (0L).
  1053.  
  1054. Returns
  1055.  
  1056. The rcgetul function returns an unsigned long from the input record stream 
  1057. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  1058. empty, or if there is an illegal character in the field, the error indicator 
  1059. for the record stream is set, and rcgetul returns zero (0L).  If the record 
  1060. stream is at end-of-file (end-of-file indicator set), rcgetul returns zero 
  1061. (0L).  If a previous error has occurred on the record stream that has not 
  1062. been cleared (error indicator set), rcgetul returns zero (0L).  
  1063.  
  1064.  
  1065. 1.5 Current Position Functions
  1066.  
  1067. 1.5.1 The rbegcolno Function
  1068.  
  1069. Synopsis
  1070.  
  1071.      #include <recio.h>
  1072.      int rbegcolno(REC *rp);
  1073.  
  1074. Description
  1075.  
  1076. The rbegcolno function gets the current setting of the first column number 
  1077. in the record for the record stream pointed to by rp.
  1078.  
  1079. Returns
  1080.  
  1081. The rbegcolno function returns 0 if column numbering starts with zero or 
  1082. 1 if column numbering starts with one.
  1083.  
  1084.  
  1085. 1.5.2 The rcolno Function
  1086.  
  1087. Synopsis
  1088.  
  1089.      #include <recio.h>
  1090.      size_t rcolno(REC *rp);
  1091.  
  1092. Description
  1093.  
  1094. The rcolno function gets the current column number of the current record 
  1095. for the record stream pointed to by rp.
  1096.  
  1097. Returns
  1098.  
  1099. The rcolno function returns the current column number of the current record 
  1100. for the record stream pointed to by rp.  The rcolno function returns zero 
  1101. prior to the reading of the first record.
  1102.  
  1103.  
  1104. 1.5.3 The rflds Function
  1105.  
  1106. Synopsis
  1107.  
  1108.      #include <recio.h>
  1109.      char *rflds(REC *rp);
  1110.  
  1111. Description
  1112.  
  1113. The rflds function gets a pointer to the field buffer associated with 
  1114. the record stream pointed to by rp.  The last field read from the current 
  1115. record is stored in the field buffer.  The field is terminated by a
  1116. null character.
  1117.  
  1118. Returns
  1119.  
  1120. The rflds function returns a pointer to the field buffer associated with 
  1121. the record stream pointed to by rp.
  1122.  
  1123.  
  1124. 1.5.4 The rfldno Function
  1125.  
  1126. Synopsis
  1127.  
  1128.      #include <recio.h>
  1129.      size_t rfldno(REC *rp);
  1130.  
  1131. Description
  1132.  
  1133. The rfldno function gets the number of fields that have been read from 
  1134. the current record for the record stream pointed to by rp.
  1135.  
  1136. Returns
  1137.  
  1138. The rfldno function returns the number of fields that have been read from 
  1139. the current record for the record stream pointed to by rp.
  1140.  
  1141.  
  1142. 1.5.5 The rnames Function
  1143.  
  1144. Synopsis
  1145.  
  1146.      #include <recio.h>
  1147.      char *rnames(REC *rp);
  1148.  
  1149. Description
  1150.  
  1151. The rnames function gets a pointer to the name of the file associated
  1152. with the record stream pointed to by rp.
  1153.  
  1154. Returns
  1155.  
  1156. The rnames function returns a pointer to the name of the file associated
  1157. with the record stream pointed to by rp.
  1158.  
  1159.  
  1160. 1.5.6 The rgetrec Function
  1161.  
  1162. Synopsis
  1163.  
  1164.      #include <recio.h>
  1165.      char *rgetrec(REC *rp);
  1166.  
  1167. Description
  1168.  
  1169. The rgetrec function gets the next record from the record stream pointed
  1170. to by rp.  The rgetrec function increments the record number, clears the 
  1171. field number to zero, resets the column number to rbegcolno(), and returns 
  1172. a pointer to the record buffer.  
  1173.  
  1174. Record numbering starts at one (1L).  Before the first record in a record 
  1175. stream is read into the record buffer, the record number is zero.
  1176.  
  1177. Field numbering starts at one (1).  Before the first field in a record is 
  1178. read into the field buffer, the field number is zero.
  1179.  
  1180. Column numbering starts at either zero or one, depending on the setting of 
  1181. the rsetbegcolno function.  Column numbering defaults to zero.
  1182.  
  1183. If an error occurs, the error indicator for the record stream is set, 
  1184. the callback error function is called (if registered), and the rgetrec 
  1185. function returns a null pointer.
  1186.  
  1187. If the end-of-file is reached, the end-of-file indicator for the record
  1188. stream is set and the rgetrec function returns a null pointer.
  1189.  
  1190. Returns
  1191.  
  1192. The rgetrec function returns a pointer to the record buffer if the next 
  1193. record was successfully read.  If there are no more records, the end-of-file 
  1194. indicator is set and rgetrec returns a null pointer.  If an error occurred, 
  1195. the error indicator is set and rgetrec returns a null pointer.
  1196.  
  1197.  
  1198. 1.5.7 The rrecs Function
  1199.  
  1200. Synopsis
  1201.  
  1202.      #include <recio.h>
  1203.      char *rrecs(REC *rp);
  1204.  
  1205. Description
  1206.  
  1207. The rrecs function gets a pointer to the record buffer associated with 
  1208. the record stream pointed to by rp.  The current record is stored in the 
  1209. record buffer.  The record is terminated by a null character.
  1210.  
  1211. Returns
  1212.  
  1213. The rrecs function returns a pointer to the record buffer associated with 
  1214. the record stream pointed to by rp.
  1215.  
  1216.  
  1217. 1.5.8 The rrecno Function
  1218.  
  1219. Synopsis
  1220.  
  1221.      #include <recio.h>
  1222.      long rrecno(REC *rp);
  1223.  
  1224. Description
  1225.  
  1226. The rrecno function gets the number of records that have been read from 
  1227. the record stream pointed to by rp.
  1228.  
  1229. Returns
  1230.  
  1231. The rrecno function returns the number of records that have been read from 
  1232. the record stream pointed to by rp.
  1233.  
  1234.  
  1235. 1.5.9 The rsetbegcolno Function
  1236.  
  1237. Synopsis
  1238.  
  1239.      #include <recio.h>
  1240.      int rsetbegcolno(REC *rp, int colno);
  1241.  
  1242. Description
  1243.  
  1244. The rsetbegcolno function sets the first column number colno for the record 
  1245. stream pointed to by rp.  Column numbering can start at either 0 or 1.
  1246.  
  1247. If an error occurs, the error indicator for the record stream is set, the 
  1248. callback error function is called (if registered), and the rsetbegcolno 
  1249. function returns EOF.
  1250.  
  1251. Returns
  1252.  
  1253. The rsetbegcolno function returns zero if the first column number was 
  1254. successfully set, or EOF if any errors were detected.
  1255.  
  1256.  
  1257. 1.5.10 The rsetfldstr Function
  1258.  
  1259. Synopsis
  1260.  
  1261.      #include <recio.h>
  1262.      int rsetfldstr(REC *rp, char *s);
  1263.  
  1264. Description
  1265.  
  1266. The rsetfldstr function copies the string s into the field buffer of the 
  1267. record stream pointed to by rp.  Any existing string in the field buffer
  1268. is overwritten.  The field buffer size is increased, if necessary, to 
  1269. accommodate the string.  
  1270.  
  1271. A side effect of using the rsetfldstr function is that the error and 
  1272. end-of-file indicators for the record stream are cleared (provided 
  1273. rsetfldstr does not create an error).
  1274.  
  1275. If an error occurs, the error indicator for the record stream is set, 
  1276. the callback error function is called (if registered), and the rsetfldstr 
  1277. function returns EOF.
  1278.  
  1279. Returns
  1280.  
  1281. The rsetfldstr function returns zero if the string is successfully copied 
  1282. into the field buffer, or EOF if any errors were detected.
  1283.  
  1284.  
  1285. 1.6 Error-Handling Functions
  1286.  
  1287. 1.6.1 The errno Macro
  1288.  
  1289. Synopsis
  1290.  
  1291.      #include <errno.h>
  1292.  
  1293. Description
  1294.  
  1295. The errno macro "expands to a modifiable lvalue that has type int, the
  1296. value of which is set to a positive error number by several library
  1297. functions." -Section 4.1.3 of ANSI X3.159-1989.
  1298.  
  1299.      
  1300. 1.6.2 The rclearerr Function
  1301.  
  1302. Synopsis
  1303.  
  1304.      #include <recio.h>
  1305.      void rclearerr(REC *rp);
  1306.  
  1307. Description
  1308.  
  1309. The rclearerr function clears the end-of-file and error indicators for
  1310. the record stream pointed to by rp.
  1311.  
  1312. Returns
  1313.  
  1314. The rclearerr function returns no value.
  1315.  
  1316.  
  1317. 1.6.3 The rcxtno Function
  1318.  
  1319. Synopsis
  1320.  
  1321.      #include <recio.h>
  1322.      int rcxtno(REC *rp);
  1323.  
  1324. Description
  1325.  
  1326. The rcxtno function gets the context number from the record stream pointed 
  1327. to by rp.  Context numbers can be assigned to a record stream using the 
  1328. rsetcxtno function.  A zero context number indicates that the context 
  1329. number has not been assigned.  The recin stream returns the macro value 
  1330. of RECIN.
  1331.  
  1332. Returns
  1333.  
  1334. The rcxtno function returns the context number from the record stream pointed 
  1335. to by rp.
  1336.  
  1337.  
  1338. 1.6.4 The reof Function
  1339.  
  1340. Synopsis
  1341.  
  1342.      #include <recio.h>
  1343.      int reof(REC *rp);
  1344.  
  1345. Description
  1346.  
  1347. The reof function tests the end-of-file indicator for the record stream
  1348. pointed to by rp.
  1349.  
  1350. Returns
  1351.  
  1352. The reof function returns nonzero if and only if the end-of-file indicator
  1353. is set for the record stream pointed to by rp.
  1354.  
  1355.  
  1356. 1.6.5 The rerror Function
  1357.  
  1358. Synopsis
  1359.  
  1360.      #include <recio.h>
  1361.      int rerror(REC *rp);
  1362.  
  1363. Description
  1364.  
  1365. The rerror function tests the error indicator for the record stream
  1366. pointed to by rp.
  1367.  
  1368. Returns
  1369.  
  1370. The rerror function returns nonzero if and only if the error indicator
  1371. is set for the record stream pointed to by rp.
  1372.  
  1373.  
  1374. 1.6.6 The rerrstr Function
  1375.  
  1376. Synopsis
  1377.  
  1378.      #include <recio.h>
  1379.      char *rerrstr(REC *rp);
  1380.  
  1381. Description
  1382.  
  1383. The rerrstr function gets the error message for the record stream pointed 
  1384. to by rp.  The text of the error message is implementation dependent.
  1385.  
  1386. Returns
  1387.  
  1388. The rerrstr function returns a pointer to a string containing an error 
  1389. message.
  1390.  
  1391.  
  1392. 1.6.7 The risvalid Function
  1393.  
  1394. Synopsis
  1395.  
  1396.      #include <recio.h>
  1397.      int risvalid(REC *rp);
  1398.  
  1399. Description
  1400.  
  1401. The risvalid function tests if rp is a valid pointer to a record stream.
  1402.  
  1403. Returns
  1404.  
  1405. The risvalid function returns a nonzero value if and only if rp is a 
  1406. valid pointer to an open record stream.
  1407.  
  1408.  
  1409. 1.6.8 The rsetcxtno Function
  1410.  
  1411. Synopsis
  1412.  
  1413.      #include <recio.h>
  1414.      int rsetcxtno(REC *rp, int cxtno);
  1415.  
  1416. Description
  1417.  
  1418. The rsetcxtno function sets the context number cxtno on the record stream 
  1419. pointed to by rp.  Assigning a context number allows a file format to be more 
  1420. easily identified in the callback error function.  Negative context numbers 
  1421. are reserved; a zero context number indicates an that the context has not 
  1422. been assigned.  A macro value RECIN is preassigned to the recin stream.
  1423.  
  1424. If an error occurs, the rsetcxtno function returns EOF.
  1425.  
  1426. Returns
  1427.  
  1428. The rsetcxtno returns zero if the context number was successfully assigned
  1429. to the record stream, or EOF if any errors were detected.
  1430.  
  1431.  
  1432. 1.6.9 The rseterr Function
  1433.  
  1434. Synopsis
  1435.  
  1436.      #include <recio.h>
  1437.      int rseterr(REC *rp, int errnum);
  1438.  
  1439. Description
  1440.  
  1441. The rseterr function sets the global error number errno to the value of 
  1442. errnum if the record stream pointed to by rp is null.  If rp points to 
  1443. a valid record stream, the rseterr function sets the error indicator on 
  1444. the record stream.  The callback error function is called (if registered).  
  1445. If the record stream error indicator is already set on entry to the rseterr 
  1446. function, the rseterr function does nothing.
  1447.  
  1448. Returns
  1449.  
  1450. The rseterr function returns the error number.  If the callback error 
  1451. function corrects the error and clears the error number, the function 
  1452. returns zero.
  1453.  
  1454.  
  1455. 1.6.10 The rseterrfn Function
  1456.  
  1457. Synopsis
  1458.  
  1459.      #include <recio.h>
  1460.      void rseterrfn(void(*rerrfn)(REC *rp));
  1461.  
  1462. Description
  1463.  
  1464. The rseterrfn function registers the callback error function rerrfn for the 
  1465. record stream pointed to by rp.
  1466.  
  1467. Returns
  1468.  
  1469. The rseterrfn function returns no value.  The callback error function rerrfn 
  1470. returns no value.
  1471.  
  1472.  
  1473. 1.6.11 The rstrerror Function
  1474.  
  1475. Synopsis
  1476.  
  1477.      #include <recio.h>
  1478.      char *rstrerror(int errnum);
  1479.  
  1480. Description
  1481.  
  1482. The rstrerror function maps the error number in errnum to an error 
  1483. message string.  The error number and the text of the error message 
  1484. are implementation dependent.  (To map errno to an error string, use 
  1485. the strerror function.)  
  1486.  
  1487. Returns
  1488.  
  1489. The rstrerror function returns a pointer to a string containing an
  1490. error message.
  1491.  
  1492.  
  1493.  
  1494. 2.0 PORTABILITY ISSUES
  1495.  
  1496. The first six characters of this function are common to another function. 
  1497. Ref 3.1.2 of ANSI X3.159-1989.  (1.2.1, 1.2.2, 1.2.4, 1.3.3, 1.3.4, 1.3.13, 
  1498. 1.4.1-1.4.4, 1.4.11, 1.4.12, 1.5.10, 1.6.9, 1.6.10)
  1499.  
  1500.  
  1501.  
  1502. 3.0 REFERENCES
  1503.  
  1504. 1. ANSI X3.159-1989, "American National Standard for Information Systems -
  1505.    Programming Language - C," American National Standards Institute, 
  1506.    11 West 42nd Street, New York, NY 10036, 1990.
  1507.  
  1508.  
  1509. 4.0 INDEX
  1510.  
  1511. errno macro ............ 1.6.1
  1512. FLDBUFSIZ macro ........ 1.1.3, 1.2.4
  1513. rbegcolno function ..... 1.5.1, 1.5.6
  1514. rbgeti function ........ 1.3.1
  1515. rbgetl function ........ 1.3.2
  1516. rbgetui function ....... 1.3.3
  1517. rbgetul function ....... 1.3.4
  1518. rcbgeti function ....... 1.4.1
  1519. rcbgetl function ....... 1.4.2
  1520. rcbgetui function ...... 1.4.3
  1521. rcbgetul function ...... 1.4.4
  1522. rcgetc function ........ 1.4.5
  1523. rcgetd function ........ 1.4.6
  1524. rcgetf function ........ 1.4.7
  1525. rcgeti function ........ 1.4.8
  1526. rcgetl function ........ 1.4.9
  1527. rcgets function ........ 1.4.10
  1528. rcgetui function ....... 1.4.11
  1529. rcgetul function ....... 1.4.12
  1530. rclearerr function ..... 1.6.2
  1531. rclose function ........ 1.2.1
  1532. rcloseall function ..... 1.2.2
  1533. rcolno function ........ 1.5.2
  1534. rcxtno function ........ 1.6.3
  1535. REC object ............. 1.1.2
  1536. recin expression ....... 1.1.4
  1537. RECBUFSIZ macro ........ 1.1.3, 1.2.5
  1538. RECFLDCH macro ......... 1.1.3, 1.3.13
  1539. RECTXTCH macro ......... 1.1.3, 1.3.14
  1540. reof function .......... 1.6.4
  1541. rerror function ........ 1.6.5
  1542. rerrstr function ....... 1.6.6
  1543. rflds function ......... 1.5.3
  1544. rfldno function ........ 1.5.4
  1545. rgetc function ......... 1.3.5
  1546. rgetd function ......... 1.3.6
  1547. rgetf function ......... 1.3.7
  1548. rgeti function ......... 1.3.8
  1549. rgetl function ......... 1.3.9
  1550. rgetrec function ....... 1.5.6
  1551. rgets function ......... 1.3.10
  1552. rgetui function ........ 1.3.11
  1553. rgetul function ........ 1.3.12
  1554. risvalid function ...... 1.6.7
  1555. rnames function ........ 1.5.5
  1556. ropen function  ........ 1.2.3
  1557. ROPEN_MAX macro ........ 1.1.3
  1558. rrecs function ......... 1.5.7
  1559. rrecno function ........ 1.5.8
  1560. rsetbegcolno function .. 1.5.6, 1.5.9
  1561. rsetcxtno function ..... 1.6.8
  1562. rseterr function ....... 1.6.9
  1563. rseterrfn function ..... 1.6.10
  1564. rsetfldch function ..... 1.3.13
  1565. rsetfldsiz function .... 1.2.4
  1566. rsetfldstr function .... 1.5.10
  1567. rsetrecsiz function .... 1.2.5
  1568. rsettxtch function ..... 1.3.14
  1569. rskipfld function  ..... 1.3.15
  1570. rskipnfld function ..... 1.3.16
  1571. rstrerror function ..... 1.6.11
  1572.