ios_dup() — Apollo

IOS_$DUP                          Domain/OS                           IOS_$DUP


NAME
     ios_$dup - duplicate a stream

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

     ios_$id_t ios_$dup(
          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_$dup(
          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_$dup(old_stream_id,
          &                            new_stream_id, status)

DESCRIPTION
     Ios_$dup copies an existing stream open on old_stream_id onto another
     stream ID.  The stream ID returned by ios_$dup refers to the same connec-
     tion as the stream ID passed in old_stream_id.  Note that the stream must
     be closed via both stream IDs before the connection actually closes.
     Also, ios_$dup 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.

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

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

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

     status
          The completion status.

NOTES
     Ios_$dup is identical to ios_$replicate except that ios_$dup looks for an
     available stream ID in ascending order from the preferred stream ID,
     while ios_$replicate looks in descending order.  Both ios_$dup and
     ios_$replicate 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
