Procedure

   void rdtext_c ( ConstSpiceChar * file,
                   SpiceInt         lenout,
                   SpiceChar      * line,
                   SpiceBoolean   * eof    )

Abstract

   Read the next line of text from a text file.

Required_Reading

   None.

Keywords

   FILES
   TEXT

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  ---------------------------------------------------
   file       I   Name of text file.
   lenout     I   Available room in output line.
   line       O   Next line from the text file.
   eof        O   End-of-file indicator.

Detailed_Input

   file        is the name of the text file from which the next
               line is to be read. If the file is not currently
               open, it is opened with a logical unit determined
               at run time, and the first line of the file is
               returned. Otherwise, the next line not yet read
               from the file is read and returned.
               
   lenout      is the available room in the output line, including
               the terminating null.  If the maximum expected length
               of an output line is N, lenout should be at least N+1.

Detailed_Output

   line        is next line of text in the specified file.
               If the end of the file is reached, LINE is blank.

   eof         is true when the end of the file is reached, and is
               otherwise false.

Parameters

   None.

Exceptions

   1) If too many files are open already, the error
      SPICE(TOOMANYFILESOPEN) is signaled.

   2) If the attempt to open the file fails, the error
      SPICE(FILEOPENFAILED) is signaled.

   3) If the attempt to read from the file fails, the error
      SPICE(FILEREADFAILED) is signaled.

   4) If the attempt to "inquire" the status of the file fails,
      the error SPICE(INQUIREFAILED) is signaled.

Files

   See input FILE.

Particulars

   rdtext_c reads the next line from a text file. If the file is
   not currently open, it is opened with a logical unit determined
   at run time, and the first line of the file is returned.
   Otherwise, the next line not yet read from the file is returned.

   If the end of the file is reached, an empty line is returned,
   the end-of-file indicator is true, and the file is closed.

   Several files may be opened and read simultaneously. Thus,
   you may begin reading from one file before the end of another
   file has been reached. rdtext_c maintains a separate file pointer
   for each file.

Examples

   Let FILE.1 contain the following lines.

      Mary had a little lamb
      Everywhere that Mary went

   Let FILE.2 contain the following lines.

      Its fleece was white as snow.
      The lamb was sure to go.

      Note:  You do not what and end-of-file on the same line as
      text.  That text will be ignored.


   Then the code fragment

   #include "SpiceUsr.h"
   #define LENOUT 32

   main(void)
      {

      SpiceBoolean eof;
      SpiceChar    line[LENOUT];

      eof = SPICEFALSE;

      do {
         rdtext_c ( "file.1", LENOUT, line, &eof );
         printf ( "%s \n", line );

         rdtext_c ( "file.2", LENOUT, line, &eof );
         printf ( "%s \n", line );
         }
      while ( !eof );

      }

   produces the following output

      Mary had a little lamb
      Its fleece was white as snow.
      Everywhere that Mary went
      The lamb was sure to go.

Restrictions

   None.

Literature_References

   None.

Author_and_Institution

   N.J. Bachman    (JPL)
   H.A. Neilan     (JPL)
   M.J. Spencer    (JPL)
   I.M. Underwood  (JPL)

Version

   -CSPICE Version 2.0.0, 07-OCT-1999   (NJB)

      Changed argument list to conform to SPICE convention:  LENOUT
      now precedes the output string.
      
      Added description of lenout to the header.
      
      Added local logical variable for EOF flag.
      
   -CSPICE Version 1.0.0, 25-MAY-1999   (EDW)

Index_Entries

   read a line from a text file

Link to routine rdtext_c source file rdtext_c.c