Programming Guide

sm_fio_gets

Reads a line from a file 

char *sm_fio_gets(int file_stream, int maxlen);

file_stream
A handle to the required file stream, obtained by sm_fio_open.

maxlen
The number of bytes to read.

Returns

Description

sm_fio_gets reads maxlen bytes from the current line in file_stream or to the end of the line and returns that string. If the current line is shorter than maxlen, sm_fio_gets only reads up to the end of the line. If the current line is longer than maxlen, the function returns only maxlen characters and sets the error code to SMFIO_LINE_BREAK. The next read operation on this file stream by sm_fio_gets continues where the last read ended. This function strips newline characters before reading it into the return value.

If the read operation fails, the function returns an empty string and sets the appropriate error code. You can get this error code by calling sm_fio_error. Because an empty string can also be a valid return value—for example, the file stream contains a blank line—you should interleave calls to sm_fio_gets with calls to sm_fio_error to determine whether an error condition exists and to ascertain its nature. sm_fio_gets can set one of these error codes:

SMFIO_INVALID_HANDLE

Invalid file handle.

SMFIO_HANDLE_CLOSE

Handle points to closed file.

SMFIO_EOF

Already at end of file.

SMFIO_IO_ERROR

Standard I/O error. Check the value in system variable errno to determine the nature of the error.

SMFIO_LINE_BREAK

The line is longer than maxlen characters.

Note: Because the same error code variable is shared by all JPL file I/O routines, you should call sm_fio_error before calling any other I/O library functions.

Example

/* Write the contents of an ASCII file to a single- *
	 * line text array. The file stream handle was      *
	 * obtained earlier by a call to sm_fio_open()      *
	 */

proc getStr()
	{
	  vars str, occurNo, err, fileStream, maxOccurs  
	  call sm_fio_error_set(0)

  /* get array size */
	  maxOccurs = @widget("comments")->max_occurrences

  /* get file stream handle sent from previous dialog */
	  receive BUNDLE f_handle DATA fileStream

  /* loop through array occurrences */
	  for occurNo = 1 && err = 0 \
	      while (err == 0 && occurNo <= maxOccurs)
	  {
	     /* get the next string in file stream */
	     str = sm_fio_gets(fileStream, 32)

     /* check for error condition like EOF */
	     if (str == "")
	     {
	        err = sm_fio_error()
	     }
	     /* read string into occurrence */
	     comments[occurNo] = str
	  }

  /* close the file stream when done */
	  call sm_fio_close(fileStream)
	  return
	}