ios_replicate()

IOS_$REPLICATE                    Domain/OS                     IOS_$REPLICATE


NAME
     ios_$replicate - replicate a stream

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

     ios_$id_t ios_$replicate(
          ios_$id_t &old_stream_id,
          ios_$id_t &new_stream_id,
          status_$t *status)

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

     function ios_$replicate(
          in old_stream_id: ios_$id_t;
          in new_stream_id: ios_$id_t;
          out status: status_$t): ios_$id_t;

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

           integer*2 return_stream_id, old_stream_id, new_stream_id
           integer*4 status

           return_stream_id = ios_$replicate(old_stream_id,
          &                                  new_stream_id, status)

DESCRIPTION
     Ios_$replicate copies an existing stream open on old_stream_id onto
     another stream ID.  The stream ID returned by ios_$replicate refers to
     the same connection as the stream ID passed in old_stream_id.  Note that
     the stream must be closed via both stream IDs before the connection actu-
     ally closes.  Also, ios_$replicate does not create another stream marker.
     Therefore, once data is read using any valid ID for a stream, the stream
     marker has moved on, leaving the data inaccessible without a seek back to
     it.

     A parent process can use ios_$replicate to maintain a stream connection
     passed to a child process.  If the parent uses ios_$replicate to copy the
     stream and passes the returned stream ID to the child, the child cannot
     close the connection on the parent by calling ios_$close with the stream
     ID passed to it.  Even if the child calls ios_$close with the replicate
     stream ID, the connection will remain open to the parent and accessible
     via the original stream ID.

     old_stream_id
          An ID of the stream to replicate.  This stream ID remains a valid
          connection to the object after ios_$replicate returns.

     new_stream_id
          The preferred ID to copy the stream onto.  If new_stream_id is
          available, ios_$replicate returns that value; otherwise,
          ios_$replicate begins searching from that number downward (to lower
          numbers) until it finds an available stream ID to return.

          If there is no preferred value for the returned stream ID, specify
          ios_$max for new_stream_id.  A new_stream_id of ios_$max causes
          ios_$replicate to begin searching at the highest possible stream ID
          and return the first available stream ID it finds.

     status
          The completion status.

NOTES
     Ios_$replicate is identical to ios_$dup except that ios_$replicate looks
     for an available stream ID in descending order from the preferred stream
     ID, while ios_$dup looks in ascending order.  Both ios_$replicate and
     ios_$dup only copy existing streams; the old stream ID remains a valid
     connection.  Use ios_$switch to switch a connection from one stream ID to
     a new stream ID, leaving the old stream ID invalid.
Museum
