IOS_$PUTP                         Domain/OS                          IOS_$PUTP


NAME
     ios_$putp - write to an object, returning amount written

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

     long ios_$putp(
          ios_$id_t &stream_id,
          ios_$put_get_opts_t &put_options,
          char *put_buffer,
          long &buffer_size,
          status_$t *status)

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

     function ios_$putp(
          in stream_id: ios_$id_t;
          in put_options: ios_$put_get_opts_t;
          in put_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 nbytes
           parameter (nbytes = 128)

           integer*2 stream_id, put_options
           integer*4 buffer_size, status, bytes_written
           character put_buffer*(nbytes)

           bytes_written = ios_$putp(stream_id, put_options,
          &                          put_buffer, buffer_size, status)

DESCRIPTION
     Ios_$putp writes up to buffer_size bytes from put_buffer to the object
     open on stream_id.  It returns the number of bytes written.  The number
     of bytes written will always be 0 or the number of bytes requested unless
     the calling program specifies the ios_$partial_ok_opt put option.

     stream_id
          The ID of the stream on which the object is open.

     put_options
          The options to use when writing to an object.  Specify a combination
          of the following:

          ios_$cond_opt
               Write only if the stream can accept the data immediately.  If
               the stream is full and the call would be blocked, ios_$putp
               returns with the ios_$put_conditional_failed error code in
               status.

          ios_$no_put_get_opts
               Write the next record.  If the stream cannot accept the next
               record, then wait until it can.  This is the default and is
               included for languages that lack Pascal set types.  It is
               equivalent to specifying [] in Pascal.

          ios_$partial_ok_opt
               If the number of bytes requested cannot be written, write as
               many bytes  as possible.  This option overrides the default,
               which is to write no data unless all the data requested can be
               written.

          ios_$partial_record_opt
               The contents of put_buffer is a partial record.  Unless this
               option is specified, ios_$putp assumes that the data in
               put_buffer completes the current record and terminates the
               record before returning.  With ios_$partial_record_opt speci-
               fied, ios_$putp writes the contents of put_buffer to the object
               but leaves the current record unterminated.  If the object open
               on stream_id is not record oriented ios_$putp ignores this
               option.

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

     put_buffer
          The data to write to the object.

     buffer_size
          The number of bytes in put_buffer.

     status
          The completion status.

SEE ALSO
     ec2_$wait_slow_io, ios_$get_ec, ios_$put.