ios_switch() — Apollo

IOS_$SWITCH                       Domain/OS                        IOS_$SWITCH


NAME
     ios_$switch - switch a stream to another ID

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

     ios_$id_t ios_$switch(
          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_$switch(
          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 ret_stream_id, old_stream_id, new_stream_id
           integer*4 status

           ret_stream_id = ios_$switch(old_stream_id, new_stream_id, status)

DESCRIPTION
     Ios_$switch relabels the stream on old_stream_id with the stream ID it
     returns.  On a successful return from ios_$switch, the old stream ID
     passed in old_stream_id is no longer valid.

     old_stream_id
          The ID of the stream to switch.  When ios_$switch returns success-
          fully, old_stream_id is no longer valid.

     new_stream_id
          The preferred new ID for the stream.  If new_stream_id is available,
          ios_$switch returns it as the new ID for the stream; otherwise,
          ios_$switch begins searching from that value downward (to lower
          numbers) until it finds a free 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_$switch to
          begin searching at the highest possible stream ID and return the
          first available stream ID it finds.

     status
          The completion status.

NOTES
     Ios_$switch relabels a stream with a new ID, leaving the old ID invalid.
     Use ios_$replicate and ios_$dup to copy streams onto new IDs, leaving the
     old stream IDs still valid.
Museum
