Museum

IOS_$GET                          Domain/OS                           IOS_$GET


NAME
     ios_$get - read data from a stream

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/ios.h>

     long ios_$get(
          ios_$id_t &stream_id,
          ios_$put_get_opts_t &get_options,
          char *get_buffer,
          long &buffer_size,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/ios.ins.pas';

     function ios_$get(
          in stream_id: ios_$id_t;
          in get_options: ios_$put_get_opts_t;
          out get_buffer: univ string;
          in buffer_size: integer32;
          out status: status_$t): integer32;

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/ios.ins.ftn'

           integer*2 buf_length
           parameter (buf_length = 128)

           integer*2 stream_id, get_options
           integer*4 ret_length, buffer_size, status
           character get_buffer*(buf_length)

           ret_length = ios_$get(stream_id, get_options, get_buffer,
          &                      buffer_size, status)

DESCRIPTION
     Ios_$get reads either the next record or up to buffer_size bytes of data
     from a stream into get_buffer then moves the stream marker to the next
     unread byte.  It returns the number of bytes written into get_buffer.

     stream_id
          The ID of the stream to read from.

     get_options
          A set of options affecting ios_$get's behavior.  Specify a combina-
          tion of the following:

          ios_$cond_opt
               Read data, if available.  If data is not available, ios_$get
               sets the completion status code to ios_$get_conditional_failed
               and returns.  For example, data on an serial I/O (SIO) line is
               not always available immediately, so ios_$cond_opt is a suit-
               able option when reading from SIO lines.

          ios_$no_put_get_opts
               Get the next record.  This is the default and is included for
               languages that lack Pascal set types.  It is equivalent to
               specifying [] in Pascal.

          ios_$no_rec_bndry_opt
               Ignore boundaries in the input stream while reading data.  The
               caller can use this option if it is not interested in any data
               groupings supported by the object type.  For example,
               ios_$no_rec_bndry_opt will cause ios_$get to ignore
               ios_$newline characters in an unstructured (uid_$unstruct)
               object.

          ios_$preview_opt
               Read data but do not update the stream marker.

     get_buffer
          A buffer to store the data read by ios_$get.

     buffer_size
          The size of get_buffer in bytes.  Ios_$get will read buffer_size or
          less bytes into get_buffer.  Unless ios_$no_rec_bndry_opt is speci-
          fied in get_options, if there are more than buffer_size bytes
          remaining in the current record, ios_$get will return a number of
          bytes read equivalent to buffer_size, and the completion status will
          indicate an ios_$buffer_too_small error.  (Ios_$inq_rec_remainder
          returns the number of bytes remaining in the current record.)

     status
          The completion status.

NOTES
     Both ios_$locate or ios_$get can access data in a stream.  Ios_$get
     copies the data into a buffer, while ios_$locate returns a pointer to the
     data.  Use the ios_$locate call to access data that is needed only once
     and not modified because ios_$locate normally does not copy the data and
     so is faster.