reelexchange_intro(1) DG/UX R4.11 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
-- 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 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. The name of the file should be the name by which you wish to
refer to the tape drive. This is the value which will be used with
the -a option to the taccess and tlabel commands. Initially, this
directory contains one ADN file, drive1 which contains the following
information:
S 1 reel
T 1600 SYSV.1600 /dev/rmt/0 /dev/rmt/0n
The information on the first line of the file ("S 1 reel") is used
internally by the REELexchange commands. All of your ADN files
should contain this information on the first line as well. The
second line is a tape identifier entry (indicated by "T"). This
entry identifies tape density in bpi (1600), the tape drive type
(SYSV.1600), the device-special file for the tape drive (/dev/rmt/0),
and the corresponding rewind device file (/dev/rmt/0n). The ADN
file, drive1 is intended to be used as a prototype for creating your
own ADN files. DG/UX supports 800, 1600, 3200 and 6250 bpi tape
drives. The corresponding tape drive types for these tape densities
are SYSV.800, SYSV.1600, SYSV.3200 and SYSV.6250, respectively.
/var/reelexchange/default.adn
This file contains the name of one of the ADN files in the
/var/reelexchange/Adn directory. The tape drive name specified in
this file will be used as the default ADN file by the taccess and
tlabel commands whenever no ADN file is specified via the -a option.
/var/reelexchange/tapecap
This file contains entries describing each type of tape drive
supported by REELexchange.
/var/reelexchange/dibm
/var/reelexchange/dansi
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 dibm with
keyword/value pairs (as described for the tkey command) creates
default settings for IBM file labels. A file named dansi does the
same for ANSI file labels.
Common default modifications are for expiration date and system name.
Here are example lines from a dibm file which override those
particular defaults:
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.
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 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=ebcdic 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.
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
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 testown Owner Name and Address Code
HDR1: fid testfid Data Set Identifier
... 000000 Data Set Serial Number
... 1 Volume Sequence 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 testsys System Code
HDR2: fmt V Record Format (vbs)
blen 40 Block Length
rlen 100 Record Length
... 3 Tape Density
... 0 Data Set Position
job testjob Job Step Identification
cc A Control Character
bat R Block Attribute
devid testdid 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:
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 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 testown Owner Name and Address Code
HDR1: fid testfid Data Set Identifier
... 000000 Data Set Serial Number
... 1 Volume Sequence 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 testsys System Code
HDR2: fmt V Record Format (vbs)
blen 40 Block Length
rlen 100 Record Length
... 3 Tape Density
... 0 Data Set Position
job testjob Job Step Identification
cc A Control Character
bat R Block Attribute
devid testdid 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
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/labelsettings
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 dibm (for IBM tapes) and
dansi (for ANSI tapes) files located in the /var/reelexchange
directory. The built-in default values are:
IBM ANSI
--- ----
own="" own=""
fid="" acc=""
gen=0 fid=""
genv=0 gen=0
cre=currentdate genv=0
exp=1/1/2001 cre=currentdate
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 the subsection titled "Record Translation" for more 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
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.
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.
/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/dibm IBM label defaults.
/var/reelexchange/dansi ANSI label defaults.
DIAGNOSTICS
Error,adn name does not exist
Problem: The named tape drive is not identified under the
current configuration.
Solution: Check the drive name. If a new drive needs to be
configured, reinstall the software.
Error - ans r unknown label type name
Problem: The tape uses a label type not understood by
REELexchange.
Solution: None. REELexchange can only read IBM or ANSI
standard tapes.
Error, blen not in range 1 to 32760
Problem: The block length must be in the stated range.
Solution: Reset the block length keyword to a legal value.
Error: corrupted adn file filename
Problem: The configuration files are inconsistent.
Solution: Reinstall the REELexchange software.
Error,fmt invalid
Problem: An illegal format has been specified.
Solution: Reselect the format, using one of the legal values
described in chapter 3.
Error, hard error on rewind ioctl
Problem: The tape drive failed while rewinding.
Solution: Release the tape and unmount it.
Error, illegal label size number
Problem: The label record size (number) is less than eighty
bytes.
Solution: The record size must be eighty bytes or greater.
Error, i/o error reading label
Problem: The tape drive failed during a read operation.
Solution: Release the tape and unmount it. Retry the tape
session. If the problem persists, tape drive maintenance may
be in order.
Error: No default device name...
Problem: A default tape drive name was not specified during
installation.
Solution: Reinstall the REELexchange software and designate
the default tape drive name.
Error, read error skipping file in tposn
Problem: The tape drive failed during a positioning move.
Solution: Release the tape and unmount it. Retry the tape
session. If the problem persists, tape drive maintenance may
be in order.
Error, record does not equal block size
Problem: The block size is not an integral multiple of the
record size. This occurs under the fixed record format.
Solution: Redefine the block and/or record size appropriately.
Error, record exceeds block size num1 > num2
Problem: The given record size exceeds the given block size
for a fixed or non-spanned record format.
Solution: Redefine the block and/or record size appropriately.
Error,rdefadn could not access default adn filename
Problem: The configuration files are inconsistent.
Solution: Reinstall the REELexchange software.
Error: tape on adn has VSN VSN1 instead of VSN2
Problem: The mounted tape has a VSN(VSN1) different from the
VSN(VSN2) specified by the earlier taccess command.
Solution: Release the tape and retry the session. Use the
tlabel command to check the tape's VSN if necessary.
Error: Unknown label Identifier:name
Problem: The tape labels are non-standard.
Solution: None. REELexchange supports IBM and ANSI standard
tapes.
Error, unknown record format name
Problem: The specified format is non-standard.
Solution: None. REELexchange supports IBM and ANSI standard
tapes.
Error, unknown segment descriptor
Problem: The tape format is non-standard.
Solution: None. REELexchange supports IBM and ANSI standard
tapes.
Error, Variable length records require termination processing
Problem: The file contains variable length records and record
translation has not been specified.
Solution: Use the tkey command to enable record translation
processing.
REEL-Permission Denied
Problem: The REELexchange software is not properly installed.
Solution: Reinstall the REELexchange software.
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)