gtpc2m7a | C/C++ Language Support User's Guide |
This function performs one of the four above commands related to tape
positioning and tape buffer control.
Format
#include <tpftape.h>
int tape_cntl(const char *name, enum t_cntl command, ...);
- name
- This argument is a pointer to type char, which must be a
3-character string identifying the tape to be acted upon. This function
can only be called for a general tape.
- command
- The action to be performed on the specified general tape. The
argument must belong to the enumeration type t_cntl, defined in
tpftape.h. Specify one of the following:
- CNTL_FSB
- Forward space block. This causes the tape to be moved in the
forward direction a specified number of physical blocks. Note that for
a blocked tape, a single physical block may represent more than one logical
record.
- CNTL_FSR
- Forward Space Record. This causes the tape to be forward spaced by
a specified number of records (blocks).
Two additional parameters are required for Forward Space Block. The
first is a valid data level from the enumeration type t_lvl,
expressed as Dx, where x represents the hexadecimal number
of the level (0-F). The FARW on this data level is modified by
the CNTL_FSB subfunction.
The second parameter must be an integer specifying the number of physical
blocks to be forward spaced.
- CNTL_BSB
- Backward space block. This causes the tape to be moved in the
backward direction a specified number of physical blocks. Note that for
a blocked tape, a single physical block may represent more than one logical
record. Two additional parameters are required for Backward Space
Block. The first is a valid data level from the enumeration type
t_lvl, expressed as Dx, where x represents the
hexadecimal number of the level (0-F). The FARW on this data
level is modified by the CNTL_BSB subfunction.
The second parameter is an integer specifying the number of physical blocks
to be backward spaced.
- CNTL_REW
- Rewind. This causes the tape to be positioned at the first record
of the current volume, or optionally, at the first record on the first volume
in a multi-volume tape data set.
Code the predefined term FALLBACK to rewind to the first record
on the first volume of a multi-volume data set, or code the defined term
NO_FALLBACK to rewind to the first record on the currently mounted
volume. Either value may be coded on a single volume data set.
- CNTL_FLUSH
- Flush tape buffer(s). For output tapes, this command causes any
write data in the tape buffers (the control unit buffer and/or host buffer) to
be written to the tape.
This function requires between two and four arguments, which depend on the
term coded for command.
Normal Return
Integer value of zero.
Error Return
Nonzero integer contents of CE1SUG.
Programming Considerations
- The specified tape must have been opened using tape_open and
must NOT be currently assigned to the issuing ECB. On completion of
this function, the tape is left in the reserved state, making it
available for use by any ECB.
- The specified tape must be currently mounted and ready.
- This function calls the equivalent of waitc. To ensure
consistent results it is recommended that an explicit waitc
function be coded prior to the call to tape_cntl to ensure that
errors for other I/O operations are not reflected in the function return
value.
- The CNTL_FLUSH command has no effect on tapes opened for
input. If any hardware errors (or end of volume) occur during the
buffer flush operation, an automatic switch to the next volume occurs.
- The FALLBACK/NO_FALLBACK options have no meaning for
single-volume tape data sets.
Examples
The following example flushes the write buffer, rewinds, and positions the
VPH tape (already opened) at the fourth physical block. The program
checks that the CNTL_FSB request completed successfully before
continuing.
#include <tpftape.h>
·
·
·
tape_cntl("VPH", CNTL_FLUSH);
tape_cntl("VPH", CNTL_REW, FALLBACK);
if (tape_cntl("VPH", CNTL_FSB, D6, 3))
{
serrc_op(SERRC_EXIT,0x1234,"ERROR ON VPH TAPE",NULL) ;
}
.
.
.
Related Information