c_tpbsf - Backspaces (count) files on tape

SYNTAX

#include "tapeio.h"

FUNCTION c_tpbsf (unit, count, mode)

     long     *unit;
     long     *count;
     long     *mode;

PARAMETERS

unit (input, integer)

Unit number to be used as a reference for the drive. This number is set by c_tpopen() and should not be altered.

count (input/output, integer)

The number of files to be backspaced over. If the beginning of tape is encountered before all files are skipped, c_tpbsf() will return TAPE_BOT and count will return the number of files actually skipped. The tape will be positioned at the beginning of tape.

mode (input, integer)

A value of NO_HANDLE (0) specifies that errors are to be returned to the calling program. A value of HANDLE (1) specifies that when an error occurs the routine is to return an error to the calling program and display a message to the terminal.

DESCRIPTION

The c_tpbsf() call is used to backspace count files on a tape device. c_tpbsf() will leave the tape positioned at the beginning of the target file. Some examples of c_tpbsf() follow:

    Tape location before,              Tape location after call, 
    called with count = 1              returns TAPE_SUCC, count = 1
                |                          | 
                V                          V
  ------------------------------     ------------------------------
  |   |E|   |E|    |E|     |E|E|     |   |E|   |E|    |E|     |E|E|
  |   |O|   |O|    |O|     |O|O|     |   |O|   |O|    |O|     |O|O|
  |   |F|   |F|    |F|     |F|F|     |   |F|   |F|    |F|     |F|F| 
  ------------------------------     ------------------------------ 


    Tape location before,              Tape location after call,
    called with count = 5              returns TAPE_BOT, count = 4
                             |       |
                             V       V
  ------------------------------     ------------------------------
  |   |E|   |E|    |E|     |E|E|     |   |E|   |E|    |E|     |E|E|
  |   |O|   |O|    |O|     |O|O|     |   |O|   |O|    |O|     |O|O|
  |   |F|   |F|    |F|     |F|F|     |   |F|   |F|    |F|     |F|F|
  ------------------------------     ------------------------------

RETURN VALUE

c_tpbsf() returns

     TAPE_SUCC (0) -->  for successful completion
     TAPE_BOT  -->  beginning of tape
     TPBSF_BSF -->  device error