REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
NAME
REELexchange - commands for reading and writing IBM and ANSI
tapes
DESCRIPTION
REELexchange is a set of commands for reading and writing
IBM and ANSI tapes. The standard tape formats are defined
in:
MVS/370 Magnetic Tape Labels and File Structure
Administration Release Number: 1.1, Order Number:GC26-4064-1
ANSI Magnetic Tape Labels and File Structure for Information
Interchange ANSI X3.27-1978
REELexchange supports all aspects of the tape formats
including multiple file, multiple volume storage and the
following record/blocking schemes:
fixed length records
fixed length, blocked records
variable length records
variable length, blocked records
variable length, spanned records
variable length, blocked, spanned records
unformatted
Tape access capabilities include:
reading file(s) from tape(s);
writing file(s) to tape(s);
initial labeling of blank tapes;
record translation;
label manipulation;
This man page is divided into the following sections and
subsections:
General Guidelines
- Configuration Files
Licensed material--property of copyright holder(s) Page 1
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
- File Labels
- Volume Serial Numbers
- Tapesets
- Tape Sessions
- Record and Blocking Schemes
- Record Translation
Reading Files From a Tapeset
- Sequential File Reads
- Random File Reads
- Automatically Reading Every File
- Understanding File Labels
- Multiple Volume Tapesets
Creating Labeled Tapes
Writing Files to a Tapeset
- Setting File Labels
- Default File Labels
- Setting Record Formats
- Multiple Volume Tapesets
The REELexchange Commands
GENERAL GUIDELINES
This section includes configuration information, definition
of terminology, and other general information regarding
REELexchange.
Configuration Files
The REELexchange commands use a number of configuration
files for describing system/tape drive characteristics and
for specifying default values for certain commands. The
default directory used by REELexchange to search for
configuration files is /var/reelexchange. This default can
Licensed material--property of copyright holder(s) Page 2
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
be modified by creating an environment variable called
REELXL whose value is the name of the alternate
configuration directory. For purposes of illustration, the
directory /var/reelexchange is used throughout the remainder
of this man page since it should be the configuration
directory for the vast majority of users. Below is a list
of configuration files used by REELexchange along with a
brief description of each file.
/var/reelexchange/Adn/*
There should be one file in this directory for each tape
drive on the system. This file contains entries which
identify the type of the tape drive, tape density in bpi,
and the device-special files that it should use for I/O.
/var/reelexchange/default.adn
This file contains the name of the tape drive to use by
default for any of the REELexchange commands whenever one is
not specified via the -a option.
/var/reelexchange/tapecap
This file contains entries describing each type of tape
drive supported by REELexchange.
/var/reelexchange/tapecap /var/reelexchange/tapecap
These files, if present, contain default parameters for IBM
and ANSI labels, respectively (see below).
File Labels
IBM and ANSI tape standards include labels for each file on
tape. These labels are automatically processed during file
reads. They can also be defined for use during file writes.
The tkey command sets the labels and the tdisplay command
reports all current settings.
REELexchange has built-in defaults for file labels. These
defaults can be modified through the creation of files in
the /var/reelexchange directory. Creating a file named
d_ibm with keyword/value pairs (as described for the tkey
command) creates default settings for IBM file labels. A
file named d_ansi does the same for ANSI file labels.
Common default modifications are for expiration date and
system name. Here are example lines from a d_ibm file which
override those particular defaults:
Licensed material--property of copyright holder(s) Page 3
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
exp=12/31/1991
sys=reel1
Volume Serial Numbers
REELexchange requires that each tape be identified by its
Volume Serial Number (VSN). The VSN is a six character name
encoded on the tape. When a tape session is started, the
user must provide the tape's VSN. REELexchange then reads
the tape to verify that the mounted tape does indeed possess
the named VSN.
If a tape's VSN is unknown, the tlabel command can determine
it. Mount the tape and issue the command:
$ tlabel -r
Tapesets
The term tapeset is used throughout this man page. A
tapeset is one or more individual tapes that are considered
one logical tape. That is, tapes can be grouped together
and considered to be one continuous tape. The tapes in the
tapeset are ordered from one to n , where n is the number of
tapes in the group.
Tapes are also referred to as volumes. Therefore, a
multiple volume tapeset is a tapeset consisting of two or
more tapes.
When dealing with multiple volume tapesets, order must be
maintained for the tape data to be correctly accessed. The
taccess command, as described later, maintains tape
ordering.
Tape Sessions
A tape session consists of mounting a tape, reading and/or
writing the tape, and unmounting the tape. REELexchange
requires that the taccess command be run when starting a
tape session and the trelease command be run when finishing
a tape session.
The use of these two commands is described later in this man
page. The following subsections describe tape session
scenarios where taccess and tread are used with each and
every session.
Licensed material--property of copyright holder(s) Page 4
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
Record and Blocking Schemes
REELexchange supports all record and blocking schemes: fixed
and variable length records, fixed block, spanned block,
etc. Read operations automatically detect and process the
formatting of each file. For writing files, these formats
can be defined for each file.
See tkey and tdisplay man pages for more detailed
information.
Record Translation
One of the difficulties of reading/writing IBM and ANSI
tapes on a UNIX system is translating between IBM/ANSI
records and UNIX data. The difficulty arises from the fact
that the UNIX operating system does not support records. On
UNIX, the notion of a record only has meaning to
applications. For example, the program vi considers a
record to be all the characters it finds between the ASCII
character '\n' (newline); database applications define
records to be arbitrary fixed or variable length chunks of
data.
When REELexchange is reading or writing a file, it cannot
guess the most appropriate way to do record translation.
The tkey command provides special keys to control how record
translation is done.
The keyword pchar is used to define the ASCII character
REELexchange should use for padding and unpadding records.
pchar may be assigned any octal constant (3 octal digits) or
the value "none" which disables pad character processing.
Pad character processing only affects fixed length record
formats. REELexchange adds pad characters to records shorter
than the current record length when writing tape files and
removes trailing pad characters from records while reading
tape files.
WARNING: Interaction of pchar and tchar may result in the
loss of some characters in a text file. For example, if
pchar =' ' (space) and tchar ='\n' (newline), and if a text
file contains consecutive spaces before the newline
character, then those spaces will be lost after the file is
written to a tape and retrieved back to disk later. This is
because the consecutive space characters are regarded as
padding characters and are stripped off in the unpadding
process when retrieving from the tape.
The keyword tchar is used to define the ASCII character
Licensed material--property of copyright holder(s) Page 5
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
REELexchange should use to delimit records. When writing a
tape file, twrite uses tchar to determine record boundaries
in the input stream. tchar should be specified when creating
tapes that use variable length record formats.
The keyword conv controls whether data is converted from/to
EBCDIC before it is read/written to tape. conv=ebcidic
implies that the tape contains EBCDIC data. conv=none
implies no conversion (tape contains ASCII data).
The tdisplay command may be used to display the current
setting of the translation keywords. An example of the
output generated by tdisplay -t is shown below:
Translation processing:
Key Value
--- -----
pchar 40 (octal)
tchar 12 (octal)
conv none
See the subsection entitled Setting Record Formats for
further information.
READING FILES FROM A TAPESET
Reading files from tape is accomplished via the tread
command. Files can be read and placed directly in UNIX
files or they can be directed to standard output (stdout).
The tread command automatically adjusts for the formatting
scheme of each file and translates incoming records
according to the settings made via the tkey command. A look
at an example shows how simple it is to read in files from a
labeled tape.
Sequential File Reads
EXAMPLE A
In this example, a single IBM labeled, 1600 bpi, 2400 feet
long tape with VSN 000001 contains three data files which
are to be read into UNIX files. The computer system has a
single nine-track taped drive identified to REELexchange as
the default drive. To begin the session, issue the command:
$ taccess -v000001 -d1600 -f2300
The taccess command identifies the tape to REELexchange. It
must be the first command issued before any other
REELexchange commands can be used on the tape.
Licensed material--property of copyright holder(s) Page 6
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
To read the first file, issue this command:
$ tread >file1
This command reads the first file on the tape and places it
in the UNIX file, file1. The tape is automatically
positioned to the beginning of the second file, so to read
the second file issue the command:
$ tread >file2
The third file can then be read with the same command
modified to put the data in file3. Terminate the session
with the command:
$ trelease
Random File Reads
The tposn command allows files to be read in any order from
the tape. It positions the tape to the start point of any
file on the tape. In the preceding Example A, the second
file on the tape could have been read first by using the
command:
$ tposn -r -n2
Tape files are numbered according to their order on the tape
beginning with the first file at number 1. The second file
is number 2, etc.
Automatically Reading Every File
EXAMPLE B
In this example, a tape contains an unknown number of files
all of which need to be read into UNIX files. Below is a
UNIX shell (bourne shell) script which automatically reads
in all files and puts them into files numbered from 1 to n
where n is the number of files on the tape. To use the
script, edit a UNIX file to contain only this text:
FILENO=1
while ( tread > $FILENO )
do
FILENO=`expr $FILENO + 1`
done
rm $FILENO
Understanding File Labels
Licensed material--property of copyright holder(s) Page 7
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
Each tape has file labels which contain descriptive
information about each file and its contents. REELexchange
makes file label information available via the tdisplay
command. To display the label information of the file at
the current tape position, use the command:
$ tdisplay -r
Here is a sample of a report generated by this command:
Read labels
Key Value Field Name
--- ----- ----------
VOL: ... 000000 Volume Serial Number
own test_own Owner Name and Address Code
HDR1: fid test_fid Data Set Identifier
... 000000 Data Set Serial Number
... 1 Volume Seqence Number
... 1 Data Set Sequence Number
gen 100 Generation Number
genv 50 Version Number
cre 1/1/91 Creation Date
exp 1/1/92 Expiration Date
acc 1 Data Set Security
... 0 Block Count
sys test_sys System Code
HDR2: fmt V Record Format (vbs)
blen 40 Block Length
rlen 100 Record Length
... 3 Tape Density
... 0 Data Set Position
job test_job Job Step Identification
cc A Control Character
bat R Block Attribute
devid test_did Reserved (device id)
cpid C Checkpoint Data Set ID
When writing a file to tape, these labels can be configured
as needed. See the subsection entitled Setting File Labels.
Multiple Volume Tapesets
Reelexchange handles multi-volume tapesets simply. The -v
option of the taccess command takes an ordered list of VSNs
(volume serial numbers) which represents the tapes in the
order they belong to the tapeset. The first tape in the
group should be mounted before executing taccess. As other
tapes in the group need to be mounted, REELexchange prompts
for the appropriate unmount and mount. The prompts appear
as:
Licensed material--property of copyright holder(s) Page 8
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
Please mount 000002 on tape0
Hit <cr> when complete
CREATING LABELED TAPES
To label a tape, mount it and issue the tlabel command. For
example, to label an IBM tape you might issue the command:
$ tlabel -d1600 -lIBM -v000001
Where -d1600 indicates 1600 bpi density, -lIBM indicates IBM
format, and -v0000001 indicates the volume serial number
(VSN) is 000001. See tlabel(1) for more information.
WRITING FILES TO A TAPESET
The command twrite allows a UNIX file to be written on a
tape file. twrite writes file labels and then reformats the
UNIX file into tape records. Both the labels and records
are constructed according to configurable parameters.
As with tread , the twrite command can only be used
following an initial taccess command. Moreover, it is
important to position the tape correctly before writing a
file. The tposn command is used to position the tape before
files are written.
EXAMPLE C
Consider the example where a labeled (IBM) but empty tape is
the destination for three UNIX files. The first step is to
start the tape session by mounting the tape and issuing the
command:
$ taccess -v000001 -d1600 -f2350
The UNIX files are named data1, data2, and data3. To write
data1 to tape:
$ tposn -w -n1 $ twrite < data1
The first command positions the tape for writing at the
beginning of the first tape (file number 1). The second
command actually performs the file write. To write the
second and third files:
$ twrite < data2 $ twrite < data3
To close the session, use the trelease command.
As mentioned before, current label information and record
Licensed material--property of copyright holder(s) Page 9
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
formats are used to create appropriate tape labels as each
file is written. The next two subsections describe what
labels and formats are and how to modify them.
Setting File Labels
Each tape file has labels. When a file is written to tape,
REELexchange uses the current values of its internal label
variables to create the appropriate tape labels. The tkey
command is used to set the label variables. Their current
values are summarized by the tdisplay command.
IBM tape file labels are reported by tdisplay in this
format:
Write labels
Key Value Field Name
--- ----- ----------
VOL: ... 000000 Volume Serial Number
own test_own Owner Name and Address Code
HDR1: fid test_fid Data Set Identifier
... 000000 Data Set Serial Number
... 1 Volume Seqence Number
... 1 Data Set Sequence Number
gen 100 Generation Number
genv 50 Version Number
cre 1/1/91 Creation Date
exp 1/1/92 Expiration Date
acc 1 Data Set Security
... 0 Block Count
sys test_sys System Code
HDR2: fmt V Record Format (vbs)
blen 40 Block Length
rlen 100 Record Length
... 3 Tape Density
... 0 Data Set Position
job test_job Job Step Identification
cc A Control Character
bat R Block Attribute
devid test_did Reserved (device id)
cpid C Checkpoint Data Set ID
ANSI tape labels are reported by tdisplay in this format:
Write labels
Key Value Field Name
--- ----- ----------
VOL: ... 000000 Volume Serial Number
acc Volume accessibility
Licensed material--property of copyright holder(s) Page 10
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
own Owner Identifier
HDR1: fid File Identifier
... 000000 File Set Identifier
... 1 File Section Number
... 1 File Sequence Number
gen 0 Generation Number
genv 0 Version Number
cre 1/1/1991 Creation Date
exp 1/1/2001 Expiration Date
facc File accessibility
... 0 Block Count
sys System Code
HDR2: fmt F Record Format
blen 800 Block Length
rlen 80 Record Length
usr User Data
... 0 Buffer-Offset
Label fields are modified with the tkey command. tkey
recognizes the "key" names listed by tdisplay. (Note the key
value "..." indicates a field maintained by REELexchange
only--the user cannot set the field's value). For example,
to set the Generation Number to 5, use this command:
$ tkey gen=5
To change both the Generation Number and the Expiration
Date:
$ tkey gen=5 exp=12/31/1999
File label settings can be grouped into a file, one
parameter per line and read by tkey with the -f option:
$ tkey -f/usr/data/label_settings
Where the file /usr/data/label_settings can contain entries
of this type:
gen=5
exp=12/31/1999
Default File Labels
REELexchange uses default values for the file label
parameters. Sites may establish different defaults via
d_ibm (for IBM tapes) and d_ansi (for ANSI tapes) files
located in the /var/reelexchange directory. The built-in
default values are:
IBM ANSI
Licensed material--property of copyright holder(s) Page 11
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
--- ----
own="" own=""
fid="" acc=""
gen=0 fid=""
genv=0 gen=0
cre=current_date genv=0
exp=1/1/2001 cre=current_date
acc=0 exp=1/12001
sys="" facc=''
fmt=F fmt=F
blen=800 blen=800
rlen=80 rlen=80
job="" usr1=""
cc=''
bat=""
devid=""
cpid=''
Setting Record Formats
REELexchange supports all record formats for both IBM and
ANSI standards.
The IBM record format may be set one of two ways. The first
is by setting the fmt and bat label fields to legal values
describing the desired record format (values are defined by
the IBM standard). The second, and preferred way, is by
using a special tkey keyword rfmt. Legal values for rfmt and
the record formats they imply are:
u - unformatted
f - fixed length records
fb - fixed length blocked records
v - variable length records
vb - variable length blocked records
vs - variable length spanned records
vbs - variable length block spanned records
rfmt changes the value of the fmt and bat keywords to the
appropriate values for the given record format. The current
value of rfmt is displayed by tdisplay at the end of the
line for the fmt key.
The ANSI record format is set using the tkey keyword fmt.
Legal values for fmt and the record formats they imply are:
F - fixed length records
D - variable length records
S - spanned records
See subsection entitled Record Translation for more
Licensed material--property of copyright holder(s) Page 12
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
information.
Multiple Volume Tapesets
REELexchange can write to multi-volume tapesets. When
beginning a session where a tapeset will consume more than
one tape volume, list several labeled tapes on the opening
taccess command. List AT LEAST as many tapes as will be used
during the session. For example:
$ taccess -v0000001,0000002,0000003 -d1600 -f2350
WARNING: If too few tapes are listed and an attempt is made
to write or read past the end of the last tape, REELexchange
will abort the access session and the entire session may
have to be repeated.
When twrite comes to the end of the first tape, it prompts
for the second tape in the list to be mounted. It does the
same at the end of the second tape, prompting for the third
tape. This process continues until the session is closed
with the trelease command, or until it runs out of tapes.
Should this happen, twrite signals the condition and fails
to write the last file:
twrite: Error, nextvol ran off end of volume list
THE REELEXCHANGE COMMANDS
This section gives a brief description of each of the
REELexchange commands. For a formal description of command
syntax, refer to the man page for the command in question.
taccess
The taccess command must always be used to begin a tape
session. Through it, the user identifies the tapeset and
its characteristics: density, length, tape format. Also,
the user specifies the Volume Serial Number(s) (VSNs) for
the tape volume(s). If a multi-volume tapeset is being
processed, then the full list of VSNs must be named.
The taccess command also implicitly performs the equivalent
of tposn -r -n1 (i.e. It positions the tape to read the
first file).
tdisplay
Licensed material--property of copyright holder(s) Page 13
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
tdisplay reports the current settings of file labels and
record translation parameters. The tkey command is used to
modify label and translation settings.
The -r option reports the file labels found after a tposn -r
or a tread command has been issued.
The -w option reports the file labels which would be written
by a subsequent twrite command. When a tposn command is
executed, these labels always revert to the default values.
The tkey command allows the labels to be modified before
writing.
The -d option displays the default file labels used during
file writes. They can be changed with the tkey -d command.
Current record translation settings are reported via the -t
option:
Translation processing:
Key Value
--- -----
pchar 40(octal)
tchar 12(octal)
conv none
tkey
tkey modifies file labels and record translation parameters.
See the subsections entitled Record Translation and Setting
File Labels for more information.
tlabel
tlabel writes the appropriate volume labels on a tape. A
tape must be labeled before it can be written or read by
twrite and tread. tlabel -r reports the VSN of the labeled
tape.
tposn
tposn moves the tape to be correctly positioned for either a
subsequent read ( tread ) or write ( twrite ). Read and
write start at different positions for a file, so the
position must be made specifically for the planned
operation. With the -r option, tposn positions for a read.
The -w option positions for a subsequent write.
Licensed material--property of copyright holder(s) Page 14
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
tposn resets file labels. If positioning for a write, tposn
resets the current file labels to default values. These
default values can be modified using the tkey command.
tread
The tread command reads a file from tape and sends the
output to standard output (stdout). It automatically reads
file labels making them available for review via the
tdisplay command. tread automatically detects the tape file
format and translates records according to the current
translation settings as configured by the tkey command.
trelease
trelease ends a tape session.
tsniff
tsniff produces a table of contents report on the tapeset.
It reads each tape in order and produces a report. For
example:
Tape Contents - vsn: 000001
fseq fid fmt blen rlen blocks
---- --- --- ---- ---- ------
1 F 100 100 194
2 F 1000 100 20
3 D 200 100 28
4 S 30 100 209
twrite
The twrite command writes a file to the tape receiving input
from standard input (stdin). It also writes file labels as
configured by the tkey command. twrite automatically
translates the UNIX data into tape records according to the
current translation settings, also configured by the tkey
command.
FILES
/var/reelexchange/default.adn File containing name of
default tape drive.
Licensed material--property of copyright holder(s) Page 15
REELexchange_intro(1) DG/UX 4.30 REELexchange_intro(1)
/var/reelexchange/tapecap File containing descriptive
entries for all tape drives
supported by REELexchange.
/var/reelexchange/Adn/* Each file in this directory
describes a tape drive on
the system. The name of one
of these files can be
specified with the -a option
of the taccess command to
identify a particular tape
drive to REELexchange.
/var/reelexchange/d_ibm IBM label defaults.
/var/reelexchange/d_ansi ANSI label defaults.
SEE ALSO
taccess(1), tdisplay(1), tkey(1), tlabel(1), tposn(1),
tread(1), trelease(1), tsniff(1), twrite(1).
Licensed material--property of copyright holder(s) Page 16